@doist/comms-sdk 0.5.1 → 0.6.0

package/README.md

@@ -121,6 +121,31 @@ const refreshed = await refreshAuthToken({
 const api = new CommsApi(refreshed.accessToken)
 ```
 
+### REST hooks
+
+REST hooks require a Todoist OAuth access token with Todoist Comms audience. Subscribe
+with an HTTPS target URL up to 150 characters and one of the exported
+`HOOK_EVENTS`; the backend will POST webhook payloads to that URL when
+matching events happen:
+
+```typescript
+import { CommsApi, HOOK_EVENTS } from '@doist/comms-sdk'
+
+const api = new CommsApi('TODOIST_OAUTH_ACCESS_TOKEN')
+
+const subscription = await api.hooks.subscribe({
+    targetUrl: 'https://example.com/comms-hook',
+    event: 'thread_added',
+    workspaceId: 1,
+})
+
+console.log(subscription.id, HOOK_EVENTS)
+
+await api.hooks.unsubscribe({
+    targetUrl: 'https://example.com/comms-hook',
+})
+```
+
 ### Short-lived processes (CLIs, scripts)
 
 On Node, the SDK keeps a connection pool alive across requests so HTTP/2

package/dist/cjs/clients/groups-client.js

@@ -106,7 +106,11 @@ class GroupsClient extends base_client_1.BaseClient {
      * @param args.userId - The user ID to add.
      */
     addUser(args) {
-        return this.simple('POST', 'add_user', { ...args }, entities_1.StatusOkSchema);
+        // The backend only exposes the plural `add_users` endpoint (routed via
+        // Todoist); there is no `add_user`. Delegate to `addUsers` so the wire
+        // contract lives in one place.
+        const { userId, ...rest } = args;
+        return this.addUsers({ ...rest, userIds: [userId] });
     }
     /**
      * Adds multiple users to a group.
@@ -137,7 +141,11 @@ class GroupsClient extends base_client_1.BaseClient {
      * @param args.userId - The user ID to remove.
      */
     removeUser(args) {
-        return this.simple('POST', 'remove_user', { ...args }, entities_1.StatusOkSchema);
+        // The backend only exposes the plural `remove_users` endpoint (routed
+        // via Todoist); there is no `remove_user`. Delegate to `removeUsers` so
+        // the wire contract lives in one place.
+        const { userId, ...rest } = args;
+        return this.removeUsers({ ...rest, userIds: [userId] });
     }
     /**
      * Removes multiple users from a group.

package/dist/cjs/clients/hooks-client.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HooksClient = void 0;
+const endpoints_1 = require("../consts/endpoints");
+const http_client_1 = require("../transport/http-client");
+const entities_1 = require("../types/entities");
+const base_client_1 = require("./base-client");
+/**
+ * Client for `/api/v1/hooks/`. REST hooks require Todoist OAuth bearer tokens
+ * that include Comms audience; session tokens are rejected by the backend.
+ */
+class HooksClient extends base_client_1.BaseClient {
+    /**
+     * Subscribes the current OAuth app to a REST hook event.
+     *
+     * @param args - The hook subscription parameters.
+     * @param args.targetUrl - HTTPS endpoint, up to 150 characters, that will receive webhook POSTs.
+     * @param args.event - Event name to subscribe to.
+     * @param args.workspaceId - Optional workspace filter.
+     * @param args.channelId - Optional channel filter.
+     * @param args.threadId - Optional thread filter.
+     * @param args.conversationId - Optional conversation filter for message events.
+     * @returns The `{ status: 'ok', id }` response for the subscription.
+     */
+    subscribe(args) {
+        return (0, http_client_1.request)({
+            httpMethod: 'POST',
+            baseUri: this.getBaseUri(),
+            relativePath: `${endpoints_1.ENDPOINT_HOOKS}/subscribe`,
+            apiToken: this.apiToken,
+            payload: args,
+            customFetch: this.customFetch,
+        }).then((response) => entities_1.HookSubscribeResponseSchema.parse(response.data));
+    }
+    /**
+     * Unsubscribes all hooks with the target URL for the current OAuth app.
+     *
+     * @param args - The hook unsubscribe parameters.
+     * @param args.targetUrl - Target URL to remove.
+     */
+    unsubscribe(args) {
+        return (0, http_client_1.request)({
+            httpMethod: 'POST',
+            baseUri: this.getBaseUri(),
+            relativePath: `${endpoints_1.ENDPOINT_HOOKS}/unsubscribe`,
+            apiToken: this.apiToken,
+            payload: args,
+            customFetch: this.customFetch,
+        }).then((response) => entities_1.StatusOkSchema.parse(response.data));
+    }
+}
+exports.HooksClient = HooksClient;

package/dist/cjs/clients/threads-client.js

@@ -181,7 +181,8 @@ class ThreadsClient extends base_client_1.BaseClient {
      * @param args.objIndex - The index of the last known read message.
      */
     markRead(args) {
-        return this.simple('POST', 'mark_read', { ...args }, entities_1.StatusOkSchema);
+        const { id, ...rest } = args;
+        return this.simple('POST', 'mark_read', { threadId: id, ...rest }, entities_1.StatusOkSchema);
     }
     /**
      * Marks a thread as unread.
@@ -191,7 +192,8 @@ class ThreadsClient extends base_client_1.BaseClient {
      * @param args.objIndex - The index of the last unread message. Use -1 to mark the whole thread as unread.
      */
     markUnread(args) {
-        return this.simple('POST', 'mark_unread', { ...args }, entities_1.StatusOkSchema);
+        const { id, ...rest } = args;
+        return this.simple('POST', 'mark_unread', { threadId: id, ...rest }, entities_1.StatusOkSchema);
     }
     /**
      * Marks a thread as unread for others. Useful to notify others about thread changes.

package/dist/cjs/comms-api.js

@@ -7,6 +7,7 @@ const comments_client_1 = require("./clients/comments-client");
 const conversation_messages_client_1 = require("./clients/conversation-messages-client");
 const conversations_client_1 = require("./clients/conversations-client");
 const groups_client_1 = require("./clients/groups-client");
+const hooks_client_1 = require("./clients/hooks-client");
 const inbox_client_1 = require("./clients/inbox-client");
 const reactions_client_1 = require("./clients/reactions-client");
 const search_client_1 = require("./clients/search-client");
@@ -53,6 +54,7 @@ class CommsApi {
         this.reactions = new reactions_client_1.ReactionsClient(clientConfig);
         this.search = new search_client_1.SearchClient(clientConfig);
         this.attachments = new attachments_client_1.AttachmentsClient(clientConfig);
+        this.hooks = new hooks_client_1.HooksClient(clientConfig);
     }
     /**
      * Drains the SDK's process-global connection pool. CLIs and scripts

package/dist/cjs/consts/endpoints.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ENDPOINT_ATTACHMENTS = exports.ENDPOINT_CONVERSATION_MESSAGES = exports.ENDPOINT_SEARCH = exports.ENDPOINT_REACTIONS = exports.ENDPOINT_INBOX = exports.ENDPOINT_NOTIFICATIONS = exports.ENDPOINT_COMMENTS = exports.ENDPOINT_CONVERSATIONS = exports.ENDPOINT_GROUPS = exports.ENDPOINT_THREADS = exports.ENDPOINT_CHANNELS = exports.ENDPOINT_WORKSPACES = exports.ENDPOINT_USERS = void 0;
+exports.ENDPOINT_HOOKS = exports.ENDPOINT_ATTACHMENTS = exports.ENDPOINT_CONVERSATION_MESSAGES = exports.ENDPOINT_SEARCH = exports.ENDPOINT_REACTIONS = exports.ENDPOINT_INBOX = exports.ENDPOINT_NOTIFICATIONS = exports.ENDPOINT_COMMENTS = exports.ENDPOINT_CONVERSATIONS = exports.ENDPOINT_GROUPS = exports.ENDPOINT_THREADS = exports.ENDPOINT_CHANNELS = exports.ENDPOINT_WORKSPACES = exports.ENDPOINT_USERS = void 0;
 exports.getCommsBaseUri = getCommsBaseUri;
 const api_version_1 = require("../types/api-version");
 const BASE_URI = 'https://comms.todoist.com';
@@ -31,3 +31,4 @@ exports.ENDPOINT_REACTIONS = 'reactions';
 exports.ENDPOINT_SEARCH = 'search';
 exports.ENDPOINT_CONVERSATION_MESSAGES = 'conversation_messages';
 exports.ENDPOINT_ATTACHMENTS = 'attachments';
+exports.ENDPOINT_HOOKS = 'hooks';

package/dist/cjs/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.closeDefaultDispatcher = exports.CommsApi = exports.WorkspacesClient = exports.WorkspaceUsersClient = exports.UsersClient = exports.ThreadsClient = exports.SearchClient = exports.ReactionsClient = exports.InboxClient = exports.GroupsClient = exports.ConversationsClient = exports.ConversationMessagesClient = exports.CommentsClient = exports.ChannelsClient = exports.AttachmentsClient = void 0;
+exports.closeDefaultDispatcher = exports.CommsApi = exports.WorkspacesClient = exports.WorkspaceUsersClient = exports.UsersClient = exports.ThreadsClient = exports.SearchClient = exports.ReactionsClient = exports.InboxClient = exports.HooksClient = exports.GroupsClient = exports.ConversationsClient = exports.ConversationMessagesClient = exports.CommentsClient = exports.ChannelsClient = exports.AttachmentsClient = void 0;
 __exportStar(require("./authentication"), exports);
 var attachments_client_1 = require("./clients/attachments-client");
 Object.defineProperty(exports, "AttachmentsClient", { enumerable: true, get: function () { return attachments_client_1.AttachmentsClient; } });
@@ -28,6 +28,8 @@ var conversations_client_1 = require("./clients/conversations-client");
 Object.defineProperty(exports, "ConversationsClient", { enumerable: true, get: function () { return conversations_client_1.ConversationsClient; } });
 var groups_client_1 = require("./clients/groups-client");
 Object.defineProperty(exports, "GroupsClient", { enumerable: true, get: function () { return groups_client_1.GroupsClient; } });
+var hooks_client_1 = require("./clients/hooks-client");
+Object.defineProperty(exports, "HooksClient", { enumerable: true, get: function () { return hooks_client_1.HooksClient; } });
 var inbox_client_1 = require("./clients/inbox-client");
 Object.defineProperty(exports, "InboxClient", { enumerable: true, get: function () { return inbox_client_1.InboxClient; } });
 var reactions_client_1 = require("./clients/reactions-client");

package/dist/cjs/types/entities.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SearchResultSchema = exports.SEARCH_RESULT_TYPES = exports.UnreadConversationSchema = exports.UnreadThreadSchema = exports.InboxThreadSchema = exports.ConversationMessageSchema = exports.ConversationMessageObjectSchema = exports.WorkspaceUserSchema = exports.CommentSchema = exports.CommentObjectSchema = exports.ConversationSchema = exports.ConversationObjectSchema = exports.GroupSchema = exports.ThreadSchema = exports.ThreadObjectSchema = exports.ChannelSchema = exports.ChannelObjectSchema = exports.WorkspaceSchema = exports.UserSchema = exports.BaseUserSchema = exports.RequestAttachmentSchema = exports.AttachmentSchema = exports.StatusOkSchema = exports.SystemMessageSchema = void 0;
+exports.SearchResultSchema = exports.SEARCH_RESULT_TYPES = exports.UnreadConversationSchema = exports.UnreadThreadSchema = exports.InboxThreadSchema = exports.ConversationMessageSchema = exports.ConversationMessageObjectSchema = exports.WorkspaceUserSchema = exports.CommentSchema = exports.CommentObjectSchema = exports.ConversationSchema = exports.ConversationObjectSchema = exports.GroupSchema = exports.ThreadSchema = exports.ThreadObjectSchema = exports.ChannelSchema = exports.ChannelObjectSchema = exports.WorkspaceSchema = exports.UserSchema = exports.BaseUserSchema = exports.RequestAttachmentSchema = exports.AttachmentSchema = exports.HookSubscribeResponseSchema = exports.StatusOkSchema = exports.SystemMessageSchema = void 0;
 exports.createChannelSchema = createChannelSchema;
 exports.createThreadSchema = createThreadSchema;
 exports.createConversationSchema = createConversationSchema;
@@ -27,6 +27,9 @@ exports.SystemMessageSchema = zod_1.z.union([zod_1.z.string(), zod_1.z.unknown()
  * mark-read / mark-all-read / mute / clear-unread / etc.
  */
 exports.StatusOkSchema = zod_1.z.object({ status: zod_1.z.literal('ok') });
+exports.HookSubscribeResponseSchema = exports.StatusOkSchema.extend({
+    id: zod_1.z.number().int(),
+});
 // Attachment entity from API. Mirrors the canonical backend shape produced
 // by `unify_attachments` / `validate_file_attachment_json`. Only
 // `attachmentId` and `urlType` are guaranteed; everything else depends on

package/dist/cjs/types/requests.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.THREAD_ACTIONS = exports.ARCHIVE_FILTER_VALUES = exports.GetOrCreateConversationArgsSchema = exports.GetConversationsArgsSchema = exports.GetCommentsArgsSchema = exports.GetThreadsArgsSchema = exports.GetChannelsArgsSchema = exports.CreateMessageArgsSchema = exports.CreateConversationArgsSchema = exports.UpdateCommentArgsSchema = exports.CreateCommentArgsSchema = exports.UpdateThreadArgsSchema = exports.CreateThreadArgsSchema = exports.UpdateChannelArgsSchema = exports.CreateChannelArgsSchema = void 0;
+exports.THREAD_ACTIONS = exports.UnsubscribeHookArgsSchema = exports.SubscribeHookArgsSchema = exports.SubscribeMessageHookArgsSchema = exports.SubscribeNonMessageHookArgsSchema = exports.SubscribeHookArgsBaseSchema = exports.HookTargetUrlSchema = exports.HookEventSchema = exports.MessageHookEventSchema = exports.NonMessageHookEventSchema = exports.HOOK_EVENTS = exports.MESSAGE_HOOK_EVENTS = exports.NON_MESSAGE_HOOK_EVENTS = exports.ARCHIVE_FILTER_VALUES = exports.GetOrCreateConversationArgsSchema = exports.GetConversationsArgsSchema = exports.GetCommentsArgsSchema = exports.GetThreadsArgsSchema = exports.GetChannelsArgsSchema = exports.CreateMessageArgsSchema = exports.CreateConversationArgsSchema = exports.UpdateCommentArgsSchema = exports.CreateCommentArgsSchema = exports.UpdateThreadArgsSchema = exports.CreateThreadArgsSchema = exports.UpdateChannelArgsSchema = exports.CreateChannelArgsSchema = void 0;
 const zod_1 = require("zod");
 const entities_1 = require("./entities");
 const enums_1 = require("./enums");
@@ -113,5 +113,67 @@ exports.GetOrCreateConversationArgsSchema = zod_1.z.object({
 });
 // Inbox
 exports.ARCHIVE_FILTER_VALUES = ['active', 'archived', 'all'];
+// Hooks
+exports.NON_MESSAGE_HOOK_EVENTS = [
+    'workspace_added',
+    'workspace_updated',
+    'workspace_deleted',
+    'workspace_user_added',
+    'workspace_user_updated',
+    'workspace_user_removed',
+    'channel_added',
+    'channel_updated',
+    'channel_deleted',
+    'channel_user_added',
+    'channel_user_removed',
+    'thread_added',
+    'thread_updated',
+    'thread_deleted',
+    'comment_added',
+    'comment_updated',
+    'comment_deleted',
+    'group_added',
+    'group_updated',
+    'group_deleted',
+    'group_user_added',
+    'group_user_removed',
+];
+exports.MESSAGE_HOOK_EVENTS = ['message_added', 'message_updated'];
+exports.HOOK_EVENTS = [...exports.NON_MESSAGE_HOOK_EVENTS, ...exports.MESSAGE_HOOK_EVENTS];
+exports.NonMessageHookEventSchema = zod_1.z.enum(exports.NON_MESSAGE_HOOK_EVENTS);
+exports.MessageHookEventSchema = zod_1.z.enum(exports.MESSAGE_HOOK_EVENTS);
+exports.HookEventSchema = zod_1.z.enum(exports.HOOK_EVENTS);
+exports.HookTargetUrlSchema = zod_1.z
+    .url()
+    .max(150)
+    .refine((value) => {
+    try {
+        return new URL(value).protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}, { message: 'URL must use HTTPS' });
+exports.SubscribeHookArgsBaseSchema = zod_1.z.object({
+    targetUrl: exports.HookTargetUrlSchema,
+    workspaceId: zod_1.z.number().nullable().optional(),
+    channelId: zod_1.z.string().nullable().optional(),
+    threadId: zod_1.z.string().nullable().optional(),
+});
+exports.SubscribeNonMessageHookArgsSchema = exports.SubscribeHookArgsBaseSchema.extend({
+    event: exports.NonMessageHookEventSchema,
+    conversationId: zod_1.z.never().optional(),
+});
+exports.SubscribeMessageHookArgsSchema = exports.SubscribeHookArgsBaseSchema.extend({
+    event: exports.MessageHookEventSchema,
+    conversationId: zod_1.z.string().nullable().optional(),
+});
+exports.SubscribeHookArgsSchema = zod_1.z.union([
+    exports.SubscribeNonMessageHookArgsSchema,
+    exports.SubscribeMessageHookArgsSchema,
+]);
+exports.UnsubscribeHookArgsSchema = zod_1.z.object({
+    targetUrl: exports.HookTargetUrlSchema,
+});
 // Threads
 exports.THREAD_ACTIONS = ['close', 'reopen'];

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

@@ -103,7 +103,11 @@ export class GroupsClient extends BaseClient {
      * @param args.userId - The user ID to add.
      */
     addUser(args) {
-        return this.simple('POST', 'add_user', { ...args }, StatusOkSchema);
+        // The backend only exposes the plural `add_users` endpoint (routed via
+        // Todoist); there is no `add_user`. Delegate to `addUsers` so the wire
+        // contract lives in one place.
+        const { userId, ...rest } = args;
+        return this.addUsers({ ...rest, userIds: [userId] });
     }
     /**
      * Adds multiple users to a group.
@@ -134,7 +138,11 @@ export class GroupsClient extends BaseClient {
      * @param args.userId - The user ID to remove.
      */
     removeUser(args) {
-        return this.simple('POST', 'remove_user', { ...args }, StatusOkSchema);
+        // The backend only exposes the plural `remove_users` endpoint (routed
+        // via Todoist); there is no `remove_user`. Delegate to `removeUsers` so
+        // the wire contract lives in one place.
+        const { userId, ...rest } = args;
+        return this.removeUsers({ ...rest, userIds: [userId] });
     }
     /**
      * Removes multiple users from a group.

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

@@ -0,0 +1,48 @@
+import { ENDPOINT_HOOKS } from '../consts/endpoints.js';
+import { request } from '../transport/http-client.js';
+import { HookSubscribeResponseSchema, StatusOkSchema, } from '../types/entities.js';
+import { BaseClient } from './base-client.js';
+/**
+ * Client for `/api/v1/hooks/`. REST hooks require Todoist OAuth bearer tokens
+ * that include Comms audience; session tokens are rejected by the backend.
+ */
+export class HooksClient extends BaseClient {
+    /**
+     * Subscribes the current OAuth app to a REST hook event.
+     *
+     * @param args - The hook subscription parameters.
+     * @param args.targetUrl - HTTPS endpoint, up to 150 characters, that will receive webhook POSTs.
+     * @param args.event - Event name to subscribe to.
+     * @param args.workspaceId - Optional workspace filter.
+     * @param args.channelId - Optional channel filter.
+     * @param args.threadId - Optional thread filter.
+     * @param args.conversationId - Optional conversation filter for message events.
+     * @returns The `{ status: 'ok', id }` response for the subscription.
+     */
+    subscribe(args) {
+        return request({
+            httpMethod: 'POST',
+            baseUri: this.getBaseUri(),
+            relativePath: `${ENDPOINT_HOOKS}/subscribe`,
+            apiToken: this.apiToken,
+            payload: args,
+            customFetch: this.customFetch,
+        }).then((response) => HookSubscribeResponseSchema.parse(response.data));
+    }
+    /**
+     * Unsubscribes all hooks with the target URL for the current OAuth app.
+     *
+     * @param args - The hook unsubscribe parameters.
+     * @param args.targetUrl - Target URL to remove.
+     */
+    unsubscribe(args) {
+        return request({
+            httpMethod: 'POST',
+            baseUri: this.getBaseUri(),
+            relativePath: `${ENDPOINT_HOOKS}/unsubscribe`,
+            apiToken: this.apiToken,
+            payload: args,
+            customFetch: this.customFetch,
+        }).then((response) => StatusOkSchema.parse(response.data));
+    }
+}

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

@@ -178,7 +178,8 @@ export class ThreadsClient extends BaseClient {
      * @param args.objIndex - The index of the last known read message.
      */
     markRead(args) {
-        return this.simple('POST', 'mark_read', { ...args }, StatusOkSchema);
+        const { id, ...rest } = args;
+        return this.simple('POST', 'mark_read', { threadId: id, ...rest }, StatusOkSchema);
     }
     /**
      * Marks a thread as unread.
@@ -188,7 +189,8 @@ export class ThreadsClient extends BaseClient {
      * @param args.objIndex - The index of the last unread message. Use -1 to mark the whole thread as unread.
      */
     markUnread(args) {
-        return this.simple('POST', 'mark_unread', { ...args }, StatusOkSchema);
+        const { id, ...rest } = args;
+        return this.simple('POST', 'mark_unread', { threadId: id, ...rest }, StatusOkSchema);
     }
     /**
      * Marks a thread as unread for others. Useful to notify others about thread changes.

package/dist/esm/comms-api.js

@@ -4,6 +4,7 @@ import { CommentsClient } from './clients/comments-client.js';
 import { ConversationMessagesClient } from './clients/conversation-messages-client.js';
 import { ConversationsClient } from './clients/conversations-client.js';
 import { GroupsClient } from './clients/groups-client.js';
+import { HooksClient } from './clients/hooks-client.js';
 import { InboxClient } from './clients/inbox-client.js';
 import { ReactionsClient } from './clients/reactions-client.js';
 import { SearchClient } from './clients/search-client.js';
@@ -50,6 +51,7 @@ export class CommsApi {
         this.reactions = new ReactionsClient(clientConfig);
         this.search = new SearchClient(clientConfig);
         this.attachments = new AttachmentsClient(clientConfig);
+        this.hooks = new HooksClient(clientConfig);
     }
     /**
      * Drains the SDK's process-global connection pool. CLIs and scripts

package/dist/esm/consts/endpoints.js

@@ -27,3 +27,4 @@ export const ENDPOINT_REACTIONS = 'reactions';
 export const ENDPOINT_SEARCH = 'search';
 export const ENDPOINT_CONVERSATION_MESSAGES = 'conversation_messages';
 export const ENDPOINT_ATTACHMENTS = 'attachments';
+export const ENDPOINT_HOOKS = 'hooks';

package/dist/esm/index.js

@@ -5,6 +5,7 @@ export { CommentsClient } from './clients/comments-client.js';
 export { ConversationMessagesClient } from './clients/conversation-messages-client.js';
 export { ConversationsClient } from './clients/conversations-client.js';
 export { GroupsClient } from './clients/groups-client.js';
+export { HooksClient } from './clients/hooks-client.js';
 export { InboxClient } from './clients/inbox-client.js';
 export { ReactionsClient } from './clients/reactions-client.js';
 export { SearchClient } from './clients/search-client.js';

package/dist/esm/types/entities.js

@@ -17,6 +17,9 @@ export const SystemMessageSchema = z.union([z.string(), z.unknown()]).nullable()
  * mark-read / mark-all-read / mute / clear-unread / etc.
  */
 export const StatusOkSchema = z.object({ status: z.literal('ok') });
+export const HookSubscribeResponseSchema = StatusOkSchema.extend({
+    id: z.number().int(),
+});
 // Attachment entity from API. Mirrors the canonical backend shape produced
 // by `unify_attachments` / `validate_file_attachment_json`. Only
 // `attachmentId` and `urlType` are guaranteed; everything else depends on

package/dist/esm/types/requests.js

@@ -110,5 +110,67 @@ export const GetOrCreateConversationArgsSchema = z.object({
 });
 // Inbox
 export const ARCHIVE_FILTER_VALUES = ['active', 'archived', 'all'];
+// Hooks
+export const NON_MESSAGE_HOOK_EVENTS = [
+    'workspace_added',
+    'workspace_updated',
+    'workspace_deleted',
+    'workspace_user_added',
+    'workspace_user_updated',
+    'workspace_user_removed',
+    'channel_added',
+    'channel_updated',
+    'channel_deleted',
+    'channel_user_added',
+    'channel_user_removed',
+    'thread_added',
+    'thread_updated',
+    'thread_deleted',
+    'comment_added',
+    'comment_updated',
+    'comment_deleted',
+    'group_added',
+    'group_updated',
+    'group_deleted',
+    'group_user_added',
+    'group_user_removed',
+];
+export const MESSAGE_HOOK_EVENTS = ['message_added', 'message_updated'];
+export const HOOK_EVENTS = [...NON_MESSAGE_HOOK_EVENTS, ...MESSAGE_HOOK_EVENTS];
+export const NonMessageHookEventSchema = z.enum(NON_MESSAGE_HOOK_EVENTS);
+export const MessageHookEventSchema = z.enum(MESSAGE_HOOK_EVENTS);
+export const HookEventSchema = z.enum(HOOK_EVENTS);
+export const HookTargetUrlSchema = z
+    .url()
+    .max(150)
+    .refine((value) => {
+    try {
+        return new URL(value).protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}, { message: 'URL must use HTTPS' });
+export const SubscribeHookArgsBaseSchema = z.object({
+    targetUrl: HookTargetUrlSchema,
+    workspaceId: z.number().nullable().optional(),
+    channelId: z.string().nullable().optional(),
+    threadId: z.string().nullable().optional(),
+});
+export const SubscribeNonMessageHookArgsSchema = SubscribeHookArgsBaseSchema.extend({
+    event: NonMessageHookEventSchema,
+    conversationId: z.never().optional(),
+});
+export const SubscribeMessageHookArgsSchema = SubscribeHookArgsBaseSchema.extend({
+    event: MessageHookEventSchema,
+    conversationId: z.string().nullable().optional(),
+});
+export const SubscribeHookArgsSchema = z.union([
+    SubscribeNonMessageHookArgsSchema,
+    SubscribeMessageHookArgsSchema,
+]);
+export const UnsubscribeHookArgsSchema = z.object({
+    targetUrl: HookTargetUrlSchema,
+});
 // Threads
 export const THREAD_ACTIONS = ['close', 'reopen'];

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

@@ -0,0 +1,29 @@
+import { type HookSubscribeResponse, type StatusOk } from '../types/entities.js';
+import type { SubscribeHookArgs, UnsubscribeHookArgs } from '../types/requests.js';
+import { BaseClient } from './base-client.js';
+/**
+ * Client for `/api/v1/hooks/`. REST hooks require Todoist OAuth bearer tokens
+ * that include Comms audience; session tokens are rejected by the backend.
+ */
+export declare class HooksClient extends BaseClient {
+    /**
+     * Subscribes the current OAuth app to a REST hook event.
+     *
+     * @param args - The hook subscription parameters.
+     * @param args.targetUrl - HTTPS endpoint, up to 150 characters, that will receive webhook POSTs.
+     * @param args.event - Event name to subscribe to.
+     * @param args.workspaceId - Optional workspace filter.
+     * @param args.channelId - Optional channel filter.
+     * @param args.threadId - Optional thread filter.
+     * @param args.conversationId - Optional conversation filter for message events.
+     * @returns The `{ status: 'ok', id }` response for the subscription.
+     */
+    subscribe(args: SubscribeHookArgs): Promise<HookSubscribeResponse>;
+    /**
+     * Unsubscribes all hooks with the target URL for the current OAuth app.
+     *
+     * @param args - The hook unsubscribe parameters.
+     * @param args.targetUrl - Target URL to remove.
+     */
+    unsubscribe(args: UnsubscribeHookArgs): Promise<StatusOk>;
+}

package/dist/types/comms-api.d.ts

@@ -4,6 +4,7 @@ import { CommentsClient } from './clients/comments-client.js';
 import { ConversationMessagesClient } from './clients/conversation-messages-client.js';
 import { ConversationsClient } from './clients/conversations-client.js';
 import { GroupsClient } from './clients/groups-client.js';
+import { HooksClient } from './clients/hooks-client.js';
 import { InboxClient } from './clients/inbox-client.js';
 import { ReactionsClient } from './clients/reactions-client.js';
 import { SearchClient } from './clients/search-client.js';
@@ -46,6 +47,7 @@ export declare class CommsApi {
     reactions: ReactionsClient;
     search: SearchClient;
     attachments: AttachmentsClient;
+    hooks: HooksClient;
     /**
      * Creates a new Comms API client.
      *

package/dist/types/consts/endpoints.d.ts

@@ -23,3 +23,4 @@ export declare const ENDPOINT_REACTIONS = "reactions";
 export declare const ENDPOINT_SEARCH = "search";
 export declare const ENDPOINT_CONVERSATION_MESSAGES = "conversation_messages";
 export declare const ENDPOINT_ATTACHMENTS = "attachments";
+export declare const ENDPOINT_HOOKS = "hooks";

package/dist/types/index.d.ts

@@ -5,6 +5,7 @@ export { CommentsClient } from './clients/comments-client.js';
 export { ConversationMessagesClient } from './clients/conversation-messages-client.js';
 export { ConversationsClient } from './clients/conversations-client.js';
 export { GroupsClient } from './clients/groups-client.js';
+export { HooksClient } from './clients/hooks-client.js';
 export { InboxClient } from './clients/inbox-client.js';
 export { ReactionsClient } from './clients/reactions-client.js';
 export { SearchClient } from './clients/search-client.js';

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

@@ -11,6 +11,11 @@ export declare const StatusOkSchema: z.ZodObject<{
     status: z.ZodLiteral<"ok">;
 }, z.core.$strip>;
 export type StatusOk = z.infer<typeof StatusOkSchema>;
+export declare const HookSubscribeResponseSchema: z.ZodObject<{
+    status: z.ZodLiteral<"ok">;
+    id: z.ZodNumber;
+}, z.core.$strip>;
+export type HookSubscribeResponse = z.infer<typeof HookSubscribeResponseSchema>;
 export declare const AttachmentSchema: z.ZodObject<{
     attachmentId: z.ZodString;
     urlType: z.ZodString;

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

@@ -264,6 +264,161 @@ export type GetReactionsArgs = {
     commentId?: string;
     messageId?: string;
 };
+export declare const NON_MESSAGE_HOOK_EVENTS: readonly ["workspace_added", "workspace_updated", "workspace_deleted", "workspace_user_added", "workspace_user_updated", "workspace_user_removed", "channel_added", "channel_updated", "channel_deleted", "channel_user_added", "channel_user_removed", "thread_added", "thread_updated", "thread_deleted", "comment_added", "comment_updated", "comment_deleted", "group_added", "group_updated", "group_deleted", "group_user_added", "group_user_removed"];
+export type NonMessageHookEvent = (typeof NON_MESSAGE_HOOK_EVENTS)[number];
+export declare const MESSAGE_HOOK_EVENTS: readonly ["message_added", "message_updated"];
+export type MessageHookEvent = (typeof MESSAGE_HOOK_EVENTS)[number];
+export declare const HOOK_EVENTS: readonly ["workspace_added", "workspace_updated", "workspace_deleted", "workspace_user_added", "workspace_user_updated", "workspace_user_removed", "channel_added", "channel_updated", "channel_deleted", "channel_user_added", "channel_user_removed", "thread_added", "thread_updated", "thread_deleted", "comment_added", "comment_updated", "comment_deleted", "group_added", "group_updated", "group_deleted", "group_user_added", "group_user_removed", "message_added", "message_updated"];
+export type HookEvent = (typeof HOOK_EVENTS)[number];
+export declare const NonMessageHookEventSchema: z.ZodEnum<{
+    workspace_added: "workspace_added";
+    workspace_updated: "workspace_updated";
+    workspace_deleted: "workspace_deleted";
+    workspace_user_added: "workspace_user_added";
+    workspace_user_updated: "workspace_user_updated";
+    workspace_user_removed: "workspace_user_removed";
+    channel_added: "channel_added";
+    channel_updated: "channel_updated";
+    channel_deleted: "channel_deleted";
+    channel_user_added: "channel_user_added";
+    channel_user_removed: "channel_user_removed";
+    thread_added: "thread_added";
+    thread_updated: "thread_updated";
+    thread_deleted: "thread_deleted";
+    comment_added: "comment_added";
+    comment_updated: "comment_updated";
+    comment_deleted: "comment_deleted";
+    group_added: "group_added";
+    group_updated: "group_updated";
+    group_deleted: "group_deleted";
+    group_user_added: "group_user_added";
+    group_user_removed: "group_user_removed";
+}>;
+export declare const MessageHookEventSchema: z.ZodEnum<{
+    message_added: "message_added";
+    message_updated: "message_updated";
+}>;
+export declare const HookEventSchema: z.ZodEnum<{
+    workspace_added: "workspace_added";
+    workspace_updated: "workspace_updated";
+    workspace_deleted: "workspace_deleted";
+    workspace_user_added: "workspace_user_added";
+    workspace_user_updated: "workspace_user_updated";
+    workspace_user_removed: "workspace_user_removed";
+    channel_added: "channel_added";
+    channel_updated: "channel_updated";
+    channel_deleted: "channel_deleted";
+    channel_user_added: "channel_user_added";
+    channel_user_removed: "channel_user_removed";
+    thread_added: "thread_added";
+    thread_updated: "thread_updated";
+    thread_deleted: "thread_deleted";
+    comment_added: "comment_added";
+    comment_updated: "comment_updated";
+    comment_deleted: "comment_deleted";
+    group_added: "group_added";
+    group_updated: "group_updated";
+    group_deleted: "group_deleted";
+    group_user_added: "group_user_added";
+    group_user_removed: "group_user_removed";
+    message_added: "message_added";
+    message_updated: "message_updated";
+}>;
+export declare const HookTargetUrlSchema: z.ZodURL;
+export declare const SubscribeHookArgsBaseSchema: z.ZodObject<{
+    targetUrl: z.ZodURL;
+    workspaceId: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    channelId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    threadId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export declare const SubscribeNonMessageHookArgsSchema: z.ZodObject<{
+    targetUrl: z.ZodURL;
+    workspaceId: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    channelId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    threadId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    event: z.ZodEnum<{
+        workspace_added: "workspace_added";
+        workspace_updated: "workspace_updated";
+        workspace_deleted: "workspace_deleted";
+        workspace_user_added: "workspace_user_added";
+        workspace_user_updated: "workspace_user_updated";
+        workspace_user_removed: "workspace_user_removed";
+        channel_added: "channel_added";
+        channel_updated: "channel_updated";
+        channel_deleted: "channel_deleted";
+        channel_user_added: "channel_user_added";
+        channel_user_removed: "channel_user_removed";
+        thread_added: "thread_added";
+        thread_updated: "thread_updated";
+        thread_deleted: "thread_deleted";
+        comment_added: "comment_added";
+        comment_updated: "comment_updated";
+        comment_deleted: "comment_deleted";
+        group_added: "group_added";
+        group_updated: "group_updated";
+        group_deleted: "group_deleted";
+        group_user_added: "group_user_added";
+        group_user_removed: "group_user_removed";
+    }>;
+    conversationId: z.ZodOptional<z.ZodNever>;
+}, z.core.$strip>;
+export declare const SubscribeMessageHookArgsSchema: z.ZodObject<{
+    targetUrl: z.ZodURL;
+    workspaceId: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    channelId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    threadId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    event: z.ZodEnum<{
+        message_added: "message_added";
+        message_updated: "message_updated";
+    }>;
+    conversationId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export declare const SubscribeHookArgsSchema: z.ZodUnion<readonly [z.ZodObject<{
+    targetUrl: z.ZodURL;
+    workspaceId: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    channelId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    threadId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    event: z.ZodEnum<{
+        workspace_added: "workspace_added";
+        workspace_updated: "workspace_updated";
+        workspace_deleted: "workspace_deleted";
+        workspace_user_added: "workspace_user_added";
+        workspace_user_updated: "workspace_user_updated";
+        workspace_user_removed: "workspace_user_removed";
+        channel_added: "channel_added";
+        channel_updated: "channel_updated";
+        channel_deleted: "channel_deleted";
+        channel_user_added: "channel_user_added";
+        channel_user_removed: "channel_user_removed";
+        thread_added: "thread_added";
+        thread_updated: "thread_updated";
+        thread_deleted: "thread_deleted";
+        comment_added: "comment_added";
+        comment_updated: "comment_updated";
+        comment_deleted: "comment_deleted";
+        group_added: "group_added";
+        group_updated: "group_updated";
+        group_deleted: "group_deleted";
+        group_user_added: "group_user_added";
+        group_user_removed: "group_user_removed";
+    }>;
+    conversationId: z.ZodOptional<z.ZodNever>;
+}, z.core.$strip>, z.ZodObject<{
+    targetUrl: z.ZodURL;
+    workspaceId: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    channelId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    threadId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    event: z.ZodEnum<{
+        message_added: "message_added";
+        message_updated: "message_updated";
+    }>;
+    conversationId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>]>;
+export type SubscribeHookArgs = z.infer<typeof SubscribeHookArgsSchema>;
+export declare const UnsubscribeHookArgsSchema: z.ZodObject<{
+    targetUrl: z.ZodURL;
+}, z.core.$strip>;
+export type UnsubscribeHookArgs = z.infer<typeof UnsubscribeHookArgsSchema>;
 export type AddChannelUserArgs = {
     id: string;
     userId: number;

package/package.json

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