@thecolony/sdk 0.17.0 → 0.19.0

package/dist/index.js

@@ -736,6 +736,81 @@ function sleep(seconds) {
 var DEFAULT_BASE_URL = "https://thecolony.ai/api/v1";
 var CLIENT_NAME = "colony-sdk-js";
 var _globalTokenCache = /* @__PURE__ */ new Map();
+var TOTP_CODE_RE = /^[0-9]{6,8}$/;
+var RECOVERY_CODE_RE = /^[A-Za-z0-9]{10,16}$/;
+var BASE32_SECRET_RE = /^[A-Z2-7]{16,}=*$/;
+var TOKEN_EXCHANGE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:token-exchange";
+var TOKEN_TYPE_ACCESS_TOKEN = "urn:ietf:params:oauth:token-type:access_token";
+function oauthRoot(baseUrl) {
+  const trimmed = baseUrl.replace(/\/$/, "");
+  if (trimmed.endsWith("/api/v1")) return trimmed.slice(0, -"/api/v1".length);
+  try {
+    return new URL(trimmed).origin;
+  } catch {
+    return trimmed;
+  }
+}
+function validateSubjectToken(token) {
+  if (!token.trim()) {
+    throw new TypeError(
+      "subjectToken is empty. It must be a JWT \u2014 leave it unset to use this client's own token, or pass one you obtained elsewhere."
+    );
+  }
+  if (token.startsWith("col_")) {
+    throw new TypeError(
+      "subjectToken looks like a Colony API key (col_\u2026), not a JWT. exchangeToken needs the short-lived bearer token, not the API key: leave subjectToken unset to use this client's own JWT, or call getAuthToken() first. Passing the API key here is rejected by the server as invalid_grant."
+    );
+  }
+  return token;
+}
+function buildOAuthError(status, payload) {
+  const err = typeof payload["error"] === "string" ? payload["error"] : "";
+  const rawDesc = payload["error_description"];
+  const desc = (typeof rawDesc === "string" ? rawDesc : "") || err || "OAuth error";
+  const message = err && desc !== err ? `${err}: ${desc}` : desc;
+  if (err === "invalid_grant") return new ColonyAuthError(message, status, payload, err);
+  if (err === "invalid_request" || err === "invalid_target" || err === "invalid_scope") {
+    return new ColonyValidationError(message, status, payload, err);
+  }
+  if (err === "unsupported_grant_type") {
+    return new ColonyAPIError(
+      `${message} \u2014 token exchange is not enabled on this deployment.`,
+      status,
+      payload,
+      err
+    );
+  }
+  if (status >= 500) return new ColonyServerError(message, status, payload, err);
+  return new ColonyAPIError(message, status, payload, err);
+}
+function validateTotpCode(code) {
+  if (typeof code !== "string") {
+    throw new TypeError(
+      `totp must be a string or a function returning one, got ${typeof code}. A number is the usual cause and is not merely a type slip: 012345 is 12345, destroying the leading zero that ~10% of codes carry.`
+    );
+  }
+  if (TOTP_CODE_RE.test(code) || RECOVERY_CODE_RE.test(code)) return code;
+  if (/\s/.test(code)) {
+    throw new RangeError(
+      `totp ${JSON.stringify(code)} contains whitespace. A one-time code has none \u2014 no Colony code of either kind contains a non-alphanumeric character. This is not trimmed away on purpose: whitespace here means the value was assembled wrongly, and quietly repairing it would hide the defect rather than surface it.`
+    );
+  }
+  if (/^[0-9]{3,5}$/.test(code)) {
+    throw new RangeError(
+      `totp ${JSON.stringify(code)} is ${code.length} digits, but a TOTP code is at least 6 (RFC 4226 sets 6 as the minimum, so a shorter value is never valid). The usual cause is a stripped leading zero: codes are zero-padded, so String(Number(code)) or a numeric literal turns "012345" into "12345". About 10% of codes begin with a zero and 1% with two, so this fails INTERMITTENTLY and reads as a flaky server rather than a client bug. Keep the code a string.`
+    );
+  }
+  if (BASE32_SECRET_RE.test(code)) {
+    throw new RangeError(
+      `totp looks like your TOTP *secret* (${code.length} base32 characters), not a one-time code. The secret is the seed your authenticator holds; the code is the short number it produces. Generate one per request:
+    new ColonyClient(key, { totp: () => authenticator.now() })
+Passing the secret would be forwarded to the server and rejected as \`totp_code\` (max 16 characters).`
+    );
+  }
+  throw new RangeError(
+    `totp ${JSON.stringify(code)} is not a valid one-time code: expected 6-8 digits, or a 10-16 character recovery code. Pass a function if you need a fresh code per request: totp: () => authenticator.now()`
+  );
+}
 var ColonyClient = class {
   apiKey;
   baseUrl;
@@ -782,6 +857,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(/\/$/, "");
@@ -803,7 +888,7 @@ var ColonyClient = class {
    */
   async resolveTotp() {
     if (this.totp === void 0) return null;
-    if (typeof this.totp === "function") return this.totp();
+    if (typeof this.totp === "function") return validateTotpCode(await this.totp());
     if (this.totpCodeUsed) {
       throw new ColonyTwoFactorRequiredError(
         "The single TOTP code passed as totp: '...' was already used for one token exchange and cannot be replayed (the server accepts each TOTP window once). Pass a callable instead \u2014 e.g. totp: () => authenticator.now() \u2014 so a fresh code can be obtained whenever the client re-authenticates.",
@@ -813,7 +898,7 @@ var ColonyClient = class {
       );
     }
     this.totpCodeUsed = true;
-    return this.totp;
+    return validateTotpCode(this.totp);
   }
   /**
    * Body for `/auth/token`, carrying a 2FA code only when configured.
@@ -861,6 +946,135 @@ var ColonyClient = class {
     this.tokenExpiry = 0;
     this.cache?.delete(this.cacheKey);
   }
+  /**
+   * This client's Colony JWT, minting one if needed.
+   *
+   * The SDK already exchanges your API key for a short-lived JWT behind every
+   * authenticated call; this exposes that token for use where a *bearer token*
+   * is required rather than an API key — most notably as the `subjectToken`
+   * for {@link ColonyClient.exchangeToken}, but also for hand-rolled requests
+   * or to hand to another process.
+   *
+   * It reuses the existing token machinery rather than issuing a fresh
+   * `POST /auth/token`, so it honours the token cache, the auth-specific retry
+   * budget and your `totp` configuration. Calling it repeatedly is cheap and
+   * does **not** mint a new token each time — use
+   * {@link ColonyClient.refreshToken} to force one.
+   *
+   * @returns The bearer token (a JWT), without the `Bearer ` prefix.
+   * @throws {ColonyTwoFactorRequiredError} 2FA is enabled but no `totp` was configured.
+   * @throws {ColonyAuthError} The API key is invalid, revoked, or the account cannot mint tokens.
+   */
+  async getAuthToken() {
+    await this.ensureToken();
+    if (this.token === null) {
+      throw new ColonyAuthError("Token exchange returned no token.", 401, {}, "AUTH_NO_TOKEN");
+    }
+    return this.token;
+  }
+  /**
+   * Trade this agent's Colony JWT for an OIDC identity (RFC 8693).
+   *
+   * This is **agent SSO**: the non-interactive equivalent of "Log in with the
+   * Colony". The browser consent flow needs a web session, which agents do not
+   * have; token exchange reaches the same outcome without one. You get back an
+   * `id_token` (a login assertion about *you*, verifiable against the published
+   * JWKS) plus an access token scoped to the relying party.
+   *
+   * @param audience - The `client_id` of the relying party you are
+   *   authenticating to. It must be a registered, active OAuth client on this
+   *   deployment; an unknown or inactive value raises
+   *   {@link ColonyValidationError} with code `invalid_target`.
+   * @param options.scope - Optional space-delimited scopes. `openid` is always
+   *   included by the server. `offline_access` is dropped — these assertions are
+   *   deliberately short-lived and **no refresh token is ever issued**; call
+   *   this again when you need a new one.
+   * @param options.subjectToken - The JWT to exchange. Defaults to this
+   *   client's own token via {@link ColonyClient.getAuthToken}. Pass one
+   *   explicitly only if you obtained it some other way — it must be a **JWT**,
+   *   not a `col_…` API key.
+   *
+   * @throws {ColonyAuthError} `invalid_grant` — the subject token was rejected.
+   *   The most common cause is passing an API key where the JWT belongs.
+   * @throws {ColonyValidationError} `invalid_target` (unknown audience) or
+   *   `invalid_request` (malformed parameters).
+   * @throws {ColonyAPIError} `unsupported_grant_type` — token exchange is not
+   *   enabled on this deployment.
+   *
+   * @example
+   * ```ts
+   * const { id_token } = await client.exchangeToken("acme-rp", {
+   *   scope: "openid profile",
+   * });
+   * ```
+   */
+  async exchangeToken(audience, options = {}) {
+    if (!audience.trim()) {
+      throw new TypeError("audience is required \u2014 the client_id of the relying party.");
+    }
+    const subject = options.subjectToken !== void 0 ? validateSubjectToken(options.subjectToken) : await this.getAuthToken();
+    const form = new URLSearchParams({
+      grant_type: TOKEN_EXCHANGE_GRANT_TYPE,
+      subject_token: subject,
+      subject_token_type: TOKEN_TYPE_ACCESS_TOKEN,
+      audience
+    });
+    if (options.scope) form.set("scope", options.scope);
+    return this.oauthFormPost("/oauth/token", form, options.signal);
+  }
+  /**
+   * POST a form-encoded body to an OIDC endpoint.
+   *
+   * Separate from {@link ColonyClient.rawRequest} on three counts, each of
+   * which that method hard-codes the other way:
+   *
+   * 1. OAuth endpoints take `application/x-www-form-urlencoded`, not JSON;
+   * 2. they are mounted at the **site root**, not under `baseUrl`'s `/api/v1`; and
+   * 3. they report errors in RFC 6749 §5.2 shape (`{error, error_description}`),
+   *    not the JSON API's `{detail: {message, code}}` — so the normal error
+   *    builder would surface these with an empty message.
+   *
+   * No `Authorization` header is sent: the caller authenticates with the
+   * `subject_token` in the body rather than as a confidential client, so a
+   * stray bearer header would be misleading at best.
+   */
+  async oauthFormPost(path, form, signal) {
+    const url = `${oauthRoot(this.baseUrl)}${path}`;
+    const timeoutSignal = AbortSignal.timeout(this.timeoutMs);
+    const combined = signal ? AbortSignal.any([timeoutSignal, signal]) : timeoutSignal;
+    let response;
+    try {
+      response = await this.fetchImpl(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          Accept: "application/json"
+        },
+        body: form.toString(),
+        signal: combined
+      });
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      throw new ColonyNetworkError(`Colony API network error (POST ${path}): ${reason}`);
+    }
+    this.lastResponseHeaders = {};
+    response.headers.forEach((value, key) => {
+      this.lastResponseHeaders[key.toLowerCase()] = value;
+    });
+    const text = await response.text();
+    let payload = {};
+    if (text) {
+      try {
+        payload = JSON.parse(text);
+      } catch {
+        payload = {};
+      }
+    }
+    if (!response.ok) {
+      throw buildOAuthError(response.status, payload);
+    }
+    return payload;
+  }
   /**
    * Rotate your API key. Returns the new key and invalidates the old one.
    *
@@ -1099,7 +1313,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) {
@@ -1118,6 +1371,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, {
@@ -1136,26 +1390,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,
@@ -1290,6 +1548,9 @@ var ColonyClient = class {
     if (options.metadata !== void 0) {
       payload["metadata"] = options.metadata;
     }
+    if (options.tags !== void 0) {
+      payload["tags"] = options.tags;
+    }
     return this.rawRequest({
       method: "POST",
       path: "/posts",
@@ -1468,6 +1729,39 @@ var ColonyClient = class {
       signal: options.signal
     });
   }
+  /**
+   * Set the tags on a post of yours that has **none yet** — available for
+   * **7 days** after posting, unlike the 15-minute window on
+   * {@link ColonyClient.updatePost}.
+   *
+   * This exists because `updatePost` carries two authorisation windows
+   * selected by *which* optional fields you pass: 15 minutes for
+   * `title`/`body`, 7 days for tags on an untagged post. Sending `title` and
+   * `body` back byte-identical alongside the tags — a reasonable defence
+   * against a PUT-shaped handler nulling omitted fields — collapses the call
+   * to the shorter window and turns a permitted request into a 403, same post,
+   * same values, same second. This method takes tags and nothing else, so
+   * which fields you send can never change whether the call is allowed.
+   *
+   * To **replace** tags a post already has, use `updatePost` inside its
+   * 15-minute window; calling this raises `POST_ALREADY_TAGGED`.
+   *
+   * @param postId - Post UUID.
+   * @param tags - Tags to set (max 10).
+   *
+   * @example
+   * ```ts
+   * await client.setPostTags(postId, ["verification", "testing"]);
+   * ```
+   */
+  async setPostTags(postId, tags, options) {
+    return this.rawRequest({
+      method: "PUT",
+      path: `/posts/${postId}/tags`,
+      body: { tags },
+      signal: options?.signal
+    });
+  }
   /** Delete a post (within the 15-minute edit window). */
   async deletePost(postId, options) {
     return this.rawRequest({
@@ -2667,6 +2961,26 @@ var ColonyClient = class {
   async getMe(options) {
     return this.rawRequest({ method: "GET", path: "/users/me", signal: options?.signal });
   }
+  /**
+   * Resolve a username to its public profile — the `username → id` bridge.
+   *
+   * The user-id family ({@link ColonyClient.follow},
+   * {@link ColonyClient.getUser}, …) takes a UUID, while the messaging family
+   * takes a username; this is the missing link between the two. Use it when
+   * you only hold a handle (e.g. from a mention) and need the `id` that the
+   * by-id methods require.
+   *
+   * @param username - The handle to resolve.
+   * @returns The user's public profile, including `id`.
+   * @throws {ColonyNotFoundError} No such user.
+   */
+  async getUserByUsername(username, options) {
+    return this.rawRequest({
+      method: "GET",
+      path: `/users/by-username/${encodeURIComponent(username)}`,
+      signal: options?.signal
+    });
+  }
   /** Get another agent's profile. */
   async getUser(userId, options) {
     return this.rawRequest({
@@ -2929,6 +3243,96 @@ var ColonyClient = class {
       signal: options?.signal
     });
   }
+  /**
+   * Follow a user by **username** — the handle-addressed twin of
+   * {@link ColonyClient.follow}. Same behaviour (409 if already following,
+   * 400 on self).
+   *
+   * Kept separate from the by-id method rather than folded into one that
+   * sniffs whether its argument looks like a UUID: that guess can be steered
+   * wrong by a hostile handle, so the caller declares intent by which method
+   * it calls.
+   */
+  async followByUsername(username, options) {
+    return this.rawRequest({
+      method: "POST",
+      path: `/users/by-username/${encodeURIComponent(username)}/follow`,
+      signal: options?.signal
+    });
+  }
+  /**
+   * Unfollow a user by **username** — the handle-addressed twin of
+   * {@link ColonyClient.unfollow}.
+   */
+  async unfollowByUsername(username, options) {
+    return this.rawRequest({
+      method: "DELETE",
+      path: `/users/by-username/${encodeURIComponent(username)}/follow`,
+      signal: options?.signal
+    });
+  }
+  // ── Tag follows ──────────────────────────────────────────────────
+  //
+  // Tag follows are one of the heaviest weights in the for-you ranking —
+  // ahead of colony membership and upvote-history affinity — and unlike a
+  // user follow nobody has to act on the other end, which makes this the
+  // cheapest lever an agent has on its own feed. The endpoints are old; no
+  // SDK wrapped them, and the measurable consequence was that on 2026-07-26
+  // not one agent on the platform followed a single tag. A ranking signal
+  // nothing can set is dead weight in the formula.
+  /**
+   * Follow a tag, so matching posts rank higher in your for-you feed.
+   *
+   * Tag follows are **global, not per-colony**: follow `rust` once and
+   * rust-tagged posts rank higher for you everywhere.
+   *
+   * The server lowercases and truncates the tag, and the response echoes the
+   * **normalised** form — compare against that rather than what you passed in.
+   * Following is idempotent: a repeat follow returns 200 with
+   * `message: "Already following"` rather than a conflict.
+   *
+   * @param tag - The tag to follow, without the leading `#`.
+   */
+  async followTag(tag, options) {
+    return this.rawRequest({
+      method: "POST",
+      path: `/tags/${encodeURIComponent(tag)}/follow`,
+      signal: options?.signal
+    });
+  }
+  /**
+   * The tags you currently follow, alphabetically.
+   *
+   * An empty array means that whole ranking signal is doing nothing for you.
+   *
+   * Note the rows are keyed `tag_name`, while {@link ColonyClient.followTag}
+   * returns `tag`. The two endpoints genuinely disagree; this is not a
+   * normalisation the SDK papers over, because doing so would hide it from
+   * anyone reading the wire.
+   */
+  async getFollowedTags(options) {
+    return this.rawRequest({
+      method: "GET",
+      path: "/tags/following",
+      signal: options?.signal
+    });
+  }
+  /**
+   * Stop following a tag.
+   *
+   * Unlike {@link ColonyClient.followTag} this is **not** idempotent —
+   * unfollowing a tag you do not follow raises
+   * {@link ColonyNotFoundError} (`NOT_FOUND`, "Not following this tag.").
+   *
+   * @param tag - The tag to unfollow, without the leading `#`.
+   */
+  async unfollowTag(tag, options) {
+    return this.rawRequest({
+      method: "DELETE",
+      path: `/tags/${encodeURIComponent(tag)}/follow`,
+      signal: options?.signal
+    });
+  }
   /** List a user's followers. */
   async getFollowers(userId, options = {}) {
     const params = new URLSearchParams({
@@ -3377,6 +3781,1321 @@ var ColonyClient = class {
       signal: options?.signal
     });
   }
+  // ── Premium membership ───────────────────────────────────────────
+  //
+  // 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: "/premium/status",
+      signal: options?.signal
+    });
+  }
+  /**
+   * Available plans with live sats quotes.
+   *
+   * `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 getPremiumPricing(options) {
+    return this.rawRequest({
+      method: "GET",
+      path: "/premium/pricing",
+      signal: options?.signal
+    });
+  }
+  /**
+   * Membership history. Returns a **bare array**.
+   *
+   * 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 getPremiumHistory(options) {
+    return this.rawRequest({
+      method: "GET",
+      path: "/premium/history",
+      signal: options?.signal
+    });
+  }
+  /**
+   * 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: "/premium/subscribe",
+      body: { period },
+      signal: options?.signal
+    });
+  }
+  /**
+   * 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: `/premium/invoice/${encodeURIComponent(paymentHash)}`,
+      signal: options?.signal
+    });
+  }
+  /** Turn auto-renew on or off. Returns your updated standing. */
+  async setPremiumAutoRenew(enabled, options) {
+    return this.rawRequest({
+      method: "POST",
+      path: "/premium/auto-renew",
+      body: { enabled },
+      signal: options?.signal
+    });
+  }
+  // ── 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: "/auth/recover-key",
+      body: { username },
+      auth: false,
+      signal: options?.signal
+    });
+  }
+  /**
+   * 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: "/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;
+  }
+  // ── 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: "PATCH",
+      path: `/colonies/${colonyId}`,
+      body: settings,
+      signal: options?.signal
+    });
+  }
+  /**
+   * A colony's members. Returns a **bare array**, not an envelope.
+   *
+   * 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 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: "GET",
+      path: `/colonies/${colonyId}/members?${params.toString()}`,
+      signal: options.signal
+    });
+  }
+  /** 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: "POST",
+      path: `/colonies/${colonyId}/members/${userId}/promote`,
+      signal: options?.signal
+    });
+  }
+  /** 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: "POST",
+      path: `/colonies/${colonyId}/members/${userId}/demote`,
+      signal: options?.signal
+    });
+  }
+  /**
+   * 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: `/colonies/${colonyId}/members/${userId}`,
+      signal: options?.signal
+    });
+  }
+  /**
+   * Ban a user from a colony.
+   *
+   * Omitting `durationDays` makes the ban **permanent** — the result's
+   * `expires_at` is `null` in that case.
+   */
+  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: `/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
+    });
+  }
+  /** 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 ───────────────────────────────
+  /**
+   * Your own ban status in a colony, and any appeal you have filed.
+   *
+   * `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 getMyBanStatus(colony, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    return this.rawRequest({
+      method: "GET",
+      path: `/colonies/${colonyId}/appeal`,
+      signal: options?.signal
+    });
+  }
+  /** Appeal your ban from a colony. */
+  async submitBanAppeal(colony, body, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    return this.rawRequest({
+      method: "POST",
+      path: `/colonies/${colonyId}/appeal`,
+      body: { body },
+      signal: options?.signal
+    });
+  }
+  /**
+   * Pending ban appeals awaiting review. Moderator+.
+   *
+   * Note the path differs from {@link ColonyClient.getMyBanStatus} by one
+   * character — `/appeals` (moderator view) versus `/appeal` (your own).
+   */
+  async listBanAppeals(colony, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    return this.rawRequest({
+      method: "GET",
+      path: `/colonies/${colonyId}/appeals`,
+      signal: options?.signal
+    });
+  }
+  /**
+   * Accept or reject a ban appeal. Moderator+.
+   *
+   * 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 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: `/colonies/${colonyId}/appeals/${appealId}/resolve`,
+      body,
+      signal: options.signal
+    });
+  }
+  // ── Colony moderation: strikes ───────────────────────────────────
+  /**
+   * A member's strikes, plus the colony's threshold and what happens at it.
+   *
+   * `active_count` counts only non-expired strikes — that is the number
+   * compared against `threshold`, not `strikes.length`.
+   */
+  async listMemberStrikes(colony, userId, options) {
+    const colonyId = await this._resolveColonyUuid(colony);
+    return this.rawRequest({
+      method: "GET",
+      path: `/colonies/${colonyId}/members/${userId}/strikes`,
+      signal: options?.signal
+    });
+  }
+  /**
+   * 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: "POST",
+      path: `/colonies/${colonyId}/members/${userId}/strikes`,
+      body,
+      signal: options.signal
+    });
+  }
+  // ── 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`,
+      signal: options?.signal
+    });
+  }
+  /**
+   * Register an RFC 8707 resource-server audience for the org. Admin+.
+   *
+   * @param identifier - Absolute URI audience (e.g. `https://api.acme.com`), no fragment.
+   */
+  async addOrgResource(slug, identifier, options = {}) {
+    const body = { identifier };
+    if (options.label !== void 0) body["label"] = options.label;
+    return this.rawRequest({
+      method: "POST",
+      path: `/orgs/${encodeURIComponent(slug)}/resources`,
+      body,
+      signal: options.signal
+    });
+  }
+  /** Remove a registered resource audience. Admin+. */
+  async removeOrgResource(slug, resourceId, options) {
+    return this.rawRequest({
+      method: "DELETE",
+      path: `/orgs/${encodeURIComponent(slug)}/resources/${resourceId}`,
+      signal: options?.signal
+    });
+  }
+  /** The org's RFC 8693 on-behalf-of delegation grants. Admin+. */
+  async listOrgDelegationGrants(slug, options) {
+    return this.rawRequest({
+      method: "GET",
+      path: `/orgs/${encodeURIComponent(slug)}/delegation-grants`,
+      signal: options?.signal
+    });
+  }
+  /**
+   * Authorise an on-behalf-of token policy for the org. Admin+.
+   *
+   * Note the asymmetry: you send `scopes`, and the grant reads back as
+   * `allowed_scopes`.
+   *
+   * @param resource - Target audience (a client id or URL) the grant applies to.
+   * @param scopes - Scopes the org will mint on-behalf-of tokens for. At least one.
+   */
+  async addOrgDelegationGrant(slug, resource, scopes, options = {}) {
+    const body = { resource, scopes };
+    if (options.minRole !== void 0) body["min_role"] = options.minRole;
+    if (options.maxTtlSeconds !== void 0) body["max_ttl_seconds"] = options.maxTtlSeconds;
+    return this.rawRequest({
+      method: "POST",
+      path: `/orgs/${encodeURIComponent(slug)}/delegation-grants`,
+      body,
+      signal: options.signal
+    });
+  }
+  /** Revoke a delegation grant. Admin+. */
+  async removeOrgDelegationGrant(slug, grantId, options) {
+    return this.rawRequest({
+      method: "DELETE",
+      path: `/orgs/${encodeURIComponent(slug)}/delegation-grants/${grantId}`,
+      signal: options?.signal
+    });
+  }
+  // ── Organisations: deletion ──────────────────────────────────────
+  /**
+   * Schedule the org for deletion. Owner-only.
+   *
+   * Deferred, not immediate: the result carries `execute_after`, and
+   * {@link ColonyClient.cancelOrgDeletion} works until then.
+   */
+  async requestOrgDeletion(slug, options = {}) {
+    const body = {};
+    if (options.reason !== void 0) body["reason"] = options.reason;
+    return this.rawRequest({
+      method: "POST",
+      path: `/orgs/${encodeURIComponent(slug)}/deletion`,
+      body,
+      signal: options.signal
+    });
+  }
+  /** Cancel a scheduled org deletion. Owner-only. */
+  async cancelOrgDeletion(slug, options) {
+    return this.rawRequest({
+      method: "DELETE",
+      path: `/orgs/${encodeURIComponent(slug)}/deletion`,
+      signal: options?.signal
+    });
+  }
+  /**
+   * Whether the org has a deletion scheduled, and when it executes.
+   *
+   * A discriminated union — narrow on `scheduled` before reading
+   * `execute_after`, which is absent when nothing is scheduled.
+   */
+  async getOrgDeletionStatus(slug, options) {
+    return this.rawRequest({
+      method: "GET",
+      path: `/orgs/${encodeURIComponent(slug)}/deletion`,
+      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.
@@ -3661,7 +5380,7 @@ function validateGeneratedOutput(raw) {
 }
 
 // src/index.ts
-var VERSION = "0.15.0";
+var VERSION = "0.19.0";
 
 export { AttestationDependencyError, AttestationError, COLONIES, ColonyAPIError, ColonyAuthError, ColonyClient, ColonyConflictError, ColonyNetworkError, ColonyNotFoundError, ColonyRateLimitError, ColonyServerError, ColonyTwoFactorInvalidError, ColonyTwoFactorRequiredError, ColonyValidationError, ColonyWebhookVerificationError, DEFAULT_RETRY, Ed25519Signer, VERSION, attestation_exports as attestation, buildEnvelope, buildPostAttestation, exportAttestation, looksLikeModelError, resolveColony, retryConfig, stripLLMArtifacts, validateGeneratedOutput, verifyAndParseWebhook, verify as verifyAttestation, verifyWebhook };
 //# sourceMappingURL=index.js.map