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

package/dist/cjs/clients/workspace-users-client.js

@@ -9,7 +9,20 @@ const base_client_1 = require("./base-client");
  * rejects non-empty `name` and `channelIds` — set neither.
  */
 class WorkspaceUsersClient extends base_client_1.BaseClient {
-    /** Returns workspace user objects for the given workspace id. */
+    /**
+     * Returns a list of workspace user objects for the given workspace id.
+     *
+     * @param args - The arguments for getting workspace users.
+     * @param args.workspaceId - The workspace ID.
+     * @param args.archived - Optional flag to filter archived users.
+     * @returns An array of workspace user objects.
+     *
+     * @example
+     * ```typescript
+     * const users = await api.workspaceUsers.getWorkspaceUsers({ workspaceId: 123 })
+     * users.forEach(u => console.log(u.fullName, u.userType))
+     * ```
+     */
     getWorkspaceUsers(args) {
         return (0, http_client_1.request)({
             httpMethod: 'GET',
@@ -20,7 +33,12 @@ class WorkspaceUsersClient extends base_client_1.BaseClient {
             customFetch: this.customFetch,
         }).then((response) => response.data.map((user) => entities_1.WorkspaceUserSchema.parse(user)));
     }
-    /** Returns workspace user IDs for the given workspace id. */
+    /**
+     * Returns a list of workspace user IDs for the given workspace id.
+     *
+     * @param workspaceId - The workspace ID.
+     * @returns An array of user IDs.
+     */
     getWorkspaceUserIds(workspaceId) {
         return (0, http_client_1.request)({
             httpMethod: 'GET',
@@ -31,7 +49,20 @@ class WorkspaceUsersClient extends base_client_1.BaseClient {
             customFetch: this.customFetch,
         }).then((response) => response.data);
     }
-    /** Gets a user by id. */
+    /**
+     * Gets a user by id.
+     *
+     * @param args - The arguments for getting a user by ID.
+     * @param args.workspaceId - The workspace ID.
+     * @param args.userId - The user's ID.
+     * @returns The workspace user object.
+     *
+     * @example
+     * ```typescript
+     * const user = await api.workspaceUsers.getUserById({ workspaceId: 123, userId: 456 })
+     * console.log(user.fullName, user.email)
+     * ```
+     */
     getUserById(args) {
         return (0, http_client_1.request)({
             httpMethod: 'GET',
@@ -42,7 +73,22 @@ class WorkspaceUsersClient extends base_client_1.BaseClient {
             customFetch: this.customFetch,
         }).then((response) => entities_1.WorkspaceUserSchema.parse(response.data));
     }
-    /** Gets a user by email. */
+    /**
+     * Gets a user by email.
+     *
+     * @param args - The arguments for getting a user by email.
+     * @param args.workspaceId - The workspace ID.
+     * @param args.email - The user's email.
+     * @returns The workspace user object.
+     *
+     * @example
+     * ```typescript
+     * const user = await api.workspaceUsers.getUserByEmail({
+     *   workspaceId: 123,
+     *   email: 'user@example.com',
+     * })
+     * ```
+     */
     getUserByEmail(args) {
         return (0, http_client_1.request)({
             httpMethod: 'GET',
@@ -53,7 +99,14 @@ class WorkspaceUsersClient extends base_client_1.BaseClient {
             customFetch: this.customFetch,
         }).then((response) => entities_1.WorkspaceUserSchema.parse(response.data));
     }
-    /** Gets the user's info in the context of the workspace. */
+    /**
+     * Gets the user's info in the context of the workspace.
+     *
+     * @param args - The arguments for getting user info.
+     * @param args.workspaceId - The workspace ID.
+     * @param args.userId - The user's ID.
+     * @returns Information about the user in the workspace context.
+     */
     getUserInfo(args) {
         return (0, http_client_1.request)({
             httpMethod: 'GET',
@@ -64,7 +117,23 @@ class WorkspaceUsersClient extends base_client_1.BaseClient {
             customFetch: this.customFetch,
         }).then((response) => response.data);
     }
-    /** Gets the user's local time (e.g., "2017-05-10 07:55:40"). */
+    /**
+     * Gets the user's local time (e.g., "2017-05-10 07:55:40").
+     *
+     * @param args - The arguments for getting user local time.
+     * @param args.workspaceId - The workspace ID.
+     * @param args.userId - The user's ID.
+     * @returns The user's local time as a string.
+     *
+     * @example
+     * ```typescript
+     * const localTime = await api.workspaceUsers.getUserLocalTime({
+     *   workspaceId: 123,
+     *   userId: 456,
+     * })
+     * console.log('User local time:', localTime)
+     * ```
+     */
     getUserLocalTime(args) {
         return (0, http_client_1.request)({
             httpMethod: 'GET',
@@ -75,7 +144,15 @@ class WorkspaceUsersClient extends base_client_1.BaseClient {
             customFetch: this.customFetch,
         }).then((response) => response.data);
     }
-    /** Adds a person to a workspace. */
+    /**
+     * Adds a person to a workspace.
+     *
+     * @param args - The arguments for adding a user.
+     * @param args.workspaceId - The workspace ID.
+     * @param args.email - The user's email.
+     * @param args.userType - Optional user type (USER, GUEST, or ADMIN).
+     * @returns The created workspace user object.
+     */
     addUser(args) {
         return (0, http_client_1.request)({
             httpMethod: 'POST',
@@ -90,7 +167,16 @@ class WorkspaceUsersClient extends base_client_1.BaseClient {
             customFetch: this.customFetch,
         }).then((response) => entities_1.WorkspaceUserSchema.parse(response.data));
     }
-    /** Updates a person in a workspace. */
+    /**
+     * Updates a person in a workspace.
+     *
+     * @param args - The arguments for updating a user.
+     * @param args.workspaceId - The workspace ID.
+     * @param args.userType - The user type (USER, GUEST, or ADMIN).
+     * @param args.email - Optional email of the user to update.
+     * @param args.userId - Optional user ID to update (use either email or userId).
+     * @returns The updated workspace user object.
+     */
     updateUser(args) {
         return (0, http_client_1.request)({
             httpMethod: 'POST',
@@ -106,7 +192,14 @@ class WorkspaceUsersClient extends base_client_1.BaseClient {
             customFetch: this.customFetch,
         }).then((response) => entities_1.WorkspaceUserSchema.parse(response.data));
     }
-    /** Removes a person from a workspace. */
+    /**
+     * Removes a person from a workspace.
+     *
+     * @param args - The arguments for removing a user.
+     * @param args.workspaceId - The workspace ID.
+     * @param args.email - Optional email of the user to remove.
+     * @param args.userId - Optional user ID to remove (use either email or userId).
+     */
     removeUser(args) {
         return (0, http_client_1.request)({
             httpMethod: 'POST',
@@ -121,7 +214,14 @@ class WorkspaceUsersClient extends base_client_1.BaseClient {
             customFetch: this.customFetch,
         }).then(() => undefined);
     }
-    /** Sends a new workspace invitation to the selected user. */
+    /**
+     * Sends a new workspace invitation to the selected user.
+     *
+     * @param args - The arguments for resending an invite.
+     * @param args.workspaceId - The workspace ID.
+     * @param args.email - The user's email.
+     * @param args.userId - Optional user ID.
+     */
     resendInvite(args) {
         return (0, http_client_1.request)({
             httpMethod: 'POST',

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

@@ -12,7 +12,25 @@ exports.ChannelListSchema = zod_1.z.array(entities_1.ChannelSchema);
  * currently rejects any `color` other than `1` on add/update.
  */
 class WorkspacesClient extends base_client_1.BaseClient {
-    /** Gets all the user's workspaces. */
+    constructor() {
+        super(...arguments);
+        this.linkBaseUrl = this.getLinkBaseUrl();
+        // Reuse the shared singleton when no custom base is configured.
+        this.channelListSchema = this.linkBaseUrl
+            ? zod_1.z.array((0, entities_1.createChannelSchema)(this.linkBaseUrl))
+            : exports.ChannelListSchema;
+    }
+    /**
+     * Gets all the user's workspaces.
+     *
+     * @returns An array of all workspaces the user belongs to.
+     *
+     * @example
+     * ```typescript
+     * const workspaces = await api.workspaces.getWorkspaces()
+     * workspaces.forEach(ws => console.log(ws.name))
+     * ```
+     */
     getWorkspaces() {
         return (0, http_client_1.request)({
             httpMethod: 'GET',
@@ -23,7 +41,18 @@ class WorkspacesClient extends base_client_1.BaseClient {
             customFetch: this.customFetch,
         }).then((response) => response.data.map((workspace) => entities_1.WorkspaceSchema.parse(workspace)));
     }
-    /** Gets a single workspace object by id. */
+    /**
+     * Gets a single workspace object by id.
+     *
+     * @param id - The workspace ID.
+     * @returns The workspace object.
+     *
+     * @example
+     * ```typescript
+     * const workspace = await api.workspaces.getWorkspace(123)
+     * console.log(workspace.name)
+     * ```
+     */
     getWorkspace(id) {
         return (0, http_client_1.request)({
             httpMethod: 'GET',
@@ -34,7 +63,17 @@ class WorkspacesClient extends base_client_1.BaseClient {
             customFetch: this.customFetch,
         }).then((response) => entities_1.WorkspaceSchema.parse(response.data));
     }
-    /** Gets the user's default workspace. */
+    /**
+     * Gets the user's default workspace.
+     *
+     * @returns The default workspace object.
+     *
+     * @example
+     * ```typescript
+     * const workspace = await api.workspaces.getDefaultWorkspace()
+     * console.log(workspace.name)
+     * ```
+     */
     getDefaultWorkspace() {
         return (0, http_client_1.request)({
             httpMethod: 'GET',
@@ -45,7 +84,18 @@ class WorkspacesClient extends base_client_1.BaseClient {
             customFetch: this.customFetch,
         }).then((response) => entities_1.WorkspaceSchema.parse(response.data));
     }
-    /** Creates a new workspace. */
+    /**
+     * Creates a new workspace.
+     *
+     * @param name - The name of the new workspace.
+     * @returns The created workspace object.
+     *
+     * @example
+     * ```typescript
+     * const workspace = await api.workspaces.createWorkspace('My Team')
+     * console.log('Created:', workspace.name)
+     * ```
+     */
     createWorkspace(name) {
         return (0, http_client_1.request)({
             httpMethod: 'POST',
@@ -56,7 +106,18 @@ class WorkspacesClient extends base_client_1.BaseClient {
             customFetch: this.customFetch,
         }).then((response) => entities_1.WorkspaceSchema.parse(response.data));
     }
-    /** Updates an existing workspace. */
+    /**
+     * Updates an existing workspace.
+     *
+     * @param id - The workspace ID.
+     * @param name - The new name for the workspace.
+     * @returns The updated workspace object.
+     *
+     * @example
+     * ```typescript
+     * const workspace = await api.workspaces.updateWorkspace(123, 'New Team Name')
+     * ```
+     */
     updateWorkspace(id, name) {
         return (0, http_client_1.request)({
             httpMethod: 'POST',
@@ -67,7 +128,16 @@ class WorkspacesClient extends base_client_1.BaseClient {
             customFetch: this.customFetch,
         }).then((response) => entities_1.WorkspaceSchema.parse(response.data));
     }
-    /** Removes a workspace and all its data (not recoverable). */
+    /**
+     * Removes a workspace and all its data (not recoverable).
+     *
+     * @param id - The workspace ID.
+     *
+     * @example
+     * ```typescript
+     * await api.workspaces.removeWorkspace(123)
+     * ```
+     */
     removeWorkspace(id) {
         return (0, http_client_1.request)({
             httpMethod: 'POST',
@@ -78,7 +148,18 @@ class WorkspacesClient extends base_client_1.BaseClient {
             customFetch: this.customFetch,
         }).then(() => undefined);
     }
-    /** Gets the public channels of a workspace. */
+    /**
+     * Gets the public channels of a workspace.
+     *
+     * @param id - The workspace ID.
+     * @returns An array of public channel objects.
+     *
+     * @example
+     * ```typescript
+     * const channels = await api.workspaces.getPublicChannels(123)
+     * channels.forEach(ch => console.log(ch.name))
+     * ```
+     */
     getPublicChannels(id) {
         return (0, http_client_1.request)({
             httpMethod: 'GET',
@@ -87,7 +168,7 @@ class WorkspacesClient extends base_client_1.BaseClient {
             apiToken: this.apiToken,
             payload: { id },
             customFetch: this.customFetch,
-        }).then((response) => exports.ChannelListSchema.parse(response.data));
+        }).then((response) => this.channelListSchema.parse(response.data));
     }
 }
 exports.WorkspacesClient = WorkspacesClient;

package/dist/cjs/comms-api.js

@@ -36,6 +36,7 @@ class CommsApi {
         const clientConfig = {
             apiToken: authToken,
             baseUrl: options?.baseUrl,
+            version: options?.version,
             customFetch: options?.customFetch,
         };
         this.users = new users_client_1.UsersClient(clientConfig);

package/dist/cjs/consts/endpoints.js

@@ -2,16 +2,21 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 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';
-const API_VERSION = 'v1';
 /**
  * Gets the base URI for Comms API requests.
  *
+ * Preserves any path component on `domainBase` so callers can route through
+ * a proxy (e.g. `https://proxy.example.com/comms` → `.../comms/api/v1/`).
+ *
+ * @param version - API version. Defaults to 'v1'.
  * @param domainBase - Custom domain base URL. Defaults to Comms' API domain.
  * @returns Complete base URI with trailing slash (e.g., 'https://comms.todoist.com/api/v1/')
  */
-function getCommsBaseUri(domainBase = BASE_URI) {
-    return new URL(`/api/${API_VERSION}/`, domainBase).toString();
+function getCommsBaseUri(version = api_version_1.DEFAULT_API_VERSION, domainBase = BASE_URI) {
+    const base = domainBase.endsWith('/') ? domainBase : `${domainBase}/`;
+    return new URL(`api/${version}/`, base).toString();
 }
 exports.ENDPOINT_USERS = 'users';
 exports.ENDPOINT_WORKSPACES = 'workspaces';

package/dist/cjs/testUtils/test-defaults.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.mockWorkspaceUser = exports.mockComment = exports.mockConversation = exports.mockGroup = exports.mockThread = exports.mockChannel = exports.mockWorkspace = exports.mockUser = exports.TEST_GROUP_ID = exports.TEST_MESSAGE_ID = exports.TEST_CONVERSATION_ID = exports.TEST_COMMENT_ID = exports.TEST_THREAD_ID = exports.TEST_CHANNEL_ID = exports.TEST_API_TOKEN = void 0;
+exports.mockWorkspaceUser = exports.mockComment = exports.mockConversation = exports.mockGroup = exports.mockThread = exports.mockChannel = exports.mockWorkspace = exports.mockUser = exports.TEST_GROUP_ID = exports.TEST_MESSAGE_ID = exports.TEST_CONVERSATION_ID = exports.TEST_COMMENT_ID = exports.TEST_THREAD_ID = exports.TEST_CHANNEL_ID = exports.TEST_API_BASE_URL = exports.TEST_API_TOKEN = void 0;
+const endpoints_1 = require("../consts/endpoints");
 exports.TEST_API_TOKEN = 'test-api-token';
+exports.TEST_API_BASE_URL = (0, endpoints_1.getCommsBaseUri)().replace(/\/$/, '');
 // Canonical test IDs — shaped so they pass SDK-side validation.
 exports.TEST_CHANNEL_ID = '7YpL3oZ4kZ9vP7Q1tR2sX3y';
 exports.TEST_THREAD_ID = '7YpL3oZ4kZ9vP7Q1tR2sX3z';

package/dist/cjs/types/api-version.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_API_VERSION = exports.API_VERSIONS = void 0;
+/**
+ * Supported Comms API versions
+ */
+exports.API_VERSIONS = ['v1'];
+exports.DEFAULT_API_VERSION = 'v1';