@doist/comms-sdk 0.1.0-alpha.1 → 0.2.0

package/dist/types/clients/inbox-client.d.ts

@@ -5,16 +5,92 @@ import { BaseClient } from './base-client.js';
 export declare class InboxClient extends BaseClient {
     /**
      * Gets inbox items (threads).
+     *
+     * @param args - The arguments for getting inbox.
+     * @param args.workspaceId - The workspace ID.
+     * @param args.newerThan - Optional date to get items newer than.
+     * @param args.olderThan - Optional date to get items older than.
+     * @param args.limit - Optional limit on number of items returned.
+     * @param args.cursor - Optional cursor for pagination.
+     * @param args.archiveFilter - Optional filter: 'active' (default), 'archived', or 'all'.
+     * @returns Inbox threads.
+     *
+     * @example
+     * ```typescript
+     * const inbox = await api.inbox.getInbox({
+     *   workspaceId: 123,
+     *   newerThan: new Date('2024-01-01'),
+     * })
+     *
+     * // Include archived (done) items alongside active ones
+     * const allInbox = await api.inbox.getInbox({
+     *   workspaceId: 123,
+     *   archiveFilter: 'all',
+     * })
+     * ```
      */
     getInbox(args: GetInboxArgs): Promise<InboxThread[]>;
-    /** Gets unread count for inbox. */
+    /**
+     * Gets unread count for inbox.
+     *
+     * @param workspaceId - The workspace ID.
+     * @returns The unread count.
+     *
+     * @example
+     * ```typescript
+     * const count = await api.inbox.getCount(123)
+     * console.log(`Unread items: ${count}`)
+     * ```
+     */
     getCount(workspaceId: number): Promise<number>;
-    /** Archives a thread in the inbox. */
+    /**
+     * Archives a thread in the inbox.
+     *
+     * @param id - The thread ID.
+     *
+     * @example
+     * ```typescript
+     * await api.inbox.archiveThread('7YpL3oZ4kZ9vP7Q1tR2sX3z')
+     * ```
+     */
     archiveThread(id: string): Promise<void>;
-    /** Unarchives a thread in the inbox. */
+    /**
+     * Unarchives a thread in the inbox.
+     *
+     * @param id - The thread ID.
+     *
+     * @example
+     * ```typescript
+     * await api.inbox.unarchiveThread('7YpL3oZ4kZ9vP7Q1tR2sX3z')
+     * ```
+     */
     unarchiveThread(id: string): Promise<void>;
-    /** Marks all inbox items as read in a workspace. */
+    /**
+     * Marks all inbox items as read in a workspace.
+     *
+     * @param workspaceId - The workspace ID.
+     *
+     * @example
+     * ```typescript
+     * await api.inbox.markAllRead(123)
+     * ```
+     */
     markAllRead(workspaceId: number): Promise<void>;
-    /** Archives all inbox items in a workspace. */
+    /**
+     * Archives all inbox items in a workspace.
+     *
+     * @param args - The arguments for archiving all.
+     * @param args.workspaceId - The workspace ID.
+     * @param args.channelIds - Optional array of channel IDs to filter by.
+     * @param args.olderThan - Optional date to filter items older than.
+     *
+     * @example
+     * ```typescript
+     * await api.inbox.archiveAll({
+     *   workspaceId: 123,
+     *   olderThan: new Date('2024-01-01'),
+     * })
+     * ```
+     */
     archiveAll(args: ArchiveAllArgs): Promise<void>;
 }

package/dist/types/clients/reactions-client.d.ts

@@ -5,15 +5,53 @@ import { BaseClient } from './base-client.js';
  * Client for interacting with Comms reaction endpoints.
  */
 export declare class ReactionsClient extends BaseClient {
-    /** Adds an emoji reaction to a thread, comment, or conversation message. */
+    /**
+     * Adds an emoji reaction to a thread, comment, or conversation message.
+     *
+     * @param args - The arguments for adding a reaction.
+     * @param args.threadId - Optional thread ID.
+     * @param args.commentId - Optional comment ID.
+     * @param args.messageId - Optional message ID (for conversation messages).
+     * @param args.reaction - The reaction emoji to add.
+     *
+     * @example
+     * ```typescript
+     * await api.reactions.add({ threadId: '7YpL3oZ4kZ9vP7Q1tR2sX3z', reaction: '👍' })
+     * ```
+     */
     add(args: AddReactionArgs): Promise<void>;
     /**
      * Gets reactions for a thread, comment, or conversation message.
      *
      * Returns an object with emoji reactions as keys and arrays of user IDs as
      * values, or null if no reactions.
+     *
+     * @param args - The arguments for getting reactions.
+     * @param args.threadId - Optional thread ID.
+     * @param args.commentId - Optional comment ID.
+     * @param args.messageId - Optional message ID (for conversation messages).
+     * @returns A reaction object with emoji reactions as keys and arrays of user IDs as values, or null if no reactions.
+     *
+     * @example
+     * ```typescript
+     * const reactions = await api.reactions.get({ threadId: '7YpL3oZ4kZ9vP7Q1tR2sX3z' })
+     * // Returns: { "👍": [101, 202, 303], "❤️": [101, 202] }
+     * ```
      */
     get(args: GetReactionsArgs): Promise<ReactionObject>;
-    /** Removes an emoji reaction from a thread, comment, or conversation message. */
+    /**
+     * Removes an emoji reaction from a thread, comment, or conversation message.
+     *
+     * @param args - The arguments for removing a reaction.
+     * @param args.threadId - Optional thread ID.
+     * @param args.commentId - Optional comment ID.
+     * @param args.messageId - Optional message ID (for conversation messages).
+     * @param args.reaction - The reaction emoji to remove.
+     *
+     * @example
+     * ```typescript
+     * await api.reactions.remove({ threadId: '7YpL3oZ4kZ9vP7Q1tR2sX3z', reaction: '👍' })
+     * ```
+     */
     remove(args: RemoveReactionArgs): Promise<void>;
 }

package/dist/types/clients/search-client.d.ts

@@ -7,14 +7,64 @@ import { BaseClient } from './base-client.js';
 export declare class SearchClient extends BaseClient {
     /**
      * Searches across all threads and conversations in a workspace.
+     *
+     * @param args - The arguments for searching.
+     * @param args.query - The search query string. Optional when `mentionSelf: true` is set; required otherwise.
+     * @param args.workspaceId - The workspace ID to search in.
+     * @param args.channelIds - Optional array of channel IDs to filter by.
+     * @param args.authorIds - Optional array of author user IDs to filter by.
+     * @param args.mentionSelf - Optional flag to filter by mentions of the current user. When true, `query` may be omitted.
+     * @param args.dateFrom - Optional start date for filtering (YYYY-MM-DD).
+     * @param args.dateTo - Optional end date for filtering (YYYY-MM-DD).
+     * @param args.limit - Optional limit on number of results returned.
+     * @param args.cursor - Optional cursor for pagination.
+     * @returns Search results with pagination.
+     *
+     * @example
+     * ```typescript
+     * const results = await api.search.search({
+     *   query: 'important meeting',
+     *   workspaceId: 123,
+     * })
+     * ```
      */
     search(args: SearchArgs): Promise<SearchResponse>;
     /**
      * Searches within comments of a specific thread.
+     *
+     * @param args - The arguments for searching within a thread.
+     * @param args.query - The search query string.
+     * @param args.threadId - The thread ID to search in.
+     * @param args.limit - Optional limit on number of results returned.
+     * @param args.cursor - Optional cursor for pagination.
+     * @returns Comment IDs that match the search query.
+     *
+     * @example
+     * ```typescript
+     * const results = await api.search.searchThread({
+     *   query: 'deadline',
+     *   threadId: '7YpL3oZ4kZ9vP7Q1tR2sX3z',
+     * })
+     * ```
      */
     searchThread(args: SearchThreadArgs): Promise<SearchThreadResponse>;
     /**
      * Searches within messages of a specific conversation.
+     *
+     * @param args - The arguments for searching within a conversation.
+     * @param args.query - The search query string.
+     * @param args.conversationId - The conversation ID to search in.
+     * @param args.limit - Optional limit on number of results returned.
+     * @param args.cursor - Optional cursor for pagination.
+     * @returns Message IDs that match the search query.
+     *
+     * @example
+     * ```typescript
+     * const results = await api.search.searchConversation({
+     *   query: 'budget',
+     *   conversationId: '7YpL3oZ4kZ9vP7Q1tR2sX42',
+     * })
+     * ```
      */
     searchConversation(args: SearchConversationArgs): Promise<SearchConversationResponse>;
 }

package/dist/types/clients/threads-client.d.ts

@@ -293,51 +293,243 @@ export declare const ThreadListSchema: z.ZodArray<z.ZodPipe<z.ZodObject<{
  */
 export declare class ThreadsClient extends BaseClient {
     /**
-     * Lists threads. At least one of `channelId` / `workspaceId` is required.
+     * Gets threads. At least one of `channelId` / `workspaceId` is required.
      * `newerThan` / `olderThan` (`Date`) are converted to the
      * `newer_than_ts` / `older_than_ts` epoch-second params on the wire.
+     *
+     * @param args - The arguments for getting threads.
+     * @param args.workspaceId - The workspace ID.
+     * @param args.channelId - Optional channel ID to narrow to a single channel.
+     * @param args.archived - Optional flag to include archived threads.
+     * @param args.newerThan - Optional date to get threads newer than.
+     * @param args.olderThan - Optional date to get threads older than.
+     * @param args.limit - Optional limit on number of threads returned.
+     * @returns An array of thread objects.
+     *
+     * @example
+     * ```typescript
+     * const threads = await api.threads.getThreads({
+     *   workspaceId: 123,
+     *   channelId: '7YpL3oZ4kZ9vP7Q1tR2sX44',
+     * })
+     * threads.forEach(t => console.log(t.title))
+     * ```
      */
     getThreads(args: GetThreadsArgs): Promise<Thread[]>;
-    /** Fetches a single thread by ID. */
+    /**
+     * Gets a single thread object by id.
+     *
+     * @param id - The thread ID.
+     * @returns The thread object.
+     */
     getThread(id: string): Promise<Thread>;
-    /** Creates a new thread. `id` is auto-generated if not supplied. */
+    /**
+     * Creates a new thread in a channel. `id` is auto-generated if not supplied.
+     *
+     * @param args - The arguments for creating a thread.
+     * @param args.channelId - The channel ID.
+     * @param args.title - Optional thread title.
+     * @param args.content - The thread content.
+     * @param args.recipients - Optional array of user IDs to notify.
+     * @param args.groups - Optional array of custom group IDs to notify.
+     * @returns The created thread object.
+     *
+     * @example
+     * ```typescript
+     * const thread = await api.threads.createThread({
+     *   channelId: '7YpL3oZ4kZ9vP7Q1tR2sX44',
+     *   title: 'New Feature Discussion',
+     *   content: 'Let\'s discuss the new feature...',
+     * })
+     * ```
+     */
     createThread(args: CreateThreadArgs): Promise<Thread>;
-    /** Partial update of an existing thread. */
+    /**
+     * Partial update of an existing thread.
+     *
+     * @param args - The arguments for updating a thread.
+     * @param args.id - The thread ID.
+     * @param args.title - Optional new thread title.
+     * @param args.content - Optional new thread content.
+     * @returns The updated thread object.
+     */
     updateThread(args: UpdateThreadArgs): Promise<Thread>;
-    /** Permanently deletes a thread. */
+    /**
+     * Permanently deletes a thread.
+     *
+     * @param id - The thread ID.
+     */
     deleteThread(id: string): Promise<StatusOk>;
-    /** Saves a thread (formerly "star"). */
+    /**
+     * Saves a thread (formerly "star").
+     *
+     * @param id - The thread ID.
+     */
     saveThread(id: string): Promise<StatusOk>;
-    /** Unsaves a thread (formerly "unstar"). */
+    /**
+     * Unsaves a thread (formerly "unstar").
+     *
+     * @param id - The thread ID.
+     */
     unsaveThread(id: string): Promise<StatusOk>;
+    /**
+     * Pins a thread.
+     *
+     * @param id - The thread ID.
+     */
     pinThread(id: string): Promise<StatusOk>;
+    /**
+     * Unpins a thread.
+     *
+     * @param id - The thread ID.
+     */
     unpinThread(id: string): Promise<StatusOk>;
-    /** Moves a thread to another channel. */
+    /**
+     * Moves a thread to another channel.
+     *
+     * @param args - The arguments for moving a thread.
+     * @param args.id - The thread ID.
+     * @param args.toChannel - The target channel ID.
+     * @returns The updated thread object.
+     */
     moveToChannel(args: MoveThreadToChannelArgs): Promise<Thread>;
+    /**
+     * Marks a thread as read.
+     *
+     * @param args - The arguments for marking a thread as read.
+     * @param args.id - The thread ID.
+     * @param args.objIndex - The index of the last known read message.
+     */
     markRead(args: MarkThreadReadArgs): Promise<StatusOk>;
+    /**
+     * Marks a thread as unread.
+     *
+     * @param args - The arguments for marking a thread as unread.
+     * @param args.id - The thread ID.
+     * @param args.objIndex - The index of the last unread message. Use -1 to mark the whole thread as unread.
+     */
     markUnread(args: MarkThreadUnreadArgs): Promise<StatusOk>;
+    /**
+     * Marks a thread as unread for others. Useful to notify others about thread changes.
+     *
+     * @param args - The arguments for marking a thread as unread for others.
+     * @param args.id - The thread ID.
+     * @param args.objIndex - The index of the last unread message. Use -1 to mark the whole thread as unread.
+     */
     markUnreadForOthers(args: MarkThreadUnreadForOthersArgs): Promise<StatusOk>;
     /**
      * Marks every thread in a workspace or channel as read. Exactly one of
      * `workspaceId` / `channelId` should be set.
+     *
+     * @param args - Either workspaceId or channelId (one is required).
+     * @param args.workspaceId - The workspace ID.
+     * @param args.channelId - The channel ID.
+     *
+     * @example
+     * ```typescript
+     * // Mark all in workspace
+     * await api.threads.markAllRead({ workspaceId: 123 })
+     *
+     * // Mark all in channel
+     * await api.threads.markAllRead({ channelId: '7YpL3oZ4kZ9vP7Q1tR2sX44' })
+     * ```
      */
     markAllRead(args: {
         workspaceId?: number;
         channelId?: string;
     }): Promise<StatusOk>;
+    /**
+     * Clears unread threads in a workspace.
+     *
+     * @param workspaceId - The workspace ID.
+     */
     clearUnread(workspaceId: number): Promise<StatusOk>;
     /**
      * Returns unread threads for a workspace, paired with the unread version
      * counter and (optionally) the inbox unread count.
+     *
+     * @param workspaceId - The workspace ID.
+     * @returns Object containing the array of unread thread references, a version counter, and optionally the inbox unread count.
      */
     getUnread(workspaceId: number): Promise<{
         data: UnreadThread[];
         version: number;
         inboxUnread?: number | null;
     }>;
+    /**
+     * Mutes a thread for a specified number of minutes.
+     * When muted, you will not get notified in your inbox about new comments.
+     *
+     * @param args - The arguments for muting a thread.
+     * @param args.id - The thread ID.
+     * @param args.minutes - Number of minutes to mute the thread.
+     * @returns The updated thread object.
+     *
+     * @example
+     * ```typescript
+     * const thread = await api.threads.muteThread({ id: '7YpL3oZ4kZ9vP7Q1tR2sX3z', minutes: 30 })
+     * ```
+     */
     muteThread(args: MuteThreadArgs): Promise<Thread>;
+    /**
+     * Unmutes a thread.
+     * You will start to see notifications in your inbox again when new comments are added.
+     *
+     * @param id - The thread ID.
+     * @returns The updated thread object.
+     */
     unmuteThread(id: string): Promise<Thread>;
+    /**
+     * Closes a thread by adding a comment with a close action.
+     *
+     * @param args - The arguments for closing a thread.
+     * @param args.id - The thread ID.
+     * @param args.content - The comment content.
+     * @param args.attachments - Optional array of {@link Attachment} objects.
+     * @param args.actions - Optional array of action objects.
+     * @param args.recipients - Optional array of user IDs to notify directly.
+     * @param args.groups - Optional array of custom group IDs to notify.
+     * @param args.directMentions - Optional array of user IDs that were @-mentioned in
+     *   `content`.
+     * @param args.notifyAudience - Optional broader audience to notify in addition to
+     *   `recipients` and `groups`. `'channel'` notifies everyone in the channel;
+     *   `'thread'` notifies everyone who has interacted with the thread.
+     * @returns The created comment object.
+     *
+     * @example
+     * ```typescript
+     * const comment = await api.threads.closeThread({
+     *   id: '7YpL3oZ4kZ9vP7Q1tR2sX3z',
+     *   content: 'Closing this thread — resolved.',
+     * })
+     * ```
+     */
     closeThread(args: CloseThreadArgs): Promise<Comment>;
+    /**
+     * Reopens a thread by adding a comment with a reopen action.
+     *
+     * @param args - The arguments for reopening a thread.
+     * @param args.id - The thread ID.
+     * @param args.content - The comment content.
+     * @param args.attachments - Optional array of {@link Attachment} objects.
+     * @param args.actions - Optional array of action objects.
+     * @param args.recipients - Optional array of user IDs to notify directly.
+     * @param args.groups - Optional array of custom group IDs to notify.
+     * @param args.directMentions - Optional array of user IDs that were @-mentioned in
+     *   `content`.
+     * @param args.notifyAudience - Optional broader audience to notify in addition to
+     *   `recipients` and `groups`. `'channel'` notifies everyone in the channel;
+     *   `'thread'` notifies everyone who has interacted with the thread.
+     * @returns The created comment object.
+     *
+     * @example
+     * ```typescript
+     * const comment = await api.threads.reopenThread({
+     *   id: '7YpL3oZ4kZ9vP7Q1tR2sX3z',
+     *   content: 'Reopening — need further discussion.',
+     * })
+     * ```
+     */
     reopenThread(args: ReopenThreadArgs): Promise<Comment>;
     private addCommentWithAction;
     private simple;

package/dist/types/clients/users-client.d.ts

@@ -38,82 +38,209 @@ type MfaChallengeArgs = {
  * `loginWithTodoist` are the available entry points.
  */
 export declare class UsersClient extends BaseClient {
-    /** Registers a new user via the Todoist-ID bridge. */
+    /**
+     * Registers a new user via the Todoist-ID bridge.
+     *
+     * @param args - Registration arguments.
+     * @param args.name - The new user's full name.
+     * @param args.email - The new user's email.
+     * @param args.password - The new user's password.
+     * @param args.lang - Optional preferred language.
+     * @param args.acceptTerms - Optional flag confirming the user accepts the terms of service.
+     * @returns The newly registered user object.
+     */
     register(args: RegisterArgs): Promise<User>;
-    /** Logs in an existing user. */
+    /**
+     * Logs in an existing user.
+     *
+     * @param args - Login credentials.
+     * @param args.email - The user's email.
+     * @param args.password - The user's password.
+     * @param args.setSessionCookie - Optional flag to set a session cookie (default: true).
+     * @returns The authenticated user object.
+     *
+     * @example
+     * ```typescript
+     * const user = await api.users.login({
+     *   email: 'user@example.com',
+     *   password: 'secret',
+     * })
+     * ```
+     */
     login(args: LoginArgs): Promise<User>;
     /**
      * Logs in using a valid token (sent via Authorization header). The SDK
      * client is already configured with the token, so no args are needed.
+     *
+     * @returns The authenticated user object.
      */
     loginWithToken(): Promise<User>;
     /**
      * Exchanges the browser's Todoist web-session cookie for a Comms session.
      * Only useful when running in a browser context on the shared Todoist
      * registrable domain — the cookie is sent automatically by the browser.
+     *
+     * @returns The authenticated user object.
      */
     loginWithTodoist(): Promise<User>;
-    /** Logs in (and auto-signs-up) via a Google ID token. */
+    /**
+     * Logs in (and auto-signs-up) via a Google ID token.
+     *
+     * @param args - Google login arguments.
+     * @param args.idToken - The Google ID token.
+     * @param args.nonce - The nonce that was sent to Google.
+     * @param args.timezone - Optional user timezone.
+     * @param args.lang - Optional preferred language.
+     * @param args.mfaToken - Optional MFA token from a prior `mfaChallenge` response.
+     * @returns The authenticated user object.
+     */
     loginWithGoogle(args: LoginWithGoogleArgs): Promise<User>;
     /**
      * Completes an MFA challenge issued by `loginWithGoogle` (returns an MFA
      * token to pass back to `loginWithGoogle.mfaToken`).
+     *
+     * @param args - MFA challenge arguments.
+     * @param args.challengeId - The challenge ID from the prior login attempt.
+     * @param args.factor - The MFA factor identifier.
+     * @param args.methodType - The MFA method type.
+     * @returns The MFA token to forward to `loginWithGoogle`.
      */
     mfaChallenge(args: MfaChallengeArgs): Promise<MfaChallengeResponse>;
     /** Logs out the current user and clears the session cookie. */
     logout(): Promise<void>;
-    /** Returns the user associated with the current access token. */
+    /**
+     * Gets the user associated with the current access token.
+     *
+     * @returns The authenticated user's information.
+     *
+     * @example
+     * ```typescript
+     * const user = await api.users.getSessionUser()
+     * console.log(user.fullName, user.email)
+     * ```
+     */
     getSessionUser(): Promise<User>;
     /**
      * Fetches a single user. Defaults to the session user when no `id` is
      * passed. Cross-workspace lookups require that the caller and the target
      * share a workspace.
+     *
+     * @param args - Optional lookup arguments.
+     * @param args.id - The user ID. Defaults to the session user.
+     * @param args.workspaceId - Optional workspace ID for cross-workspace lookups.
+     * @param args.asList - Optional flag controlling list-style response.
+     * @returns The user object.
      */
     getUser(args?: {
         id?: number;
         workspaceId?: number;
         asList?: boolean;
     }): Promise<User>;
-    /** Looks up a user by their email address. */
+    /**
+     * Looks up a user by their email address.
+     *
+     * @param email - The email to look up.
+     * @returns The user object.
+     */
     getUserByEmail(email: string): Promise<User>;
     /**
      * Updates the logged-in user's profile. Most fields are proxied to
      * Todoist (full name, password, language, timezone, etc.).
+     *
+     * @param args - The user properties to update.
+     * @returns The updated user object.
+     *
+     * @example
+     * ```typescript
+     * const user = await api.users.update({
+     *   name: 'John Doe',
+     *   timezone: 'America/New_York',
+     * })
+     * ```
      */
     update(args: UpdateUserArgs): Promise<User>;
-    /** Updates the user's password. Requires `currentPassword`. */
+    /**
+     * Updates the user's password.
+     *
+     * @param args - Password update arguments.
+     * @param args.newPassword - The new password.
+     * @param args.currentPassword - The user's existing password. Optional — sent for
+     *   re-authentication when the account has a password set.
+     * @returns The updated user object.
+     */
     updatePassword(args: {
         newPassword: string;
         currentPassword?: string;
     }): Promise<User>;
-    /** Removes the user's avatar. */
+    /**
+     * Removes the user's avatar.
+     *
+     * @returns The updated user object.
+     */
     removeAvatar(): Promise<User>;
     /**
      * Invalidates the current API token and returns the user with a fresh
      * token.
+     *
+     * @returns The user object with the new token.
+     *
+     * @example
+     * ```typescript
+     * const user = await api.users.invalidateToken()
+     * console.log('New token:', user.token)
+     * ```
      */
     invalidateToken(): Promise<User>;
     /**
      * Validates that an arbitrary token is still active. Note this is sent
      * as a GET — the token is read from the query string, not the
      * Authorization header.
+     *
+     * @param token - The token to validate.
      */
     validateToken(token: string): Promise<void>;
-    /** Marks the user as active on a workspace (presence beacon). */
+    /**
+     * Marks the user as active on a workspace (presence beacon).
+     *
+     * @param args - Heartbeat arguments.
+     * @param args.workspaceId - The workspace ID.
+     * @param args.platform - The platform identifier (e.g., 'mobile', 'desktop', 'api').
+     *
+     * @example
+     * ```typescript
+     * await api.users.heartbeat({ workspaceId: 123, platform: 'api' })
+     * ```
+     */
     heartbeat(args: {
         workspaceId: number;
         platform: string;
     }): Promise<void>;
-    /** Resets the user's presence for a workspace. */
+    /**
+     * Resets the user's presence for a workspace (marks the user as inactive).
+     *
+     * @param workspaceId - The workspace ID.
+     */
     resetPresence(workspaceId: number): Promise<void>;
-    /** Checks whether an email address is registered (and verified). */
+    /**
+     * Checks whether an email address is registered (and verified).
+     *
+     * @param email - The email to check.
+     * @returns Object indicating whether the email exists and is verified.
+     */
     checkEmail(email: string): Promise<EmailExistsResponse>;
     /**
      * Returns the current per-channel mail unsubscribe settings for the
      * caller's primary email.
+     *
+     * @returns Object mapping email-type keys to their opt-out flag.
      */
     getUnsubscribeSettings(): Promise<Record<string, boolean>>;
-    /** Toggles per-email-type opt-out settings. */
+    /**
+     * Toggles per-email-type opt-out settings.
+     *
+     * @param settings - Object mapping email-type keys to their opt-out flag.
+     * @returns Status object with `"ok"` status.
+     */
     updateUnsubscribeSettings(settings: Record<string, boolean>): Promise<{
         status: string;
     }>;