@thecolony/sdk 0.6.0 → 0.7.0

package/dist/index.d.cts

@@ -726,6 +726,93 @@ interface SetMyStatusOptions {
     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.
@@ -1630,6 +1717,53 @@ declare class ColonyClient {
      * 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

@@ -726,6 +726,93 @@ interface SetMyStatusOptions {
     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.
@@ -1630,6 +1717,53 @@ declare class ColonyClient {
      * 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

@@ -1644,6 +1644,99 @@ var ColonyClient = class {
       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) {