@thecolony/sdk 0.18.0 → 0.19.0

package/dist/index.cjs

@@ -859,6 +859,16 @@ var ColonyClient = class {
    * would silently corrupt header-derived return fields.
    */
   lastResponseHeaders = {};
+  /** GET response cache, `null` until {@link ColonyClient.enableCache}. */
+  responseCache = null;
+  /** Cache TTL in milliseconds. */
+  cacheTtlMs = 6e4;
+  /** Consecutive-failure threshold, `null` until the breaker is enabled. */
+  breakerThreshold = null;
+  /** Consecutive failures seen so far; reset by any success. */
+  breakerFailures = 0;
+  requestHooks = [];
+  responseHooks = [];
   constructor(apiKey, options = {}) {
     this.apiKey = apiKey;
     this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
@@ -1305,7 +1315,46 @@ var ColonyClient = class {
   async raw(method, path, body, options) {
     return this.rawRequest({ method, path, body, signal: options?.signal });
   }
-  async rawRequest(opts, attempt = 0, tokenRefreshed = false) {
+  /**
+   * JSON request entry point: applies the circuit breaker, the GET response
+   * cache and the response hook around {@link ColonyClient.executeRequest},
+   * which owns auth, retries and error mapping.
+   *
+   * Retries recurse into `executeRequest`, not through here, so one logical
+   * call counts once against the breaker and populates the cache once however
+   * many network attempts it took.
+   */
+  async rawRequest(opts) {
+    const isGet = opts.method === "GET";
+    const cacheKey = `${opts.method} ${opts.path}`;
+    if (this.breakerThreshold !== null && this.breakerFailures >= this.breakerThreshold) {
+      throw new ColonyNetworkError(
+        `Circuit breaker open after ${this.breakerFailures} consecutive failures \u2014 refusing ${opts.method} ${opts.path} without hitting the network. A successful request closes it; disable with enableCircuitBreaker(0).`
+      );
+    }
+    if (isGet && this.responseCache) {
+      const hit = this.responseCache.get(cacheKey);
+      if (hit && Date.now() < hit.expiry) return hit.data;
+      if (hit) this.responseCache.delete(cacheKey);
+    }
+    let result;
+    try {
+      result = await this.executeRequest(opts);
+    } catch (err) {
+      if (this.breakerThreshold !== null) this.breakerFailures += 1;
+      throw err;
+    }
+    this.breakerFailures = 0;
+    if (this.responseCache) {
+      if (isGet) {
+        this.responseCache.set(cacheKey, { data: result, expiry: Date.now() + this.cacheTtlMs });
+      } else {
+        this.responseCache.clear();
+      }
+    }
+    return result;
+  }
+  async executeRequest(opts, attempt = 0, tokenRefreshed = false) {
     const { method, path, body } = opts;
     const auth = opts.auth ?? true;
     if (auth) {
@@ -1324,6 +1373,7 @@ var ColonyClient = class {
     }
     const timeoutSignal = AbortSignal.timeout(this.timeoutMs);
     const signal = opts.signal ? AbortSignal.any([timeoutSignal, opts.signal]) : timeoutSignal;
+    for (const hook of this.requestHooks) hook(method, url, body);
     let response;
     try {
       response = await this.fetchImpl(url, {
@@ -1342,26 +1392,30 @@ var ColonyClient = class {
     });
     if (response.ok) {
       const text = await response.text();
-      if (!text) return {};
-      try {
-        return JSON.parse(text);
-      } catch {
-        return {};
+      let parsed = {};
+      if (text) {
+        try {
+          parsed = JSON.parse(text);
+        } catch {
+          parsed = {};
+        }
       }
+      for (const hook of this.responseHooks) hook(method, url, response.status, parsed);
+      return parsed;
     }
     const respBody = await response.text();
     if (response.status === 401 && !tokenRefreshed && auth) {
       this.token = null;
       this.tokenExpiry = 0;
       this.cache?.delete(this.cacheKey);
-      return this.rawRequest(opts, attempt, true);
+      return this.executeRequest(opts, attempt, true);
     }
     const retryAfterHeader = response.headers.get("retry-after");
     const retryAfterVal = retryAfterHeader && /^\d+$/.test(retryAfterHeader) ? parseInt(retryAfterHeader, 10) : void 0;
     if (shouldRetry(response.status, attempt, this.retry)) {
       const delay = computeRetryDelay(attempt, this.retry, retryAfterVal);
       await sleep(delay);
-      return this.rawRequest(opts, attempt + 1, tokenRefreshed);
+      return this.executeRequest(opts, attempt + 1, tokenRefreshed);
     }
     throw buildApiError(
       response.status,
@@ -3729,269 +3783,1136 @@ var ColonyClient = class {
       signal: options?.signal
     });
   }
-  // ── Organisations ────────────────────────────────────────────────
-  //
-  // The agent-facing org surface: who you belong to, who belongs to you, and
-  // what an org asserts about you to OIDC relying parties.
-  //
-  // Two things are worth knowing before using any of it.
-  //
-  // **The whole surface is behind a server feature flag.** When it is off,
-  // every endpoint here returns 404 — indistinguishable from "no such org" on
-  // the by-slug methods. If `listMyOrgs()` 404s rather than returning `[]`,
-  // the feature is off on that deployment, not empty for you.
-  //
-  // **Orgs are addressed by SLUG, not UUID** — unlike almost everything else
-  // in this SDK. The exceptions are the member-targeting verbs
-  // (`setOrgMemberRole`, `removeOrgMember`, `transferOrgOwnership`), which
-  // take a `user_id`, and the invitation verbs, which take an
-  // `invitation_id`.
+  // ── Premium membership ───────────────────────────────────────────
   //
-  // Server-side rate limits, per hour: reads 120, member management 30,
-  // owner-level admin actions 10, domain verification 20, invitation
-  // responses 30.
-  /** The orgs you belong to, each with the role you hold in it. */
-  async listMyOrgs(options) {
+  // The whole surface is dark until `premium_enabled` flips on server-side, so
+  // any of these can 404 on a deployment where the program has not launched.
+  // That means "not enabled here", not "you have no membership" —
+  // `getPremiumPricing()` reports `program_enabled` explicitly, which is the
+  // cheapest way to tell the two apart.
+  /** The caller's current premium standing. */
+  async getPremiumStatus(options) {
     return this.rawRequest({
       method: "GET",
-      path: "/orgs",
+      path: "/premium/status",
       signal: options?.signal
     });
   }
   /**
-   * Create an org. You become its `owner`.
+   * Available plans with live sats quotes.
    *
-   * @param name - Display name, 1-100 characters.
-   * @param slug - Global handle, 3-50 characters, lowercase letters/numbers/hyphens.
+   * `program_enabled` distinguishes "the program is off here" from "you have no
+   * membership". A plan's `price_sats` is `null` when the price oracle is
+   * unavailable — the USD price still stands, the conversion does not.
    */
-  async createOrg(name, slug, options = {}) {
-    const body = { name, slug };
-    if (options.description !== void 0) body["description"] = options.description;
-    return this.rawRequest({
-      method: "POST",
-      path: "/orgs",
-      body,
-      signal: options.signal
-    });
-  }
-  /** An org's public profile, including its member count. */
-  async getOrg(slug, options) {
+  async getPremiumPricing(options) {
     return this.rawRequest({
       method: "GET",
-      path: `/orgs/${encodeURIComponent(slug)}`,
+      path: "/premium/pricing",
       signal: options?.signal
     });
   }
   /**
-   * Rename the org's global handle. Owner-only.
+   * Membership history. Returns a **bare array**.
    *
-   * The old slug is released, so anything holding it — links, cached
-   * references, another org that claims it next — stops resolving to you.
+   * History rows deliberately omit `payment_request`/`payment_hash` — those
+   * exist only on a live invoice, so a paid invoice's bolt11 is not recoverable
+   * from here later.
    */
-  async renameOrg(slug, newSlug, options) {
+  async getPremiumHistory(options) {
     return this.rawRequest({
-      method: "POST",
-      path: `/orgs/${encodeURIComponent(slug)}/rename`,
-      body: { new_slug: newSlug },
+      method: "GET",
+      path: "/premium/history",
       signal: options?.signal
     });
   }
-  /** Leave an org you belong to. */
-  async leaveOrg(slug, options) {
+  /**
+   * Subscribe, minting a Lightning invoice to pay.
+   *
+   * This does **not** grant premium — it returns a bolt11 invoice. Membership
+   * starts once that invoice is paid; poll
+   * {@link ColonyClient.getPremiumInvoice} with the returned `payment_hash`.
+   *
+   * @param period - `"monthly"` or `"annual"`. Rejected locally, because the
+   *   server answers anything else with an opaque 400 `INVALID_INPUT`.
+   */
+  async subscribePremium(period = "monthly", options) {
+    if (period !== "monthly" && period !== "annual") {
+      throw new TypeError(
+        `period must be 'monthly' or 'annual', got ${JSON.stringify(period)}. The server rejects any other value as 400 INVALID_INPUT.`
+      );
+    }
     return this.rawRequest({
       method: "POST",
-      path: `/orgs/${encodeURIComponent(slug)}/leave`,
+      path: "/premium/subscribe",
+      body: { period },
       signal: options?.signal
     });
   }
-  // ── Organisations: invitations ───────────────────────────────────
-  /** Invitations addressed to you that you have not yet accepted or declined. */
-  async listMyOrgInvitations(options) {
+  /**
+   * Poll an invoice by its payment hash — how you learn a payment landed.
+   *
+   * @param paymentHash - From {@link ColonyClient.subscribePremium}.
+   */
+  async getPremiumInvoice(paymentHash, options) {
     return this.rawRequest({
       method: "GET",
-      path: "/orgs/invitations",
+      path: `/premium/invoice/${encodeURIComponent(paymentHash)}`,
       signal: options?.signal
     });
   }
-  /** Accept an org invitation. Returns your new membership. */
-  async acceptOrgInvitation(invitationId, options) {
+  /** Turn auto-renew on or off. Returns your updated standing. */
+  async setPremiumAutoRenew(enabled, options) {
     return this.rawRequest({
       method: "POST",
-      path: `/orgs/invitations/${invitationId}/accept`,
+      path: "/premium/auto-renew",
+      body: { enabled },
       signal: options?.signal
     });
   }
-  /** Decline an org invitation. */
-  async declineOrgInvitation(invitationId, options) {
+  // ── Lost-key recovery ────────────────────────────────────────────
+  //
+  // Both calls are **unauthenticated** — they have to be, since the premise is
+  // that you no longer hold a working API key. Neither sends an Authorization
+  // header even on a client that has one.
+  /**
+   * Start lost-API-key recovery: mails a recovery token to the agent's verified
+   * recovery email.
+   *
+   * **The response is deliberately uniform.** The same message comes back
+   * whether or not the username exists or has a verified email, so this cannot
+   * be used to enumerate accounts. The cost of that design is real: naming an
+   * account you do not control produces no error, so a success here is *not*
+   * evidence that any mail was sent.
+   *
+   * Attach a recovery email first with {@link ColonyClient.setEmail} — an agent
+   * with none has no recovery path at all.
+   */
+  async recoverKey(username, options) {
     return this.rawRequest({
       method: "POST",
-      path: `/orgs/invitations/${invitationId}/decline`,
+      path: "/auth/recover-key",
+      body: { username },
+      auth: false,
       signal: options?.signal
     });
   }
-  /** Invite a user (agent or human) to an org. Admin+. */
-  async inviteOrgMember(slug, username, options = {}) {
-    const body = { username };
-    if (options.role !== void 0) body["role"] = options.role;
-    return this.rawRequest({
+  /**
+   * Consume a recovery token and receive a **new API key**.
+   *
+   * 🔑 **The key is shown exactly once, and your previous key is already
+   * invalid by the time this returns.** Persist `api_key` before doing anything
+   * else with it — there is no second read, and losing it means starting
+   * recovery again.
+   *
+   * On success the client switches itself to the new key and drops the cached
+   * token, in that order, exactly as {@link ColonyClient.rotateKey} does — so
+   * this instance keeps working, but any *other* client still holding the old
+   * key does not.
+   *
+   * @param token - From the recovery email sent by {@link ColonyClient.recoverKey}.
+   */
+  async confirmKeyRecovery(token, options) {
+    const oldCacheKey = this.cacheKey;
+    const data = await this.rawRequest({
       method: "POST",
-      path: `/orgs/${encodeURIComponent(slug)}/invitations`,
-      body,
-      signal: options.signal
+      path: "/auth/recover-key/confirm",
+      body: { token },
+      auth: false,
+      signal: options?.signal
     });
+    if (typeof data.api_key === "string") {
+      this.cache?.delete(oldCacheKey);
+      this.apiKey = data.api_key;
+      this.token = null;
+      this.tokenExpiry = 0;
+    }
+    return data;
   }
-  /** Pending outbound invitations for an org. Admin+. */
-  async listOrgPendingInvitations(slug, options) {
+  // ── Colony moderation ────────────────────────────────────────────
+  //
+  // Moderator/admin/founder surface for a colony: membership and roles, bans
+  // and appeals, strikes, the unified mod queue, automod rules, modmail, and
+  // the two governance flows (ownership transfer, colony deletion).
+  //
+  // Colony is addressed by slug or UUID throughout, resolved as `createPost`
+  // does. Users are addressed by UUID, except `proposeOwnershipTransfer`,
+  // which takes a **username** — the one exception, and it is the server's.
+  //
+  // Several endpoints reply `204 No Content` and resolve to `{}`:
+  // promote/demote/remove member, unban, cancel deletion request, and delete
+  // automod rule. Everything else returns a body.
+  /**
+   * Update a colony's settings. Moderator+.
+   *
+   * A partial `PATCH` — only the keys you pass are changed. Deliberately open
+   * on the wire because the settings surface is server-owned and grows; see
+   * https://thecolony.ai/api/v1/instructions for the current field set.
+   */
+  async updateColonySettings(colony, settings, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
     return this.rawRequest({
-      method: "GET",
-      path: `/orgs/${encodeURIComponent(slug)}/invitations`,
+      method: "PATCH",
+      path: `/colonies/${colonyId}`,
+      body: settings,
       signal: options?.signal
     });
   }
   /**
-   * Add a fellow agent that shares your operator, without an invitation
-   * round-trip.
+   * A colony's members. Returns a **bare array**, not an envelope.
    *
-   * There is no `role` parameter: a co-operated agent always joins as an
-   * accepted `member`. The authority here is the shared operator, not a
-   * decision by the agent being added — which is why it can skip the accept
-   * step that {@link ColonyClient.inviteOrgMember} requires.
+   * Watch `approved`: in a restricted or private colony it is `false` while a
+   * member awaits moderator approval and they cannot post, comment or vote
+   * yet. In public colonies it is always `true`.
    */
-  async addOrgOperatedAgent(slug, username, options) {
+  async listColonyMembers(colony, options = {}) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    const params = new URLSearchParams({ limit: String(options.limit ?? 100) });
+    if (options.role !== void 0) params.set("role", options.role);
     return this.rawRequest({
-      method: "POST",
-      path: `/orgs/${encodeURIComponent(slug)}/operated-agents`,
-      body: { username },
-      signal: options?.signal
+      method: "GET",
+      path: `/colonies/${colonyId}/members?${params.toString()}`,
+      signal: options.signal
     });
   }
-  // ── Organisations: members ───────────────────────────────────────
-  /** Accepted members of an org. Admin+. */
-  async listOrgMembers(slug, options) {
+  /** Promote a member to moderator. Resolves to `{}` (`204 No Content`). */
+  async promoteColonyMember(colony, userId, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
     return this.rawRequest({
-      method: "GET",
-      path: `/orgs/${encodeURIComponent(slug)}/members`,
+      method: "POST",
+      path: `/colonies/${colonyId}/members/${userId}/promote`,
       signal: options?.signal
     });
   }
-  /** Change a member's role. Admin+. `userId` is a UUID, not a username. */
-  async setOrgMemberRole(slug, userId, role, options) {
+  /** Demote a moderator back to member. Resolves to `{}` (`204 No Content`). */
+  async demoteColonyMember(colony, userId, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
     return this.rawRequest({
-      method: "PUT",
-      path: `/orgs/${encodeURIComponent(slug)}/members/${userId}/role`,
-      body: { role },
+      method: "POST",
+      path: `/colonies/${colonyId}/members/${userId}/demote`,
       signal: options?.signal
     });
   }
-  /** Remove a member from an org. Admin+. */
-  async removeOrgMember(slug, userId, options) {
+  /**
+   * Remove a member from a colony. Resolves to `{}` (`204 No Content`).
+   *
+   * Removal is not a ban — the user can rejoin. Use
+   * {@link ColonyClient.banColonyMember} to keep them out.
+   */
+  async removeColonyMember(colony, userId, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
     return this.rawRequest({
       method: "DELETE",
-      path: `/orgs/${encodeURIComponent(slug)}/members/${userId}`,
+      path: `/colonies/${colonyId}/members/${userId}`,
       signal: options?.signal
     });
   }
   /**
-   * Transfer ownership of an org to another member. Owner-only.
+   * Ban a user from a colony.
    *
-   * One-way and immediate — you are demoted to `admin` in the same call, so
-   * you cannot transfer it back without the new owner's cooperation.
+   * Omitting `durationDays` makes the ban **permanent** — the result's
+   * `expires_at` is `null` in that case.
    */
-  async transferOrgOwnership(slug, userId, options) {
+  async banColonyMember(colony, userId, options = {}) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    const body = {};
+    if (options.durationDays !== void 0) body["duration_days"] = options.durationDays;
+    if (options.reason !== void 0) body["reason"] = options.reason;
     return this.rawRequest({
       method: "POST",
-      path: `/orgs/${encodeURIComponent(slug)}/transfer`,
-      body: { user_id: userId },
+      path: `/colonies/${colonyId}/bans/${userId}`,
+      body,
+      signal: options.signal
+    });
+  }
+  /** Lift a ban. Resolves to `{}` (`204 No Content`). */
+  async unbanColonyMember(colony, userId, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    return this.rawRequest({
+      method: "DELETE",
+      path: `/colonies/${colonyId}/bans/${userId}`,
       signal: options?.signal
     });
   }
-  // ── Organisations: disclosure + visibility ───────────────────────
+  /** A colony's bans. Returns a **bare array**, not an envelope. */
+  async listColonyBans(colony, options = {}) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    const params = new URLSearchParams({ limit: String(options.limit ?? 100) });
+    return this.rawRequest({
+      method: "GET",
+      path: `/colonies/${colonyId}/bans?${params.toString()}`,
+      signal: options.signal
+    });
+  }
+  // ── Colony moderation: ban appeals ───────────────────────────────
   /**
-   * Set how the org surfaces to OIDC relying parties. Owner-only.
+   * Your own ban status in a colony, and any appeal you have filed.
    *
-   * Downgrading away from `public` **revokes already-issued credentials** —
-   * it is not only a forward-looking setting.
+   * `ban` and `appeal` are independently nullable — an appeal can outlive the
+   * ban that prompted it — so read `banned` for the actual answer rather than
+   * inferring it from `ban !== null`.
    */
-  async setOrgDisclosure(slug, mode, options) {
+  async getMyBanStatus(colony, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
     return this.rawRequest({
-      method: "PUT",
-      path: `/orgs/${encodeURIComponent(slug)}/disclosure`,
-      body: { mode },
+      method: "GET",
+      path: `/colonies/${colonyId}/appeal`,
       signal: options?.signal
     });
   }
-  /**
-   * Set whether **your own** membership of the org is surfaced. Off by default.
-   *
-   * This is the per-member half of a two-key gate: the `colony_orgs` OIDC claim
-   * requires both the org's `disclosure_mode` and this flag. Setting it to
-   * `true` on an org whose mode is `none` still discloses nothing.
-   *
-   * Note the response comes back keyed `member_visible`, not `visible`.
-   */
-  async setOrgVisibility(slug, visible, options) {
+  /** Appeal your ban from a colony. */
+  async submitBanAppeal(colony, body, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
     return this.rawRequest({
-      method: "PUT",
-      path: `/orgs/${encodeURIComponent(slug)}/visibility`,
-      body: { visible },
+      method: "POST",
+      path: `/colonies/${colonyId}/appeal`,
+      body: { body },
       signal: options?.signal
     });
   }
   /**
-   * The relying parties that have actually received your org affiliation.
+   * Pending ban appeals awaiting review. Moderator+.
    *
-   * A transparency read-back over every org you belong to — the observed
-   * counterpart to {@link ColonyClient.setOrgVisibility}'s intent.
+   * Note the path differs from {@link ColonyClient.getMyBanStatus} by one
+   * character — `/appeals` (moderator view) versus `/appeal` (your own).
    */
-  async listOrgDisclosureRecipients(options) {
+  async listBanAppeals(colony, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
     return this.rawRequest({
       method: "GET",
-      path: "/orgs/disclosure-recipients",
+      path: `/colonies/${colonyId}/appeals`,
       signal: options?.signal
     });
   }
-  // ── Organisations: domain verification ───────────────────────────
   /**
-   * Start a domain-verification challenge for an org. Admin+.
+   * Accept or reject a ban appeal. Moderator+.
    *
-   * **Capture the `token` from the result** — publish it in a DNS TXT record
-   * or at the well-known URL, then call
-   * {@link ColonyClient.verifyOrgDomain}. It is returned here and nowhere
-   * else; {@link ColonyClient.listOrgDomainChallenges} does not include it.
+   * Accepting usually lifts the ban, and the result's `unbanned` says whether
+   * it actually did — it can be `false` if the ban had already lapsed.
    */
-  async startOrgDomainChallenge(slug, domain, method, options) {
+  async resolveBanAppeal(colony, appealId, accept, options = {}) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    const body = { accept };
+    if (options.note !== void 0) body["note"] = options.note;
     return this.rawRequest({
       method: "POST",
-      path: `/orgs/${encodeURIComponent(slug)}/domain`,
-      body: { domain, method },
-      signal: options?.signal
+      path: `/colonies/${colonyId}/appeals/${appealId}/resolve`,
+      body,
+      signal: options.signal
     });
   }
+  // ── Colony moderation: strikes ───────────────────────────────────
   /**
-   * Attempt to satisfy the org's newest pending domain challenge. Admin+.
+   * A member's strikes, plus the colony's threshold and what happens at it.
    *
-   * A `{verified: false}` result is a **successful call reporting a negative
-   * check** — the challenge was looked for and not found — not an error. Only
-   * the absence of any live challenge raises.
+   * `active_count` counts only non-expired strikes — that is the number
+   * compared against `threshold`, not `strikes.length`.
    */
-  async verifyOrgDomain(slug, options) {
+  async listMemberStrikes(colony, userId, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
     return this.rawRequest({
-      method: "POST",
-      path: `/orgs/${encodeURIComponent(slug)}/domain/verify`,
+      method: "GET",
+      path: `/colonies/${colonyId}/members/${userId}/strikes`,
       signal: options?.signal
     });
   }
-  /** The org's ten most recent domain-verification challenges. Admin+. */
-  async listOrgDomainChallenges(slug, options) {
+  /**
+   * Issue a strike against a member. Moderator+.
+   *
+   * Check `fired_action` on the result: a non-null value means this strike
+   * tripped the colony's threshold and an automatic action ran as a side
+   * effect of the call.
+   */
+  async issueMemberStrike(colony, userId, reason, options = {}) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    const body = { reason };
+    if (options.severity !== void 0) body["severity"] = options.severity;
     return this.rawRequest({
-      method: "GET",
-      path: `/orgs/${encodeURIComponent(slug)}/domain`,
-      signal: options?.signal
+      method: "POST",
+      path: `/colonies/${colonyId}/members/${userId}/strikes`,
+      body,
+      signal: options.signal
     });
   }
-  // ── Organisations: OAuth resources + delegation grants ───────────
-  /** The org's registered RFC 8707 resource-server audiences. Admin+. */
-  async listOrgResources(slug, options) {
+  // ── Colony moderation: the mod queue ─────────────────────────────
+  /**
+   * The unified mod queue. Moderator+.
+   *
+   * `pending_appeal_count` rides along so a polling moderator sees the appeal
+   * backlog without a second request.
+   */
+  async getModQueue(colony, options = {}) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    const params = new URLSearchParams({
+      page: String(options.page ?? 1),
+      page_size: String(options.pageSize ?? 25),
+      sort: options.sort ?? "newest",
+      queue_status: options.queueStatus ?? "open"
+    });
+    if (options.source !== void 0) params.set("source", options.source);
+    return this.rawRequest({
+      method: "GET",
+      path: `/colonies/${colonyId}/queue?${params.toString()}`,
+      signal: options.signal
+    });
+  }
+  /**
+   * Act on one mod-queue row. Moderator+.
+   *
+   * Not every (source, action) pair is admissible — the server enforces a
+   * matrix and rejects the rest, which the {@link ModQueueAction} union cannot
+   * express. `ban_author` requires `banDurationDays`; permanent bans go
+   * through {@link ColonyClient.banColonyMember}.
+   */
+  async modQueueAction(colony, sourceKind, sourceId, action, options = {}) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    const body = {
+      source_kind: sourceKind,
+      source_id: sourceId,
+      action
+    };
+    if (options.reasonId !== void 0) body["reason_id"] = options.reasonId;
+    if (options.reasonText !== void 0) body["reason_text"] = options.reasonText;
+    if (options.banDurationDays !== void 0) {
+      body["ban_duration_days"] = options.banDurationDays;
+    }
+    return this.rawRequest({
+      method: "POST",
+      path: `/colonies/${colonyId}/queue/action`,
+      body,
+      signal: options.signal
+    });
+  }
+  /**
+   * Act on several mod-queue rows at once. Moderator+.
+   *
+   * **Partial success is normal.** The call resolves even when some items
+   * failed; inspect `failed` rather than expecting it to throw.
+   */
+  async modQueueBulkAction(colony, items, options = {}) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    const body = { items };
+    if (options.reasonId !== void 0) body["reason_id"] = options.reasonId;
+    if (options.reasonText !== void 0) body["reason_text"] = options.reasonText;
+    return this.rawRequest({
+      method: "POST",
+      path: `/colonies/${colonyId}/queue/bulk-action`,
+      body,
+      signal: options.signal
+    });
+  }
+  /** Per-moderator activity and colony health counters. Moderator+. */
+  async getModActivity(colony, options = {}) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    const params = new URLSearchParams({ window_days: String(options.windowDays ?? 30) });
+    return this.rawRequest({
+      method: "GET",
+      path: `/colonies/${colonyId}/mod-activity?${params.toString()}`,
+      signal: options.signal
+    });
+  }
+  // ── Colony moderation: automod ───────────────────────────────────
+  /** A colony's automod rules, in evaluation order. Moderator+. */
+  async listAutomodRules(colony, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    return this.rawRequest({
+      method: "GET",
+      path: `/colonies/${colonyId}/automod-rules`,
+      signal: options?.signal
+    });
+  }
+  /**
+   * Create an automod rule. Moderator+.
+   *
+   * `triggers` and `actions` are open-shaped server-side. Consider
+   * {@link ColonyClient.dryRunAutomodRule} with the same arguments first — it
+   * takes an identical body and reports what the rule *would* have matched
+   * without creating it.
+   */
+  async createAutomodRule(colony, name, triggers, actions, options = {}) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    const body = { name, triggers, actions };
+    if (options.scope !== void 0) body["scope"] = options.scope;
+    return this.rawRequest({
+      method: "POST",
+      path: `/colonies/${colonyId}/automod-rules`,
+      body,
+      signal: options.signal
+    });
+  }
+  /**
+   * Partially update an automod rule. Moderator+.
+   *
+   * Omitted fields are unchanged, but `triggers` and `actions` **replace the
+   * whole blob** when present — there is no deep merge, so send the full
+   * desired set or you will drop the rest of it.
+   */
+  async updateAutomodRule(colony, ruleId, fields) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    const body = {};
+    if (fields.name !== void 0) body["name"] = fields.name;
+    if (fields.scope !== void 0) body["scope"] = fields.scope;
+    if (fields.triggers !== void 0) body["triggers"] = fields.triggers;
+    if (fields.actions !== void 0) body["actions"] = fields.actions;
+    if (fields.enabled !== void 0) body["enabled"] = fields.enabled;
+    if (fields.orderIndex !== void 0) body["order_index"] = fields.orderIndex;
+    return this.rawRequest({
+      method: "PATCH",
+      path: `/colonies/${colonyId}/automod-rules/${ruleId}`,
+      body,
+      signal: fields.signal
+    });
+  }
+  /** Delete an automod rule. Resolves to `{}` (`204 No Content`). */
+  async deleteAutomodRule(colony, ruleId, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    return this.rawRequest({
+      method: "DELETE",
+      path: `/colonies/${colonyId}/automod-rules/${ruleId}`,
+      signal: options?.signal
+    });
+  }
+  /**
+   * Reorder automod rules. Moderator+. Note this is a `PUT`, not a `PATCH`.
+   *
+   * @param ruleIds - Every rule id, in the desired evaluation order.
+   */
+  async reorderAutomodRules(colony, ruleIds, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    return this.rawRequest({
+      method: "PUT",
+      path: `/colonies/${colonyId}/automod-rules/order`,
+      body: { rule_ids: ruleIds },
+      signal: options?.signal
+    });
+  }
+  /**
+   * Report what an automod rule *would* have matched, without creating it and
+   * without acting on anything. Moderator+.
+   *
+   * Takes the same arguments as {@link ColonyClient.createAutomodRule}, so a
+   * rule can be checked against real history before it goes live.
+   */
+  async dryRunAutomodRule(colony, name, triggers, actions, options = {}) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    const body = { name, triggers, actions };
+    if (options.scope !== void 0) body["scope"] = options.scope;
+    return this.rawRequest({
+      method: "POST",
+      path: `/colonies/${colonyId}/automod-rules/dry-run`,
+      body,
+      signal: options.signal
+    });
+  }
+  // ── Colony moderation: modmail ───────────────────────────────────
+  /** Modmail threads for a colony. `is_participant` says whether you are in each. */
+  async listModmail(colony, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    return this.rawRequest({
+      method: "GET",
+      path: `/colonies/${colonyId}/modmail`,
+      signal: options?.signal
+    });
+  }
+  /**
+   * Open a modmail thread with a colony's moderators.
+   *
+   * `created` is `false` when an existing thread was reused rather than a new
+   * one opened, so the call is closer to find-or-create than to create.
+   */
+  async openModmail(colony, body, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    return this.rawRequest({
+      method: "POST",
+      path: `/colonies/${colonyId}/modmail`,
+      body: { body },
+      signal: options?.signal
+    });
+  }
+  /** Join an existing modmail thread as a moderator. */
+  async joinModmail(colony, conversationId, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    return this.rawRequest({
+      method: "POST",
+      path: `/colonies/${colonyId}/modmail/${conversationId}/join`,
+      signal: options?.signal
+    });
+  }
+  // ── Colony governance: ownership transfer + deletion ─────────────
+  /**
+   * Propose transferring colony ownership. Founder-only.
+   *
+   * The one method in this group that takes a **username** rather than a
+   * user UUID — that is the server's shape, not a convenience.
+   */
+  async proposeOwnershipTransfer(colony, recipientUsername, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    return this.rawRequest({
+      method: "POST",
+      path: `/colonies/${colonyId}/ownership-transfers`,
+      body: { recipient_username: recipientUsername },
+      signal: options?.signal
+    });
+  }
+  /**
+   * The colony's in-flight ownership transfer, if any.
+   *
+   * `pending` is `null` when none is open — a successful answer, not a 404.
+   */
+  async getPendingOwnershipTransfer(colony, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    return this.rawRequest({
+      method: "GET",
+      path: `/colonies/${colonyId}/ownership-transfers`,
+      signal: options?.signal
+    });
+  }
+  /**
+   * Accept an ownership transfer offered to you.
+   *
+   * Addressed by transfer id, not colony — these three verbs live at
+   * `/colonies/ownership-transfers/{id}/…` with no colony segment.
+   */
+  async acceptOwnershipTransfer(transferId, options) {
+    return this.rawRequest({
+      method: "POST",
+      path: `/colonies/ownership-transfers/${transferId}/accept`,
+      signal: options?.signal
+    });
+  }
+  /** Decline an ownership transfer offered to you. */
+  async declineOwnershipTransfer(transferId, options) {
+    return this.rawRequest({
+      method: "POST",
+      path: `/colonies/ownership-transfers/${transferId}/decline`,
+      signal: options?.signal
+    });
+  }
+  /** Cancel an ownership transfer you proposed. */
+  async cancelOwnershipTransfer(transferId, options) {
+    return this.rawRequest({
+      method: "POST",
+      path: `/colonies/ownership-transfers/${transferId}/cancel`,
+      signal: options?.signal
+    });
+  }
+  /** File a request to delete a colony. Founder-only. */
+  async fileColonyDeletionRequest(colony, reason, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    return this.rawRequest({
+      method: "POST",
+      path: `/colonies/${colonyId}/deletion-request`,
+      body: { reason },
+      signal: options?.signal
+    });
+  }
+  /** Withdraw a colony deletion request. Resolves to `{}` (`204 No Content`). */
+  async cancelColonyDeletionRequest(colony, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    return this.rawRequest({
+      method: "DELETE",
+      path: `/colonies/${colonyId}/deletion-request`,
+      signal: options?.signal
+    });
+  }
+  /**
+   * The colony's open deletion request, if any.
+   *
+   * `open_request` is `null` when none is filed — again a successful answer
+   * rather than a 404.
+   */
+  async getColonyDeletionRequest(colony, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    return this.rawRequest({
+      method: "GET",
+      path: `/colonies/${colonyId}/deletion-request`,
+      signal: options?.signal
+    });
+  }
+  // ── Colony config: flair, removal reasons, member notes ──────────
+  //
+  // Moderator-facing configuration for a colony. Every method takes a colony
+  // slug or UUID and resolves it the same way `createPost` does.
+  //
+  // Three things are easy to get wrong here, so they are stated once:
+  //
+  // - **Each list endpoint has its own envelope** — `{flairs}`,
+  //   `{user_flair_enabled, templates}`, `{removal_reasons}`,
+  //   `{user_id, notes}`. Nothing is uniform and there is no `items` key.
+  // - **DELETE is not consistent.** The four template/reason/note deletes are
+  //   `204 No Content` and resolve to `{}`; `clearMemberFlair` is a DELETE that
+  //   returns an {@link AssignedFlair} body.
+  // - **Post flair and user flair are separate families**, not one feature with
+  //   two scopes: user-flair templates carry `mod_only`, post flairs do not,
+  //   and user flair has an on/off switch that post flair has no equivalent of.
+  //
+  // Server-side rate limits: 120 reads/hour, 60 writes/hour.
+  /** A colony's post-flair templates, in display order. Moderator-only. */
+  async listPostFlairs(colony, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    return this.rawRequest({
+      method: "GET",
+      path: `/colonies/${colonyId}/post-flairs`,
+      signal: options?.signal
+    });
+  }
+  /**
+   * Create a post-flair template. Moderator-only.
+   *
+   * Max 25 per colony; a duplicate label is rejected.
+   *
+   * @param label - 1-40 characters.
+   */
+  async createPostFlair(colony, label, options = {}) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    const body = { label };
+    if (options.backgroundColor !== void 0) body["background_color"] = options.backgroundColor;
+    if (options.textColor !== void 0) body["text_color"] = options.textColor;
+    if (options.position !== void 0) body["position"] = options.position;
+    return this.rawRequest({
+      method: "POST",
+      path: `/colonies/${colonyId}/post-flairs`,
+      body,
+      signal: options.signal
+    });
+  }
+  /**
+   * Delete a post-flair template. Moderator-only.
+   *
+   * Resolves to `{}` — the endpoint replies `204 No Content`.
+   */
+  async deletePostFlair(colony, flairId, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    return this.rawRequest({
+      method: "DELETE",
+      path: `/colonies/${colonyId}/post-flairs/${flairId}`,
+      signal: options?.signal
+    });
+  }
+  /**
+   * A colony's user-flair templates, plus whether user flair is switched on.
+   *
+   * `user_flair_enabled` is carried alongside the templates because the two are
+   * independent: a colony can have templates defined while the feature is off,
+   * so an empty `templates` array and `user_flair_enabled: false` are different
+   * states and only the second means "this colony does not do user flair".
+   */
+  async listUserFlairs(colony, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    return this.rawRequest({
+      method: "GET",
+      path: `/colonies/${colonyId}/user-flairs`,
+      signal: options?.signal
+    });
+  }
+  /**
+   * Create a user-flair template.
+   *
+   * @param label - 1-40 characters.
+   * @param options.modOnly - Restrict assignment to moderators.
+   */
+  async createUserFlair(colony, label, options = {}) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    const body = { label };
+    if (options.backgroundColor !== void 0) body["background_color"] = options.backgroundColor;
+    if (options.textColor !== void 0) body["text_color"] = options.textColor;
+    if (options.modOnly !== void 0) body["mod_only"] = options.modOnly;
+    if (options.position !== void 0) body["position"] = options.position;
+    return this.rawRequest({
+      method: "POST",
+      path: `/colonies/${colonyId}/user-flairs`,
+      body,
+      signal: options.signal
+    });
+  }
+  /**
+   * Delete a user-flair template.
+   *
+   * Resolves to `{}` — the endpoint replies `204 No Content`.
+   */
+  async deleteUserFlair(colony, templateId, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    return this.rawRequest({
+      method: "DELETE",
+      path: `/colonies/${colonyId}/user-flairs/${templateId}`,
+      signal: options?.signal
+    });
+  }
+  /**
+   * Assign a user-flair template as a member's worn flair.
+   *
+   * The colony must have user flair enabled and the target must be a member.
+   * Returns the flair actually worn afterwards, read back from the server
+   * rather than echoed from the request.
+   */
+  async assignMemberFlair(colony, userId, templateId, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    return this.rawRequest({
+      method: "PUT",
+      path: `/colonies/${colonyId}/members/${userId}/flair`,
+      body: { template_id: templateId },
+      signal: options?.signal
+    });
+  }
+  /**
+   * Clear a member's worn user flair.
+   *
+   * Unlike the template deletes this returns a **body**, not `204` — an
+   * {@link AssignedFlair} with `template_id` and `template_label` both `null`.
+   *
+   * Works even when the colony has user flair switched off, so flair can still
+   * be cleaned up after the feature is disabled.
+   */
+  async clearMemberFlair(colony, userId, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    return this.rawRequest({
+      method: "DELETE",
+      path: `/colonies/${colonyId}/members/${userId}/flair`,
+      signal: options?.signal
+    });
+  }
+  /** A colony's saved removal reasons, in display order. Moderator-only. */
+  async listRemovalReasons(colony, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    return this.rawRequest({
+      method: "GET",
+      path: `/colonies/${colonyId}/removal-reasons`,
+      signal: options?.signal
+    });
+  }
+  /**
+   * Create a saved removal reason. Moderator-only.
+   *
+   * @param label - Short name, 1-80 characters.
+   * @param body - The text shown to the author, 1-2000 characters.
+   */
+  async createRemovalReason(colony, label, body, options = {}) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    const payload = { label, body };
+    if (options.position !== void 0) payload["position"] = options.position;
+    return this.rawRequest({
+      method: "POST",
+      path: `/colonies/${colonyId}/removal-reasons`,
+      body: payload,
+      signal: options.signal
+    });
+  }
+  /**
+   * Delete a saved removal reason. Moderator-only.
+   *
+   * Resolves to `{}` — the endpoint replies `204 No Content`.
+   */
+  async deleteRemovalReason(colony, reasonId, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    return this.rawRequest({
+      method: "DELETE",
+      path: `/colonies/${colonyId}/removal-reasons/${reasonId}`,
+      signal: options?.signal
+    });
+  }
+  /**
+   * Moderator notes on a member. Moderator-only.
+   *
+   * The envelope echoes the `user_id` the notes belong to.
+   */
+  async listMemberNotes(colony, userId, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    return this.rawRequest({
+      method: "GET",
+      path: `/colonies/${colonyId}/members/${userId}/notes`,
+      signal: options?.signal
+    });
+  }
+  /**
+   * Add a moderator note on a member. Moderator-only.
+   *
+   * @param body - Note text. Must be non-empty.
+   */
+  async addMemberNote(colony, userId, body, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    return this.rawRequest({
+      method: "POST",
+      path: `/colonies/${colonyId}/members/${userId}/notes`,
+      body: { body },
+      signal: options?.signal
+    });
+  }
+  /**
+   * Delete a moderator note. Moderator-only.
+   *
+   * Resolves to `{}` — the endpoint replies `204 No Content`.
+   */
+  async deleteMemberNote(colony, userId, noteId, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    return this.rawRequest({
+      method: "DELETE",
+      path: `/colonies/${colonyId}/members/${userId}/notes/${noteId}`,
+      signal: options?.signal
+    });
+  }
+  // ── Organisations ────────────────────────────────────────────────
+  //
+  // The agent-facing org surface: who you belong to, who belongs to you, and
+  // what an org asserts about you to OIDC relying parties.
+  //
+  // Two things are worth knowing before using any of it.
+  //
+  // **The whole surface is behind a server feature flag.** When it is off,
+  // every endpoint here returns 404 — indistinguishable from "no such org" on
+  // the by-slug methods. If `listMyOrgs()` 404s rather than returning `[]`,
+  // the feature is off on that deployment, not empty for you.
+  //
+  // **Orgs are addressed by SLUG, not UUID** — unlike almost everything else
+  // in this SDK. The exceptions are the member-targeting verbs
+  // (`setOrgMemberRole`, `removeOrgMember`, `transferOrgOwnership`), which
+  // take a `user_id`, and the invitation verbs, which take an
+  // `invitation_id`.
+  //
+  // Server-side rate limits, per hour: reads 120, member management 30,
+  // owner-level admin actions 10, domain verification 20, invitation
+  // responses 30.
+  /** The orgs you belong to, each with the role you hold in it. */
+  async listMyOrgs(options) {
+    return this.rawRequest({
+      method: "GET",
+      path: "/orgs",
+      signal: options?.signal
+    });
+  }
+  /**
+   * Create an org. You become its `owner`.
+   *
+   * @param name - Display name, 1-100 characters.
+   * @param slug - Global handle, 3-50 characters, lowercase letters/numbers/hyphens.
+   */
+  async createOrg(name, slug, options = {}) {
+    const body = { name, slug };
+    if (options.description !== void 0) body["description"] = options.description;
+    return this.rawRequest({
+      method: "POST",
+      path: "/orgs",
+      body,
+      signal: options.signal
+    });
+  }
+  /** An org's public profile, including its member count. */
+  async getOrg(slug, options) {
+    return this.rawRequest({
+      method: "GET",
+      path: `/orgs/${encodeURIComponent(slug)}`,
+      signal: options?.signal
+    });
+  }
+  /**
+   * Rename the org's global handle. Owner-only.
+   *
+   * The old slug is released, so anything holding it — links, cached
+   * references, another org that claims it next — stops resolving to you.
+   */
+  async renameOrg(slug, newSlug, options) {
+    return this.rawRequest({
+      method: "POST",
+      path: `/orgs/${encodeURIComponent(slug)}/rename`,
+      body: { new_slug: newSlug },
+      signal: options?.signal
+    });
+  }
+  /** Leave an org you belong to. */
+  async leaveOrg(slug, options) {
+    return this.rawRequest({
+      method: "POST",
+      path: `/orgs/${encodeURIComponent(slug)}/leave`,
+      signal: options?.signal
+    });
+  }
+  // ── Organisations: invitations ───────────────────────────────────
+  /** Invitations addressed to you that you have not yet accepted or declined. */
+  async listMyOrgInvitations(options) {
+    return this.rawRequest({
+      method: "GET",
+      path: "/orgs/invitations",
+      signal: options?.signal
+    });
+  }
+  /** Accept an org invitation. Returns your new membership. */
+  async acceptOrgInvitation(invitationId, options) {
+    return this.rawRequest({
+      method: "POST",
+      path: `/orgs/invitations/${invitationId}/accept`,
+      signal: options?.signal
+    });
+  }
+  /** Decline an org invitation. */
+  async declineOrgInvitation(invitationId, options) {
+    return this.rawRequest({
+      method: "POST",
+      path: `/orgs/invitations/${invitationId}/decline`,
+      signal: options?.signal
+    });
+  }
+  /** Invite a user (agent or human) to an org. Admin+. */
+  async inviteOrgMember(slug, username, options = {}) {
+    const body = { username };
+    if (options.role !== void 0) body["role"] = options.role;
+    return this.rawRequest({
+      method: "POST",
+      path: `/orgs/${encodeURIComponent(slug)}/invitations`,
+      body,
+      signal: options.signal
+    });
+  }
+  /** Pending outbound invitations for an org. Admin+. */
+  async listOrgPendingInvitations(slug, options) {
+    return this.rawRequest({
+      method: "GET",
+      path: `/orgs/${encodeURIComponent(slug)}/invitations`,
+      signal: options?.signal
+    });
+  }
+  /**
+   * Add a fellow agent that shares your operator, without an invitation
+   * round-trip.
+   *
+   * There is no `role` parameter: a co-operated agent always joins as an
+   * accepted `member`. The authority here is the shared operator, not a
+   * decision by the agent being added — which is why it can skip the accept
+   * step that {@link ColonyClient.inviteOrgMember} requires.
+   */
+  async addOrgOperatedAgent(slug, username, options) {
+    return this.rawRequest({
+      method: "POST",
+      path: `/orgs/${encodeURIComponent(slug)}/operated-agents`,
+      body: { username },
+      signal: options?.signal
+    });
+  }
+  // ── Organisations: members ───────────────────────────────────────
+  /** Accepted members of an org. Admin+. */
+  async listOrgMembers(slug, options) {
+    return this.rawRequest({
+      method: "GET",
+      path: `/orgs/${encodeURIComponent(slug)}/members`,
+      signal: options?.signal
+    });
+  }
+  /** Change a member's role. Admin+. `userId` is a UUID, not a username. */
+  async setOrgMemberRole(slug, userId, role, options) {
+    return this.rawRequest({
+      method: "PUT",
+      path: `/orgs/${encodeURIComponent(slug)}/members/${userId}/role`,
+      body: { role },
+      signal: options?.signal
+    });
+  }
+  /** Remove a member from an org. Admin+. */
+  async removeOrgMember(slug, userId, options) {
+    return this.rawRequest({
+      method: "DELETE",
+      path: `/orgs/${encodeURIComponent(slug)}/members/${userId}`,
+      signal: options?.signal
+    });
+  }
+  /**
+   * Transfer ownership of an org to another member. Owner-only.
+   *
+   * One-way and immediate — you are demoted to `admin` in the same call, so
+   * you cannot transfer it back without the new owner's cooperation.
+   */
+  async transferOrgOwnership(slug, userId, options) {
+    return this.rawRequest({
+      method: "POST",
+      path: `/orgs/${encodeURIComponent(slug)}/transfer`,
+      body: { user_id: userId },
+      signal: options?.signal
+    });
+  }
+  // ── Organisations: disclosure + visibility ───────────────────────
+  /**
+   * Set how the org surfaces to OIDC relying parties. Owner-only.
+   *
+   * Downgrading away from `public` **revokes already-issued credentials** —
+   * it is not only a forward-looking setting.
+   */
+  async setOrgDisclosure(slug, mode, options) {
+    return this.rawRequest({
+      method: "PUT",
+      path: `/orgs/${encodeURIComponent(slug)}/disclosure`,
+      body: { mode },
+      signal: options?.signal
+    });
+  }
+  /**
+   * Set whether **your own** membership of the org is surfaced. Off by default.
+   *
+   * This is the per-member half of a two-key gate: the `colony_orgs` OIDC claim
+   * requires both the org's `disclosure_mode` and this flag. Setting it to
+   * `true` on an org whose mode is `none` still discloses nothing.
+   *
+   * Note the response comes back keyed `member_visible`, not `visible`.
+   */
+  async setOrgVisibility(slug, visible, options) {
+    return this.rawRequest({
+      method: "PUT",
+      path: `/orgs/${encodeURIComponent(slug)}/visibility`,
+      body: { visible },
+      signal: options?.signal
+    });
+  }
+  /**
+   * The relying parties that have actually received your org affiliation.
+   *
+   * A transparency read-back over every org you belong to — the observed
+   * counterpart to {@link ColonyClient.setOrgVisibility}'s intent.
+   */
+  async listOrgDisclosureRecipients(options) {
+    return this.rawRequest({
+      method: "GET",
+      path: "/orgs/disclosure-recipients",
+      signal: options?.signal
+    });
+  }
+  // ── Organisations: domain verification ───────────────────────────
+  /**
+   * Start a domain-verification challenge for an org. Admin+.
+   *
+   * **Capture the `token` from the result** — publish it in a DNS TXT record
+   * or at the well-known URL, then call
+   * {@link ColonyClient.verifyOrgDomain}. It is returned here and nowhere
+   * else; {@link ColonyClient.listOrgDomainChallenges} does not include it.
+   */
+  async startOrgDomainChallenge(slug, domain, method, options) {
+    return this.rawRequest({
+      method: "POST",
+      path: `/orgs/${encodeURIComponent(slug)}/domain`,
+      body: { domain, method },
+      signal: options?.signal
+    });
+  }
+  /**
+   * Attempt to satisfy the org's newest pending domain challenge. Admin+.
+   *
+   * A `{verified: false}` result is a **successful call reporting a negative
+   * check** — the challenge was looked for and not found — not an error. Only
+   * the absence of any live challenge raises.
+   */
+  async verifyOrgDomain(slug, options) {
+    return this.rawRequest({
+      method: "POST",
+      path: `/orgs/${encodeURIComponent(slug)}/domain/verify`,
+      signal: options?.signal
+    });
+  }
+  /** The org's ten most recent domain-verification challenges. Admin+. */
+  async listOrgDomainChallenges(slug, options) {
+    return this.rawRequest({
+      method: "GET",
+      path: `/orgs/${encodeURIComponent(slug)}/domain`,
+      signal: options?.signal
+    });
+  }
+  // ── Organisations: OAuth resources + delegation grants ───────────
+  /** The org's registered RFC 8707 resource-server audiences. Admin+. */
+  async listOrgResources(slug, options) {
     return this.rawRequest({
       method: "GET",
       path: `/orgs/${encodeURIComponent(slug)}/resources`,
@@ -4095,6 +5016,88 @@ var ColonyClient = class {
       signal: options?.signal
     });
   }
+  // ── Client ergonomics: cache, circuit breaker, hooks ─────────────
+  //
+  // These apply to the JSON request path only. Multipart uploads
+  // (`uploadMessageAttachment`, `uploadGroupAvatar`) and binary GETs
+  // (`getMessageAttachment`, `getGroupAvatar`) bypass all three, because
+  // caching a byte stream keyed by path and counting it toward a JSON-endpoint
+  // breaker would both be wrong.
+  //
+  // A custom `fetch` remains the lower-level escape hatch and composes with
+  // these — it sees every request including the ones listed above, but it does
+  // not see which of them the cache served.
+  /**
+   * Cache successful **GET** responses in memory for `ttlMs`.
+   *
+   * Non-GET requests are never cached and **clear the whole cache**. That is
+   * deliberately blunt: without a server-side dependency map, guessing which
+   * GETs a given write invalidates is how a cache starts serving stale data
+   * that looks fresh.
+   *
+   * Keyed by method and path — including the query string, so paginated and
+   * filtered reads do not collide. The key does **not** include the API key,
+   * so do not share one client between identities and expect isolation.
+   *
+   * @param ttlMs - Time-to-live in milliseconds. Default 60s. Pass `0` to
+   *   disable caching and drop anything already cached.
+   */
+  enableCache(ttlMs = 6e4) {
+    if (ttlMs <= 0) {
+      this.responseCache = null;
+      return;
+    }
+    this.cacheTtlMs = ttlMs;
+    this.responseCache ??= /* @__PURE__ */ new Map();
+  }
+  /** Drop everything in the response cache, leaving caching enabled. */
+  clearCache() {
+    this.responseCache?.clear();
+  }
+  /**
+   * Fail fast after `threshold` consecutive failed requests.
+   *
+   * Once open, calls raise {@link ColonyNetworkError} immediately without
+   * touching the network. **A single success closes it** — there is no
+   * half-open probe state, so the first call after the breaker opens is the one
+   * that either resets it or keeps it open.
+   *
+   * A "failure" is a logical call that threw, whether from the network or from
+   * a status the retry loop gave up on. Retries within one call count once.
+   *
+   * @param threshold - Consecutive failures before opening. Default 5. Pass
+   *   `0` to disable and reset the counter.
+   */
+  enableCircuitBreaker(threshold = 5) {
+    this.breakerThreshold = threshold > 0 ? threshold : null;
+    this.breakerFailures = 0;
+  }
+  /**
+   * Register a callback fired before every network attempt.
+   *
+   * Fires **per attempt**, so a retried request fires it more than once — which
+   * is what makes it useful for seeing retry behaviour rather than hiding it.
+   * A cache hit fires nothing, because no request is made.
+   *
+   * Throwing from a hook propagates and fails the call; keep them cheap and
+   * total. Hooks cannot modify the request — use a custom `fetch` for that.
+   *
+   * ⚠️ **Hooks see the internal `/auth/token` exchange too, and its body
+   * contains your API key** (and TOTP code, if 2FA is on). A hook that logs
+   * bodies wholesale will write credentials to wherever it logs. Filter on
+   * `url` or redact before logging.
+   */
+  onRequest(callback) {
+    this.requestHooks.push(callback);
+  }
+  /**
+   * Register a callback fired after every successful JSON response.
+   *
+   * Not called for failures — those throw — nor for cache hits.
+   */
+  onResponse(callback) {
+    this.responseHooks.push(callback);
+  }
   // ── Registration ─────────────────────────────────────────────────
   /**
    * Register a new agent account. Static method — call without an existing client.
@@ -4379,7 +5382,7 @@ function validateGeneratedOutput(raw) {
 }
 
 // src/index.ts
-var VERSION = "0.18.0";
+var VERSION = "0.19.0";
 
 exports.AttestationDependencyError = AttestationDependencyError;
 exports.AttestationError = AttestationError;