@loomcycle/client 1.124.0 → 1.126.0

package/dist/types.d.ts

@@ -187,6 +187,81 @@ export interface RunPromptResponse {
     system: PromptBlock[];
     input: PromptBlock[];
 }
+/** Input for {@link LoomcycleClient.runFile} — one File-tool op on the inbox of
+ *  a run, from outside the run (`POST /v1/runs/{run_id}/file`). The run is the
+ *  path's; the fields are the tool's own, snake_case as on the wire. download
+ *  and upload are not offered here: they need a run's HTTP allowlist. */
+export type RunFileInput = {
+    op: "stat" | "ls" | "extract" | "import" | "keep" | "rm" | "clear";
+    /** stat / ls / rm / extract / import: `volume:inbox:<path>`, or a bare path in the inbox. */
+    path?: string;
+    /** keep: the inbox file to copy. */
+    from?: string;
+    /** keep: `volume:<name>:<path>` in a read-write dynamic volume of your tenant. */
+    to?: string;
+    overwrite?: boolean;
+    recursive?: boolean;
+    /** clear: one folder of the inbox to empty instead of all of it. */
+    prefix?: string;
+    images?: boolean;
+    max_rows?: number;
+    excerpt_chars?: number;
+    title?: string;
+    doc_path?: string;
+    scope?: string;
+    tags?: string[];
+    /** import: where the document came from, kept on it as a link back. */
+    source?: RunFileImportSource;
+    /** import: headings to add by line number, so a file whose structure is only
+     *  in its numbering imports as sections. The file is not changed, so the
+     *  document keeps the record of where it came from. */
+    headings?: RunFileImportHeading[];
+};
+/** import's `source`: the item's web link (a SharePoint `webUrl`, an email's
+ *  `webLink`), never a download or upload link. */
+export interface RunFileImportSource {
+    /** An http(s) link, at most 2048 bytes; a signature in its query is masked. */
+    url?: string;
+    kind?: "sharepoint" | "email" | "attachment" | "web" | "other";
+    /** One line, at most 300 characters. */
+    title?: string;
+}
+/** One entry of import's `headings`. Lines count from 1 in the file as it is;
+ *  give entries in increasing line order. */
+export type RunFileImportHeading = 
+/** The line itself becomes a heading; `lines` (1–10) joins a wrapped title. */
+{
+    line: number;
+    level: 2 | 3 | 4 | 5 | 6;
+    as: "heading";
+    lines?: number;
+}
+/** A heading with `title` is inserted before the line, which stays body text. */
+ | {
+    line: number;
+    level: 2 | 3 | 4 | 5 | 6;
+    as: "marker";
+    title: string;
+};
+/** What {@link LoomcycleClient.downloadRunInboxFile} returns: one inbox file's
+ *  bytes and what the server says about them. */
+export interface RunInboxDownload {
+    /** The bytes (empty for a HEAD request). */
+    bytes: Uint8Array;
+    /** 200, or 206 for a range. */
+    status: number;
+    /** The type the server served: the recorded type when it is one a browser
+     *  cannot run, else `application/octet-stream`. */
+    contentType: string;
+    /** The file's name, from Content-Disposition. */
+    filename: string;
+    /** SHA-256 (hex) of the file's bytes as served — the whole file, also for a range. */
+    sha256: string;
+    /** The producer the runtime recorded (`mcp:<server>/<tool>`, `http`, …), or
+     *  `unknown` when the file changed since it was kept. */
+    origin: string;
+    headers: Headers;
+}
 /** The reply from `GET /v1/runs/{run_id}/effective-config` — for every
  *  overridable field, the value this run will actually use and which layer
  *  decided it.
@@ -1361,6 +1436,11 @@ export interface ClientOptions {
      *  When present, attached as `Authorization: Bearer <token>` on
      *  every request. */
     authToken?: string;
+    /** A source of short-lived bearers, instead of `authToken` (pass one or
+     *  the other): every request asks it for the token, and a 401 is retried
+     *  once with the token it hands back. An app signed in through loomcycle
+     *  passes an `OAuthTokenProvider`, which refreshes before expiry. */
+    tokenProvider?: TokenProvider;
     /** Custom fetch implementation; defaults to global `fetch`.
      *  Useful for testing (vi.fn()) or for runtimes that ship their
      *  own fetch (e.g. node-fetch on older Node). */
@@ -2045,19 +2125,34 @@ export interface UserSummary {
     registered?: boolean;
     display_name?: string;
     access_mode?: string;
-    status?: string;
+    /** The registered user's status; `""` for a subject seen only in runs. */
+    status?: UserStatus | (string & {});
 }
 export interface ListUsersResponse {
     users: UserSummary[];
 }
-/** One first-class users-table row (POST/PATCH /v1/_users). The tenant is
- *  server-derived from the authenticated principal, never sent. */
+/** A first-class user's status.
+ *
+ *  - `active` — the user may do what its access mode and bindings allow.
+ *  - `disabled` — refused everywhere; its delegated tokens are retired.
+ *  - `pending` — provisioned by a sign-in gate whose new users await
+ *    approval: the person can sign in, but every request is refused until
+ *    {@link LoomcycleClient.approveUser} makes the user `active`. Only a gate
+ *    puts a user here and only the approval takes one out, so createUser and
+ *    updateUser refuse it.
+ *
+ *  Fields typed `UserStatus | (string & {})` still accept a status a newer
+ *  server adds. */
+export type UserStatus = "active" | "disabled" | "pending";
+/** One first-class users-table row (POST/PATCH /v1/_users). The tenant is the
+ *  authenticated principal's, or the one an admin or `auth:manage` caller
+ *  names with `opts.tenant`; it is never in the body. */
 export interface UserRecord {
     tenant_id: string;
     subject: string;
     display_name: string;
     access_mode: string;
-    status: string;
+    status: UserStatus | (string & {});
     created_at: string;
     created_by: string;
 }
@@ -2067,14 +2162,18 @@ export interface CreateUserBody {
     /** "tenant" (default) collaborates on the tenant's shared primitives;
      *  "isolated" confines the member to its own user scope. */
     access_mode?: string;
-    status?: string;
+    /** Default `active`. `pending` is refused (400 `invalid_status`). */
+    status?: "active" | "disabled" | (string & {});
 }
 /** PATCH body — an omitted key leaves the column unchanged; a present key
  *  (even the empty string) is applied. */
 export interface UpdateUserBody {
     display_name?: string;
     access_mode?: string;
-    status?: string;
+    /** `disabled` also retires the user's delegated tokens. `pending` is
+     *  refused (400 `invalid_status`), and `active` on a pending user with 409
+     *  `use_approve`: call {@link LoomcycleClient.approveUser} instead. */
+    status?: "active" | "disabled" | (string & {});
 }
 /** The show-once result of POST /v1/_users/{subject}/tokens. `token` is the
  *  plaintext bearer, returned exactly once and never retrievable again. */
@@ -2127,6 +2226,171 @@ export interface ListUserTokensResponse {
     subject: string;
     tokens: UserTokenMeta[];
 }
+/** One identity-provider account a user signs in with, from
+ *  GET /v1/_users/{subject}/identities. Never a secret. */
+export interface UserIdentity {
+    /** The configured sign-in gate. */
+    gate: string;
+    /** The provider's issuer, when it reports one. */
+    issuer?: string;
+    /** The account's subject at the provider. */
+    external_subject: string;
+    email?: string;
+    email_verified: boolean;
+    created_at: string;
+    /** Absent until the account has been used to sign in. */
+    last_login_at?: string;
+}
+export interface UserIdentitiesResponse {
+    subject: string;
+    identities: UserIdentity[];
+}
+/** A sign-in gate's kind. Fields typed with it still accept a kind a newer
+ *  server adds. */
+export type AuthGateKind = "token" | "password" | "oidc" | "oauth" | "external" | "device" | (string & {});
+/** One configured sign-in gate, from GET /v1/_authgate. Never key material. */
+export interface AuthGate {
+    name: string;
+    kind: AuthGateKind;
+    label: string;
+    /** Whether a browser can sign in through it. */
+    interactive: boolean;
+    /** The gate's identity map, when it has one: whether it may provision
+     *  beyond the new-user floor, the tenant it maps to (or the claim naming
+     *  it) and how it provisions users. */
+    trusted?: boolean;
+    tenant?: string;
+    tenant_claim?: string;
+    provision?: string;
+    /** An external gate's signing key. */
+    key?: AuthGateKey;
+    callback_url?: string;
+    discovery_url?: string;
+    /** With `probe: true`: what the external gate's discovery document said. */
+    probe?: AuthGateProbe;
+    /** An external gate's removal timing. */
+    on_removed?: AuthGateRemoval;
+}
+/** An external gate's key as configured: algorithm, key id and fingerprint,
+ *  or for an HMAC secret the NAME of the env var holding it — never a key. */
+export interface AuthGateKey {
+    alg: string;
+    kid?: string;
+    fingerprint?: string;
+    secret_env?: string;
+}
+/** Durations, e.g. `168h0m0s`; `erase_after` may be `never`. */
+export interface AuthGateRemoval {
+    unbind_after: string;
+    erase_after: string;
+}
+export interface AuthGateProbe {
+    reachable: boolean;
+    /** The discovery document's HTTP status. */
+    status?: number;
+    /** A failure class (`unreachable`, `status`, …), never the response. */
+    error?: string;
+    name_matches: boolean;
+    key_matches: boolean;
+    capabilities?: string[];
+}
+export interface AuthGateListResponse {
+    gates: AuthGate[];
+}
+/** POST /v1/_authgate/{gate}/invites. The tenant is `opts.tenant`, not a
+ *  field here. */
+export interface CreateInviteBody {
+    /** An existing user to give a login at this gate. It keeps its access mode
+     *  and groups: the invite may restate but never raise them. Omitted, the
+     *  invite makes a new user when it is redeemed. */
+    subject?: string;
+    /** A new user's access mode, `tenant` or `isolated`; default the gate's
+     *  new-user floor. Beyond the floor only on a trusted gate (403
+     *  `beyond_floor` otherwise). */
+    access_mode?: string;
+    /** Groups for the new user; each must exist in the tenant. */
+    groups?: string[];
+    /** Fix the login the invitee gets; otherwise the invitee picks one (409
+     *  `login_taken` if it is in use at the gate). */
+    login?: string;
+    email?: string;
+    /** How long the link lives, as a Go duration (`72h`); default and maximum
+     *  are the gate's. */
+    ttl?: string;
+    /** Where the person lands after redeeming: a path on the server, or one
+     *  of the gate's `allowed_return_to`. */
+    return_to?: string;
+}
+/** A one-time invite link. `url` carries the code in its fragment: hand it to
+ *  the person and do not log it. It is shown once — listing invites never
+ *  returns it. */
+export interface CreatedInvite {
+    invite_id: string;
+    url: string;
+    expires_at: string;
+}
+export type AuthInviteState = "live" | "redeemed" | "revoked" | "expired";
+/** One invite from GET /v1/_authgate/{gate}/invites. Never its code. */
+export interface AuthInvite {
+    invite_id: string;
+    gate: string;
+    tenant_id: string;
+    /** Set for an invite to an existing user. */
+    subject?: string;
+    access_mode?: string;
+    groups: string[];
+    login?: string;
+    email?: string;
+    return_to?: string;
+    /** The owner invite of a tenant that has never had a user. */
+    bootstrap?: boolean;
+    created_by?: string;
+    created_at: string;
+    expires_at: string;
+    state: AuthInviteState;
+    redeemed_at?: string;
+    redeemed_subject?: string;
+    revoked_at?: string;
+}
+export interface AuthInviteListResponse {
+    invites: AuthInvite[];
+}
+/** A one-time password-reset link; like {@link CreatedInvite}, `url`
+ *  carries the code and is shown once. */
+export interface CreatedPasswordReset {
+    reset_id: string;
+    url: string;
+    expires_at: string;
+}
+/** A user's login at one gate, from GET /v1/_authgate/{gate}/identities. */
+export interface GateIdentity {
+    gate: string;
+    login: string;
+    email?: string;
+    email_verified: boolean;
+    created_at: string;
+    last_login_at?: string;
+    /** Whether the user has a password set. */
+    has_password: boolean;
+    /** Whether the user has a confirmed authenticator. */
+    has_totp: boolean;
+}
+export interface GateIdentitiesResponse {
+    tenant_id: string;
+    subject: string;
+    identities: GateIdentity[];
+}
+/** GET /v1/_authgate/{gate}/tenant-status: what a website needs to decide
+ *  on an owner (bootstrap) invite, and nothing about who the users are. */
+export interface GateTenantStatus {
+    tenant_id: string;
+    /** Whether the tenant has a user now. */
+    has_users: boolean;
+    /** Whether it has ever had one; once true, no owner invite or owner create
+     *  by an `auth:manage` credential is possible again. */
+    bootstrapped: boolean;
+    bootstrap_invite_live: boolean;
+}
 /** One entry in the runnable-agent catalog — the name to run + its tier.
  *  Intentionally lean: no operator metadata (versions, retired, hashes). */
 export interface RunnableAgent {
@@ -2161,6 +2425,8 @@ export interface WhoamiResponse {
     /** How the caller signed in. Absent on a server that predates Web UI
      *  sessions. */
     auth?: WhoamiAuth;
+    /** What narrows the caller's token below its scopes, when anything does. */
+    restrictions?: TokenRestrictions;
 }
 /** GET /v1/_me's sign-in block. `mode` is always present; the rest only when
  *  a Web UI session (not a bearer) authenticated the request. */
@@ -2175,6 +2441,10 @@ export interface WhoamiAuth {
     auth_time?: string;
     /** When the session stops authenticating unless renewed by activity. */
     session_expires_at?: string;
+    /** `pending` when the session's user awaits approval: every other request
+     *  the session makes is refused until the user is approved. Absent
+     *  otherwise. */
+    status?: "pending";
 }
 /** GET /v1/_me's capability summary. Bounded and non-secret: a fixed list of
  *  Web UI pages, no per-instance data. */
@@ -2391,11 +2661,12 @@ export interface MemorySearchInput {
      *
      *  The four document filters need a search that can return documents (no
      *  `sources`, or `sources` including `"documents"`; otherwise 400
-     *  `invalid_filter`), are refused on `scope: "tenant"` (400 `invalid_filter`),
-     *  and need SQL Memory on the server (400 `filter_unavailable`). They resolve in
-     *  the caller's own tenant. The response then carries {@link
-     *  MemorySearchResponse.filter}. For chunk-level filters (type, status, tags, a
-     *  validity instant) use `document({ op: "search" })`. */
+     *  `invalid_filter`) and SQL Memory on the server (400 `filter_unavailable`).
+     *  They resolve in the caller's own tenant. With a {@link documentsScope}
+     *  different from `scope` they aim at that scope's documents instead. The
+     *  response then carries {@link MemorySearchResponse.filter}. For chunk-level
+     *  filters (type, status, tags, a validity instant) use
+     *  `document({ op: "search" })`. */
     underPaths?: string[];
     /** Never return the chunks of documents named at or under these paths (sent as
      *  `exclude_under_paths`). Documents only, as {@link underPaths}. */
@@ -2406,6 +2677,23 @@ export interface MemorySearchInput {
     /** Never return the chunks of these documents (sent as
      *  `exclude_document_ids`). Documents only, as {@link underPaths}. */
     excludeDocumentIds?: string[];
+    /** Also search the DOCUMENTS of this scope in the same call (sent as
+     *  `documents_scope`): for example a user's own notes together with the
+     *  tenant's reference documents. Both are ranked into one list under one
+     *  `topK`, and each entry then carries {@link MemorySearchEntry.scope}. Only
+     *  documents come from this scope; facts and notes still come from `scope`.
+     *  The four document filters aim at this scope's documents.
+     *
+     *  Equal to `scope` (and {@link documentsScopeId} omitted or equal to
+     *  `scopeId`), it is the same as adding `"documents"` to `sources`. It cannot
+     *  be combined with `sources: ["traces"]` (400 `invalid_documents_scope`). A
+     *  caller whose access does not reach that scope's documents gets 403. */
+    documentsScope?: "agent" | "user" | "tenant";
+    /** The subject of {@link documentsScope} (sent as `documents_scope_id`): the
+     *  agent name or user id. Required when `documentsScope` is `"agent"` or
+     *  `"user"` and differs from `scope`; ignored for `"tenant"`. The tenant is
+     *  always the caller's own. */
+    documentsScopeId?: string;
 }
 /** What a document filter on {@link LoomcycleClient.memorySearch} resolved to —
  *  present on the response ONLY when a filter was sent. */
@@ -2427,6 +2715,9 @@ export interface MemorySearchDocumentFilter {
      *  false while access-control rules can deny the caller reading part of the
      *  scope — the counts then cover only documents it may read. */
     inverted: boolean;
+    /** The scope the filter resolved in — present when it aimed at a
+     *  {@link MemorySearchInput.documentsScope} different from `scope`. */
+    scope?: "agent" | "user" | "tenant";
 }
 /** The observed-time predicate on {@link MemorySearchInput}. Timestamps are
  *  RFC3339 instants — resolve phrases like "the first weekend of October"
@@ -2501,6 +2792,10 @@ export interface MemorySearchEntry {
         kind: "description" | "claim" | "question";
         text: string;
     };
+    /** The scope this hit came from — present on every entry when the request
+     *  set a {@link MemorySearchInput.documentsScope} different from `scope`, so
+     *  the caller's own memory can be told from the other scope's documents. */
+    scope?: "agent" | "user" | "tenant";
 }
 export interface MemorySearchResponse {
     scope: string;
@@ -2518,6 +2813,11 @@ export interface MemorySearchResponse {
     /** What the document filter resolved to — present only when one was sent
      *  ({@link MemorySearchInput.underPaths} and its siblings). */
     filter?: MemorySearchDocumentFilter;
+    /** The second scope searched for documents and its store scope id ("" for
+     *  tenant) — present only when the request set a
+     *  {@link MemorySearchInput.documentsScope} different from `scope`. */
+    documents_scope?: "agent" | "user" | "tenant";
+    documents_scope_id?: string;
 }
 export interface MemoryTimeFilter {
     mode: "prefer" | "require";
@@ -4342,6 +4642,16 @@ export interface AgentTranscription {
     /** At most the operator's `transcription.stt.max_minutes_per_run`. */
     max_minutes_per_run?: number;
 }
+/** An agent's text-to-speech settings. It can switch speech off for the agent
+ *  and lower the operator's per-run character cap; it can never raise it or
+ *  pick an engine, a model or a voice list. */
+export interface AgentSpeech {
+    /** Whether the agent may speak. Default `true` when the operator configured
+     *  an engine; `false` switches it off for this agent. */
+    enabled?: boolean;
+    /** At most the operator's `speech.max_chars_per_run`. */
+    max_chars_per_run?: number;
+}
 /** The `context` block of an {@link AgentDefOverlay}: {@link ContextOptions}
  *  in its wire spelling — see there for what each field does. A fork merges it
  *  per field, and the spawn tree inherits it. */
@@ -4538,6 +4848,8 @@ export interface AgentDefOverlay {
     compaction?: AgentCompaction;
     /** OCR and speech-to-text settings, merged per field. */
     transcription?: AgentTranscription;
+    /** Text-to-speech settings, merged per field. */
+    speech?: AgentSpeech;
     /** How history is distilled, merged per field. */
     context?: AgentContext;
     /** Volumes the file and exec tools may resolve paths against. None declared
@@ -5409,7 +5721,17 @@ export interface LLMEmbeddingsResponse {
     usage: LLMEmbeddingsUsage;
 }
 /** A whitelisted grouping dimension for the usage report. */
-export type UsageDimension = "tenant" | "user" | "provider" | "model" | "source";
+export type UsageDimension = "tenant" | "user" | "provider" | "model" | "source"
+/** What the calls were for (see `UsageAggregate.purpose`). */
+ | "purpose"
+/** The model tier the calls were resolved through; "pinned" for a named model. */
+ | "tier" | "user_tier"
+/** The agent that made the calls — the per-call detail window only. */
+ | "agent"
+/** foreground | background, derived from the purpose. */
+ | "class";
+/** The period a usage report splits its window into (UTC; weeks start Monday). */
+export type UsageBucket = "hour" | "day" | "week" | "month";
 /** One grouped row of a usage report; only the grouped dimensions are set. */
 export interface UsageAggregate {
     tenant_id?: string;
@@ -5418,6 +5740,21 @@ export interface UsageAggregate {
     model?: string;
     /** operator | tenant | user */
     credential_source?: string;
+    /** chat | gateway | consolidation | rerank | decision | compaction | recap |
+     *  unit_generation | image_description | embedding | ocr | stt | tts — set
+     *  when grouped by `purpose`. */
+    purpose?: string;
+    tier?: string;
+    user_tier?: string;
+    agent?: string;
+    /** foreground | background — set when grouped by `class`. */
+    class?: string;
+    /** RFC 3339 start of the UTC period the row sums, when a bucket was asked for. */
+    period?: string;
+    /** The row folds every value of the first dimension outside `top`. */
+    other?: boolean;
+    /** Characters text-to-speech and embedding calls sent; absent when none. */
+    input_chars?: number;
     input_tokens: number;
     output_tokens: number;
     cache_creation_tokens: number;
@@ -5426,12 +5763,20 @@ export interface UsageAggregate {
     currency?: string;
     call_count: number;
     unpriced_calls: number;
+    /** Seconds of audio the group's speech calls transcribed (stt) or produced
+     *  (tts), the unit a per-minute price is computed from; absent when it has none. */
+    audio_seconds?: number;
 }
 export interface UsageReportResponse {
     group_by: string[];
     from?: string;
     to?: string;
+    bucket?: UsageBucket;
     rows: UsageAggregate[];
+    /** The oldest instant the per-call ledger holds; before it only whole days
+     *  survive, so hour buckets and the agent dimension stop there. Absent when
+     *  nothing is archived. */
+    detail_since?: string;
 }
 /** A per-scope token budget (RFC AW) plus its live month-to-date usage.
  *  `soft_limit` / `hard_limit` are absent when that tier is unset (no ceiling
@@ -6754,3 +7099,239 @@ export interface AuthzSimulateResponse {
     /** Lists the draft's bindings name that no layer has. */
     missing_acls: string[] | null;
 }
+/** The authorization server's metadata (RFC 8414), from
+ *  `GET /.well-known/oauth-authorization-server`. Published only when the
+ *  server knows its public address (`LOOMCYCLE_PUBLIC_URL`). */
+export interface OAuthServerMetadata {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    revocation_endpoint: string;
+    response_types_supported: string[];
+    grant_types_supported: string[];
+    code_challenge_methods_supported: string[];
+    token_endpoint_auth_methods_supported: string[];
+    revocation_endpoint_auth_methods_supported: string[];
+    /** The server adds `iss` to every authorization response (RFC 9207). */
+    authorization_response_iss_parameter_supported: boolean;
+}
+/** The token endpoint's answer (RFC 6749 §5.1). */
+export interface OAuthTokenResponse {
+    access_token: string;
+    /** Always `Bearer`. */
+    token_type: string;
+    /** Seconds the access token lives. */
+    expires_in: number;
+    /** Single use: each refresh returns a new one and spends the old one.
+     *  Presenting a spent one ends the whole sign-in. */
+    refresh_token: string;
+}
+/** A token answer with the moment the access token expires — what a caller
+ *  persists. */
+export interface OAuthTokenSet extends OAuthTokenResponse {
+    /** When the access token expires, in milliseconds since the epoch
+     *  (`Date.now()` at receipt plus `expires_in`). */
+    expires_at: number;
+}
+/** Input to `LoomcycleOAuth.beginAuthorize`. */
+export interface BeginAuthorizeOptions {
+    /** The app's registered client id. */
+    clientId: string;
+    /** One of the app's registered redirect URIs, exactly (a loopback one may
+     *  carry any port). */
+    redirectUri: string;
+    /** An opaque value to round-trip; a random one is generated when omitted.
+     *  1 to 1024 characters. */
+    state?: string;
+}
+/** What `LoomcycleOAuth.beginAuthorize` returns. Persist `verifier` and
+ *  `state` (session storage, never a URL) until the redirect comes back, then
+ *  send the person to `url`. */
+export interface AuthorizeRequest {
+    url: string;
+    /** The PKCE code verifier. A secret until the exchange: keep it out of
+     *  URLs and logs. */
+    verifier: string;
+    state: string;
+}
+/** The parameters the server puts on the redirect back to the app: `code`
+ *  on success, `error` (+ `error_description`) otherwise, `state` as sent,
+ *  and `iss` when the server knows its issuer (RFC 9207). */
+export interface AuthorizeResponseParams {
+    code?: string;
+    state?: string;
+    iss?: string;
+    error?: string;
+    error_description?: string;
+}
+/** Input to `LoomcycleOAuth.completeAuthorize`: the redirect's parameters
+ *  plus what `beginAuthorize` returned. */
+export interface CompleteAuthorizeOptions extends AuthorizeResponseParams {
+    /** The `state` beginAuthorize returned; a redirect carrying any other is
+     *  refused before the code is used. */
+    expectedState: string;
+    verifier: string;
+    clientId: string;
+    /** The same redirect URI the authorization request named. */
+    redirectUri: string;
+    signal?: AbortSignal;
+}
+/** Input to `LoomcycleOAuth.refresh`. */
+export interface RefreshTokenOptions {
+    refreshToken: string;
+    clientId: string;
+    signal?: AbortSignal;
+}
+/** Input to `LoomcycleOAuth.revoke`. */
+export interface RevokeTokenOptions {
+    /** A refresh token (ends the whole sign-in) or an access token (ends that
+     *  token only). */
+    token: string;
+    clientId: string;
+    signal?: AbortSignal;
+}
+/** Supplies the bearer for every request of a `LoomcycleClient` built with
+ *  `tokenProvider` instead of `authToken`. `OAuthTokenProvider` implements it
+ *  for an app sign-in; any other source of short-lived tokens can too. */
+export interface TokenProvider {
+    /** The token for the next request, refreshed ahead of expiry; undefined
+     *  sends none. A throw fails the request with that error. */
+    getToken(): Promise<string | undefined>;
+    /** Called at most once per request, after the server answered 401 to
+     *  `rejected`: a different token to retry with once, or undefined to let
+     *  the 401 stand. */
+    onUnauthorized?(rejected: string | undefined): Promise<string | undefined>;
+}
+/** A client's refresh-token lifetimes: Go durations or whole days (`"7d"`). */
+export interface AppClientRefresh {
+    idle?: string;
+    absolute?: string;
+}
+/** An app client's definition: an entry of the config's `auth.clients`, and
+ *  the body of a ClientDef. */
+export interface AppClientConfig {
+    /** `public`, the only kind: the app holds no secret and PKCE binds a code
+     *  to it. */
+    kind: string;
+    /** The name the login page shows. */
+    label?: string;
+    /** Exact https URIs, loopback URIs (any port, exact path) and private-use
+     *  scheme URIs (`myapp://callback`). */
+    redirect_uris: string[];
+    /** Origins allowed to call the token and revoke endpoints from a browser:
+     *  https, loopback, `chrome-extension://`, `moz-extension://`, `tauri://`. */
+    allowed_origins?: string[];
+    /** Go duration, 1m to 24h; default 1h. */
+    access_token_ttl?: string;
+    refresh?: AppClientRefresh;
+    /** Narrows every token the client's sign-ins mint, as a token's
+     *  restrictions record does. */
+    restrictions?: Record<string, unknown>;
+}
+/** The body of `POST /v1/_clientdef`. */
+export interface ClientDefInput {
+    op: "create" | "update" | "get" | "list" | "retire" | "verify";
+    /** The client id. Unique across the deployment, retired names included. */
+    name?: string;
+    def_id?: string;
+    client?: AppClientConfig;
+    description?: string;
+    /** Admin only. On create: the tenant whose people the client signs in, ""
+     *  (the default) for every tenant. On list: focus one tenant. A tenant
+     *  operator's clients are always its own tenant's. */
+    tenant?: string;
+    /** verify: the content hash to compare with the deployed one. */
+    content_sha256?: string;
+}
+/** A runtime-registered client (a ClientDef version). */
+export interface ClientDefRecord {
+    name: string;
+    source: "def";
+    def_id: string;
+    version: number;
+    /** The tenant whose people it signs in; "" for every tenant. */
+    tenant_id: string;
+    all_tenants: boolean;
+    label: string;
+    redirect_uris: string[];
+    /** The definition as stored. */
+    client: AppClientConfig;
+    description: string;
+    content_sha256: string;
+    created_at: string;
+    created_by: string;
+    created_by_tenant: string;
+    read_only: false;
+}
+/** A client declared in the server's config: read only through the API. */
+export interface ConfigAppClient {
+    name: string;
+    source: "config";
+    label: string;
+    all_tenants: true;
+    tenant_id: string;
+    redirect_uris: string[];
+    allowed_origins: string[];
+    access_token_ttl: string;
+    refresh_idle: string;
+    refresh_absolute: string;
+    read_only: true;
+}
+/** A client as `get` and `list` report it. */
+export type AppClientEntry = ClientDefRecord | ConfigAppClient;
+/** `op: "list"`: the clients the caller may see, config ones included. */
+export interface ClientDefListResponse {
+    clients: AppClientEntry[];
+}
+/** `op: "verify"`: whether a client is deployed and matches a hash. An absent
+ *  client (or one the caller may not see) answers `deployed: false`. */
+export interface ClientDefVerifyResult {
+    name: string;
+    deployed: boolean;
+    current_def_id?: string;
+    current_sha256?: string;
+    version?: number;
+    matches: boolean;
+}
+/** `op: "retire"`. */
+export interface ClientDefRetireResult {
+    name: string;
+    retired: boolean;
+}
+/** One row of `GET /v1/_clientdef/names`. */
+export interface ClientDefNameSummary {
+    name: string;
+    source: "def" | "config";
+    tenant_id: string;
+    label: string;
+    read_only: boolean;
+}
+export interface ClientDefNamesResponse {
+    names: ClientDefNameSummary[];
+}
+/** What to show the person: open `verificationUri` and type `userCode`, or
+ *  open `verificationUriComplete`, which carries the code. */
+export interface DeviceLoginPrompt {
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete?: string;
+    /** Seconds until the code expires. */
+    expiresIn: number;
+}
+export interface DeviceLoginOptions {
+    /** How the client names itself on the approval page (default "loomcycle-ts"). */
+    clientId?: string;
+    /** Called once with the code to show; polling starts after it returns. */
+    onPrompt: (prompt: DeviceLoginPrompt) => void | Promise<void>;
+    signal?: AbortSignal;
+}
+/** The token issued to the person who approved the login: their own member
+ *  token, never wider than the session they approved from and never living
+ *  past it. Keep it in an OS credential store, never a plain file. */
+export interface DeviceLoginResult {
+    accessToken: string;
+    tokenType: string;
+    /** Seconds until the token expires. */
+    expiresIn?: number;
+    scope?: string[];
+}