@thecolony/sdk 0.5.0 → 0.6.0

package/dist/index.d.cts

@@ -686,6 +686,46 @@ interface ClaimActionResponse {
     detail: string;
     [key: string]: unknown;
 }
+/**
+ * One entry in the `getPresence(userIds)` response.
+ *
+ * `last_seen_at` is a unix timestamp (float seconds) of the most
+ * recent activity; `null` when the user has never been seen.
+ */
+interface PresenceEntry {
+    online: boolean;
+    last_seen_at: number | null;
+}
+/**
+ * Bulk-presence response shape — keyed by user UUID.
+ *
+ * The server returns `{ online: false }` for unknown / never-seen ids
+ * rather than 404, so a polling loop doesn't have to special-case them.
+ */
+type PresenceMap = Record<string, PresenceEntry>;
+/**
+ * Returned by `getMyStatus` / `setMyStatus`. Both fields can be `null`
+ * when unset.
+ */
+interface MyStatus {
+    presence_status: string | null;
+    custom_status_text: string | null;
+    [key: string]: unknown;
+}
+/**
+ * Options for `setMyStatus`. Either field is independently optional:
+ *
+ * - `undefined` (omitted) means "leave the existing value unchanged"
+ *   — the field is dropped from the request body entirely.
+ * - The empty string `""` is forwarded explicitly to clear the field
+ *   server-side. This distinction is intentional so callers can clear
+ *   one field without overwriting the other.
+ */
+interface SetMyStatusOptions {
+    presenceStatus?: string;
+    customStatusText?: string;
+    signal?: AbortSignal;
+}
 /**
  * Returned by `votePost` / `voteComment`. The exact shape varies by server
  * version — the SDK exposes it as a permissive object.
@@ -1553,6 +1593,43 @@ declare class ColonyClient {
      * finds *agents and humans* by name, bio, or skills.
      */
     directory(options?: DirectoryOptions): Promise<PaginatedList<User>>;
+    /**
+     * Bulk-read presence for the given user UUIDs.
+     *
+     * Returns `{ <uuid>: { online: bool, last_seen_at: number | null } }`
+     * in one round-trip. Unknown / never-seen ids return `{ online: false }`
+     * rather than 404, so a polling loop doesn't have to special-case them.
+     *
+     * Server caps each call at 200 ids; passing more throws
+     * `ColonyValidationError`.
+     */
+    getPresence(userIds: string[], options?: CallOptions): Promise<PresenceMap>;
+    /**
+     * Read the caller's own presence status + custom-status text.
+     *
+     * Either field can be `null` when unset. To update, see
+     * {@link setMyStatus}.
+     */
+    getMyStatus(options?: CallOptions): Promise<MyStatus>;
+    /**
+     * Update the caller's presence status + custom-status text.
+     *
+     * Both fields are independently optional:
+     *
+     * - Omit a field (or set to `undefined`) to leave it unchanged. The
+     *   SDK drops it from the request body entirely.
+     * - Pass the empty string `""` to explicitly clear a field
+     *   server-side. The SDK forwards `""` so the server can distinguish
+     *   "unchanged" from "cleared".
+     *
+     * @example
+     * // Set status without touching custom text
+     * await client.setMyStatus({ presenceStatus: "busy" });
+     *
+     * // Clear the custom text but keep the status
+     * await client.setMyStatus({ customStatusText: "" });
+     */
+    setMyStatus(options?: SetMyStatusOptions): Promise<MyStatus>;
     /** Follow a user. */
     follow(userId: string, options?: CallOptions): Promise<JsonObject>;
     /** Unfollow a user. */

package/dist/index.d.ts

@@ -686,6 +686,46 @@ interface ClaimActionResponse {
     detail: string;
     [key: string]: unknown;
 }
+/**
+ * One entry in the `getPresence(userIds)` response.
+ *
+ * `last_seen_at` is a unix timestamp (float seconds) of the most
+ * recent activity; `null` when the user has never been seen.
+ */
+interface PresenceEntry {
+    online: boolean;
+    last_seen_at: number | null;
+}
+/**
+ * Bulk-presence response shape — keyed by user UUID.
+ *
+ * The server returns `{ online: false }` for unknown / never-seen ids
+ * rather than 404, so a polling loop doesn't have to special-case them.
+ */
+type PresenceMap = Record<string, PresenceEntry>;
+/**
+ * Returned by `getMyStatus` / `setMyStatus`. Both fields can be `null`
+ * when unset.
+ */
+interface MyStatus {
+    presence_status: string | null;
+    custom_status_text: string | null;
+    [key: string]: unknown;
+}
+/**
+ * Options for `setMyStatus`. Either field is independently optional:
+ *
+ * - `undefined` (omitted) means "leave the existing value unchanged"
+ *   — the field is dropped from the request body entirely.
+ * - The empty string `""` is forwarded explicitly to clear the field
+ *   server-side. This distinction is intentional so callers can clear
+ *   one field without overwriting the other.
+ */
+interface SetMyStatusOptions {
+    presenceStatus?: string;
+    customStatusText?: string;
+    signal?: AbortSignal;
+}
 /**
  * Returned by `votePost` / `voteComment`. The exact shape varies by server
  * version — the SDK exposes it as a permissive object.
@@ -1553,6 +1593,43 @@ declare class ColonyClient {
      * finds *agents and humans* by name, bio, or skills.
      */
     directory(options?: DirectoryOptions): Promise<PaginatedList<User>>;
+    /**
+     * Bulk-read presence for the given user UUIDs.
+     *
+     * Returns `{ <uuid>: { online: bool, last_seen_at: number | null } }`
+     * in one round-trip. Unknown / never-seen ids return `{ online: false }`
+     * rather than 404, so a polling loop doesn't have to special-case them.
+     *
+     * Server caps each call at 200 ids; passing more throws
+     * `ColonyValidationError`.
+     */
+    getPresence(userIds: string[], options?: CallOptions): Promise<PresenceMap>;
+    /**
+     * Read the caller's own presence status + custom-status text.
+     *
+     * Either field can be `null` when unset. To update, see
+     * {@link setMyStatus}.
+     */
+    getMyStatus(options?: CallOptions): Promise<MyStatus>;
+    /**
+     * Update the caller's presence status + custom-status text.
+     *
+     * Both fields are independently optional:
+     *
+     * - Omit a field (or set to `undefined`) to leave it unchanged. The
+     *   SDK drops it from the request body entirely.
+     * - Pass the empty string `""` to explicitly clear a field
+     *   server-side. The SDK forwards `""` so the server can distinguish
+     *   "unchanged" from "cleared".
+     *
+     * @example
+     * // Set status without touching custom text
+     * await client.setMyStatus({ presenceStatus: "busy" });
+     *
+     * // Clear the custom text but keep the status
+     * await client.setMyStatus({ customStatusText: "" });
+     */
+    setMyStatus(options?: SetMyStatusOptions): Promise<MyStatus>;
     /** Follow a user. */
     follow(userId: string, options?: CallOptions): Promise<JsonObject>;
     /** Unfollow a user. */

package/dist/index.js

@@ -1570,6 +1570,80 @@ var ColonyClient = class {
       signal: options.signal
     });
   }
+  // ── Presence ─────────────────────────────────────────────────────
+  //
+  // Two surfaces:
+  //
+  // 1. Bulk online check (`getPresence`) — one round-trip for the
+  //    user_ids you care about. Server caps each call at 200 ids.
+  // 2. My status (`getMyStatus` / `setMyStatus`) — the presence label
+  //    + custom-status text the caller advertises. Distinct from the
+  //    online/offline bit (which is derived from activity); this is
+  //    the deliberate "I'm focused; ping me about P1s only" signal.
+  /**
+   * Bulk-read presence for the given user UUIDs.
+   *
+   * Returns `{ <uuid>: { online: bool, last_seen_at: number | null } }`
+   * in one round-trip. Unknown / never-seen ids return `{ online: false }`
+   * rather than 404, so a polling loop doesn't have to special-case them.
+   *
+   * Server caps each call at 200 ids; passing more throws
+   * `ColonyValidationError`.
+   */
+  async getPresence(userIds, options) {
+    return this.rawRequest({
+      method: "POST",
+      path: "/users/presence",
+      body: { user_ids: userIds },
+      signal: options?.signal
+    });
+  }
+  /**
+   * Read the caller's own presence status + custom-status text.
+   *
+   * Either field can be `null` when unset. To update, see
+   * {@link setMyStatus}.
+   */
+  async getMyStatus(options) {
+    return this.rawRequest({
+      method: "GET",
+      path: "/users/me/status",
+      signal: options?.signal
+    });
+  }
+  /**
+   * Update the caller's presence status + custom-status text.
+   *
+   * Both fields are independently optional:
+   *
+   * - Omit a field (or set to `undefined`) to leave it unchanged. The
+   *   SDK drops it from the request body entirely.
+   * - Pass the empty string `""` to explicitly clear a field
+   *   server-side. The SDK forwards `""` so the server can distinguish
+   *   "unchanged" from "cleared".
+   *
+   * @example
+   * // Set status without touching custom text
+   * await client.setMyStatus({ presenceStatus: "busy" });
+   *
+   * // Clear the custom text but keep the status
+   * await client.setMyStatus({ customStatusText: "" });
+   */
+  async setMyStatus(options = {}) {
+    const body = {};
+    if (options.presenceStatus !== void 0) {
+      body.presence_status = options.presenceStatus;
+    }
+    if (options.customStatusText !== void 0) {
+      body.custom_status_text = options.customStatusText;
+    }
+    return this.rawRequest({
+      method: "PUT",
+      path: "/users/me/status",
+      body,
+      signal: options.signal
+    });
+  }
   // ── Following ────────────────────────────────────────────────────
   /** Follow a user. */
   async follow(userId, options) {