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

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

@@ -7,38 +7,138 @@ import { BaseClient } from './base-client.js';
  * rejects non-empty `name` and `channelIds` — set neither.
  */
 export declare class WorkspaceUsersClient extends 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: GetWorkspaceUsersArgs): Promise<WorkspaceUser[]>;
-    /** 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: number): Promise<number[]>;
-    /** 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: GetUserByIdArgs): Promise<WorkspaceUser>;
-    /** 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: GetUserByEmailArgs): Promise<WorkspaceUser>;
-    /** 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: GetUserInfoArgs): Promise<Record<string, unknown>>;
-    /** 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: GetUserLocalTimeArgs): Promise<string>;
-    /** 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: {
         workspaceId: number;
         email: string;
         userType?: UserType;
     }): Promise<WorkspaceUser>;
-    /** 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: {
         workspaceId: number;
         userType: UserType;
         email?: string;
         userId?: number;
     }): Promise<WorkspaceUser>;
-    /** 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: {
         workspaceId: number;
         email?: string;
         userId?: number;
     }): Promise<void>;
-    /** 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: {
         workspaceId: number;
         email: string;

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

@@ -62,18 +62,91 @@ export declare const ChannelListSchema: z.ZodArray<z.ZodPipe<z.ZodObject<{
  * currently rejects any `color` other than `1` on add/update.
  */
 export declare class WorkspacesClient extends BaseClient {
-    /** Gets all the user's workspaces. */
+    /**
+     * 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(): Promise<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: number): Promise<Workspace>;
-    /** 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(): Promise<Workspace>;
-    /** 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: string): Promise<Workspace>;
-    /** 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: number, name: string): Promise<Workspace>;
-    /** 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: number): Promise<void>;
-    /** 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: number): Promise<Channel[]>;
 }

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

@@ -10,10 +10,13 @@ import { ThreadsClient } from './clients/threads-client.js';
 import { UsersClient } from './clients/users-client.js';
 import { WorkspaceUsersClient } from './clients/workspace-users-client.js';
 import { WorkspacesClient } from './clients/workspaces-client.js';
+import type { ApiVersion } from './types/api-version.js';
 import type { CustomFetch } from './types/http.js';
 export type CommsApiOptions = {
     /** Optional custom API base URL. If not provided, defaults to Comms' standard API endpoint. */
     baseUrl?: string;
+    /** Optional API version. Defaults to 'v1'. */
+    version?: ApiVersion;
     /** Optional custom fetch implementation for cross-platform compatibility (e.g., Obsidian, React Native, Electron). */
     customFetch?: CustomFetch;
 };

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

@@ -1,10 +1,15 @@
+import type { ApiVersion } from '../types/api-version.js';
 /**
  * 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/')
  */
-export declare function getCommsBaseUri(domainBase?: string): string;
+export declare function getCommsBaseUri(version?: ApiVersion, domainBase?: string): string;
 export declare const ENDPOINT_USERS = "users";
 export declare const ENDPOINT_WORKSPACES = "workspaces";
 export declare const ENDPOINT_CHANNELS = "channels";

package/dist/types/testUtils/test-defaults.d.ts

@@ -1,5 +1,6 @@
 import type { Channel, Comment, Conversation, Group, Thread, User, Workspace, WorkspaceUser } from '../types/entities.js';
 export declare const TEST_API_TOKEN = "test-api-token";
+export declare const TEST_API_BASE_URL: string;
 export declare const TEST_CHANNEL_ID = "7YpL3oZ4kZ9vP7Q1tR2sX3y";
 export declare const TEST_THREAD_ID = "7YpL3oZ4kZ9vP7Q1tR2sX3z";
 export declare const TEST_COMMENT_ID = "7YpL3oZ4kZ9vP7Q1tR2sX41";

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

@@ -0,0 +1,6 @@
+/**
+ * Supported Comms API versions
+ */
+export declare const API_VERSIONS: readonly ["v1"];
+export type ApiVersion = (typeof API_VERSIONS)[number];
+export declare const DEFAULT_API_VERSION: ApiVersion;

package/dist/types/types/index.d.ts

@@ -1,3 +1,4 @@
+export * from './api-version.js';
 export * from './entities.js';
 export * from './enums.js';
 export * from './errors.js';

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

@@ -131,25 +131,14 @@ export declare const GetThreadsArgsSchema: z.ZodObject<{
     olderThan: z.ZodOptional<z.ZodNullable<z.ZodDate>>;
     limit: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, z.core.$strip>;
-export type GetThreadsArgs = Omit<z.infer<typeof GetThreadsArgsSchema>, 'newerThan' | 'olderThan'> & {
-    newerThan?: Date | null;
-    olderThan?: Date | null;
-    /** @deprecated Use `newerThan` instead. */
-    newer_than_ts?: number | null;
-    /** @deprecated Use `olderThan` instead. */
-    older_than_ts?: number | null;
-};
+export type GetThreadsArgs = z.infer<typeof GetThreadsArgsSchema>;
 export declare const GetCommentsArgsSchema: z.ZodObject<{
     threadId: z.ZodString;
-    from: z.ZodOptional<z.ZodNullable<z.ZodDate>>;
     newerThan: z.ZodOptional<z.ZodNullable<z.ZodDate>>;
     olderThan: z.ZodOptional<z.ZodNullable<z.ZodDate>>;
     limit: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, z.core.$strip>;
-export type GetCommentsArgs = Omit<z.infer<typeof GetCommentsArgsSchema>, 'from'> & {
-    /** @deprecated Use `newerThan` instead. */
-    from?: Date | null;
-};
+export type GetCommentsArgs = z.infer<typeof GetCommentsArgsSchema>;
 export declare const GetConversationsArgsSchema: z.ZodObject<{
     workspaceId: z.ZodNumber;
     archived: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
@@ -231,10 +220,6 @@ export type GetInboxArgs = {
     workspaceId: number;
     newerThan?: Date;
     olderThan?: Date;
-    /** @deprecated Use `newerThan` instead. */
-    since?: Date;
-    /** @deprecated Use `olderThan` instead. */
-    until?: Date;
     limit?: number;
     cursor?: string;
     archiveFilter?: ArchiveFilter;
@@ -243,10 +228,6 @@ export type ArchiveAllArgs = {
     workspaceId: number;
     channelIds?: string[];
     olderThan?: Date;
-    /** @deprecated Use `olderThan` instead. */
-    until?: Date;
-    /** @deprecated Not supported by the archive_all endpoint — this value is ignored. */
-    since?: Date;
 };
 export type AddReactionArgs = {
     threadId?: string;

package/package.json

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