Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added TypeScript definitions, updated babel to copy .d.ts files #76

Closed
wants to merge 1 commit into from
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -33,7 +33,7 @@
"sinon": "^7.5.0"
},
"scripts": {
"build": "babel -d lib/ src/",
"build": "babel -D -d lib/ src/",
"prepare": "npm run build",
"prepublish": "npm run build",
"lint": "eslint src test examples",
9 changes: 9 additions & 0 deletions src/api.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
import { Config } from "./zuliprc";
import { ZulipSuccessResponse, ZulipErrorResponse } from "./types";

export function api(
baseUrl: string,
config: Config,
method: any,
params: any
): Promise<ZulipSuccessResponse | ZulipErrorResponse>;
7 changes: 7 additions & 0 deletions src/helper.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
import fetch from "isomorphic-fetch";
import FormData from "isomorphic-form-data";

export {
fetch,
FormData,
}
60 changes: 60 additions & 0 deletions src/index.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
import { Config } from "./zuliprc";
import { AccountsClient } from "./resources/accounts";
import { StreamsClient } from "./resources/streams";
import { QueuesClient } from "./resources/queues";
import { EventsClient } from "./resources/events";
import { UsersClient } from "./resources/users";
import { EmojisClient } from "./resources/emojis";
import { TypingClient } from "./resources/typing";
import { ReactionsClient } from "./resources/reactions";
import { ServerClient } from "./resources/server";
import { FiltersClient } from "./resources/filters";
import { MessagesClient } from "./resources/messages";

export type HttpMethod =
| "GET"
| "HEAD"
| "POST"
| "PUT"
| "DELETE"
| "TRACE"
| "OPTIONS"
| "CONNECT"
| "PATCH";

export interface Params {
[key: string]: any;
[key: number]: any;
}

export interface ZuliprcConfig {
zuliprc: string;
}

export interface ZulipClient {
config: Config;
callEndpoint: typeof callEndpoint;
accounts: AccountsClient;
streams: StreamsClient;
messages: MessagesClient;
queues: QueuesClient;
events: EventsClient;
users: UsersClient;
emojis: EmojisClient;
typing: TypingClient;
reactions: ReactionsClient;
server: ServerClient;
filters: FiltersClient;
}

export type InitialConfig = ZuliprcConfig | Pick<Config, "realm">;

export function getCallEndpoint(config: Config): typeof callEndpoint;

export function callEndpoint(endpoint: string, method: HttpMethod, params: Params): Promise<unknown>;

export function resources(config: Config): ZulipClient;

export function zulip(initialConfig: Partial<InitialConfig>): Promise<ZulipClient>;

export * from "./types";
13 changes: 13 additions & 0 deletions src/resources/accounts.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
import { Config } from "../zuliprc";
import { RetrieverClient, ZulipSuccessResponse, ZulipErrorResponse } from "../types";

export type AccountsClient = RetrieverClient;

// SECTION GET ACCOUNTS
// TODO Find documentation on Get Accounts
export interface GetAccountsParams { }
export type GetAccountsResponse = GetAccountsSuccess | GetAccountsError;
export interface GetAccountsSuccess extends ZulipSuccessResponse { }
export interface GetAccountsError extends ZulipErrorResponse { }

export default function accounts(config: Config): AccountsClient;
42 changes: 42 additions & 0 deletions src/resources/emojis.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
import { Config } from "../zuliprc";
import { RetrieverClient, ZulipSuccessResponse, ZulipErrorResponse } from "../types";

export type EmojisClient = RetrieverClient;

// SECTION GET EMOJIS
export interface GetEmojisParams { }

export type GetEmojisResponse = GetEmojisSuccess | GetEmojisError;

export interface GetEmojisSuccess extends ZulipSuccessResponse {
emoji: {
[key: number]: Emoji;
}
}

export interface Emoji {
author: {
email: string;
full_name: string;
id: number;
},
deactivated: boolean;
id: string;
name: string;
source_url: string;
}

export interface GetEmojisError extends ZulipErrorResponse { }

// SECTION UPLOAD EMOJIS
// TODO Find documentation on Get Emojis
export interface UploadEmojisParams { }

export type UploadEmojisResponse = UploadEmojisSuccess | UploadEmojisError;

export interface UploadEmojisSuccess extends ZulipSuccessResponse { }

export interface UploadEmojisError extends ZulipErrorResponse { }


export default function emojis(config: Config): EmojisClient;
48 changes: 48 additions & 0 deletions src/resources/events.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
import { Config } from "../zuliprc";
import { RetrieverClient, ZulipSuccessResponse, ZulipErrorResponse } from "../types";

export type EventsClient = RetrieverClient;

// SECTION GET EVENTS
export interface GetEventsParams {
/** "1375801870:2942" No The ID of a queue that you registered via POST /api/v1/register (see Register a queue). */
queue_id?: string;
/** -1 No The highest event ID in this queue that you've received and wish to acknowledge. See the code for call_on_each_event in the zulip Python module for an example implementation of correctly processing each event exactly once. */
last_event_id?: number;
/** true No Set to true if the client is requesting a nonblocking reply. If not specified, the request will block until either a new event is available or a few minutes have passed, in which case the server will send the client a heartbeat event. Defaults to false. */
dont_block?: boolean;
}

export type GetEventsResponse = GetEventsSuccess | GetEventsError;

export interface GetEventsSuccess extends ZulipSuccessResponse {
events: Event[]
}

export type Event = MessageEvent | any;

export interface MessageEvent {
avatar_url: string;
client: string;
content: string;
content_type: string;
display_recipient: string;
id: number;
recipient_id: number;
sender_email: string;
sender_full_name: string;
sender_id: number;
sender_realm_str: string;
sender_short_name: string;
subject: string;
subject_links: string[],
timestamp: number;
type: string;
}

export interface GetEventsError extends ZulipErrorResponse {
code: string;
queue_id: string;
}

export function events(config: Config): EventsClient;
9 changes: 9 additions & 0 deletions src/resources/filters.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
import { Config } from "../zuliprc";
import { RetrieverClient } from "../types";

export type FiltersClient = RetrieverClient;

// SECTION GET FILTERS FOR REALM
// TODO Find documentation on Get Filters for Realm

export function filters(config: Config): FiltersClient;
260 changes: 260 additions & 0 deletions src/resources/messages.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,260 @@
import { Config } from "../zuliprc";
import { RetrieverClient, Caller, ZulipSuccessResponse, ZulipErrorResponse, Narrow } from "../types";

// SECTION MESSAGE CLIENT
export interface MessagesClient extends RetrieverClient<GetMessageParams, GetMessageResponse> {
send: Caller<SendMessageParams, SendMessageResponse>;
render: Caller<RenderMessageParams, RenderMessageResponse>;
update: Caller<UpdateMessageParams, UpdateMessageResponse>;
getById: Caller<GetMessageParams, GetMessageResponse>;
getHistoryById: Caller<GetMessageEditHistoryParams, GetMessageEditHistoryResponse>;
// TODO: Find documentation on Delete Reaction
deleteReactionById: Caller;
deleteById: Caller<DeleteMessageParams, DeleteMessageResponse>;
flags: MessagesFlagsClient;
}

export interface MessagesFlagsClient {
add: Caller<InitialUpdateMessageFlagsParams, UpdateMessageFlagsResponse>;
remove: Caller<InitialUpdateMessageFlagsParams, UpdateMessageFlagsResponse>;
}

// SECTION GET MESSAGE
export interface GetMessageParams {
/** The message ID to fetch messages near. Required unless use_first_unread_anchor is set to true. */
anchor?: number;
/** Whether to use the (computed by the server) first unread message matching the narrow as the anchor. Mutually exclusive with anchor. Defaults to false. */
use_first_unread_anchor?: boolean;
/** The number of messages with IDs less than the anchor to retrieve. */
num_before: number;
/** The number of messages with IDs greater than the anchor to retrieve. */
num_after?: number;
/** The narrow where you want to fetch the messages from. See how to construct a narrow. Defaults to []. */
narrow?: Array<Narrow>;
/** Whether the client supports computing gravatars URLs. If enabled, avatar_url will be included in the response only if there is a Zulip avatar, and will be null for users who are using gravatar as their avatar. This option significantly reduces the compressed size of user data, since gravatar URLs are long, random strings and thus do not compress well. Defaults to false. */
client_gravatar?: boolean;
/** If true, message content is returned in the rendered HTML format. If false, message content is returned in the raw markdown-format text that user entered. Defaults to true. */
apply_markdown?: boolean;
}

export type GetMessageResponse = GetMessageSuccess | GetMessageError;

export interface GetMessageSuccess extends ZulipSuccessResponse {
anchor: number;
found_anchor: boolean;
found_oldest: boolean;
found_newest: boolean;
messages: Message[];
}

export interface Message {
avatar_url: string;
client: string;
content: string;
content_type: MessageContentType;
display_recipient: string;
flags: MessageFlag[];
id: number;
is_me_message: boolean;
reactions: [];
recipient_id: number;
sender_email: string;
sender_full_name: string;
sender_id: number;
sender_realm_str: string;
sender_short_name: string;
stream_id: number;
subject: string;
subject_links: [];
submessages: [];
timestamp: number;
type: MessageType
}

export type MessageContentType = "text/html" | string;
export type MessageFlag =
| "read"
| "starred"
| "collapsed"
| "mentioned"
| "wildcard_mentioned"
| "has_alert_word"
| "historical";

export interface GetMessageError extends ZulipErrorResponse {}

// SECTION SEND MESSAGE
export interface SendMessageParams {
/** The type of message to be sent. private for a private message and stream for a stream message. Must be one of: private, stream. */
type: MessageType;
/** The destination stream, or a CSV/JSON-encoded list containing the usernames (emails) of the recipients. */
to: string;
/** The topic of the message. Only required if type is stream, ignored otherwise. Maximum length of 60 characters. */
topic?: string;
/** The content of the message. Maximum message size of 10000 bytes. */
content: string;
}

export type SendMessageResponse = SendMessageSuccess | SendMessageError;

export interface SendMessageSuccess extends ZulipSuccessResponse {
id: number;
}

export interface SendMessageError extends ZulipErrorResponse {
code: CRUDMessageErrorCode;
stream: string;
}

export type CRUDMessageErrorCode = "STREAM_DOES_NOT_EXIST" | "BAD_REQUEST" | string;

// SECTION RENDER MESSAGE
export interface RenderMessageParams {
/** The content of the message. */
content: string;
}

export type RenderMessageResponse = RenderMessageSuccess | RenderMessageError;

export interface RenderMessageSuccess extends ZulipSuccessResponse {
rendered: string;
}

export interface RenderMessageError extends ZulipErrorResponse {}

// SECTION UPDATE MESSAGE
export interface UpdateMessageParams {
/** The ID of the message that you wish to edit/update. */
message_id: number;
/** The topic of the message. Only required for stream messages. Maximum length of 60 characters. */
topic?: string;
/** Which message(s) should be edited: just the one indicated in message_id, messages in the same topic that had been sent after this one, or all of them. Must be one of: change_one, change_later, change_all. Defaults to "change_one". */
propagate_mode?: PropogateMode;
/** The content of the message. Maximum message size of 10000 bytes. */
content?: string;
}

export type UpdateMessageResponse = UpdateMessageSuccess | UpdateMessageError;

export interface UpdateMessageSuccess extends ZulipSuccessResponse {}

export interface UpdateMessageError extends ZulipErrorResponse {
code: CRUDMessageErrorCode;
}

// SECTION GET RAW MESSAGE
export interface GetRawMessageParams {
/** The ID of the message that you wish to get the raw message of. */
message_id: number;
}

export type GetRawMessageResponse = GetRawMessageSuccess | GetRawMessageError;

export interface GetRawMessageSuccess extends ZulipSuccessResponse {
raw_content: string;
}

export interface GetRawMessageError extends ZulipErrorResponse {
code: CRUDMessageErrorCode;
}

// SECTION UPLOAD A FILE
/* // TODO Define types when implemented in client
export interface UploadFileParams {}
export type UploadFileResponse = UploadFileSuccess | UploadFileError;
export interface UploadFileSuccess extends ZulipSuccessResponse {}
export interface UploadFileError extends ZulipErrorResponse {}
*/

// SECTION DELETE A MESSAGE
export interface DeleteMessageParams {
/** The ID of the message that you wish to delete. */
message_id: number;
}

export type DeleteMessageResponse = DeleteMessageSuccess | DeleteMessageError;

export interface DeleteMessageSuccess extends ZulipSuccessResponse {}

export interface DeleteMessageError extends ZulipErrorResponse {
code: CRUDMessageErrorCode;
}

// SECTION GET MESSAGE EDIT HISTORY
export interface GetMessageEditHistoryParams {
/** The ID of the message that you wish to get the edit history of. */
message_id: number;
}

export type GetMessageEditHistoryResponse = GetMessageEditHistorySuccess | GetMessageEditHistoryError;

export interface GetMessageEditHistorySuccess extends ZulipSuccessResponse {
message_history: [NewestMessage] | (EditedMessage[] & { 0: NewestMessage });
}

export interface HistoricalMessage {
content: string;
timestamp: number;
topic: string;
user_id: number;
}

export interface NewestMessage extends HistoricalMessage {
rendered_content: string;
}

export interface EditedMessage extends NewestMessage {
content_html_diff: string;
prev_content: string;
prev_rendered_content: string;
prev_topic: string;
}

export interface GetMessageEditHistoryError extends ZulipErrorResponse {
code: string;
}

// SECTION UPDATE MESSAGE FLAGS
export interface InitialUpdateMessageFlagsParams {
/** An array containing the IDs of the target messages. */
messages: number[];
/** The flag that should be added/removed. */
flag: MessageFlag;
}

export interface UpdateMessageFlagsParams extends InitialUpdateMessageFlagsParams {
/** Whether to add the flag or remove it. Must be one of: add, remove. */
op: "add" | "remove";
}

export type UpdateMessageFlagsResponse = UpdateMessageFlagsSuccess | UpdateMessageFlagsError;

export interface UpdateMessageFlagsSuccess extends ZulipSuccessResponse {
messages: number[],
}

export interface UpdateMessageFlagsError extends ZulipErrorResponse {}

// SECTION MARK MESSAGES READ
export interface MarkMessagesReadParams {
/** The ID of the stream whose messages should be marked as read. */
stream_id: number;
}

export type MarkMessagesReadResponse = MarkMessagesReadSuccess | MarkMessagesReadError;

export interface MarkMessagesReadSuccess extends ZulipSuccessResponse {}

export interface MarkMessagesReadError extends ZulipErrorResponse {}

// SECTION GENERAL TYPES
export type PrivateMessage = "private";
export type StreamMessage = "stream";
export type MessageType = PrivateMessage | StreamMessage;

export type PropogateMode = "change_one" | "change_later" | "change_all";

export function messages(config: Config): MessagesClient;
87 changes: 87 additions & 0 deletions src/resources/queues.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
import { Config } from "../zuliprc";
import { Caller, Narrow, ZulipSuccessResponse, ZulipErrorResponse } from "../types";
import { Message } from "./messages";
import { Emoji } from "./emojis";

export interface QueuesClient {
register: Caller<RegisterEventQueueParams, RegisterEventQueueResponse>;
deregister: Caller<DeregisterEventQueueParams, DeregisterEventQueueResponse>;
}

// SECTION REGISTER EVENT QUEUE
export interface RegisterEventQueueParams {
/** Set to true if you would like the content to be rendered in HTML format (otherwise the API will return the raw text that the user entered) Defaults to false.*/
apply_markdown?: boolean;
/**
* The client_gravatar field is set to true if clients can compute their own gravatars.
* Defaults to false.
*/
client_gravatar?: boolean;
/**
* A JSON-encoded array indicating which types of events you're interested in.
* Values that you might find useful include:* message (messages), * subscription (changes in your subscriptions), * realm_user (changes in the list of users in your realm)If you do not specify this argument, you will receive all events, and have to filter out the events not relevant to your client in your client code.
* For most applications, one is only interested in messages, so one specifies: event_types=['message']
*/
event_types?: EventType[];
/**
* Set to True if you would like to receive events that occur within all public streams.
* Defaults to false.
*/
all_public_streams?: boolean;
/**
* Set to True if you would like to receive events that include the subscribers for each stream.
* Defaults to false.
*/
include_subscribers?: boolean
/**
* Same as the event_types argument except that the values in fetch_event_types are used to fetch initial data.
* If fetch_event_types is not provided, event_types is used and if event_types is not provided, this argument defaults to None.
*/
fetch_event_types?: EventType[];
/**
* A JSON-encoded array of length 2 indicating the narrow for which you'd like to receive events for.
* For instance, to receive events for the stream Denmark, you would specify narrow=['stream', 'Denmark']. Another example is narrow=['is', 'private'] for private messages. Defaults to "narrow=[]".
*/
narrow: Narrow[];
}
export type RegisterEventQueueResponse = RegisterEventQueueSuccess | RegisterEventQueueError;
export type RegisterEventQueueSuccess = ZulipSuccessResponse & EventMap & {
last_event_id: number;
queue_id: string;
};

export type EventMap = { [key in EventType]: Event<key> };

export interface RegisterEventQueueError extends ZulipErrorResponse { }

export type EventType =
| "message"
| "subscription"
| "realm_user"
| "realm_emoji";

export type Event<T extends EventType> =
T extends "message" ? { [key: number]: Message } :
T extends "subscription" ? UnknownEvent :
T extends "realm_user" ? UnknownEvent :
T extends "realm_emoji" ? { [key: number]: Emoji } : any;

export type UnknownEvent = { [key: number]: any };

// SECTION UNREGISTER EVENT QUEUE
export interface DeregisterEventQueueParams {
/** The ID of a queue that you registered via POST /api/v1/register(see Register a queue. */
queue_id: string;
}

export type DeregisterEventQueueResponse = DeregisterEventQueueSuccess | DeregisterEventQueueError;

export interface DeregisterEventQueueSuccess extends ZulipSuccessResponse {}

export interface DeregisterEventQueueError extends ZulipErrorResponse {
code: string;
queue_id?: string;
}


export function queues(config: Config): QueuesClient;
14 changes: 14 additions & 0 deletions src/resources/reactions.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
import { Config } from "../zuliprc";

export interface ReactionsClient {
add: Promise<unknown>;
remove: Promise<unknown>;
}

// SECTION ADD REACTIONS
// TODO Find documentation for Add Reactions

// SECTION REMOVE REACTIONS
// TODO Find documentation for Remove Reactions

export function reactions(config: Config): ReactionsClient;
81 changes: 81 additions & 0 deletions src/resources/server.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
import { Config } from "../zuliprc";
import { Caller, ZulipSuccessResponse, ZulipErrorResponse } from "../types";

export interface ServerClient {
settings: Caller;
}

export interface GetServerSettingsParams {}

export type GetServerSettingsResponse = GetServerSettingsSuccess | GetServerSettingsError;

export interface GetServerSettingsSuccess extends ZulipSuccessResponse {
/** object in which each key-value pair in the object indicates whether the authentication method is enabled on this server. */
authentication_methods: { [key in AuthenticationMethod]: boolean };
/** the version of Zulip running in the server. */
zulip_version: string;
/** whether mobile/push notifications are enabled. */
push_notifications_enabled: boolean;
/** whether the Zulip client that has sent a request to this endpoint is deemed incompatible with the server. */
is_incompatible: boolean;
/** setting for allowing users authenticate with an email-password combination. */
email_auth_enabled: boolean;
/** whether usernames should have an email address format. This is important for clients to know whether the validate email address format in a login prompt; this value will be false if the server has LDAP authentication enabled with a username and password combination. */
require_email_format_usernames: string;
/** the organization's canonical URI. */
realm_uri: string;
/** the organization's name (for display purposes). */
realm_name: string;
/** the URI of the organization's logo as a square image, used for identifying the organization in small locations in the mobile and desktop apps. */
realm_icon: string;
/** HTML description of the organization, as configured by the organization profile. */
realm_description: string;
/** list of dictionaries describing the available external authentication methods (such as google/github/SAML) enabled for this organization. Each dictionary specifies the name and icon that should be displayed on the login buttons (display_name and display_icon, where display_icon can be null, if no icon is to be displayed), the URLs that should be accessed to initiate login/signup using the method (login_url and signup_url) and name, which is a unique, stable, machine-readable name for the authentication method. The list is sorted in the order in which these authentication methods should be displayed. */
external_authentication_methods: ExternalAuthenticationMethod[];
}

export interface GetServerSettingsError extends ZulipErrorResponse { }

// SECTION GENERAL TYPES
export type AuthenticationMethod =
| "azuread"
| "dev"
| "email"
| "github"
| "google"
| "ldap"
| "password"
| "remoteuser"
| "saml";


export type ExternalAuthenticationMethod =
| SAMLAuthenticationMethod
| GoogleAuthenticationMethod
| GitHubAuthenticationMethod;

export interface SAMLAuthenticationMethod {
display_icon: null,
display_name: "SAML",
login_url: string;
name: "saml:idp_name",
signup_url: string;
}

export interface GoogleAuthenticationMethod {
display_icon: string;
display_name: "Google";
login_url: string;
name: "google";
signup_url: string;
}

export interface GitHubAuthenticationMethod {
display_icon: string;
display_name: "GitHub";
login_url: string;
name: "github";
signup_url: string;
}

export function server(config: Config): ServerClient;
94 changes: 94 additions & 0 deletions src/resources/streams.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
import { Config } from "../zuliprc";
import { RetrieverClient, Caller, ZulipSuccessResponse, ZulipErrorResponse, Subscription, Topic } from "../types";

export interface StreamsClient extends RetrieverClient<GetStreamsParams, GetStreamsResponse> {
getStreamId: Caller<GetStreamParams, GetStreamResponse>;
subscriptions: StreamSubscriptions;
topics: StreamTopics;
}

export type StreamSubscriptions = RetrieverClient<GetStreamSubscriptionParams, GetStreamSubscriptionResponse>;
export type StreamTopics = RetrieverClient<GetStreamTopicsParams, GetStreamTopicsResponse>;

// SECTION GET SUBSCRIPTIONS
export interface GetStreamsParams {
/** Include all public streams. Defaults to true. */
include_public?: boolean;
/** Include all streams that the user is subscribed to. Defaults to true. */
include_subscribed?: boolean;
/** Include all active streams. The user must have administrative privileges to use this parameter. Defaults to false. */
include_all_active?: boolean;
/** Include all default streams for the user's realm. Defaults to false. */
include_default?: boolean;
/** If the user is a bot, include all streams that the bot's owner is subscribed to. Defaults to false. */
include_owner_subscribed?: boolean;
}

export type GetStreamsResponse = GetStreamsSuccess | GetStreamsError;

export interface GetStreamsSuccess extends ZulipSuccessResponse {
streams: Stream[];
}

export interface GetStreamsError extends ZulipErrorResponse {
code: string;
}

// SECTION GET STREAM BY ID
export interface GetStreamParams {
/** The name of the stream to retrieve the ID for. */
stream: string;
}

export type GetStreamResponse = GetStreamSuccess | GetStreamError;

export interface GetStreamSuccess extends ZulipSuccessResponse {
stream_id: number;
}

export interface GetStreamError extends ZulipErrorResponse {
code: string;
}

// SECTION STREAM SUBSCRIPTIONS
export interface GetStreamSubscriptionParams {
/** Set to true if you would like each stream's info to include a list of current subscribers to that stream. (This may be significantly slower in organizations with thousands of users.) Defaults to false. */
include_subscribers?: boolean;
}

export type GetStreamSubscriptionResponse = GetStreamSubscriptionSuccess | GetStreamSubscriptionError;

export interface GetStreamSubscriptionSuccess extends ZulipSuccessResponse {
subscriptions: Subscription[];
}

export interface GetStreamSubscriptionError extends ZulipErrorResponse {}

// SECTION STREAM TOPICS
export interface GetStreamTopicsParams {
stream_id: number;
}

export type GetStreamTopicsResponse = GetStreamTopicsSuccess | GetStreamTopicsError;

export interface GetStreamTopicsSuccess extends ZulipSuccessResponse {
topics: Topic[];
}

export interface GetStreamTopicsError extends ZulipErrorResponse {
code: string;
}

// SECTION GENERAL TYPES
export interface Stream {
/** The unique ID of a stream. */
stream_id: number;
/** The name of a stream. */
name: string;
/** A short description of a stream. */
description: string;
/** Specifies whether a stream is private or not. Only people who have been invited can access a private stream. */
invite_only: boolean;
}

export function streams(config: Config): StreamsClient;
25 changes: 25 additions & 0 deletions src/resources/typing.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
import { Config } from "../zuliprc";
import { Caller, ZulipSuccessResponse, ZulipErrorResponse } from "../types";

export interface TypingClient {
send: Caller<SendTypingParams, SendTypingResponse>;
}

// SECTION SEND TYPING
export interface SendTypingParams {
/** Whether the user has started (start) or stopped (stop) to type. Must be one of: start, stop. */
op: TypingOperation;
/** The recipients of the message being typed, in the same format used by the send_message API. Typing notifications are only supported for private messages, so this should be a JSON-encoded list of email addresses of the message's recipients. */
to: string[];
}

export type SendTypingResponse = SendTypingSuccess | SendTypingError;

export interface SendTypingSuccess extends ZulipSuccessResponse {}

export interface SendTypingError extends ZulipErrorResponse {}

// SECTION GENERAL TYPES
export type TypingOperation = "start" | "stop";

export function typing(config: Config): TypingClient;
185 changes: 185 additions & 0 deletions src/resources/users.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,185 @@
import { Config } from "../zuliprc";
import { RetrieverClient, ZulipSuccessResponse, ZulipErrorResponse, Caller, Subscription } from "../types";

export interface UsersClient extends RetrieverClient {
create: Caller<CreateUserParams, CreateUserResponse>;
me: UsersMeClient;
}

export interface UsersMeClient {
pointer: UsersMePointerClient;
getProfile: Caller<GetProfileParams, GetProfileResponse>;
subscriptions: SubscriptionsClient;
alertWords: AlertWordsClient
}

export interface UsersMePointerClient {
retrieve: Caller<GetUserInfoPointerParams, GetUserInfoPointerResponse>;
update: Caller<UpdateUserInfoPointerParams, UpdateUserInfoPointerResponse>;
}

export interface SubscriptionsClient {
add: Caller<AddUserSubscriptionsParams, AddUserSubscriptionsResponse>;
remove: Caller<RemoveUserSubscriptionsParams, RemoveUserSubscriptionsResponse>;
}

export type AlertWordsClient = RetrieverClient<GetAlertWordsParams, GetAlertWordsResponse>;

// SECTION CREATE USER
export interface CreateUserParams {
/** The email address of the new user. */
email: string;
/** The password of the new user. */
password: string;
/** The full name of the new user. */
full_name: string;
/** The short name of the new user. Not user-visible. */
short_name: string;
}

export type CreateUserResponse = CreateUserSuccess | CreateUserError;

export interface CreateUserSuccess extends ZulipSuccessResponse {}

export interface CreateUserError extends ZulipErrorResponse { }

// SECTION GET MY INFO
export interface GetMyInfoParams {}

export type GetMyInfoResponse = GetMyInfoSuccess | GetMyInfoError;

export interface GetMyInfoSuccess extends ZulipSuccessResponse {
avatar_url: string;
client_id: string;
email: string;
full_name: string;
is_admin: boolean;
is_bot: boolean;
max_message_id: number;
pointer: number;
profile_data: { [key: string]: ProfileData };
short_name: string;
user_id: number;
}

export interface GetMyInfoError extends ZulipErrorResponse { }

// SECTION GET USER INFO POINTER
// TODO Find documentation on Get User Info Pointer
export interface GetUserInfoPointerParams { }

export type GetUserInfoPointerResponse = GetUserInfoPointerSuccess | GetUserInfoPointerError;

export interface GetUserInfoPointerSuccess extends ZulipSuccessResponse { }

export interface GetUserInfoPointerError extends ZulipErrorResponse { }

// SECTION UPDATE USER INFO POINTER
// TODO Find documentation on Update User Info Pointer
export interface UpdateUserInfoPointerParams { }

export type UpdateUserInfoPointerResponse = UpdateUserInfoPointerSuccess | UpdateUserInfoPointerError;

export interface UpdateUserInfoPointerSuccess extends ZulipSuccessResponse { }

export interface UpdateUserInfoPointerError extends ZulipErrorResponse { }

// SECTION GET PROFILE
// TODO Find documentation on
export interface GetProfileParams { }

export type GetProfileResponse = GetProfileSuccess | GetProfileError;

export interface GetProfileSuccess extends ZulipSuccessResponse { }

export interface GetProfileError extends ZulipErrorResponse { }

// SECTION ADD USER SUBSCRIPTIONS
export interface AddUserSubscriptionsParams {
/**
* A list of dictionaries containing the the key name and value specifying the name of the stream to subscribe.
* If the stream does not exist a new stream is created. The description of the stream created can be specified by
* setting the dictionary key description with an appropriate value.Note: This argument is called streams and not
* subscriptions in our Python API.
*/
subscriptions: Subscription[];
/** A boolean specifying whether the streams specified in subscriptions are invite-only or not. Defaults to false. */
invite_only?: boolean;
/**
* A list of email addresses of the users that will be subscribed to the streams specified in the subscriptions argument.
* If not provided, then the requesting user/bot is subscribed. Defaults to [].
*/
principals?: string[];
/**
* A boolean specifying whether authorization errors (such as when the requesting user is not authorized to access a private stream)
* should be considered fatal or not. When True, an authorization error is reported as such. When set to False, the returned JSON
* payload indicates that there was an authorization error, but the response is still considered a successful one. Defaults to true.
*/
authorization_errors_fatal?: boolean;
/** A boolean indicating if the history should be available to newly subscribed members. Defaults to "None". */
history_public_to_subscribers?: boolean;
/**
* A boolean indicating if the stream is an announcements only stream. Only organization admins can post to announcements only streams.
* Defaults to false.
*/
is_announcement_only?: boolean;
/**
* If announce is True and one of the streams specified in subscriptions has to be created (i.e. doesn't exist to begin with),
* an announcement will be made notifying that a new stream was created.
* */
announce?: boolean;
}

export type AddUserSubscriptionsResponse = AddUserSubscriptionsSuccess | AddUserSubscriptionsError;

export interface AddUserSubscriptionsSuccess extends ZulipSuccessResponse {
already_subscribed?: UserSubscriptionStatuses;
subscribed?: UserSubscriptionStatuses;
unauthorized?: string[];
}

export interface AddUserSubscriptionsError extends ZulipErrorResponse { }

// SECTION REMOVE USER SUBSCRIPTIONS
export interface RemoveUserSubscriptionsParams {
/** A list of stream names to unsubscribe from. This argument is called streams in our Python API. */
subscriptions: string[] & { 0: string };
/**
* A list of email addresses of the users that will be unsubscribed from the streams specified in the subscriptions argument.
* If not provided, then the requesting user/bot is unsubscribed. */
principals?: string[];
}

export type RemoveUserSubscriptionsResponse = RemoveUserSubscriptionsSuccess | RemoveUserSubscriptionsError;

export interface RemoveUserSubscriptionsSuccess extends ZulipSuccessResponse {
not_removed: string[];
removed: string;
}

export interface RemoveUserSubscriptionsError extends ZulipErrorResponse {
code: string;
stream: string;
}

// SECTION GET ALERT WORDS
// TODO Find documentation on Get Alert Words
export interface GetAlertWordsParams { }

export type GetAlertWordsResponse = GetAlertWordsSuccess | GetAlertWordsError;

export interface GetAlertWordsSuccess extends ZulipSuccessResponse { }

export interface GetAlertWordsError extends ZulipErrorResponse { }

// SECTION GENERAL TYPES
export interface ProfileData {
value: string;
rendered_value?: string;
}

export interface UserSubscriptionStatuses {
[key: string]: string[]
}

export function users(config: Config): UsersClient;
68 changes: 68 additions & 0 deletions src/types.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
export type Caller<P = unknown, R = unknown> = (params: P) => Promise<R>;

export interface RetrieverClient<P = unknown, R = unknown> {
retrieve: Caller<P, R>;
}

export interface ZulipApiResponse {
msg: string;
}

export interface ZulipSuccessResponse extends ZulipApiResponse {
result: "success";
}

export interface ZulipErrorResponse {
result: "error";
}

// TODO Expand the possible types for Narrow operations
export interface Narrow {
operator: string;
operand: string | string[];
negated?: boolean;
}


export interface Subscription {
/** The unique ID of a stream. */
stream_id: number;
/** The name of a stream. */
name: string;
/** A short description of a stream. */
description: string;
/** Specifies whether a stream is private or not. Only people who have been invited can access a private stream. */
invite_only: boolean;
/** A list of email addresses of users who are also subscribed to a given stream. Included only if include_subscribers is true. */
subscribers: string[];
/** A boolean specifiying whether desktop notifications are enabled for the given stream. */
desktop_notifications: boolean;
/** A boolean specifiying whether push notifications are enabled for the given stream. */
push_notifications: boolean;
/** A boolean specifiying whether audible notifications are enabled for the given stream. */
audible_notifications: boolean;
/** A boolean specifying whether the given stream has been pinned to the top. */
pin_to_top: boolean;
/** Email address of the given stream. */
email_address: string;
/** Whether the given stream is muted or not. Muted streams do not count towards your total unread count and thus, do not show up in All messages view (previously known as Home view). */
in_home_view: boolean;
/** Stream color. (e.g. "#6f6c6f") */
color: string;
}

export interface Topic {
/** The name of the topic. */
name: string;
/** The message ID of the last message sent to this topic. */
max_id: number;
}

/*
The following can be used for quickly creating new API accessors following the design of zulip-js
export interface XYZParams { }
export type XYZResponse = XYZSuccess | XYZError;
export interface XYZSuccess extends ZulipSuccessResponse { }
export interface XYZError extends ZulipErrorResponse { }
*/
9 changes: 9 additions & 0 deletions src/zuliprc.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
export interface Config {
realm: string;
username: string;
password: string;
apiURL: string;
apiToken: string;
}

export function parseConfigFile(filename: string): Promise<Config>;