@verne-software/sdk 1.2.0 → 1.4.0

package/dist/index.d.mts

@@ -1,10 +1,20 @@
 /**
  * Paginated response wrapper returned by list endpoints.
+ *
+ * Lists are cursor-paged: pass `next_cursor` back as `cursor` while `has_more` is
+ * `true`. `next_cursor` is `null` (or absent) on the last page.
  */
 interface Paginated<T> {
     data: T[];
     has_more: boolean;
-    next_cursor?: string;
+    next_cursor?: string | null;
+}
+/** Query parameters shared by every cursor-paged list. */
+interface ListParams {
+    /** Items per page, 1 to 100. Defaults to 20; the server clamps values outside the range. */
+    limit?: number;
+    /** The `next_cursor` of the previous page. Opaque: pass it back, do not parse it. */
+    cursor?: string;
 }
 /**
  * Per-request options that can override client defaults.
@@ -19,23 +29,35 @@ interface RequestOptions {
 }
 /**
  * Configuration for the unified Verne client.
- * Each key corresponds to a service; only provide keys for the services you use.
+ *
+ * A Nautilus API key looks like `vrn_…` and carries a set of scopes — the APIs it may
+ * call (`relay`, `gate`, `clockwork`, `passepartout`). Pass it once as `apiKey`. The
+ * per-service fields are for using a *different* key for one service; they override
+ * `apiKey` for that service. Keys created before scopes existed (`vrn_gate_…`,
+ * `vrn_relay_…`, …) keep working for the one API they name. There is no test or live
+ * mode: every key acts on your real data.
  */
 interface VerneConfig {
-    /** API key for the Relay (Webhooks-as-a-Service) service. Format: vrn_relay_<env>_<secret> */
+    /** The API key used for every service that has no key of its own below. */
+    apiKey?: string;
+    /** Key for Relay (Webhooks-as-a-Service), when it differs from `apiKey`. */
     relay?: string;
-    /** API key for the Gate (Auth-as-a-Service) service. Format: vrn_gate_<env>_<secret> */
+    /** Key for Gate (sign-in and users), when it differs from `apiKey`. */
     gate?: string;
+    /** Key for Passepartout (Telegram sign-in), when it differs from `apiKey`. */
+    passepartout?: string;
+    /** Key for Clockwork (Cron-as-a-Service), when it differs from `apiKey`. */
+    clockwork?: string;
     /** Base URL override. Defaults to https://api.vernesoft.com */
     baseUrl?: string;
     /** Default request timeout in milliseconds. Defaults to 30000. */
     timeoutMs?: number;
 }
 /**
- * Configuration for a single-service client (Relay or Gate).
+ * Configuration for a single-service client (Relay, Gate, Passepartout or Clockwork).
  */
 interface ServiceConfig {
-    /** API key for the service. */
+    /** API key (`vrn_…`) with the scope for the service. */
     apiKey: string;
     /** Base URL override. Defaults to https://api.vernesoft.com */
     baseUrl?: string;
@@ -49,14 +71,19 @@ interface HttpClientConfig {
     timeoutMs?: number;
 }
 interface HttpRequestOptions extends RequestOptions {
-    /** When true, omit the Authorization header (used by gate.tokens.create). */
+    /** When true, omit the Authorization header (calls authenticated by something else). */
     skipAuth?: boolean;
     /** Body to send as JSON. */
     body?: unknown;
+    /** Query parameters. `undefined` and `null` values are dropped. */
+    query?: QueryParams;
+    /** An end user's session token, sent as `X-Session-Token`. */
+    sessionToken?: string;
 }
+type QueryParams = Record<string, string | number | boolean | Date | null | undefined>;
 declare class HttpClient {
     private readonly apiKey;
-    private readonly baseUrl;
+    readonly baseUrl: string;
     private readonly timeoutMs;
     constructor(config: HttpClientConfig);
     get<T>(path: string, options?: HttpRequestOptions): Promise<T>;
@@ -67,29 +94,226 @@ declare class HttpClient {
     private request;
 }
 
-/** A Kratos identity managed by Gate. */
+/** A recurring HTTP job scheduled on a cron expression. */
+interface CronJob {
+    id: string;
+    tenant_id: string;
+    name: string;
+    /** Cron expression, e.g. `'0 * * * *'` (hourly). */
+    schedule: string;
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body: string | null;
+    is_active: boolean;
+    last_run_at: string | null;
+    next_run_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/** Parameters for creating a new cron job. */
+interface CreateCronJobParams {
+    name: string;
+    /** Cron expression, e.g. `'0 * * * *'` (hourly). */
+    schedule: string;
+    url: string;
+    /** HTTP method to invoke the target URL with. Defaults to `POST`. */
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}
+/**
+ * Parameters for updating an existing cron job. All fields are optional —
+ * only the fields you provide are changed.
+ */
+interface UpdateCronJobParams {
+    name?: string;
+    /** Cron expression, e.g. `'0 * * * *'` (hourly). */
+    schedule?: string;
+    url?: string;
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    is_active?: boolean;
+}
+/** A one-shot HTTP job scheduled to run once at a specific time. */
+interface DelayedJob {
+    id: string;
+    tenant_id: string;
+    name: string;
+    /** ISO 8601 timestamp at which the job should fire. */
+    run_at: string;
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body: string | null;
+    status: string;
+    created_at: string;
+    updated_at: string;
+}
+/** Parameters for scheduling a new delayed job. */
+interface CreateDelayedJobParams {
+    name: string;
+    /** ISO 8601 timestamp at which the job should fire. */
+    run_at: string;
+    url: string;
+    /** HTTP method to invoke the target URL with. Defaults to `POST`. */
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}
+/** A single execution (run) of a cron or delayed job. */
+interface Execution {
+    id: string;
+    job_id: string;
+    status: string;
+    started_at: string;
+    completed_at: string | null;
+    duration_ms: number | null;
+    response_status: number | null;
+    response_body: string | null;
+    error_message: string | null;
+    /** Which attempt of the run this row is, from 1. A retried run has one row per attempt. */
+    attempt?: number;
+}
+/** Where the tenant stands against its plan's job limits. `limit` is `null` for no limit. */
+interface ClockworkUsage {
+    plan: string;
+    tier?: string;
+    cron: {
+        active: number;
+        limit: number | null;
+    };
+    delayed: {
+        pending: number;
+        limit: number | null;
+    };
+}
+
+declare class ClockworkDelayedResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Returns all delayed (one-shot) jobs for the current tenant.
+     */
+    list(options?: RequestOptions): Promise<DelayedJob[]>;
+    /**
+     * Schedules a new delayed job to run once at the given `run_at` time.
+     *
+     * @example
+     * const job = await clockwork.delayed.create({
+     *   name: 'send-reminder',
+     *   run_at: '2026-01-01T09:00:00Z',
+     *   url: 'https://example.com/hooks/reminder',
+     * });
+     */
+    create(params: CreateDelayedJobParams, options?: RequestOptions): Promise<DelayedJob>;
+    /**
+     * Cancels a pending delayed job. Resolves on `204 No Content`.
+     */
+    cancel(jobId: string, options?: RequestOptions): Promise<void>;
+    /**
+     * Returns the execution history for a delayed job.
+     */
+    executions(jobId: string, options?: RequestOptions): Promise<Execution[]>;
+}
+
+declare class ClockworkJobsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Returns all cron jobs for the current tenant.
+     */
+    list(options?: RequestOptions): Promise<CronJob[]>;
+    /**
+     * Creates a new recurring cron job.
+     *
+     * @example
+     * const job = await clockwork.jobs.create({
+     *   name: 'nightly-report',
+     *   schedule: '0 2 * * *',
+     *   url: 'https://example.com/hooks/report',
+     * });
+     */
+    create(params: CreateCronJobParams, options?: RequestOptions): Promise<CronJob>;
+    /**
+     * Partially updates an existing cron job. Only the fields you provide are changed.
+     */
+    update(jobId: string, params: UpdateCronJobParams, options?: RequestOptions): Promise<CronJob>;
+    /**
+     * Deletes a cron job. Resolves on `204 No Content`.
+     */
+    delete(jobId: string, options?: RequestOptions): Promise<void>;
+    /**
+     * Returns the execution history for a cron job (most recent runs first).
+     */
+    executions(jobId: string, options?: RequestOptions): Promise<Execution[]>;
+}
+
+declare class Clockwork {
+    readonly jobs: ClockworkJobsResource;
+    readonly delayed: ClockworkDelayedResource;
+    private readonly http;
+    constructor(config: ServiceConfig);
+    /**
+     * How many jobs exist against the plan's limits. Creating a job over a limit, or
+     * resuming a paused one, is refused with `402` (`UPGRADE_REQUIRED` or
+     * `JOB_LIMIT_REACHED`) — never retried.
+     */
+    usage(options?: RequestOptions): Promise<ClockworkUsage>;
+}
+
+/**
+ * An end user (a Kratos identity) managed by Gate.
+ *
+ * The object is the identity service's own; the stable fields are typed and the rest
+ * stays reachable through the index signature.
+ */
 interface Identity {
     id: string;
     schema_id: string;
     state: 'active' | 'inactive';
     traits: IdentityTraits;
+    created_at?: string;
+    updated_at?: string;
+    state_changed_at?: string;
+    /** Your custom metadata. Read and change it with `identities.getMetadata()` / `updateMetadata()`. */
+    metadata_public?: Record<string, unknown> | null;
+    verifiable_addresses?: Array<{
+        value: string;
+        verified: boolean;
+        via: string;
+        status?: string;
+    }>;
+    recovery_addresses?: Array<{
+        value: string;
+        via: string;
+    }>;
+    [key: string]: unknown;
 }
+/**
+ * An end user's traits. The `user` schema has exactly two: `email` (required) and
+ * `locale`. Application data does not go here — keep it in custom metadata
+ * (`identities.updateMetadata()`).
+ */
 interface IdentityTraits {
     email: string;
-    tenant_id: string;
-    custom_data?: Record<string, unknown>;
+    locale?: string;
+    [key: string]: unknown;
 }
 /**
- * Parameters for creating a new identity (end-user) bound to your tenant.
- * The `traits.tenant_id` is injected automatically by the Edge Gateway.
+ * Parameters for creating a new identity (end user) bound to your tenant.
  */
 interface CreateIdentityParams {
     /** Must be 'user'. */
     schema_id: 'user';
+    /**
+     * The schema allows only these two traits; anything else is refused with
+     * `400 invalid_payload`. Use custom metadata for your own fields.
+     */
     traits: {
         email: string;
-        /** Optional arbitrary fields for your application. */
-        custom_data?: Record<string, unknown>;
+        locale?: string;
     };
     credentials?: {
         password?: {
@@ -112,9 +336,9 @@ interface JsonPatchOp {
 }
 /** Security-related Gate Identity settings for your tenant. */
 interface SecuritySettings {
-    /** Whether email-OTP (passwordless) login is enabled. */
+    /** Whether sign-in and sign-up by an emailed one-time code is enabled. */
     passwordless_enabled: boolean;
-    /** Whether TOTP two-factor authentication is enabled. */
+    /** Whether a second factor (TOTP) is required — enforced by `sessions.check()`. */
     mfa_enabled: boolean;
 }
 /**
@@ -134,6 +358,37 @@ interface OidcProvider {
  * …); pass it straight to your browser-side code to render social buttons.
  */
 type LoginFlow = Record<string, unknown>;
+/** Optional parameters of `gate.createLoginFlow()`. */
+interface LoginFlowParams {
+    /**
+     * One of the project's registered return URLs, exactly as registered (see
+     * `settings.updateReturnUrls()`). The first one is used when absent.
+     */
+    return_to?: string;
+    /**
+     * An opaque value of yours, 1–256 characters of letters, digits, `-`, `.`, `_`, `~`,
+     * returned unchanged on the redirect to your return URL. Always send one and check it.
+     */
+    state?: string;
+    /** `'aal2'` starts a step-up (second factor) flow; needs `session_token`. */
+    aal?: 'aal1' | 'aal2';
+    /** The end user's session token, for a step-up flow. Sent as `X-Session-Token`. */
+    session_token?: string;
+}
+/** Optional parameters of `gate.createRegistrationFlow()`. */
+interface RegistrationFlowParams {
+    /** As for the login flow. */
+    return_to?: string;
+    /** As for the login flow. */
+    state?: string;
+}
+/** What `exchangeOidcCode()` returns: the same shape a password login returns. */
+interface OidcExchangeResult {
+    /** The end user's session token. Keep it on your server. */
+    session_token: string;
+    session: GateSession;
+    [key: string]: unknown;
+}
 /** Short-lived access token returned by tokens.create(). */
 interface AccessToken {
     access_token: string;
@@ -150,43 +405,355 @@ interface CreateTokenParams {
     /** Custom lifetime in seconds. Default 3600, max 86400. */
     ttl_seconds?: number;
 }
-/** Result of token introspection. */
+/**
+ * One organization a user belongs to: the unit Gate uses everywhere it says who a user
+ * is — in introspection, the session check, the signed token's `orgs` claim and
+ * `identities.listOrganizations()`.
+ */
+interface OrgClaim {
+    /** The organization's id. */
+    id: string;
+    /** The name of the role the user holds there. */
+    role: string;
+    /** That role's permissions, e.g. `'invoices:write'`. */
+    permissions: string[];
+}
+/**
+ * Result of token introspection.
+ *
+ * An inactive token (unknown, expired, another tenant's, or its user deactivated or
+ * deleted) is `{ active: false }` and nothing else.
+ */
 interface IntrospectResult {
     active: boolean;
-    subject: string;
-    tenant_id: string;
-    scopes: string[];
-    expires_at: string;
+    subject?: string;
+    tenant_id?: string;
+    scopes?: string[];
+    expires_at?: string;
+    /**
+     * When `subject` is an end user's id: their organizations in the key's project, read
+     * live, the first 100 in the order they joined. Absent for any other subject.
+     */
+    orgs?: OrgClaim[];
+    /** `true`, and only then, when there are more than `orgs` shows. */
+    orgs_truncated?: boolean;
 }
 /** Parameters for checking whether a subject can perform an action. */
 interface AuthorizeParams {
-    /** ID of the user or service account (e.g. 'usr_123'). */
+    /** The end user's identity id. */
     subject: string;
-    /** Action being performed (e.g. 'relay.messages.read'). */
+    /**
+     * For an organization resource: the permission to check, e.g. `'invoices:write'`.
+     * Otherwise a label for your own records.
+     */
     action: string;
-    /** Resource identifier (e.g. 'tenant:ten_001' or 'relay:key:key_123'). */
+    /**
+     * `'organization:<uuid>'` to check a permission in an organization (prefer
+     * `organizations.authorize()` / `can()`, which build it); anything else asks only
+     * whether `subject` is one of your active end users.
+     */
     resource: string;
-    /** Optional extra attributes for policy evaluation. */
+    /** Accepted and ignored by the API today. */
     context?: Record<string, unknown>;
 }
+/** Why an organization permission check answered as it did. */
+type OrganizationAuthorizeReason = 'member_with_permission' | 'member_without_permission' | 'not_a_member' | 'subject_inactive' | 'no_such_organization';
+/**
+ * Why a check on any resource that is not an organization answered as it did — the only
+ * question it asks is *is `subject` one of your active end users?* `owned_by_tenant` is
+ * the one `allowed: true` answer.
+ */
+type OwnershipAuthorizeReason = 'owned_by_tenant' | 'subject_inactive' | 'not_owned_by_tenant' | 'not_a_known_identity';
 /** Authorization decision returned by gate.authorize(). */
 interface AuthorizeResult {
     allowed: boolean;
+    /** Identifies the decision in Gate's logs, for support. */
     decision_id: string;
-    reason: string;
+    /**
+     * A code to branch on: one of {@link OrganizationAuthorizeReason} for an organization
+     * resource, one of {@link OwnershipAuthorizeReason} for any other. The set is open —
+     * treat an unknown value as a denial.
+     */
+    reason: OrganizationAuthorizeReason | OwnershipAuthorizeReason | (string & {});
+    /**
+     * For a resource that is not an organization: the decision as a sentence, for your
+     * logs. Its wording can change; only `reason` is a contract. Absent for an
+     * organization decision.
+     */
+    message?: string;
+    /**
+     * The role the user holds in the organization — present for
+     * `member_with_permission`, `member_without_permission` and `subject_inactive`.
+     */
+    role?: string;
+}
+/** What `tokens.createSigned()` returns. */
+interface SignedToken {
+    /** The compact ES256 JWT. Valid for 15 minutes; it cannot be revoked. */
+    token: string;
+    /** The session the token was made from, as `whoami` returns it. */
+    session: GateSession;
+}
+/** The verified payload of a Gate signed token. */
+interface SignedTokenClaims {
+    /** `<base URL>/auth/<tenant id>` — checked by the verifier. */
+    iss: string;
+    /** The end user's identity id. */
+    sub: string;
+    /** The session the token was made from (revocable with `sessions.revoke()`). */
+    sid: string;
+    tenant_id: string;
+    schema_id: string;
+    email: string | null;
+    /** Always `'authenticated'` (the database role PostgREST-style consumers use). */
+    role: string;
+    /** The user's organizations across all your projects, as of when the token was made. */
+    orgs: OrgClaim[];
+    /** `true` when `orgs` is incomplete; list them with `identities.listOrganizations()`. */
+    orgs_truncated?: boolean;
+    iat: number;
+    nbf: number;
+    exp: number;
+    jti: string;
+    [claim: string]: unknown;
+}
+/** Options of `tokens.verifySigned()`. */
+interface VerifySignedOptions {
+    /** Your tenant id: the issuer is built from it. */
+    tenantId: string;
+    /** Allowed clock skew in seconds for `exp` and `nbf`. Default 10. */
+    clockToleranceSeconds?: number;
+}
+/** An end user's session, as the identity service returns it. */
+interface GateSession {
+    id: string;
+    active?: boolean;
+    authenticated_at?: string;
+    expires_at?: string;
+    issued_at?: string;
+    authenticator_assurance_level?: string;
+    authentication_methods?: Array<{
+        method: string;
+        completed_at?: string;
+        [key: string]: unknown;
+    }>;
+    devices?: Array<{
+        id?: string;
+        ip_address?: string;
+        user_agent?: string;
+        location?: string;
+    }>;
+    identity?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** The answer of `sessions.check()` — whether a session is good enough to act on. */
+interface SessionCheck {
+    active: boolean;
+    /** `'aal1'` or `'aal2'`. */
+    aal: string;
+    /** Whether your tenant requires a second factor. */
+    mfa_required: boolean;
+    /** Whether this session meets what your tenant requires — the one field to gate on. */
+    mfa_satisfied: boolean;
+    identity_id: string | null;
+    /** The user's organizations in the key's project, read now (first 100). */
+    orgs?: OrgClaim[];
+    orgs_truncated?: boolean;
+}
+/** A group of your end users (a customer's team, workspace, company). */
+interface Organization {
+    id: string;
+    /** Free text, 1–120 characters, not unique. */
+    name: string;
+    created_at: string;
+    updated_at: string;
+}
+interface CreateOrganizationParams {
+    name: string;
+}
+interface UpdateOrganizationParams {
+    name: string;
+}
+/** A named set of permissions inside one organization. */
+interface Role {
+    id: string;
+    organization_id: string;
+    /** Lowercase letters, digits, `_` and `-`; unique in the organization. */
+    name: string;
+    /** Sorted and de-duplicated by the API. */
+    permissions: string[];
+    created_at: string;
+    updated_at: string;
+}
+interface CreateRoleParams {
+    /** 1–64 characters: lowercase letters, digits, `_`, `-`, starting with a letter or digit. */
+    name: string;
+    /** Lowercase segments joined by `:`, e.g. `'invoices:write'`. `*` and `nautilus:` are reserved. */
+    permissions?: string[];
+}
+interface UpdateRoleParams {
+    name?: string;
+    /** Replaces the whole set. Everyone holding the role has the new set at once. */
+    permissions?: string[];
+}
+/** An end user's membership of an organization. */
+interface Member {
+    organization_id: string;
+    identity_id: string;
+    role_id: string;
+    /** When the membership ends, or `null` for never. */
+    expires_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+interface AddMemberParams {
+    /** One of your end users. */
+    identity_id: string;
+    /** A role of this organization. */
+    role_id: string;
+    /** A future time (at most 10 years ahead) when the membership ends. */
+    expires_at?: string | Date | null;
+}
+interface UpdateMemberParams {
+    /** Move the member to another role of this organization. */
+    role_id?: string;
+    /** Leave it out to keep the deadline, `null` to remove it, a time to set it. */
+    expires_at?: string | Date | null;
+}
+type AuditActorType = 'team_member' | 'api_key' | 'end_user' | 'system' | 'staff';
+/** Filters of `auditLog.list()`. */
+interface ListAuditLogParams extends ListParams {
+    /** One action, e.g. `'key.created'`, `'identity.login'`, `'organization.member_added'`. */
+    action?: string;
+    actor_id?: string;
+    actor_type?: AuditActorType;
+    target_id?: string;
+    /** Entries at or after this instant. */
+    from?: string | Date;
+    /** Entries before this instant. Must be later than `from`. */
+    to?: string | Date;
+}
+/** One entry of the audit log. */
+interface AuditLogEntry {
+    id: string;
+    occurred_at: string;
+    /** Open set: new actions are added over time. */
+    action: string;
+    actor: {
+        type: AuditActorType | 'unknown' | (string & {});
+        id: string | null;
+    };
+    target: {
+        type: string;
+        id: string;
+    } | null;
+    project_id: string | null;
+    details: Record<string, unknown>;
+    ip: string | null;
+    user_agent: string | null;
+}
+type LifecycleRuleKind = 'delete_unverified' | 'remind_unverified' | 'expire_roles' | 'delete_inactive';
+/** Settings of each rule kind. */
+interface LifecycleRuleParamsByKind {
+    delete_unverified: {
+        delete_after_days: number;
+        warn_before_days: number;
+    };
+    remind_unverified: {
+        remind_after_hours: number;
+    };
+    expire_roles: Record<string, never>;
+    delete_inactive: {
+        inactive_after_months: number;
+        warn_before_days: number;
+        include_without_address?: boolean;
+    };
+}
+interface LifecycleRule {
+    kind: LifecycleRuleKind;
+    configured: boolean;
+    enabled: boolean;
+    params: Record<string, unknown> | null;
+    /** Whether your plan includes the rule. */
+    available: boolean;
+    /** `'plan'` when a plan change switched the rule off. */
+    disabled_reason: 'plan' | null;
+    enabled_at: string | null;
+    updated_at: string | null;
+    /** How many people have something scheduled by this rule. */
+    pending: number;
+}
+interface LifecycleRules {
+    /** Your plan: `free`, `pro`, `advanced` or `contract`. */
+    tier: string;
+    /** All four kinds, set up or not. */
+    rules: LifecycleRule[];
+}
+interface SetLifecycleRuleParams<K extends LifecycleRuleKind = LifecycleRuleKind> {
+    enabled: boolean;
+    /** Leave out to keep the saved settings. Required on a first write (except `expire_roles`). */
+    params?: LifecycleRuleParamsByKind[K];
+}
+interface LifecycleRulePreview {
+    kind: LifecycleRuleKind;
+    available: boolean;
+    /** How many people the rule would schedule right now. */
+    matching_now: number;
+    /** `true` when the count stopped at 1,000. */
+    capped: boolean;
+}
+interface ListLifecycleActionsParams extends ListParams {
+    status?: 'pending' | 'done' | 'cancelled' | 'failed';
+    kind?: LifecycleRuleKind;
+    identity_id?: string;
+}
+interface LifecycleAction {
+    id: string;
+    kind: LifecycleRuleKind;
+    step: 'remind' | 'warn' | 'delete' | 'revoke';
+    identity_id: string;
+    status: 'pending' | 'done' | 'cancelled' | 'failed';
+    basis_at: string;
+    due_at: string;
+    /** Why it was cancelled or failed (`rule_disabled`, `verified`, `signed_in`, …). */
+    reason: string | null;
+    created_at: string;
+    finished_at: string | null;
+}
+
+/**
+ * The account's audit log, read-only: who did what, to what, when and from where. The
+ * key reads its own project's entries and the account-wide ones.
+ *
+ * Any key with the `gate` scope reads the whole log, including the IP addresses and
+ * user agents of your team members. Keep `gate` keys on your backend.
+ */
+declare class AuditLogResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * One page of entries, newest first. Filters combine; keep the same filters while
+     * paging with `cursor`.
+     *
+     * @example
+     * const page = await gate.auditLog.list({ action: 'identity.login', actor_id: userId });
+     */
+    list(params?: ListAuditLogParams, options?: RequestOptions): Promise<Paginated<AuditLogEntry>>;
 }
 
 declare class IdentitiesResource {
     private readonly http;
     constructor(http: HttpClient);
     /**
-     * Creates a new identity (end-user) bound to your tenant.
-     * The `traits.tenant_id` is injected automatically by the Edge Gateway.
+     * Creates a new identity (end user) bound to your tenant. Answers `201`.
+     *
+     * A `409 conflict` means you already have an end user with this address; the same
+     * address at another tenant is a different person and does not conflict. Traits are
+     * `email` and `locale` only — keep your own fields in custom metadata.
      */
     create(params: CreateIdentityParams, options?: RequestOptions): Promise<Identity>;
     /**
-     * Returns an identity by ID.
-     * The Gateway will reject the request if the identity does not belong to your tenant.
+     * Returns an identity by ID. An identity of another tenant is refused.
      */
     get(identityId: string, options?: RequestOptions): Promise<Identity>;
     /**
@@ -194,19 +761,19 @@ declare class IdentitiesResource {
      *
      * @example
      * await gate.identities.patch('identity_123', [
-     *   { op: 'replace', path: '/traits/custom_data/role', value: 'admin' }
+     *   { op: 'replace', path: '/traits/email', value: 'new@example.com' },
      * ]);
      */
     patch(identityId: string, ops: JsonPatchOp[], options?: RequestOptions): Promise<Identity>;
     /**
-     * Deletes an identity from Kratos.
-     * The Gateway will reject the request if the identity does not belong to your tenant.
+     * Deletes an identity, its sessions and its memberships. Fires `identity.deleted`.
      */
     delete(identityId: string, options?: RequestOptions): Promise<void>;
     /**
-     * Activates or deactivates an identity. An `inactive` identity cannot log in —
-     * Kratos rejects its credentials automatically — until it is reactivated.
-     * The identity is not deleted. Fires the `identity.state_changed` webhook event.
+     * Activates or deactivates an identity. An `inactive` identity cannot sign in, its
+     * sessions stop working (until it is active again), its access tokens introspect as
+     * `active: false`, and no signed token is issued for it. Nothing is deleted. Fires the
+     * `identity.state_changed` webhook event.
      *
      * @example
      * await gate.identities.setState('identity_123', 'inactive');
@@ -222,13 +789,178 @@ declare class IdentitiesResource {
      * a fresh verification email. Resolves on `204 No Content`.
      */
     resendVerification(identityId: string, options?: RequestOptions): Promise<void>;
+    /**
+     * Reads an identity's custom metadata (`metadata_public`) — the place for your own
+     * fields about a user. `{}` when nothing is set.
+     */
+    getMetadata(identityId: string, options?: RequestOptions): Promise<Record<string, unknown>>;
+    /**
+     * Merges `patch` into an identity's custom metadata and returns the result. Keys you
+     * leave out are kept; a key set to `null` is removed.
+     *
+     * @example
+     * await gate.identities.updateMetadata(id, { plan: 'pro', seats: null });
+     */
+    updateMetadata(identityId: string, patch: Record<string, unknown>, options?: RequestOptions): Promise<Record<string, unknown>>;
+    /**
+     * The organizations of the key's project that an end user belongs to, with the role
+     * held in each and its permissions — live, oldest membership first, cursor-paged. This
+     * is the complete list that `orgs_truncated: true` (in a token, an introspection or a
+     * session check) points to.
+     */
+    listOrganizations(identityId: string, params?: ListParams, options?: RequestOptions): Promise<Paginated<OrgClaim>>;
+}
+
+/**
+ * Automatic deletion of unconfirmed and inactive accounts, and removal of expired roles —
+ * four rules per project, all off until you switch them on. Only `delete_unverified` is
+ * in the Free plan; switching on another is `403 plan_required`.
+ */
+declare class LifecycleResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** All four rules of the key's project, set up or not, and the plan. */
+    listRules(options?: RequestOptions): Promise<LifecycleRules>;
+    /**
+     * Creates, changes, or switches a rule on or off. Leave `params` out to keep the saved
+     * settings. Switching off or changing settings cancels what the rule had scheduled.
+     *
+     * @example
+     * await gate.lifecycle.setRule('delete_unverified', {
+     *   enabled: true,
+     *   params: { delete_after_days: 14, warn_before_days: 3 },
+     * });
+     */
+    setRule<K extends LifecycleRuleKind>(kind: K, params: SetLifecycleRuleParams<K>, options?: RequestOptions): Promise<LifecycleRule>;
+    /** Removes a rule and cancels what it scheduled. Succeeds also when there was none. */
+    deleteRule(kind: LifecycleRuleKind, options?: RequestOptions): Promise<void>;
+    /**
+     * How many people a rule with these settings would affect right now. Writes nothing;
+     * works whether or not the rule is on or in your plan. `expire_roles` takes `{}`.
+     */
+    previewRule<K extends LifecycleRuleKind>(kind: K, params: LifecycleRuleParamsByKind[K], options?: RequestOptions): Promise<LifecycleRulePreview>;
+    /** What the rules have scheduled and done, oldest first, cursor-paged. */
+    listActions(params?: ListLifecycleActionsParams, options?: RequestOptions): Promise<Paginated<LifecycleAction>>;
+}
+
+/**
+ * Organizations of your end users — their teams, workspaces, companies — with named
+ * roles and members. Everything here acts on **the project the API key belongs to**.
+ *
+ * Gate keeps the data and reports it (introspection, the session check, the signed
+ * token's `orgs` claim); it does not enforce permissions. Ask with {@link can}.
+ */
+declare class OrganizationsResource {
+    private readonly http;
+    readonly roles: RolesResource;
+    readonly members: MembersResource;
+    constructor(http: HttpClient);
+    /** Creates an organization. `name` is free text, 1–120 characters, not unique. */
+    create(params: CreateOrganizationParams, options?: RequestOptions): Promise<Organization>;
+    /** Lists the project's organizations, oldest first, cursor-paged. */
+    list(params?: ListParams, options?: RequestOptions): Promise<Paginated<Organization>>;
+    get(orgId: string, options?: RequestOptions): Promise<Organization>;
+    /** Renames an organization. */
+    update(orgId: string, params: UpdateOrganizationParams, options?: RequestOptions): Promise<Organization>;
+    /** Deletes an organization with its roles and memberships. */
+    delete(orgId: string, options?: RequestOptions): Promise<void>;
+    /**
+     * *May this end user do this in this organization?* — answered from the role the user
+     * holds there and its permissions, as they are now. `permission` must match exactly
+     * (no wildcards). An organization of another project looks like a missing one
+     * (`no_such_organization`). An invalid permission (upper case, `*`, the `nautilus:`
+     * prefix) is a `400` error, never `allowed: false`. Not billed, not audited.
+     */
+    authorize(orgId: string, identityId: string, permission: string, options?: RequestOptions): Promise<AuthorizeResult>;
+    /**
+     * `true` when the end user holds `permission` in the organization — the boolean of
+     * {@link authorize}. Errors are thrown, not turned into `false`.
+     *
+     * @example
+     * if (!(await gate.organizations.can(orgId, userId, 'invoices:write'))) {
+     *   throw new Error('Forbidden');
+     * }
+     */
+    can(orgId: string, identityId: string, permission: string, options?: RequestOptions): Promise<boolean>;
+}
+/** Roles of one organization: named sets of permissions. */
+declare class RolesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Defines a role. `409 conflict` if the name is taken in the organization,
+     * `409 limit_reached` past 100 roles.
+     */
+    create(orgId: string, params: CreateRoleParams, options?: RequestOptions): Promise<Role>;
+    list(orgId: string, params?: ListParams, options?: RequestOptions): Promise<Paginated<Role>>;
+    get(orgId: string, roleId: string, options?: RequestOptions): Promise<Role>;
+    /**
+     * Renames a role and/or **replaces** its permissions. Everyone who holds it has the new
+     * permissions the next time they are read.
+     */
+    update(orgId: string, roleId: string, params: UpdateRoleParams, options?: RequestOptions): Promise<Role>;
+    /** Deletes a role. A role someone holds is refused with `409 conflict`. */
+    delete(orgId: string, roleId: string, options?: RequestOptions): Promise<void>;
+}
+/** Members of one organization: end users holding one role each. */
+declare class MembersResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Gives an end user a role in the organization. `404` if the identity is not one of
+     * your end users, `409` if they already are a member (change the role with
+     * {@link update}).
+     */
+    add(orgId: string, params: AddMemberParams, options?: RequestOptions): Promise<Member>;
+    list(orgId: string, params?: ListParams, options?: RequestOptions): Promise<Paginated<Member>>;
+    /**
+     * Changes a member's role and/or deadline. `expires_at`: leave it out to keep the
+     * deadline, `null` to remove it, a time to set it.
+     */
+    update(orgId: string, identityId: string, params: UpdateMemberParams, options?: RequestOptions): Promise<Member>;
+    /** Removes the membership. The person stays your end user. */
+    remove(orgId: string, identityId: string, options?: RequestOptions): Promise<void>;
+}
+
+/** End users' sessions: list, revoke, and check one is good enough to act on. */
+declare class SessionsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** The active sessions of one of your end users (a bare array, not paged). */
+    list(identityId: string, options?: RequestOptions): Promise<GateSession[]>;
+    /**
+     * Revokes every session of an end user — "log out everywhere". Signed tokens already
+     * issued keep verifying until their own `exp` (at most 15 minutes).
+     *
+     * Idempotent: a user of yours with no session at all is a success too. An id that is not
+     * one of your users — another account's, unknown, or one you deleted — is
+     * `403 forbidden`. `404 not_found` is rare: a user removed from the identity service
+     * other than through `identities.delete()`, which Gate still remembered as yours.
+     */
+    revokeAll(identityId: string, options?: RequestOptions): Promise<void>;
+    /**
+     * Revokes one session by its id. Revoking an already revoked session of your user is a
+     * success too; an id that is not one of your users' sessions is `404`.
+     */
+    revoke(sessionId: string, options?: RequestOptions): Promise<void>;
+    /**
+     * Whether an end user's session meets what your tenant requires — the one call to
+     * gate your own routes on. Gate on `mfa_satisfied`. Also lists the user's
+     * organizations in the key's project, read now.
+     *
+     * Throws `VerneAPIError` with `status 401` for a dead, foreign or unknown session, and
+     * `code 'mfa_required'` (`403`) when a second factor is owed: start a step-up flow with
+     * `gate.createLoginFlow({ aal: 'aal2', session_token })`.
+     */
+    check(sessionToken: string, options?: RequestOptions): Promise<SessionCheck>;
 }
 
 declare class SettingsResource {
     private readonly http;
     constructor(http: HttpClient);
     /**
-     * Returns the tenant's security settings (passwordless / MFA).
+     * Returns the tenant's security settings (passwordless / MFA). With `mfa_enabled`,
+     * `sessions.check()` refuses a session without a second factor (`403 mfa_required`).
      */
     getSecurity(options?: RequestOptions): Promise<SecuritySettings>;
     /**
@@ -256,42 +988,94 @@ declare class SettingsResource {
      * ]);
      */
     updateOidcProviders(providers: OidcProvider[], options?: RequestOptions): Promise<OidcProvider[]>;
+    /**
+     * The project's social-login return URLs — the addresses on your backend that receive
+     * the user (with a one-time `code`) after a social login. The first is the default.
+     */
+    getReturnUrls(options?: RequestOptions): Promise<string[]>;
+    /**
+     * Replaces the project's return URLs (at most 10; an empty list switches the feature
+     * off) and returns them as they will be matched — exactly, never by prefix. `https`
+     * only, except `http://localhost` and `http://127.0.0.1`; no query, fragment, `@` or
+     * wildcard (`400 invalid_payload` names the entry).
+     */
+    updateReturnUrls(urls: string[], options?: RequestOptions): Promise<string[]>;
 }
 
 declare class TokensResource {
     private readonly http;
-    private readonly apiKey;
-    constructor(http: HttpClient, apiKey: string);
+    private readonly verifiers;
+    constructor(http: HttpClient);
     /**
-     * Exchanges the Gate API key for a short-lived access token.
+     * Exchanges the Gate API key for a short-lived access token (`gat_live_…`), for
+     * `subject` — a user or a service account. Answers `201`.
      *
-     * Note: This endpoint does not use the Authorization header — the API key
-     * is passed in the request body per the Gate API specification.
+     * The key travels in the `Authorization` header like on every other call. (Until 1.4.0
+     * this SDK sent it in the body without the header, which the API refuses with `401`.)
      */
     create(params: CreateTokenParams, options?: RequestOptions): Promise<AccessToken>;
     /**
-     * Validates a Gate access token and returns its decoded attributes.
+     * Validates a Gate access token and returns its attributes. An unknown, expired or
+     * foreign token, or one whose user you deactivated or deleted, is `{ active: false }`.
+     *
+     * When the subject is an end user, `orgs` lists their organizations in the key's
+     * project, read at the moment you ask.
      */
     introspect(accessToken: string, options?: RequestOptions): Promise<IntrospectResult>;
+    /**
+     * Gets a **signed JWT** (ES256) for a signed-in end user's session, for a platform that
+     * verifies signatures instead of calling Gate (Supabase, an API gateway). The session
+     * token is the credential: no API key is sent.
+     *
+     * The token is valid for 15 minutes and **cannot be revoked**; its `orgs` claim is as old
+     * as the token. Every call mints a new one — ask again before the one you hold expires.
+     * A revoked or expired session, or a deactivated user, is a `401`.
+     *
+     * @example
+     * const { token } = await gate.tokens.createSigned(sessionToken);
+     */
+    createSigned(sessionToken: string, options?: RequestOptions): Promise<SignedToken>;
+    /**
+     * Verifies a Gate signed token offline against your tenant's public keys (fetched once
+     * and cached) and returns its claims. Throws `VerneTokenError` when the token must not
+     * be trusted — wrong issuer (another tenant), bad signature, expired, any algorithm but
+     * ES256. See {@link GateTokenVerifier} to verify without a Gate client.
+     *
+     * @example
+     * const claims = await gate.tokens.verifySigned(token, { tenantId: 'your-tenant-id' });
+     * claims.sub;  // the end user's id
+     */
+    verifySigned(token: string, options: VerifySignedOptions): Promise<SignedTokenClaims>;
 }
 
 declare class Gate {
     readonly identities: IdentitiesResource;
     readonly tokens: TokensResource;
     readonly settings: SettingsResource;
+    readonly organizations: OrganizationsResource;
+    readonly sessions: SessionsResource;
+    readonly auditLog: AuditLogResource;
+    readonly lifecycle: LifecycleResource;
     private readonly http;
     constructor(config: ServiceConfig);
     /**
-     * Checks whether a given subject is allowed to perform an action on a resource.
-     * This is the core building block for enforcing authorization in your services.
+     * Asks whether a subject may perform an action on a resource. The answer is a decision;
+     * your service enforces it.
+     *
+     * - `resource: 'organization:<id>'` — may this end user do `action` (a permission) in
+     *   that organization? `reason` is one of a fixed set and `role` is the role they hold.
+     *   Prefer `gate.organizations.authorize()` / `can()`, which build the resource.
+     * - any other resource — only *is `subject` one of your active end users?*; `reason` is
+     *   `owned_by_tenant` (allowed), `subject_inactive`, `not_owned_by_tenant` or
+     *   `not_a_known_identity`, and `message` says it in a sentence for your logs.
      *
      * @example
-     * const result = await gate.authorize({
-     *   subject: 'usr_123',
-     *   action: 'relay.messages.read',
-     *   resource: 'tenant:ten_001',
+     * const decision = await gate.authorize({
+     *   subject: userId,
+     *   action: 'invoices:write',
+     *   resource: `organization:${orgId}`,
      * });
-     * if (!result.allowed) throw new Error('Forbidden');
+     * if (!decision.allowed) throw new Error('Forbidden');
      */
     authorize(params: AuthorizeParams, options?: RequestOptions): Promise<AuthorizeResult>;
     /**
@@ -305,16 +1089,110 @@ declare class Gate {
      */
     getEnabledProviders(tenantId: string, options?: RequestOptions): Promise<string[]>;
     /**
-     * Initializes a Kratos login flow using your Gate API key. Call this from
-     * your server and pass the returned flow JSON to your browser-side code to
-     * render social login buttons. The flow already contains only the providers
-     * your tenant has enabled.
+     * Starts a Kratos login flow with your Gate API key and returns it; render its
+     * `ui.nodes` or post credentials to its `ui.action`. With a return URL registered,
+     * pass `return_to` and always a `state` for social login. A step-up (second factor) is
+     * `{ aal: 'aal2', session_token }`.
+     *
+     * @example
+     * const flow = await gate.createLoginFlow({ state: csrfBoundValue });
+     */
+    createLoginFlow(params?: LoginFlowParams, options?: RequestOptions): Promise<LoginFlow>;
+    /**
+     * Starts a Kratos registration flow. Refused with `402 ACTIVE_USER_LIMIT_REACHED` when
+     * the account is past its active-user limit and the month to move up has ended.
+     */
+    createRegistrationFlow(params?: RegistrationFlowParams, options?: RequestOptions): Promise<LoginFlow>;
+    /**
+     * Exchanges the one-time `code` your return URL received after a social login for the
+     * user's session. The code works once, for about 60 seconds, and only with a key of the
+     * project that started the login (otherwise `404`). Keep the session token server-side.
+     */
+    exchangeOidcCode(code: string, options?: RequestOptions): Promise<OidcExchangeResult>;
+}
+
+/** The Telegram end-user captured during login. */
+interface TelegramUser {
+    id: string;
+    username?: string;
+    first_name?: string;
+    photo_url?: string;
+}
+/** Response from starting a Telegram login. */
+interface LoginStart {
+    /** Opaque nonce identifying this login attempt. Poll `loginStatus(nonce)` with it. */
+    nonce: string;
+    /** `https://t.me/<bot>?start=<nonce>` — send the end-user here to authenticate. */
+    deep_link: string;
+    /** ISO-8601 timestamp after which the nonce expires. */
+    expires_at: string;
+}
+/** Current state of a Telegram login attempt. */
+interface LoginStatus {
+    /** `pending` until the user completes the Telegram flow, then `completed`. */
+    status: 'pending' | 'completed';
+    /** Present once completed — the end-user's access token. */
+    access_token?: string;
+    /** Present once completed — when the access token expires (ISO-8601). */
+    expires_at?: string;
+    /** Present once completed — the provisioned Kratos identity id. */
+    identity_id?: string;
+    /** Present once completed — the authenticated Telegram user. */
+    user?: TelegramUser;
+}
+/**
+ * Result of introspecting a Passepartout access token. An unknown, expired or foreign
+ * token, or one whose user was deactivated or deleted, is `{ active: false }`.
+ */
+interface TokenIntrospection {
+    active: boolean;
+    subject?: string;
+    tenant_id?: string;
+    scopes?: string[];
+    expires_at?: string;
+    /**
+     * The user's organizations in the key's project, with the role held in each and its
+     * permissions — read live, the first 100 in the order they joined.
+     */
+    orgs?: OrgClaim[];
+    /** `true`, and only then, when there are more than `orgs` shows. */
+    orgs_truncated?: boolean;
+}
+
+/**
+ * Verne Passepartout — Telegram Auth-as-a-Service.
+ *
+ * Lets your end-users sign in with Telegram: start a login to get a deep link,
+ * send the user to it, then poll for completion to receive an access token.
+ */
+declare class Passepartout {
+    private readonly http;
+    constructor(config: ServiceConfig);
+    /**
+     * Starts a Telegram login and returns a nonce + deep link. Send the user to
+     * `deep_link`, then poll {@link loginStatus} with `nonce` until it completes.
      *
      * @example
-     * const flow = await gate.createLoginFlow();
-     * // send `flow` to the browser as JSON
+     * const { nonce, deep_link } = await passepartout.loginStart();
+     * // redirect the user to `deep_link`, then poll:
+     * const status = await passepartout.loginStatus(nonce);
      */
-    createLoginFlow(options?: RequestOptions): Promise<LoginFlow>;
+    loginStart(options?: RequestOptions): Promise<LoginStart>;
+    /**
+     * Returns the current state of a login attempt. While the user hasn't
+     * finished, `status` is `pending`; once done it becomes `completed` and
+     * carries the `access_token` and `user`.
+     *
+     * Throws `VerneAPIError` with `403 account_disabled` when the person is deactivated,
+     * and `402 ACTIVE_USER_LIMIT_REACHED` when a *new* person signs in past the account's
+     * active-user limit (retrying does not help; existing users are unaffected).
+     */
+    loginStatus(nonce: string, options?: RequestOptions): Promise<LoginStatus>;
+    /**
+     * Validates a Passepartout access token and returns its attributes.
+     * Tokens owned by another tenant are reported as `{ active: false }`.
+     */
+    introspect(accessToken: string, options?: RequestOptions): Promise<TokenIntrospection>;
 }
 
 /** A message (event) as returned by the Relay API. */
@@ -323,7 +1201,14 @@ interface Message {
     id: string;
     /** Dot-notated event name (e.g. 'user.created'). */
     event_type: string;
-    /** Delivery status after being accepted by Relay. */
+    /**
+     * Always `'accepted'`.
+     *
+     * It records that Relay took the event, not what each subscriber endpoint did
+     * with it afterwards — per-endpoint delivery state lives in the Console under
+     * Dashboard → Relay. A literal type rather than `string`, so a `switch` over
+     * it cannot grow a branch that never runs.
+     */
     status: 'accepted';
     /** ISO 8601 timestamp of when the event was accepted. */
     timestamp: string;
@@ -335,8 +1220,13 @@ interface SendMessageParams {
     /** Arbitrary JSON payload delivered to subscribers. */
     payload: Record<string, unknown>;
     /**
-     * Optional idempotency key to prevent duplicate delivery within a 24-hour window.
-     * If a message with the same key was already accepted, a 409 is returned.
+     * Optional idempotency key, deduplicating within a 12-hour window.
+     *
+     * Sending the same key twice does not create a second event and does not
+     * fail: the second call returns `202` with the *originally* accepted message,
+     * same `id` and same `timestamp`. So a retry of a request whose response you
+     * never saw needs no special handling — there is no duplicate to tell apart
+     * from a success.
      */
     idempotency_key?: string;
     /** Restrict delivery to endpoints listening on these channels. */
@@ -344,9 +1234,14 @@ interface SendMessageParams {
 }
 /** Query parameters for listing sent events. */
 interface ListMessagesParams {
-    /** Number of items per page. Max 100. Defaults to 20. */
+    /** Number of items per page. Defaults to 20; anything above 100 is clamped to 100. */
     limit?: number;
-    /** Pagination cursor from a previous response. */
+    /**
+     * Pagination cursor from a previous response's `next_cursor`.
+     *
+     * `next_cursor` is `null` on the last page, so paginate until `has_more` is
+     * `false` rather than until `data` comes back empty.
+     */
     cursor?: string;
     /** Filter results by event type. */
     event_type?: string;
@@ -359,7 +1254,13 @@ declare class MessagesResource {
     constructor(http: HttpClient);
     /**
      * Publish an event to all endpoints subscribed to the given event_type.
-     * Automatically retries once on 429 (respects Retry-After header).
+     * Retries once on a short `429` (a `Retry-After` of a minute or less). The monthly
+     * message limit (`429 RELAY_MESSAGE_LIMIT_REACHED`, `Retry-After` until the 1st) is
+     * thrown at once, with `retryAfter` on the error.
+     *
+     * Safe to retry beyond that, if you pass an `idempotency_key`: a repeat
+     * returns the originally accepted message rather than creating a second event
+     * or failing.
      *
      * @returns The accepted message with its assigned ID and timestamp.
      */
@@ -375,13 +1276,83 @@ declare class Relay {
     constructor(config: ServiceConfig);
 }
 
+/**
+ * The unified client. Pass one API key (`apiKey`) and use any service its scopes allow;
+ * a call to a service the key has no scope for is refused by the API with `403 forbidden`.
+ *
+ * @example
+ * const verne = new Verne({ apiKey: process.env.VERNE_API_KEY });
+ * await verne.gate.organizations.create({ name: 'Acme' });
+ */
 declare class Verne {
     private readonly config;
     private _relay?;
     private _gate?;
+    private _passepartout?;
+    private _clockwork?;
     constructor(config: VerneConfig);
     get relay(): Relay;
     get gate(): Gate;
+    get passepartout(): Passepartout;
+    get clockwork(): Clockwork;
+    private serviceConfig;
+}
+
+interface GateTokenVerifierConfig {
+    /** Your tenant id. The issuer is `<baseUrl>/auth/<tenantId>`. */
+    tenantId: string;
+    /** Defaults to https://api.vernesoft.com — the same base URL as the API client. */
+    baseUrl?: string;
+    /** Allowed clock skew in seconds for `exp` and `nbf`. Default 10. */
+    clockToleranceSeconds?: number;
+    /** Timeout of a key-set request in milliseconds. Default 10000. */
+    timeoutMs?: number;
+}
+/**
+ * Verifies Gate signed tokens (ES256 JWTs) offline, against your tenant's published
+ * public keys. No API key is involved: anything that receives a token can verify it.
+ *
+ * What it checks: the algorithm is ES256 (anything else, `none` included, is refused),
+ * the key is the one the token's `kid` names in your tenant's key set, the signature,
+ * `iss` is **your** issuer (a token of another Gate tenant is refused even though its
+ * signature is valid), `exp` and `nbf`, and that `sub` is present.
+ *
+ * What it cannot check: whether the session behind the token is still alive. A signed
+ * token lives 15 minutes and cannot be revoked; for anything that must follow a
+ * revocation or a role change at once, ask `gate.sessions.check()` or introspection.
+ *
+ * The key set is cached for its `Cache-Control: max-age` (five minutes) and refetched
+ * once when a token names a key it has not seen — which is how a key rotation is
+ * followed. Keep one verifier per tenant and reuse it.
+ *
+ * @example
+ * const verifier = new GateTokenVerifier({ tenantId: process.env.VERNE_TENANT_ID! });
+ * const claims = await verifier.verify(token);
+ * claims.sub;  // the end user's id
+ * claims.orgs; // [{ id, role, permissions }]
+ */
+declare class GateTokenVerifier {
+    readonly issuer: string;
+    readonly jwksUrl: string;
+    private readonly toleranceSeconds;
+    private readonly timeoutMs;
+    private keys;
+    private fetchedAt;
+    private maxAgeMs;
+    private inflight?;
+    constructor(config: GateTokenVerifierConfig);
+    /**
+     * Verifies `token` and returns its claims. Throws {@link VerneTokenError} (with a
+     * `reason`) when the token must not be trusted.
+     */
+    verify(token: string): Promise<SignedTokenClaims>;
+    private keyFor;
+    /**
+     * Fetches the key set. With `required` false a failure keeps the keys already cached
+     * (a stale key set is still the right one unless a token says otherwise).
+     */
+    private refresh;
+    private load;
 }
 
 /**
@@ -395,27 +1366,75 @@ declare class VerneError extends Error {
  * Contains structured information from the API error envelope.
  */
 declare class VerneAPIError extends VerneError {
-    /** Machine-readable error code (e.g. 'invalid_payload', 'unauthorized'). */
+    /**
+     * Machine-readable error code, e.g. `'invalid_payload'`, `'forbidden'`, `'conflict'`,
+     * `'mfa_required'`, `'ACTIVE_USER_LIMIT_REACHED'`. Codes are an open set: compare
+     * against the ones you handle and treat the rest generically. `'unknown'` when the
+     * response carried no string code — which the API's own routes no longer do; it is
+     * left for a body that did not come from the gateway (a proxy in between, an identity
+     * service response passed through on `/auth/*`).
+     */
     readonly code: string;
     /** HTTP status code. */
     readonly status: number;
-    /** Request ID to include when contacting support. */
-    readonly requestId: string;
-    constructor({ code, message, status, requestId, }: {
+    /**
+     * Request ID to include when contacting support.
+     * Undefined when the response did not carry one.
+     */
+    readonly requestId?: string;
+    /**
+     * The members of `error` other than `code`, `message` and `request_id` — for example
+     * `plan`, `limit` and `current` on a `402` limit refusal, `kind` on a Clockwork one,
+     * `required_aal` and `current_aal` on `403 mfa_required`. Empty when there are none.
+     */
+    readonly details: Record<string, unknown>;
+    /**
+     * Seconds from the `Retry-After` header, when the response had one — on a `429` it is
+     * how long to wait. For `RELAY_MESSAGE_LIMIT_REACHED` it runs to the 1st of next month.
+     */
+    readonly retryAfter?: number;
+    /** Raw parsed error body, kept so unrecognised shapes stay diagnosable. */
+    readonly body?: unknown;
+    constructor({ code, message, status, requestId, details, retryAfter, body, }: {
         code: string;
         message: string;
         status: number;
-        requestId: string;
+        requestId?: string;
+        details?: Record<string, unknown>;
+        retryAfter?: number;
+        body?: unknown;
     });
-    static fromResponse(status: number, body: APIErrorBody): VerneAPIError;
+    /**
+     * Builds an error from a parsed response body of *unknown* shape.
+     *
+     * Every API route answers with the envelope `{ error: { code, message, request_id,
+     * ...extra } }`. Other shapes are still read, as a fallback that costs nothing: the
+     * string form `{ error: "<sentence>" }` Clockwork used before October 2026, and an
+     * identity-service body whose `code` is a number (still what Kratos' own `/auth/*`
+     * self-service routes answer). Anything unrecognised degrades — to code `'unknown'`,
+     * to `HTTP <status>` — rather than throwing: an error path must never be the thing
+     * that fails.
+     */
+    static fromResponse(status: number, body: unknown, retryAfter?: number): VerneAPIError;
+}
+/** Why a signed token was refused by {@link VerneTokenError}. */
+type TokenErrorReason = 'malformed' | 'unsupported_alg' | 'unknown_kid' | 'bad_signature' | 'wrong_issuer' | 'expired' | 'not_yet_valid' | 'missing_claim' | 'jwks_unavailable';
+/**
+ * Thrown by signed-token verification (`GateTokenVerifier`, `gate.tokens.verifySigned`)
+ * when a token must not be trusted. `reason` says why.
+ */
+declare class VerneTokenError extends VerneError {
+    readonly reason: TokenErrorReason;
+    constructor(reason: TokenErrorReason, message: string);
 }
-/** Shape of the API error envelope returned by all Verne services. */
+/** Shape of the API error envelope documented for all Verne services. */
 interface APIErrorBody {
     error: {
         code: string;
         message: string;
         request_id: string;
+        [extra: string]: unknown;
     };
 }
 
-export { type APIErrorBody, type AccessToken, type AuthorizeParams, type AuthorizeResult, type CreateIdentityParams, type CreateTokenParams, Gate, type Identity, type IdentityTraits, type IntrospectResult, type JsonPatchOp, type ListMessagesParams, type ListMessagesResponse, type LoginFlow, type Message, type OidcProvider, type Paginated, Relay, type RequestOptions, type SecuritySettings, type SendMessageParams, type ServiceConfig, Verne, VerneAPIError, type VerneConfig, VerneError };
+export { type APIErrorBody, type AccessToken, type AddMemberParams, type AuditActorType, type AuditLogEntry, type AuthorizeParams, type AuthorizeResult, Clockwork, type ClockworkUsage, type CreateCronJobParams, type CreateDelayedJobParams, type CreateIdentityParams, type CreateOrganizationParams, type CreateRoleParams, type CreateTokenParams, type CronJob, type DelayedJob, type Execution, Gate, type GateSession, GateTokenVerifier, type GateTokenVerifierConfig, type Identity, type IdentityTraits, type IntrospectResult, type JsonPatchOp, type LifecycleAction, type LifecycleRule, type LifecycleRuleKind, type LifecycleRuleParamsByKind, type LifecycleRulePreview, type LifecycleRules, type ListAuditLogParams, type ListLifecycleActionsParams, type ListMessagesParams, type ListMessagesResponse, type ListParams, type LoginFlow, type LoginFlowParams, type LoginStart, type LoginStatus, type Member, type Message, type OidcExchangeResult, type OidcProvider, type OrgClaim, type Organization, type OrganizationAuthorizeReason, type OwnershipAuthorizeReason, type Paginated, Passepartout, type RegistrationFlowParams, Relay, type RequestOptions, type Role, type SecuritySettings, type SendMessageParams, type ServiceConfig, type SessionCheck, type SetLifecycleRuleParams, type SignedToken, type SignedTokenClaims, type TelegramUser, type TokenErrorReason, type TokenIntrospection, type UpdateCronJobParams, type UpdateMemberParams, type UpdateOrganizationParams, type UpdateRoleParams, type VerifySignedOptions, Verne, VerneAPIError, type VerneConfig, VerneError, VerneTokenError };