@doist/comms-sdk 0.0.1 → 0.2.0

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

@@ -0,0 +1,322 @@
+import { ENDPOINT_USERS } from '../consts/endpoints.js';
+import { request } from '../transport/http-client.js';
+import { UserSchema } from '../types/entities.js';
+import { BaseClient } from './base-client.js';
+/**
+ * Client for the `/api/v1/users/` endpoints. Authentication flows through
+ * Todoist-ID; `register` / `login` / `loginWithGoogle` / `loginWithToken` /
+ * `loginWithTodoist` are the available entry points.
+ */
+export class UsersClient extends BaseClient {
+    /**
+     * 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) {
+        return this.post(`${ENDPOINT_USERS}/register`, args, UserSchema, { authed: false });
+    }
+    /**
+     * 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) {
+        return this.post(`${ENDPOINT_USERS}/login`, args, UserSchema, { authed: false });
+    }
+    /**
+     * 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() {
+        return this.post(`${ENDPOINT_USERS}/login_with_token`, undefined, UserSchema);
+    }
+    /**
+     * 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() {
+        return this.post(`${ENDPOINT_USERS}/login_with_todoist`, {}, UserSchema, { authed: false });
+    }
+    /**
+     * 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) {
+        return this.post(`${ENDPOINT_USERS}/login_with_google`, args, UserSchema, { authed: false });
+    }
+    /**
+     * 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) {
+        return request({
+            httpMethod: 'POST',
+            baseUri: this.getBaseUri(),
+            relativePath: `${ENDPOINT_USERS}/mfa/challenge`,
+            apiToken: undefined,
+            payload: args,
+            customFetch: this.customFetch,
+        }).then((response) => response.data);
+    }
+    /** Logs out the current user and clears the session cookie. */
+    logout() {
+        return request({
+            httpMethod: 'POST',
+            baseUri: this.getBaseUri(),
+            relativePath: `${ENDPOINT_USERS}/logout`,
+            apiToken: this.apiToken,
+            payload: undefined,
+            customFetch: this.customFetch,
+        }).then(() => undefined);
+    }
+    /**
+     * 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() {
+        return this.get(`${ENDPOINT_USERS}/get_session_user`, undefined, UserSchema);
+    }
+    /**
+     * 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) {
+        return this.get(`${ENDPOINT_USERS}/getone`, args ?? {}, UserSchema);
+    }
+    /**
+     * Looks up a user by their email address.
+     *
+     * @param email - The email to look up.
+     * @returns The user object.
+     */
+    getUserByEmail(email) {
+        return this.get(`${ENDPOINT_USERS}/get_by_email`, { email }, UserSchema);
+    }
+    /**
+     * 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) {
+        return this.post(`${ENDPOINT_USERS}/update`, args, UserSchema);
+    }
+    /**
+     * 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) {
+        return this.post(`${ENDPOINT_USERS}/update_password`, args, UserSchema);
+    }
+    /**
+     * Removes the user's avatar.
+     *
+     * @returns The updated user object.
+     */
+    removeAvatar() {
+        return this.post(`${ENDPOINT_USERS}/remove_avatar`, undefined, UserSchema);
+    }
+    /**
+     * 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() {
+        return this.post(`${ENDPOINT_USERS}/invalidate_token`, undefined, UserSchema);
+    }
+    /**
+     * 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) {
+        return request({
+            httpMethod: 'GET',
+            baseUri: this.getBaseUri(),
+            relativePath: `${ENDPOINT_USERS}/validate_token`,
+            apiToken: undefined,
+            payload: { token },
+            customFetch: this.customFetch,
+        }).then(() => undefined);
+    }
+    /**
+     * 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) {
+        return request({
+            httpMethod: 'GET',
+            baseUri: this.getBaseUri(),
+            relativePath: `${ENDPOINT_USERS}/heartbeat`,
+            apiToken: this.apiToken,
+            payload: args,
+            customFetch: this.customFetch,
+        }).then(() => undefined);
+    }
+    /**
+     * Resets the user's presence for a workspace (marks the user as inactive).
+     *
+     * @param workspaceId - The workspace ID.
+     */
+    resetPresence(workspaceId) {
+        return request({
+            httpMethod: 'POST',
+            baseUri: this.getBaseUri(),
+            relativePath: `${ENDPOINT_USERS}/reset_presence`,
+            apiToken: this.apiToken,
+            payload: { workspaceId },
+            customFetch: this.customFetch,
+        }).then(() => undefined);
+    }
+    /**
+     * 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) {
+        return request({
+            httpMethod: 'POST',
+            baseUri: this.getBaseUri(),
+            relativePath: `${ENDPOINT_USERS}/check_email`,
+            apiToken: undefined,
+            payload: { email },
+            customFetch: this.customFetch,
+        }).then((response) => response.data);
+    }
+    /**
+     * 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() {
+        return request({
+            httpMethod: 'GET',
+            baseUri: this.getBaseUri(),
+            relativePath: `${ENDPOINT_USERS}/get_unsubscribe_settings`,
+            apiToken: this.apiToken,
+            payload: undefined,
+            customFetch: this.customFetch,
+        }).then((response) => response.data);
+    }
+    /**
+     * 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) {
+        return request({
+            httpMethod: 'POST',
+            baseUri: this.getBaseUri(),
+            relativePath: `${ENDPOINT_USERS}/update_unsubscribe_settings`,
+            apiToken: this.apiToken,
+            payload: settings,
+            customFetch: this.customFetch,
+        }).then((response) => response.data);
+    }
+    get(url, params, schema) {
+        return request({
+            httpMethod: 'GET',
+            baseUri: this.getBaseUri(),
+            relativePath: url,
+            apiToken: this.apiToken,
+            payload: params,
+            customFetch: this.customFetch,
+        }).then((response) => schema.parse(response.data));
+    }
+    post(url, params, schema, options = {}) {
+        const authed = options.authed ?? true;
+        return request({
+            httpMethod: 'POST',
+            baseUri: this.getBaseUri(),
+            relativePath: url,
+            apiToken: authed ? this.apiToken : undefined,
+            payload: params,
+            customFetch: this.customFetch,
+        }).then((response) => schema.parse(response.data));
+    }
+}

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

@@ -0,0 +1,236 @@
+import { request } from '../transport/http-client.js';
+import { WorkspaceUserSchema } from '../types/entities.js';
+import { BaseClient } from './base-client.js';
+/**
+ * Client for `/api/v1/workspace_users/`. The backend's `add` endpoint
+ * rejects non-empty `name` and `channelIds` — set neither.
+ */
+export class WorkspaceUsersClient extends BaseClient {
+    /**
+     * 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 request({
+            httpMethod: 'GET',
+            baseUri: this.getBaseUri(),
+            relativePath: 'workspace_users/get',
+            apiToken: this.apiToken,
+            payload: { id: args.workspaceId, archived: args.archived },
+            customFetch: this.customFetch,
+        }).then((response) => response.data.map((user) => WorkspaceUserSchema.parse(user)));
+    }
+    /**
+     * 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 request({
+            httpMethod: 'GET',
+            baseUri: this.getBaseUri(),
+            relativePath: 'workspace_users/get_ids',
+            apiToken: this.apiToken,
+            payload: { id: workspaceId },
+            customFetch: this.customFetch,
+        }).then((response) => response.data);
+    }
+    /**
+     * 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 request({
+            httpMethod: 'GET',
+            baseUri: this.getBaseUri(),
+            relativePath: 'workspace_users/getone',
+            apiToken: this.apiToken,
+            payload: { id: args.workspaceId, user_id: args.userId },
+            customFetch: this.customFetch,
+        }).then((response) => WorkspaceUserSchema.parse(response.data));
+    }
+    /**
+     * 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 request({
+            httpMethod: 'GET',
+            baseUri: this.getBaseUri(),
+            relativePath: 'workspace_users/get_by_email',
+            apiToken: this.apiToken,
+            payload: { id: args.workspaceId, email: args.email },
+            customFetch: this.customFetch,
+        }).then((response) => WorkspaceUserSchema.parse(response.data));
+    }
+    /**
+     * 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 request({
+            httpMethod: 'GET',
+            baseUri: this.getBaseUri(),
+            relativePath: 'workspace_users/get_info',
+            apiToken: this.apiToken,
+            payload: { id: args.workspaceId, user_id: args.userId },
+            customFetch: this.customFetch,
+        }).then((response) => response.data);
+    }
+    /**
+     * 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 request({
+            httpMethod: 'GET',
+            baseUri: this.getBaseUri(),
+            relativePath: 'workspace_users/get_local_time',
+            apiToken: this.apiToken,
+            payload: { id: args.workspaceId, user_id: args.userId },
+            customFetch: this.customFetch,
+        }).then((response) => response.data);
+    }
+    /**
+     * 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 request({
+            httpMethod: 'POST',
+            baseUri: this.getBaseUri(),
+            relativePath: 'workspace_users/add',
+            apiToken: this.apiToken,
+            payload: {
+                id: args.workspaceId,
+                email: args.email,
+                userType: args.userType,
+            },
+            customFetch: this.customFetch,
+        }).then((response) => WorkspaceUserSchema.parse(response.data));
+    }
+    /**
+     * 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 request({
+            httpMethod: 'POST',
+            baseUri: this.getBaseUri(),
+            relativePath: 'workspace_users/update',
+            apiToken: this.apiToken,
+            payload: {
+                id: args.workspaceId,
+                userType: args.userType,
+                email: args.email,
+                userId: args.userId,
+            },
+            customFetch: this.customFetch,
+        }).then((response) => WorkspaceUserSchema.parse(response.data));
+    }
+    /**
+     * 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 request({
+            httpMethod: 'POST',
+            baseUri: this.getBaseUri(),
+            relativePath: 'workspace_users/remove',
+            apiToken: this.apiToken,
+            payload: {
+                id: args.workspaceId,
+                email: args.email,
+                userId: args.userId,
+            },
+            customFetch: this.customFetch,
+        }).then(() => undefined);
+    }
+    /**
+     * 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 request({
+            httpMethod: 'POST',
+            baseUri: this.getBaseUri(),
+            relativePath: 'workspace_users/resend_invite',
+            apiToken: this.apiToken,
+            payload: {
+                id: args.workspaceId,
+                email: args.email,
+                userId: args.userId,
+            },
+            customFetch: this.customFetch,
+        }).then(() => undefined);
+    }
+}