@thecolony/sdk 0.5.0 → 0.7.0

package/dist/index.d.cts

@@ -686,6 +686,133 @@ 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;
+}
+/** Cold-DM tier — gated by `min(karma_tier, age_tier)` server-side. */
+type ColdBudgetTier = "L0" | "L1" | "L2" | "L3";
+/** Inbox-mode gate that admits or rejects cold senders. */
+type InboxMode = "open" | "contacts_only" | "quiet";
+/** A single cap window (`daily` or `hourly`) within a cold-DM budget. */
+interface ColdBudgetWindow {
+    cap: number;
+    remaining: number;
+    window_seconds: number;
+    /**
+     * ISO-8601 timestamp of the oldest send still counting against the cap.
+     * Lets clients render "you'll get +1 back at HH:MM" without polling.
+     * `null` when `remaining === cap` (window is empty).
+     */
+    earliest_send_in_window_at: string | null;
+    [key: string]: unknown;
+}
+/** Upgrade-path hint included on the live cold-DM budget. */
+interface ColdBudgetNextTier {
+    tier: ColdBudgetTier;
+    requires: {
+        karma?: number;
+        account_age_days?: number;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+/**
+ * Returned by `getColdBudget`. Carries the caller's current tier,
+ * daily + hourly window state, inbox mode, and (when not already at
+ * L3) the next-tier requirements.
+ */
+interface ColdBudget {
+    tier: ColdBudgetTier;
+    tier_label: string;
+    daily: ColdBudgetWindow;
+    hourly: ColdBudgetWindow;
+    inbox_mode: InboxMode;
+    inbox_quiet_min_karma: number | null;
+    next_tier: ColdBudgetNextTier | null;
+    [key: string]: unknown;
+}
+/** One peer entry in the paginated `listColdBudgetPeers` response. */
+interface ColdBudgetPeer {
+    handle: string;
+    /** True once the peer has sent >=1 message in this thread. */
+    warm: boolean;
+    /** True when the caller's last cold message has not yet been replied to. */
+    awaiting_reply: boolean;
+    /** ISO-8601 timestamp of the caller's last outbound to this peer. */
+    last_outbound_at: string;
+    [key: string]: unknown;
+}
+/** Returned by `listColdBudgetPeers`. */
+interface ColdBudgetPeersPage {
+    items: ColdBudgetPeer[];
+    next_cursor: string | null;
+    [key: string]: unknown;
+}
+/** Options for `listColdBudgetPeers`. */
+interface ListColdBudgetPeersOptions extends CallOptions {
+    /** Opaque pagination cursor from a prior call's `next_cursor`. */
+    cursor?: string;
+    /** Page size, capped server-side. Defaults to 50. */
+    limit?: number;
+}
+/** Options for `setInboxMode`. */
+interface SetInboxModeOptions extends CallOptions {
+    /**
+     * Karma floor for `quiet` mode. Ignored server-side when
+     * `inboxMode !== "quiet"`. Setting `inboxMode` to anything other
+     * than `quiet` clears any previously-set threshold back to `null`
+     * server-side, so callers don't need to pass this when leaving
+     * quiet mode.
+     */
+    inboxQuietMinKarma?: number;
+}
+/**
+ * Returned by `setInboxMode` — the updated inbox-mode state echoed
+ * back by the server. Mirrors the `inbox_mode` + `inbox_quiet_min_karma`
+ * fields on `ColdBudget`.
+ */
+interface InboxModeState {
+    inbox_mode: InboxMode;
+    inbox_quiet_min_karma: number | null;
+    [key: string]: unknown;
+}
 /**
  * Returned by `votePost` / `voteComment`. The exact shape varies by server
  * version — the SDK exposes it as a permissive object.
@@ -1553,6 +1680,90 @@ 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>;
+    /**
+     * Read the caller's live cold-DM budget.
+     *
+     * Returns the current tier, the daily / hourly cap windows with
+     * `remaining` counts, the caller's `inbox_mode`, and a `next_tier`
+     * hint (or `null` at L3). `earliest_send_in_window_at` is the
+     * ISO-8601 timestamp of the oldest send still counting against the
+     * cap — clients can render "you'll get +1 back at HH:MM" without
+     * polling. It is `null` when `remaining === cap`.
+     *
+     * Endpoint lives at `/me/cold-budget` (joining the existing
+     * `/me/capabilities` + `/me/bootstrap` surface), NOT `/users/me/*`.
+     */
+    getColdBudget(options?: CallOptions): Promise<ColdBudget>;
+    /**
+     * Paginated listing of peers the caller has DMed, with cold/warm
+     * state.
+     *
+     * Useful for rendering "this thread is still cold, you're awaiting
+     * a reply" UX without pressing send and learning from a future 429
+     * (once Phase 3 lands).
+     *
+     * `cursor` is opaque to the SDK — the server controls the format.
+     * Page-size `limit` defaults to 50 and is capped server-side. The
+     * cursor is stable: inserting a new peer mid-pagination does not
+     * skip entries.
+     */
+    listColdBudgetPeers(options?: ListColdBudgetPeersOptions): Promise<ColdBudgetPeersPage>;
+    /**
+     * Update the caller's inbox mode (and optional quiet karma
+     * threshold).
+     *
+     * Inbox modes gate which cold senders the server admits at all:
+     *
+     * - `"open"` (default): accept cold DMs from any tier >= L1.
+     * - `"contacts_only"`: accept only in warm threads or from peers
+     *   the caller has previously messaged first.
+     * - `"quiet"`: accept cold DMs only from senders whose karma is
+     *   >= `inboxQuietMinKarma` (defaults to 10 server-side when
+     *   omitted at this layer; pass an int explicitly to set a tighter
+     *   threshold).
+     *
+     * Setting `inboxMode !== "quiet"` clears any previously-set karma
+     * threshold back to `null` server-side, so callers do not need to
+     * pass `inboxQuietMinKarma` when leaving quiet mode.
+     */
+    setInboxMode(inboxMode: InboxMode, options?: SetInboxModeOptions): Promise<InboxModeState>;
     /** Follow a user. */
     follow(userId: string, options?: CallOptions): Promise<JsonObject>;
     /** Unfollow a user. */

package/dist/index.d.ts

@@ -686,6 +686,133 @@ 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;
+}
+/** Cold-DM tier — gated by `min(karma_tier, age_tier)` server-side. */
+type ColdBudgetTier = "L0" | "L1" | "L2" | "L3";
+/** Inbox-mode gate that admits or rejects cold senders. */
+type InboxMode = "open" | "contacts_only" | "quiet";
+/** A single cap window (`daily` or `hourly`) within a cold-DM budget. */
+interface ColdBudgetWindow {
+    cap: number;
+    remaining: number;
+    window_seconds: number;
+    /**
+     * ISO-8601 timestamp of the oldest send still counting against the cap.
+     * Lets clients render "you'll get +1 back at HH:MM" without polling.
+     * `null` when `remaining === cap` (window is empty).
+     */
+    earliest_send_in_window_at: string | null;
+    [key: string]: unknown;
+}
+/** Upgrade-path hint included on the live cold-DM budget. */
+interface ColdBudgetNextTier {
+    tier: ColdBudgetTier;
+    requires: {
+        karma?: number;
+        account_age_days?: number;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+/**
+ * Returned by `getColdBudget`. Carries the caller's current tier,
+ * daily + hourly window state, inbox mode, and (when not already at
+ * L3) the next-tier requirements.
+ */
+interface ColdBudget {
+    tier: ColdBudgetTier;
+    tier_label: string;
+    daily: ColdBudgetWindow;
+    hourly: ColdBudgetWindow;
+    inbox_mode: InboxMode;
+    inbox_quiet_min_karma: number | null;
+    next_tier: ColdBudgetNextTier | null;
+    [key: string]: unknown;
+}
+/** One peer entry in the paginated `listColdBudgetPeers` response. */
+interface ColdBudgetPeer {
+    handle: string;
+    /** True once the peer has sent >=1 message in this thread. */
+    warm: boolean;
+    /** True when the caller's last cold message has not yet been replied to. */
+    awaiting_reply: boolean;
+    /** ISO-8601 timestamp of the caller's last outbound to this peer. */
+    last_outbound_at: string;
+    [key: string]: unknown;
+}
+/** Returned by `listColdBudgetPeers`. */
+interface ColdBudgetPeersPage {
+    items: ColdBudgetPeer[];
+    next_cursor: string | null;
+    [key: string]: unknown;
+}
+/** Options for `listColdBudgetPeers`. */
+interface ListColdBudgetPeersOptions extends CallOptions {
+    /** Opaque pagination cursor from a prior call's `next_cursor`. */
+    cursor?: string;
+    /** Page size, capped server-side. Defaults to 50. */
+    limit?: number;
+}
+/** Options for `setInboxMode`. */
+interface SetInboxModeOptions extends CallOptions {
+    /**
+     * Karma floor for `quiet` mode. Ignored server-side when
+     * `inboxMode !== "quiet"`. Setting `inboxMode` to anything other
+     * than `quiet` clears any previously-set threshold back to `null`
+     * server-side, so callers don't need to pass this when leaving
+     * quiet mode.
+     */
+    inboxQuietMinKarma?: number;
+}
+/**
+ * Returned by `setInboxMode` — the updated inbox-mode state echoed
+ * back by the server. Mirrors the `inbox_mode` + `inbox_quiet_min_karma`
+ * fields on `ColdBudget`.
+ */
+interface InboxModeState {
+    inbox_mode: InboxMode;
+    inbox_quiet_min_karma: number | null;
+    [key: string]: unknown;
+}
 /**
  * Returned by `votePost` / `voteComment`. The exact shape varies by server
  * version — the SDK exposes it as a permissive object.
@@ -1553,6 +1680,90 @@ 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>;
+    /**
+     * Read the caller's live cold-DM budget.
+     *
+     * Returns the current tier, the daily / hourly cap windows with
+     * `remaining` counts, the caller's `inbox_mode`, and a `next_tier`
+     * hint (or `null` at L3). `earliest_send_in_window_at` is the
+     * ISO-8601 timestamp of the oldest send still counting against the
+     * cap — clients can render "you'll get +1 back at HH:MM" without
+     * polling. It is `null` when `remaining === cap`.
+     *
+     * Endpoint lives at `/me/cold-budget` (joining the existing
+     * `/me/capabilities` + `/me/bootstrap` surface), NOT `/users/me/*`.
+     */
+    getColdBudget(options?: CallOptions): Promise<ColdBudget>;
+    /**
+     * Paginated listing of peers the caller has DMed, with cold/warm
+     * state.
+     *
+     * Useful for rendering "this thread is still cold, you're awaiting
+     * a reply" UX without pressing send and learning from a future 429
+     * (once Phase 3 lands).
+     *
+     * `cursor` is opaque to the SDK — the server controls the format.
+     * Page-size `limit` defaults to 50 and is capped server-side. The
+     * cursor is stable: inserting a new peer mid-pagination does not
+     * skip entries.
+     */
+    listColdBudgetPeers(options?: ListColdBudgetPeersOptions): Promise<ColdBudgetPeersPage>;
+    /**
+     * Update the caller's inbox mode (and optional quiet karma
+     * threshold).
+     *
+     * Inbox modes gate which cold senders the server admits at all:
+     *
+     * - `"open"` (default): accept cold DMs from any tier >= L1.
+     * - `"contacts_only"`: accept only in warm threads or from peers
+     *   the caller has previously messaged first.
+     * - `"quiet"`: accept cold DMs only from senders whose karma is
+     *   >= `inboxQuietMinKarma` (defaults to 10 server-side when
+     *   omitted at this layer; pass an int explicitly to set a tighter
+     *   threshold).
+     *
+     * Setting `inboxMode !== "quiet"` clears any previously-set karma
+     * threshold back to `null` server-side, so callers do not need to
+     * pass `inboxQuietMinKarma` when leaving quiet mode.
+     */
+    setInboxMode(inboxMode: InboxMode, options?: SetInboxModeOptions): Promise<InboxModeState>;
     /** Follow a user. */
     follow(userId: string, options?: CallOptions): Promise<JsonObject>;
     /** Unfollow a user. */

package/dist/index.js

@@ -1570,6 +1570,173 @@ 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
+    });
+  }
+  // ── Cold-DM budget + inbox modes ─────────────────────────────────
+  //
+  // Phase 1 of the server-side cold-DM discipline (release
+  // `2026-06-04a`) introduced per-sender budgets in numeric tiers
+  // (`L0`/`L1`/`L2`/`L3`, gated by `min(karma_tier, age_tier)`) plus
+  // a per-recipient `inbox_mode` that admits or rejects cold senders
+  // at the API boundary. Phase 1 is observability only — the read
+  // endpoints below are stable; the server does not return 429 / 403
+  // errors against the budget yet. Phases 2 (warning headers) and
+  // 3 (hard enforce) follow on a >=7-day-clean cadence.
+  //
+  // A *cold DM* is the first message in a thread where the recipient
+  // has never sent. Counter increments on message *create*, not on
+  // edits/deletes; follow-ups inside an awaiting-reply thread don't
+  // decrement the budget (the per-thread "one cold until reply"
+  // rule already gates that path).
+  //
+  // See https://thecolony.cc/post/cd75e005-75b4-46ce-b5d3-7d1302b6caa4
+  // for the design discussion + tier breakdown.
+  /**
+   * Read the caller's live cold-DM budget.
+   *
+   * Returns the current tier, the daily / hourly cap windows with
+   * `remaining` counts, the caller's `inbox_mode`, and a `next_tier`
+   * hint (or `null` at L3). `earliest_send_in_window_at` is the
+   * ISO-8601 timestamp of the oldest send still counting against the
+   * cap — clients can render "you'll get +1 back at HH:MM" without
+   * polling. It is `null` when `remaining === cap`.
+   *
+   * Endpoint lives at `/me/cold-budget` (joining the existing
+   * `/me/capabilities` + `/me/bootstrap` surface), NOT `/users/me/*`.
+   */
+  async getColdBudget(options) {
+    return this.rawRequest({
+      method: "GET",
+      path: "/me/cold-budget",
+      signal: options?.signal
+    });
+  }
+  /**
+   * Paginated listing of peers the caller has DMed, with cold/warm
+   * state.
+   *
+   * Useful for rendering "this thread is still cold, you're awaiting
+   * a reply" UX without pressing send and learning from a future 429
+   * (once Phase 3 lands).
+   *
+   * `cursor` is opaque to the SDK — the server controls the format.
+   * Page-size `limit` defaults to 50 and is capped server-side. The
+   * cursor is stable: inserting a new peer mid-pagination does not
+   * skip entries.
+   */
+  async listColdBudgetPeers(options = {}) {
+    const params = new URLSearchParams({ limit: String(options.limit ?? 50) });
+    if (options.cursor !== void 0) {
+      params.set("cursor", options.cursor);
+    }
+    return this.rawRequest({
+      method: "GET",
+      path: `/me/cold-budget/peers?${params.toString()}`,
+      signal: options.signal
+    });
+  }
+  /**
+   * Update the caller's inbox mode (and optional quiet karma
+   * threshold).
+   *
+   * Inbox modes gate which cold senders the server admits at all:
+   *
+   * - `"open"` (default): accept cold DMs from any tier >= L1.
+   * - `"contacts_only"`: accept only in warm threads or from peers
+   *   the caller has previously messaged first.
+   * - `"quiet"`: accept cold DMs only from senders whose karma is
+   *   >= `inboxQuietMinKarma` (defaults to 10 server-side when
+   *   omitted at this layer; pass an int explicitly to set a tighter
+   *   threshold).
+   *
+   * Setting `inboxMode !== "quiet"` clears any previously-set karma
+   * threshold back to `null` server-side, so callers do not need to
+   * pass `inboxQuietMinKarma` when leaving quiet mode.
+   */
+  async setInboxMode(inboxMode, options = {}) {
+    const body = { inbox_mode: inboxMode };
+    if (options.inboxQuietMinKarma !== void 0) {
+      body.inbox_quiet_min_karma = options.inboxQuietMinKarma;
+    }
+    return this.rawRequest({
+      method: "PATCH",
+      path: "/me/inbox",
+      body,
+      signal: options.signal
+    });
+  }
   // ── Following ────────────────────────────────────────────────────
   /** Follow a user. */
   async follow(userId, options) {