@doist/comms-sdk 3.3.1 → 3.4.0

package/dist/esm/clients/users-client.js

@@ -161,6 +161,42 @@ export class UsersClient extends BaseClient {
     update(args) {
         return this.post(`${ENDPOINT_USERS}/update`, args, UserSchema);
     }
+    /**
+     * Sets the shared status of the session user, replacing any current one.
+     * The status belongs to the Todoist account, so it is shared with Todoist.
+     * Requires the `user:write` scope.
+     *
+     * @param args - The status to set.
+     * @param args.message - 1 to 80 characters once trimmed.
+     * @param args.emoji - Optional emoji.
+     * @param args.activeUntil - Optional expiry in the future (`Date` or ISO 8601 string).
+     * @param args.effects - Optional effects, e.g. `{ pauseNotifications: {} }` to hold back
+     *   Comms notifications while the status is active.
+     * @returns The updated user object.
+     *
+     * @example
+     * ```typescript
+     * await api.users.setStatus({
+     *   message: 'Deep work',
+     *   emoji: '🎯',
+     *   activeUntil: new Date(Date.now() + 2 * 60 * 60 * 1000),
+     *   effects: { pauseNotifications: {} },
+     * })
+     * ```
+     */
+    setStatus(args) {
+        const { activeUntil, ...rest } = args;
+        const payload = activeUntil instanceof Date ? { ...rest, activeUntil: activeUntil.toISOString() } : args;
+        return this.post(`${ENDPOINT_USERS}/set_status`, payload, UserSchema);
+    }
+    /**
+     * Clears the session user's shared status. Requires the `user:write` scope.
+     *
+     * @returns The updated user object.
+     */
+    clearStatus() {
+        return this.post(`${ENDPOINT_USERS}/clear_status`, undefined, UserSchema);
+    }
     /**
      * Updates the user's password.
      *

package/dist/esm/types/entities.js

@@ -49,6 +49,19 @@ export const AttachmentSchema = z.object(attachmentShape).loose();
 // this strips unknown keys so caller typos / off-spec fields are dropped instead
 // of being forwarded on the wire. Use this for `*Args` request schemas.
 export const RequestAttachmentSchema = z.object(attachmentShape);
+// Shared user status. It lives on the Todoist account, so Comms, Todoist and
+// automations all see the same one. `activeUntil` is an RFC 3339 string, and an
+// expired status is returned as `null` rather than as an expired object.
+export const UserStatusSchema = z.object({
+    message: z.string(),
+    emoji: z.string().nullable().optional(),
+    activeUntil: z.string().nullable().optional(),
+    effects: z
+        .object({
+        pauseNotifications: z.object({ scope: z.object({ mode: z.string() }) }).optional(),
+    })
+        .optional(),
+});
 // Fields shared by `User` and `WorkspaceUser`. Profile fields
 // (`fullName`, `imageId`, avatar URLs) are sourced from Todoist-ID.
 export const BaseUserSchema = z.object({
@@ -70,6 +83,7 @@ export const BaseUserSchema = z.object({
         .optional(),
     restricted: z.boolean().nullable().optional(),
     setupPending: z.boolean().nullable().optional(),
+    status: UserStatusSchema.nullable().optional(),
 });
 // User entity from API.
 export const UserSchema = BaseUserSchema.extend({

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

@@ -1,5 +1,5 @@
 import { type User } from '../types/entities.js';
-import type { UpdateUserArgs } from '../types/requests.js';
+import type { SetStatusArgs, UpdateUserArgs } from '../types/requests.js';
 import { BaseClient } from './base-client.js';
 type EmailExistsResponse = {
     exists: boolean;
@@ -159,6 +159,36 @@ export declare class UsersClient extends BaseClient {
      * ```
      */
     update(args: UpdateUserArgs): Promise<User>;
+    /**
+     * Sets the shared status of the session user, replacing any current one.
+     * The status belongs to the Todoist account, so it is shared with Todoist.
+     * Requires the `user:write` scope.
+     *
+     * @param args - The status to set.
+     * @param args.message - 1 to 80 characters once trimmed.
+     * @param args.emoji - Optional emoji.
+     * @param args.activeUntil - Optional expiry in the future (`Date` or ISO 8601 string).
+     * @param args.effects - Optional effects, e.g. `{ pauseNotifications: {} }` to hold back
+     *   Comms notifications while the status is active.
+     * @returns The updated user object.
+     *
+     * @example
+     * ```typescript
+     * await api.users.setStatus({
+     *   message: 'Deep work',
+     *   emoji: '🎯',
+     *   activeUntil: new Date(Date.now() + 2 * 60 * 60 * 1000),
+     *   effects: { pauseNotifications: {} },
+     * })
+     * ```
+     */
+    setStatus(args: SetStatusArgs): Promise<User>;
+    /**
+     * Clears the session user's shared status. Requires the `user:write` scope.
+     *
+     * @returns The updated user object.
+     */
+    clearStatus(): Promise<User>;
     /**
      * Updates the user's password.
      *

package/dist/types/types/entities.d.ts

@@ -54,6 +54,19 @@ export declare const RequestAttachmentSchema: z.ZodObject<{
     videoAutoPlay: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
 }, z.core.$strip>;
 export type RequestAttachment = z.infer<typeof RequestAttachmentSchema>;
+export declare const UserStatusSchema: z.ZodObject<{
+    message: z.ZodString;
+    emoji: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    activeUntil: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    effects: z.ZodOptional<z.ZodObject<{
+        pauseNotifications: z.ZodOptional<z.ZodObject<{
+            scope: z.ZodObject<{
+                mode: z.ZodString;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type UserStatus = z.infer<typeof UserStatusSchema>;
 export declare const BaseUserSchema: z.ZodObject<{
     id: z.ZodNumber;
     fullName: z.ZodString;
@@ -70,6 +83,18 @@ export declare const BaseUserSchema: z.ZodObject<{
     }, z.core.$strip>>>;
     restricted: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
     setupPending: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    status: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        message: z.ZodString;
+        emoji: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        activeUntil: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        effects: z.ZodOptional<z.ZodObject<{
+            pauseNotifications: z.ZodOptional<z.ZodObject<{
+                scope: z.ZodObject<{
+                    mode: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export declare const UserSchema: z.ZodObject<{
     id: z.ZodNumber;
@@ -87,6 +112,18 @@ export declare const UserSchema: z.ZodObject<{
     }, z.core.$strip>>>;
     restricted: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
     setupPending: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    status: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        message: z.ZodString;
+        emoji: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        activeUntil: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        effects: z.ZodOptional<z.ZodObject<{
+            pauseNotifications: z.ZodOptional<z.ZodObject<{
+                scope: z.ZodObject<{
+                    mode: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
     email: z.ZodEmail;
     clientId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     cometChannel: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -1591,6 +1628,18 @@ export declare const WorkspaceUserSchema: z.ZodObject<{
     }, z.core.$strip>>>;
     restricted: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
     setupPending: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    status: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        message: z.ZodString;
+        emoji: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        activeUntil: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        effects: z.ZodOptional<z.ZodObject<{
+            pauseNotifications: z.ZodOptional<z.ZodObject<{
+                scope: z.ZodObject<{
+                    mode: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
     email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     userType: z.ZodEnum<{
         USER: "USER";
@@ -1604,6 +1653,18 @@ export declare const WorkspaceUserSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type WorkspaceUser = z.infer<typeof WorkspaceUserSchema>;
 export declare const RestrictedWorkspaceUserSchema: z.ZodObject<{
+    status: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        message: z.ZodString;
+        emoji: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        activeUntil: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        effects: z.ZodOptional<z.ZodObject<{
+            pauseNotifications: z.ZodOptional<z.ZodObject<{
+                scope: z.ZodObject<{
+                    mode: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
     id: z.ZodNumber;
     fullName: z.ZodString;
     shortName: z.ZodString;
@@ -1637,6 +1698,18 @@ export declare const VisibleWorkspaceUserSchema: z.ZodUnion<readonly [z.ZodObjec
     }, z.core.$strip>>>;
     restricted: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
     setupPending: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    status: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        message: z.ZodString;
+        emoji: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        activeUntil: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        effects: z.ZodOptional<z.ZodObject<{
+            pauseNotifications: z.ZodOptional<z.ZodObject<{
+                scope: z.ZodObject<{
+                    mode: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
     email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     userType: z.ZodEnum<{
         USER: "USER";
@@ -1648,6 +1721,18 @@ export declare const VisibleWorkspaceUserSchema: z.ZodUnion<readonly [z.ZodObjec
     timeFormat: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     version: z.ZodNumber;
 }, z.core.$strip>, z.ZodObject<{
+    status: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        message: z.ZodString;
+        emoji: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        activeUntil: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        effects: z.ZodOptional<z.ZodObject<{
+            pauseNotifications: z.ZodOptional<z.ZodObject<{
+                scope: z.ZodObject<{
+                    mode: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
     id: z.ZodNumber;
     fullName: z.ZodString;
     shortName: z.ZodString;

package/dist/types/types/requests.d.ts

@@ -185,6 +185,21 @@ export type UpdateUserArgs = {
     /** Theme ID (0-12). String aliases like `'dark'` are also accepted. */
     theme?: number | string;
 };
+export type SetStatusArgs = {
+    /** 1 to 80 characters once trimmed. */
+    message: string;
+    emoji?: string | null;
+    /** When the status ends. Must be in the future. A `Date` is sent as an ISO 8601 string. */
+    activeUntil?: Date | string | null;
+    effects?: {
+        /** Holds back Comms notifications while the status is active. They are not sent later. */
+        pauseNotifications?: {
+            scope?: {
+                mode: 'all';
+            };
+        };
+    };
+};
 type SearchArgsCommon = {
     workspaceId: number;
     channelIds?: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@doist/comms-sdk",
-    "version": "3.3.1",
+    "version": "3.4.0",
     "description": "A TypeScript wrapper for the Comms REST API.",
     "author": "Doist developers",
     "homepage": "https://doist.github.io/comms-sdk-typescript/",