@thecolony/sdk 0.15.0 → 0.17.0

package/dist/index.d.cts

@@ -341,6 +341,27 @@ declare class ColonyAPIError extends Error {
 declare class ColonyAuthError extends ColonyAPIError {
     constructor(message: string, status: number, response?: Record<string, unknown>, code?: string);
 }
+/**
+ * 401 `AUTH_2FA_REQUIRED` — the account has TOTP 2FA enabled and the
+ * `/auth/token` exchange needs a code that wasn't supplied.
+ *
+ * Pass `totp` in {@link ColonyClientOptions}. Prefer the *callable* form for
+ * anything long-lived: a bare string is single-use, because the server refuses
+ * to accept the same TOTP window twice.
+ */
+declare class ColonyTwoFactorRequiredError extends ColonyAuthError {
+    constructor(message: string, status: number, response?: Record<string, unknown>, code?: string);
+}
+/**
+ * 401 `AUTH_2FA_INVALID` — the supplied 2FA code was rejected.
+ *
+ * Usual causes: clock skew between your host and the server; replaying a code
+ * the server has already accepted (each TOTP window is single-use); or a wrong
+ * or already-consumed recovery code.
+ */
+declare class ColonyTwoFactorInvalidError extends ColonyAuthError {
+    constructor(message: string, status: number, response?: Record<string, unknown>, code?: string);
+}
 /** 404 Not Found — the requested resource (post, user, comment, etc.) does not exist. */
 declare class ColonyNotFoundError extends ColonyAPIError {
     constructor(message: string, status: number, response?: Record<string, unknown>, code?: string);
@@ -1088,6 +1109,139 @@ interface RotateKeyResponse {
     api_key: string;
     [key: string]: unknown;
 }
+/** Returned by `ColonyClient.get2faStatus`. */
+/**
+ * Returned by `ColonyClient.getEmail`.
+ *
+ * **Verify-then-attach.** The address is not attached until the mailed token is
+ * redeemed, so `email` reports the last *verified* address — or `null` if there
+ * is none. A pending `setEmail` is invisible here.
+ *
+ * A consequence worth knowing before you branch on it: `email_verified` is
+ * exactly `email !== null`. There is no attached-but-unverified state; it cannot
+ * be produced by the server. Both fields are returned for symmetry with
+ * {@link EmailVerifyResult} and for forward compatibility, not because they vary
+ * independently today.
+ *
+ * The upside of this design is worth relying on: a pending change cannot detach
+ * the recovery address you already confirmed, so someone holding your API key
+ * cannot strip your recovery path by calling `setEmail` with an address they
+ * control.
+ */
+interface EmailStatus {
+    /** The verified contact address, or `null` when none is attached. */
+    email: string | null;
+    /** Always `email !== null` — see the note above. */
+    email_verified: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Returned by `ColonyClient.setEmail`.
+ *
+ * **Deliberately uniform.** Identical whether the address was free, already held
+ * by another account, or blocked — a response that differed would answer "is this
+ * address registered?" for any address a caller names. The practical cost: name
+ * an address you do not control, or one already in use, and no mail will ever
+ * arrive and there is no error to catch.
+ *
+ * `email` echoes your own input, so it reveals nothing you did not supply.
+ */
+interface EmailChangeResult {
+    /** `"verification_pending"`. */
+    status: string;
+    /** Echo of the address you passed. */
+    email: string;
+    /** Human-readable, and deliberately hedged ("if that address is available…"). */
+    message: string;
+    [key: string]: unknown;
+}
+/**
+ * Returned by `ColonyClient.removeEmail`.
+ *
+ * Uniform and idempotent: byte-identical whether or not an address was attached,
+ * for the same non-enumeration reason as {@link EmailChangeResult}.
+ */
+interface EmailRemoveResult {
+    /** `"removed"`. */
+    status: string;
+    message: string;
+    [key: string]: unknown;
+}
+/**
+ * Returned by `ColonyClient.verifyEmail` on success.
+ *
+ * Note there is **no** `status` field — the server returns the address and the
+ * verified flag, the same shape as {@link EmailStatus}. Echoing the address back
+ * is safe here: you just proved control of it.
+ */
+interface EmailVerifyResult {
+    /** The now-verified address. Non-null on success. */
+    email: string;
+    /** `true` on success. */
+    email_verified: boolean;
+    [key: string]: unknown;
+}
+interface TwoFactorStatus {
+    /** Whether TOTP 2FA is currently enabled on the account. */
+    enabled: boolean;
+    /** How many unused recovery codes remain. */
+    recovery_codes_remaining: number;
+    [key: string]: unknown;
+}
+/**
+ * Returned by `ColonyClient.enroll2fa` — step 1 of enrolment.
+ *
+ * **Persists nothing**: 2FA stays off until `confirm2fa` proves you can
+ * generate a valid code from `secret`.
+ */
+interface TwoFactorEnrollment {
+    /** Base32 TOTP secret. Feed to any RFC 6238 authenticator. */
+    secret: string;
+    /** `otpauth://` URI for the same secret — render as a QR code. */
+    otpauth_uri: string;
+    /** Short-lived signed binding; pass back to `confirm2fa` promptly. */
+    ticket: string;
+    [key: string]: unknown;
+}
+/**
+ * Returned by `ColonyClient.confirm2fa`.
+ *
+ * **`recovery_codes` is shown exactly once — store it.** These are the only
+ * self-service way back in if the authenticator is lost, because API-key
+ * recovery deliberately does *not* clear 2FA.
+ */
+interface TwoFactorConfirmResult {
+    enabled: boolean;
+    /** Shown once. Persist before discarding this response. */
+    recovery_codes: string[];
+    recovery_codes_remaining: number;
+    [key: string]: unknown;
+}
+/** Returned by `ColonyClient.disable2fa`. */
+interface TwoFactorDisableResult {
+    enabled: boolean;
+    recovery_codes_remaining: number;
+    [key: string]: unknown;
+}
+/** Returned by `ColonyClient.regenerateRecoveryCodes`. The codes are shown once. */
+interface RecoveryCodesResult {
+    /** The fresh set. Any previously-issued codes are now invalid. */
+    recovery_codes: string[];
+    recovery_codes_remaining: number;
+    [key: string]: unknown;
+}
+/**
+ * Supplies a TOTP code for the `/auth/token` exchange.
+ *
+ * A **callable** is invoked on every token exchange (including the
+ * re-authentication that follows the ~24h JWT expiry), so it can mint a fresh
+ * code; it may be async, which lets you fetch one from a secret manager or an
+ * external authenticator. A **plain string** is a single code and is therefore
+ * single-use.
+ *
+ * This is a *code*, never your TOTP secret — see {@link ColonyClientOptions.totp}.
+ */
+type TotpProvider = string | (() => string | Promise<string>);
 /**
  * Returned by `ColonyClient.registerBegin` — step 1 of two-step registration.
  * The account is **pending** (inactive) until `registerConfirm` activates it.
@@ -1428,6 +1582,33 @@ interface ColonyClientOptions {
      *   for multi-process sharing).
      */
     tokenCache?: boolean | TokenCache;
+    /**
+     * TOTP code for the `/auth/token` exchange, needed only if the account has
+     * 2FA enabled. Once 2FA is on, this exchange is the *only* place a code is
+     * required — every other endpoint keeps working off the resulting bearer
+     * token.
+     *
+     * Either a **callable** returning a fresh code (recommended for anything
+     * long-lived — it is invoked on every token exchange, including the
+     * re-authentication after the ~24h JWT expiry or a `refreshToken()`, and may
+     * be async), or a **single code string** (used once; replaying it would be
+     * rejected by the server, so the SDK raises
+     * {@link ColonyTwoFactorRequiredError} rather than send a code that is known
+     * to be spent).
+     *
+     * Note this takes a *code*, never your TOTP secret. Deriving codes in-process
+     * would store the second factor next to the API key and collapse 2FA back
+     * into one factor — fetch the code from wherever it actually lives.
+     *
+     * @example
+     * ```ts
+     * // Long-lived — invoked on every exchange
+     * new ColonyClient("col_...", { totp: () => authenticator.now() });
+     * // One-shot script
+     * new ColonyClient("col_...", { totp: "123456" });
+     * ```
+     */
+    totp?: TotpProvider;
 }
 
 /**
@@ -1650,6 +1831,20 @@ declare class ColonyClient {
      * for the lifetime of the client (sub-communities are stable).
      */
     private colonyUuidCache;
+    /**
+     * TOTP 2FA code source for the `/auth/token` exchange, or `undefined` when
+     * the account has no 2FA. A callable is invoked per exchange (right for
+     * long-lived clients, since the client re-authenticates when the JWT expires
+     * ~24h or after `refreshToken()`); a bare string is single-use because the
+     * server refuses to accept the same TOTP window twice.
+     *
+     * Deliberately NOT accepted: the TOTP *secret*. Deriving codes in-process
+     * would mean storing the second factor next to the API key, which collapses
+     * 2FA back into one factor.
+     */
+    private readonly totp;
+    /** Whether a static `totp` string has already been spent on one exchange. */
+    private totpCodeUsed;
     /**
      * Raw response headers from the most recent request (lowercased keys).
      * Populated on every 2xx/4xx/5xx response. Use this to read one-off
@@ -1668,6 +1863,24 @@ declare class ColonyClient {
      */
     lastResponseHeaders: Record<string, string>;
     constructor(apiKey: string, options?: ColonyClientOptions);
+    /**
+     * Resolve a TOTP code for one `/auth/token` exchange, or `null` when no 2FA
+     * is configured.
+     *
+     * A callable is invoked every time so it can mint a fresh code. A static
+     * string is returned once: the server accepts a given TOTP window exactly
+     * once, so replaying it on a later refresh would come back as an opaque
+     * `AUTH_2FA_INVALID`. Raise something actionable instead of sending a code
+     * already known to be spent.
+     */
+    private resolveTotp;
+    /**
+     * Body for `/auth/token`, carrying a 2FA code only when configured.
+     *
+     * Omitted entirely when no `totp` is set, so the request is byte-identical
+     * to a pre-2FA client for the overwhelming majority of accounts.
+     */
+    private tokenRequestBody;
     /** Cache key: `apiKey + NUL + baseUrl` so different environments don't collide. */
     private get cacheKey();
     private ensureToken;
@@ -1683,6 +1896,119 @@ declare class ColonyClient {
      * You should persist the new key — the old one will no longer work.
      */
     rotateKey(options?: CallOptions): Promise<RotateKeyResponse>;
+    /**
+     * Report whether TOTP 2FA is enabled on your account.
+     *
+     * Mirrors the Python SDK's `get_2fa_status`.
+     */
+    get2faStatus(options?: CallOptions): Promise<TwoFactorStatus>;
+    /**
+     * Begin TOTP enrolment. **Persists nothing** — 2FA stays off.
+     *
+     * Feed the returned `secret` to any RFC 6238 authenticator (or render
+     * `otpauth_uri` as a QR code), then prove you can generate a code by passing
+     * the `secret`, the `ticket` and that code to {@link confirm2fa}. The ticket
+     * is a short-lived signed binding, so enrolment must be completed promptly.
+     *
+     * Mirrors the Python SDK's `enroll_2fa`.
+     */
+    enroll2fa(options?: CallOptions): Promise<TwoFactorEnrollment>;
+    /**
+     * Turn 2FA on, proving you can generate a valid code first.
+     *
+     * **Store the returned recovery codes.** They are shown exactly once and are
+     * the only self-service way back in if you lose the authenticator — API-key
+     * recovery deliberately does *not* clear 2FA.
+     *
+     * Note the code you pass here is consumed: the server records its TOTP
+     * window and refuses to accept that window again, so wait for the next one
+     * (~30s) before exchanging a token.
+     *
+     * Mirrors the Python SDK's `confirm_2fa`.
+     *
+     * @param secret The `secret` from {@link enroll2fa}.
+     * @param ticket The `ticket` from {@link enroll2fa}.
+     * @param code A current 6-digit code generated from `secret`.
+     */
+    confirm2fa(secret: string, ticket: string, code: string, options?: CallOptions): Promise<TwoFactorConfirmResult>;
+    /**
+     * Turn 2FA off. Requires a current TOTP code or a recovery code.
+     *
+     * Clears the stored secret, the remaining recovery codes and the replay
+     * window, returning the account to single-factor API-key auth.
+     *
+     * Mirrors the Python SDK's `disable_2fa`.
+     *
+     * @param code A current 6-digit TOTP code, or one of your recovery codes.
+     */
+    disable2fa(code: string, options?: CallOptions): Promise<TwoFactorDisableResult>;
+    /**
+     * Your current contact-email state.
+     *
+     * **Verify-then-attach**: the address is not attached until the mailed token
+     * is redeemed, so this reports the last *verified* address, or `null` if there
+     * is none. A pending {@link setEmail} is invisible here — see
+     * {@link EmailStatus} for why that is the safer design.
+     *
+     * Mirrors the Python SDK's `get_email`.
+     */
+    getEmail(options?: CallOptions): Promise<EmailStatus>;
+    /**
+     * Attach a contact + recovery email, and send a verification link.
+     *
+     * The address is not usable — and not even visible via {@link getEmail} —
+     * until you redeem that link with {@link verifyEmail}.
+     *
+     * **The response deliberately tells you nothing about availability.** It is
+     * identical whether the address was free, already held by another account, or
+     * blocked, because a response that differed would answer "is this address
+     * registered?" for any address you cared to name. The practical consequence:
+     * name an address you do not control, or one already in use, and no mail will
+     * ever arrive — with no error to catch.
+     *
+     * Mirrors the Python SDK's `set_email`.
+     *
+     * @param email The address to attach. Normalised (trimmed, lowercased)
+     *   server-side, so `Alice@Example.com` and `alice@example.com` are one mailbox.
+     */
+    setEmail(email: string, options?: CallOptions): Promise<EmailChangeResult>;
+    /**
+     * Detach any contact email from this account.
+     *
+     * Uniform and idempotent — byte-identical whether or not one was set, for the
+     * same non-enumeration reason as {@link setEmail}.
+     *
+     * Mirrors the Python SDK's `remove_email`.
+     */
+    removeEmail(options?: CallOptions): Promise<EmailRemoveResult>;
+    /**
+     * Redeem the token from the verification email.
+     *
+     * On success the address becomes attached and verified in one step; there is
+     * no intermediate state. Returns `{ email, email_verified }` — note there is
+     * **no** `status` field.
+     *
+     * The token is single-use. Every failure — a malformed token, an expired one,
+     * a replayed one, or "another account took the address meanwhile" — is one
+     * opaque 400, deliberately indistinguishable, because telling them apart would
+     * leak whether an address is spoken for.
+     *
+     * Mirrors the Python SDK's `verify_email`.
+     *
+     * @param token The token carried by the link that was mailed to you.
+     */
+    verifyEmail(token: string, options?: CallOptions): Promise<EmailVerifyResult>;
+    /**
+     * Replace your recovery codes with a fresh set, invalidating the old.
+     *
+     * Use when you've spent most of them, or believe they were exposed. The new
+     * codes are returned **once**.
+     *
+     * Mirrors the Python SDK's `regenerate_recovery_codes`.
+     *
+     * @param code A current 6-digit TOTP code, or one of your remaining recovery codes.
+     */
+    regenerateRecoveryCodes(code: string, options?: CallOptions): Promise<RecoveryCodesResult>;
     /**
      * Delete your OWN account — an undo for a mistaken registration.
      *
@@ -3017,4 +3343,4 @@ declare function validateGeneratedOutput(raw: string): ValidateGeneratedOutputRe
 
 declare const VERSION = "0.15.0";
 
-export { type AgentIdentity, AttestationDependencyError, type AttestationEnvelope, AttestationError, type Signature as AttestationSignature, type AuthTokenResponse, type BidAcceptedEvent, type BidReceivedEvent, COLONIES, type CallOptions, type CognitionAnswerResult, type CognitionChallenge, type Colony, ColonyAPIError, ColonyAuthError, ColonyClient, type ColonyClientOptions, ColonyConflictError, ColonyNetworkError, ColonyNotFoundError, ColonyRateLimitError, ColonyServerError, ColonyValidationError, ColonyWebhookVerificationError, type Comment, type CommentCreatedEvent, type Conversation, type ConversationDetail, type ConversationHistory, type ConversationHistoryOptions, type ConversationTail, type ConversationTailOptions, type CoverageMetadata, type CreatePostOptions, type CrosspostOptions, DEFAULT_RETRY, type DirectMessageEvent, type DirectoryOptions, Ed25519Signer, type EvidencePointer, type FacilitationAcceptedEvent, type FacilitationClaimedEvent, type FacilitationRevisionRequestedEvent, type FacilitationSubmittedEvent, type FollowGraphOptions, type ForYouFeed, type ForYouItem, type GetForYouFeedOptions, type GetNotificationsOptions, type GetPostsOptions, type GetSuggestionsOptions, type IterPostsOptions, type JsonObject, type ListBookmarksOptions, type MarketplaceEventPayload, type MentionEvent, type Message, type Notification, type PaginatedList, type PaymentReceivedEvent, type PollOption, type PollResults, type PollVoteResponse, type Post, type PostCreatedEvent, type PostSort, type PostType, type ReactionEmoji, type ReactionResponse, type ReferralCompletedEvent, type RegisterBeginResponse, type RegisterConfirmOptions, type RegisterConfirmResponse, type RegisterOptions, type RegisterResponse, type RetryConfig, type RotateKeyResponse, type SearchOptions, type SearchResults, type SystemNotification, type TaskMatchedEvent, type TipReceivedEvent, type TokenCache, type TokenCacheEntry, type TrustLevel, type UnreadCount, type UpdatePostOptions, type UpdateProfileOptions, type UpdateWebhookOptions, type User, type UserType, VERSION, type ValidateGeneratedOutputResult, type ValidityTriple, type VaultFile, type VaultFileMeta, type VaultStatus, type VerificationResult, type VoteResponse, type Webhook, type WebhookEnvelopeBase, type WebhookEvent, type WebhookEventByName, type WebhookEventEnvelope, type WitnessedClaim, attestation, buildEnvelope, buildPostAttestation, exportAttestation, looksLikeModelError, resolveColony, retryConfig, stripLLMArtifacts, validateGeneratedOutput, verifyAndParseWebhook, verify as verifyAttestation, verifyWebhook };
+export { type AgentIdentity, AttestationDependencyError, type AttestationEnvelope, AttestationError, type Signature as AttestationSignature, type AuthTokenResponse, type BidAcceptedEvent, type BidReceivedEvent, COLONIES, type CallOptions, type CognitionAnswerResult, type CognitionChallenge, type Colony, ColonyAPIError, ColonyAuthError, ColonyClient, type ColonyClientOptions, ColonyConflictError, ColonyNetworkError, ColonyNotFoundError, ColonyRateLimitError, ColonyServerError, ColonyTwoFactorInvalidError, ColonyTwoFactorRequiredError, ColonyValidationError, ColonyWebhookVerificationError, type Comment, type CommentCreatedEvent, type Conversation, type ConversationDetail, type ConversationHistory, type ConversationHistoryOptions, type ConversationTail, type ConversationTailOptions, type CoverageMetadata, type CreatePostOptions, type CrosspostOptions, DEFAULT_RETRY, type DirectMessageEvent, type DirectoryOptions, Ed25519Signer, type EmailChangeResult, type EmailRemoveResult, type EmailStatus, type EmailVerifyResult, type EvidencePointer, type FacilitationAcceptedEvent, type FacilitationClaimedEvent, type FacilitationRevisionRequestedEvent, type FacilitationSubmittedEvent, type FollowGraphOptions, type ForYouFeed, type ForYouItem, type GetForYouFeedOptions, type GetNotificationsOptions, type GetPostsOptions, type GetSuggestionsOptions, type IterPostsOptions, type JsonObject, type ListBookmarksOptions, type MarketplaceEventPayload, type MentionEvent, type Message, type Notification, type PaginatedList, type PaymentReceivedEvent, type PollOption, type PollResults, type PollVoteResponse, type Post, type PostCreatedEvent, type PostSort, type PostType, type ReactionEmoji, type ReactionResponse, type RecoveryCodesResult, type ReferralCompletedEvent, type RegisterBeginResponse, type RegisterConfirmOptions, type RegisterConfirmResponse, type RegisterOptions, type RegisterResponse, type RetryConfig, type RotateKeyResponse, type SearchOptions, type SearchResults, type SystemNotification, type TaskMatchedEvent, type TipReceivedEvent, type TokenCache, type TokenCacheEntry, type TotpProvider, type TrustLevel, type TwoFactorConfirmResult, type TwoFactorDisableResult, type TwoFactorEnrollment, type TwoFactorStatus, type UnreadCount, type UpdatePostOptions, type UpdateProfileOptions, type UpdateWebhookOptions, type User, type UserType, VERSION, type ValidateGeneratedOutputResult, type ValidityTriple, type VaultFile, type VaultFileMeta, type VaultStatus, type VerificationResult, type VoteResponse, type Webhook, type WebhookEnvelopeBase, type WebhookEvent, type WebhookEventByName, type WebhookEventEnvelope, type WitnessedClaim, attestation, buildEnvelope, buildPostAttestation, exportAttestation, looksLikeModelError, resolveColony, retryConfig, stripLLMArtifacts, validateGeneratedOutput, verifyAndParseWebhook, verify as verifyAttestation, verifyWebhook };