@atlasauth/backend 0.25.0 → 0.26.0

package/dist/client/authz-decisions.d.ts

@@ -0,0 +1,108 @@
+import { type RequestFn } from './request';
+/**
+ * The authorization decision log: every ABAC, AuthZEN, FGA-check and
+ * access-policy decision can be recorded with its (redacted) input, result, the
+ * policy revision in force and latency — sampled, shipped as `authz.decision`
+ * events to your log streams, and queryable here.
+ */
+export type DecisionSource = 'abac' | 'authzen' | 'fga' | 'access_policy' | 'mcp_gateway';
+export interface AuthzDecision {
+    object: 'authz_decision';
+    id: string;
+    source: DecisionSource;
+    decision: 'allow' | 'deny';
+    /** `Type::id` (ABAC / AuthZEN), the FGA user, or the user id (access policies). */
+    principal: string | null;
+    /** The action, the FGA relation, or the access-policy stage. */
+    action: string | null;
+    resource: string | null;
+    /** The request as kept by `input_mode`; null when capture keeps none. */
+    input: Record<string, unknown> | null;
+    /** Reasons (policy names), matched policies, error counts, FGA `allowed` / `cached`. */
+    result: Record<string, unknown>;
+    /** The signed-bundle revision in force (`rev_…`); access policies carry an `ap_…` digest. */
+    policy_revision: string | null;
+    /** The exact policy versions or FGA model that evaluated. */
+    policy_version: Record<string, unknown> | null;
+    latency_ms: number;
+    /** The probability this decision was kept at; divide counts by it for the true volume. */
+    sample_rate: number;
+    actor_id: string | null;
+    created_at: number;
+}
+export interface ListAuthzDecisionsParams {
+    source?: DecisionSource;
+    decision?: 'allow' | 'deny';
+    principal?: string;
+    action?: string;
+    resource?: string;
+    policy_revision?: string;
+    /** ISO 8601 or epoch milliseconds. */
+    since?: string | number;
+    until?: string | number;
+    /** 1–200; default 50. */
+    limit?: number;
+    starting_after?: string;
+}
+export interface AuthzDecisionPage {
+    object: 'list';
+    data: AuthzDecision[];
+    has_more: boolean;
+    /** Pass as `starting_after` for the next page. */
+    next_cursor: string | null;
+}
+export interface AuthzDecisionStats {
+    object: 'authz_decision_stats';
+    since: number;
+    until: number;
+    recorded: number;
+    /** Recorded decisions scaled back up by their sample rates. */
+    estimated_total: number;
+    by_source: Record<string, {
+        allow: number;
+        deny: number;
+        estimated_allow: number;
+        estimated_deny: number;
+    }>;
+    latency_ms: {
+        p50: number | null;
+        p95: number | null;
+        p99: number | null;
+        max: number | null;
+    };
+}
+export interface AuthzDecisionSettings {
+    object: 'authz_decision_settings';
+    /** Record decisions. Off by default. */
+    enabled: boolean;
+    /** Probability (0–1) an allow is recorded. */
+    sample_rate_allow: number;
+    /** Probability (0–1) a deny is recorded. */
+    sample_rate_deny: number;
+    /** `ids` keeps identifiers only; `full` keeps the request minus `redact`; `none` keeps no input. */
+    input_mode: 'ids' | 'full' | 'none';
+    /** Dotted paths blanked in `full` mode; `*` matches one segment. */
+    redact: string[];
+    /** Also emit each recorded decision as an `authz.decision` event. */
+    ship_to_events: boolean;
+    /** Days to keep decisions; null keeps them. */
+    retention_days: number | null;
+}
+export type UpdateAuthzDecisionSettingsBody = Partial<Omit<AuthzDecisionSettings, 'object'>>;
+export declare function authzDecisionsResource(request: RequestFn): {
+    /** Query the decision log, newest first. */
+    list(params?: ListAuthzDecisionsParams): Promise<AuthzDecisionPage>;
+    /** Follow `next_cursor` and yield every matching decision. */
+    iterate(params?: Omit<ListAuthzDecisionsParams, "starting_after">): AsyncGenerator<AuthzDecision>;
+    get(id: string): Promise<AuthzDecision>;
+    /** Counts per engine and outcome, sampling-corrected, with latency percentiles (the last 24 hours by default). */
+    stats(params?: {
+        since?: string | number;
+        until?: string | number;
+    }): Promise<AuthzDecisionStats>;
+    settings: {
+        get(): Promise<AuthzDecisionSettings>;
+        /** Fields you omit keep their value. */
+        update(body: UpdateAuthzDecisionSettingsBody): Promise<AuthzDecisionSettings>;
+    };
+};

package/dist/client/authz-decisions.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.authzDecisionsResource = authzDecisionsResource;
+const request_1 = require("./request");
+function authzDecisionsResource(request) {
+    return {
+        /** Query the decision log, newest first. */
+        list(params = {}) {
+            return request({ method: 'GET', path: '/v1/authz_decisions', query: { ...params } });
+        },
+        /** Follow `next_cursor` and yield every matching decision. */
+        async *iterate(params = {}) {
+            let after;
+            for (;;) {
+                const page = await this.list({ ...params, starting_after: after });
+                yield* page.data;
+                if (!page.has_more || !page.next_cursor)
+                    return;
+                after = page.next_cursor;
+            }
+        },
+        get(id) {
+            return request({ method: 'GET', path: `/v1/authz_decisions/${(0, request_1.enc)(id)}` });
+        },
+        /** Counts per engine and outcome, sampling-corrected, with latency percentiles (the last 24 hours by default). */
+        stats(params = {}) {
+            return request({ method: 'GET', path: '/v1/authz_decisions/stats', query: { ...params } });
+        },
+        settings: {
+            get() {
+                return request({ method: 'GET', path: '/v1/authz_decision_settings' });
+            },
+            /** Fields you omit keep their value. */
+            update(body) {
+                return request({ method: 'PUT', path: '/v1/authz_decision_settings', body });
+            },
+        },
+    };
+}
+//# sourceMappingURL=authz-decisions.js.map

package/dist/client/authz-decisions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authz-decisions.js","sourceRoot":"","sources":["../../src/client/authz-decisions.ts"],"names":[],"mappings":";;AA0FA,wDAiCC;AA3HD,uCAAgD;AA0FhD,SAAgB,sBAAsB,CAAC,OAAkB;IACvD,OAAO;QACL,4CAA4C;QAC5C,IAAI,CAAC,SAAmC,EAAE;YACxC,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,qBAAqB,EAAE,KAAK,EAAE,EAAE,GAAG,MAAM,EAAE,EAAE,CAAC,CAAC;QACvF,CAAC;QACD,8DAA8D;QAC9D,KAAK,CAAC,CAAC,OAAO,CAAC,SAA2D,EAAE;YAC1E,IAAI,KAAyB,CAAC;YAC9B,SAAS,CAAC;gBACR,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,MAAM,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,CAAC;gBACnE,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;gBACjB,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,WAAW;oBAAE,OAAO;gBAChD,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC;YAC3B,CAAC;QACH,CAAC;QACD,GAAG,CAAC,EAAU;YACZ,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,uBAAuB,IAAA,aAAG,EAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QAC5E,CAAC;QACD,kHAAkH;QAClH,KAAK,CAAC,SAA+D,EAAE;YACrE,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,2BAA2B,EAAE,KAAK,EAAE,EAAE,GAAG,MAAM,EAAE,EAAE,CAAC,CAAC;QAC7F,CAAC;QACD,QAAQ,EAAE;YACR,GAAG;gBACD,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,6BAA6B,EAAE,CAAC,CAAC;YACzE,CAAC;YACD,wCAAwC;YACxC,MAAM,CAAC,IAAqC;gBAC1C,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,6BAA6B,EAAE,IAAI,EAAE,CAAC,CAAC;YAC/E,CAAC;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/client/connections.d.ts

@@ -0,0 +1,507 @@
+import { type RequestFn } from './request';
+import type { CursorParams, ListPage } from './types';
+export type ConnectionOwnerType = 'organization' | 'user';
+export type ConnectionEnvironment = 'production' | 'sandbox';
+export type ConnectionRelayMethod = 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export type ConnectionStatus = 'connected' | 'needs_reauth' | 'revoked' | 'error' | 'not_connected';
+/**
+ * A connection: one provider account that an organization or a user owns. An OAuth connection holds its own
+ * token set (sealed in the vault), independent of any user, and is never a sign-in method.
+ */
+export interface Connection {
+    object: 'connection';
+    id: string;
+    owner: {
+        type: ConnectionOwnerType;
+        id: string;
+    };
+    kind: string;
+    provider: string;
+    name: string;
+    allowed_hosts: string[];
+    config: Record<string, unknown>;
+    status: ConnectionStatus;
+    /** Always `data`: connecting adds no sign-in method. */
+    purpose: 'data';
+    environment: ConnectionEnvironment;
+    sandbox: boolean;
+    /** The provider-side account this connection covers (a realm, a workspace, a hub, a user id). */
+    external_id: string | null;
+    host_params: Record<string, string>;
+    oauth_client_id: string | null;
+    /** Connections from one grant (a Xero split connect) share this id and one token set; null = the connection owns its tokens. */
+    token_family_id: string | null;
+    scopes: string[];
+    /** Epoch ms. */
+    expires_at: number | null;
+    metadata: Record<string, string>;
+    authorized_by_user_id: string | null;
+    connected_at: number | null;
+    last_refreshed_at: number | null;
+    status_changed_at: number | null;
+    /** Why the connection left `connected`, or why the last refresh failed: the provider's own error code and HTTP status. */
+    last_error: {
+        code: string;
+        message: string;
+        httpStatus?: number | null;
+        at: number;
+    } | null;
+    /** Consecutive failed refreshes; 0 when healthy. */
+    refresh_failures: number;
+    /** When the keep-alive worker next refreshes this connection (epoch ms). */
+    next_refresh_at: number | null;
+    /** @deprecated Always null: a connection owns its tokens. */
+    external_account_id: null;
+    has_secret: boolean;
+    /** When the entered credential expires (epoch ms); `connection.secret_expiring` reminders go out 30, 7 and 1 days before. */
+    secret_expires_at: number | null;
+    /** While a rotation's overlap window is open: when the replaced version stops being accepted. */
+    previous_valid_until: number | null;
+    allowed_methods: ConnectionRelayMethod[];
+    created_at: number;
+    updated_at: number;
+}
+export interface CreateConnectionBody {
+    owner: {
+        type: ConnectionOwnerType;
+        id: string;
+    };
+    kind: string;
+    provider: string;
+    name?: string;
+    allowed_hosts: string[];
+    config?: Record<string, unknown>;
+    environment?: ConnectionEnvironment;
+    /** Values that fill the provider's host templates, e.g. `{ subdomain: 'acme' }`. Validated per provider. */
+    host_params?: Record<string, string>;
+    /** Relay verbs this connection may use; GET, HEAD and POST unless set. */
+    allowed_methods?: ConnectionRelayMethod[];
+}
+export interface UpdateConnectionBody {
+    name?: string;
+    allowed_hosts?: string[];
+    config?: Record<string, unknown>;
+    /** Transfer to another owner; the stored tokens move with it. */
+    owner?: {
+        type: ConnectionOwnerType;
+        id: string;
+    };
+    environment?: ConnectionEnvironment;
+    host_params?: Record<string, string>;
+    shared_by_user_id?: string;
+    allowed_methods?: ConnectionRelayMethod[];
+}
+export interface ListConnectionsParams extends CursorParams {
+    owner_type?: ConnectionOwnerType;
+    owner_id?: string;
+    provider?: string;
+    environment?: ConnectionEnvironment;
+    status?: ConnectionStatus;
+}
+export interface ConnectConnectionBody {
+    redirect_url: string;
+    host_params?: Record<string, string>;
+    environment?: ConnectionEnvironment;
+    additional_scopes?: string[];
+    login_hint?: string;
+    display?: 'redirect' | 'popup';
+    /** A different provider account than the connection holds creates a sibling instead of answering 409. */
+    create_if_new?: boolean;
+    /** One grant covering several accounts (Xero organisations) becomes one connection per account, sharing one token set. */
+    split_tenants?: boolean;
+    connect_user_id?: string;
+}
+export interface ConnectionAuthorization {
+    object: 'connection_authorization';
+    connection_id: string;
+    authorization_url: string;
+    attempt_id: string;
+}
+export interface ConnectionToken {
+    object: 'connection_token';
+    connection_id: string;
+    access_token: string;
+    expires_at: number | null;
+    scopes: string[];
+    metadata: Record<string, string>;
+    token_response: Record<string, unknown>;
+    /** Further credentials by name (Slack: `user`). */
+    credentials: Record<string, {
+        access_token: string;
+        expires_at: number | null;
+        scopes: string[];
+    }>;
+    external_id: string | null;
+    environment: ConnectionEnvironment;
+    host_params: Record<string, string>;
+    refreshed: boolean;
+    /** jwt_bearer: the user the token acts as (domain-wide delegation). */
+    subject?: string;
+}
+/** What the provider said when a token was revoked. The local token is cleared in every case. */
+export interface ProviderRevokeResult {
+    /** `true` the provider confirmed; `'unsupported'` it has no revoke endpoint; `false` it refused or was unreachable (see `provider_error`). */
+    provider_revoked: boolean | 'unsupported' | 'not_connected';
+    provider_status: number | null;
+    provider_error: {
+        code: string;
+        description: string | null;
+    } | null;
+    local_cleared: true;
+}
+export type ConnectionRevoked = Connection & ProviderRevokeResult;
+export interface ConnectionDeletion extends ProviderRevokeResult {
+    object: 'connection_deletion';
+    id: string;
+    deleted: true;
+}
+export interface ConnectionTokenBatchItem {
+    id: string;
+    status: 'ok' | 'error';
+    token?: ConnectionToken;
+    error?: {
+        code: 'connection_required' | 'not_found';
+        reason?: 'not_connected' | 'needs_reauth' | 'revoked' | 'refresh_failed' | 'unknown_connection';
+    };
+}
+/** One row of a bulk import. `external_id` is the provider-side account; a re-import of it updates the same connection. */
+export interface ImportConnectionRow {
+    provider: string;
+    owner: {
+        type: ConnectionOwnerType;
+        id: string;
+    };
+    external_id: string;
+    refresh_token?: string;
+    access_token?: string;
+    /** Epoch ms or ISO 8601. */
+    expires_at?: number | string;
+    scopes?: string[] | string;
+    metadata?: Record<string, string | number | boolean>;
+    environment?: ConnectionEnvironment;
+    host_params?: Record<string, string>;
+    name?: string;
+    allowed_hosts?: string[];
+}
+export interface ImportConnectionsBody {
+    /** 1 to 500 rows. */
+    connections: ImportConnectionRow[];
+    /** Spend each refresh token against the provider and store what it issues (default true). */
+    validate?: boolean;
+    /** Check shapes only; never calls the provider. */
+    dry_run?: boolean;
+}
+export interface ImportConnectionResult {
+    index: number;
+    status: 'created' | 'updated' | 'would_create' | 'would_update' | 'failed';
+    connection_id: string | null;
+    validated: boolean;
+    refreshed: boolean;
+    error: {
+        code: string;
+        message: string;
+        field?: string;
+        provider_error?: {
+            code: string;
+            description: string | null;
+            http_status: number | null;
+        };
+    } | null;
+}
+export interface ImportConnectionsResult {
+    object: 'connection_import';
+    total: number;
+    dry_run: boolean;
+    validated: boolean;
+    created: number;
+    updated: number;
+    would_create: number;
+    would_update: number;
+    failed: number;
+    data: ImportConnectionResult[];
+}
+export interface ExportConnectionsBody {
+    owner_type?: ConnectionOwnerType;
+    owner_id?: string;
+    provider?: string;
+    environment?: ConnectionEnvironment;
+    status?: ConnectionStatus;
+    limit?: number;
+    starting_after?: string;
+    /** Include the tokens, sealed to `recipient_public_key`. Needs the `connections:export_secrets` scope. */
+    include_secrets?: boolean;
+    /** A public JWK: RSA (3072 bits or more) or EC P-256/384/521. Never the private half. */
+    recipient_public_key?: Record<string, unknown>;
+}
+export interface ExportedConnection {
+    provider: string;
+    owner: {
+        type: ConnectionOwnerType;
+        id: string;
+    };
+    external_id: string | null;
+    environment: ConnectionEnvironment;
+    host_params: Record<string, string>;
+    scopes: string[];
+    metadata: Record<string, string>;
+    name: string;
+    allowed_hosts: string[];
+    status: ConnectionStatus;
+    expires_at: number | null;
+    refresh_token?: string;
+    access_token?: string;
+}
+export type ExportConnectionsResult = {
+    object: 'connection_export';
+    sealed: false;
+    count: number;
+    has_more: boolean;
+    next_cursor: string | null;
+    connections: ExportedConnection[];
+} | {
+    object: 'connection_export';
+    sealed: true;
+    count: number;
+    has_more: boolean;
+    next_cursor: string | null;
+    recipient_key_id: string;
+    bundle: string;
+};
+export interface TokenReadOptions {
+    /** Refresh first unless at least this many seconds of validity remain (0 to 3600). */
+    minTtlSeconds?: number;
+    /** Force a refresh now. Prefer {@link refreshToken}, which does not refresh again when a peer already did. */
+    refresh?: boolean;
+    /** Skip the in-process cache for this call. */
+    noCache?: boolean;
+    /** jwt_bearer only: act as this user (Google domain-wide delegation). Never cached. */
+    subject?: string;
+}
+/** An owner's own OAuth client (BYOK) for a provider. The secret is write-only. */
+export interface ConnectionOAuthClient {
+    object: 'connection_oauth_client';
+    id: string;
+    owner: {
+        type: ConnectionOwnerType;
+        id: string;
+    };
+    provider: string;
+    environment: ConnectionEnvironment;
+    client_id: string;
+    has_secret: true;
+    scopes: string[];
+    host_params: Record<string, string>;
+    enabled: boolean;
+    /** The redirect URI to register on this client at the provider. */
+    callback_url: string;
+    created_at: number;
+    updated_at: number;
+}
+export interface SetConnectionOAuthClientBody {
+    owner: {
+        type: ConnectionOwnerType;
+        id: string;
+    };
+    provider: string;
+    environment?: ConnectionEnvironment;
+    client_id: string;
+    /** Required when the client is first created; omit to keep the stored secret. */
+    client_secret?: string;
+    scopes?: string[];
+    host_params?: Record<string, string>;
+    enabled?: boolean;
+}
+/**
+ * The credential fields of a connection's kind (write-only). api_key `{api_key}`, bearer `{token}`, basic
+ * `{username, password}`, custom_header `{value}`, hmac_secret `{secret}`, client_credentials `{client_id,
+ * client_secret, token_url...}`, jwt_bearer `{private_key | service_account_json | generate_key | assertion}`,
+ * oauth1 `{consumer_key, consumer_secret, token?, token_secret?}`, github_app_installation `{private_key}`.
+ * The kind's non-secret settings may ride along or go in `config`.
+ */
+export interface SetConnectionCredentialsBody {
+    [field: string]: unknown;
+    /** Epoch milliseconds or an ISO date. Reminders go out at 30, 7 and 1 days before. */
+    expires_at?: number | string;
+    config?: Record<string, unknown>;
+}
+export interface RotateConnectionCredentialsBody extends SetConnectionCredentialsBody {
+    /** How long the replaced version stays valid, 0 to 30 days. Default 3600. */
+    overlap_seconds?: number;
+}
+export interface ConnectionSecret {
+    object: 'connection_secret';
+    connection_id: string;
+    kind: 'api_key' | 'bearer' | 'basic' | 'custom_header' | 'hmac_secret';
+    version: number;
+    /** api_key `{api_key}`, bearer `{token}`, basic `{username, password}`, custom_header `{value}`, hmac_secret `{secret}`. */
+    secret: Record<string, string>;
+    config: Record<string, unknown>;
+    expires_at: number | null;
+}
+export interface ConnectionSecretVersions {
+    object: 'list';
+    connection_id: string;
+    current_version: number | null;
+    previous_valid_until: number | null;
+    data: Array<{
+        object: 'connection_secret_version';
+        version: number;
+        current: boolean;
+        previous: boolean;
+        created_at: number;
+        valid_until: number | null;
+    }>;
+    has_more: false;
+}
+export interface ConnectionSignature {
+    object: 'connection_signature';
+    connection_id: string;
+    /** The `Authorization: OAuth ...` header value, valid for this method, URL and body only. */
+    authorization: string;
+    method: string;
+    url: string;
+}
+export type ConnectionWebhookScheme = 'hubspot_v3' | 'shopify_hmac' | 'intercom' | 'zoom' | 'slack_v0' | 'calendly' | 'stripe' | 'generic_hmac_sha256';
+export interface VerifyConnectionWebhookBody {
+    scheme: ConnectionWebhookScheme;
+    /** The delivery's headers. */
+    headers: Record<string, string>;
+    /** The body exactly as received. */
+    raw_body: string;
+    raw_body_encoding?: 'utf8' | 'base64';
+    /** hubspot_v3: the method and the full URL the provider posted to. */
+    method?: string;
+    url?: string;
+    /** Use this webhook endpoint's signing secret and options. */
+    endpoint_id?: string;
+    tolerance_seconds?: number;
+    /** generic_hmac_sha256: `signature_header`, `encoding`, `prefix`, `algorithm`. */
+    options?: Record<string, string>;
+    /** false checks without remembering the delivery for replay protection. */
+    record_replay?: boolean;
+}
+export interface ConnectionWebhookVerification {
+    object: 'connection_webhook_verification';
+    connection_id: string;
+    scheme: ConnectionWebhookScheme;
+    valid: boolean;
+    reason: 'missing_signature' | 'missing_timestamp' | 'malformed_signature' | 'stale_timestamp' | 'bad_signature' | 'url_required' | 'replayed' | null;
+    replayed: boolean;
+    timestamp: number | null;
+    delivery_id: string | null;
+    /** Zoom endpoint.url_validation or Slack url_verification: answer the provider with this body. */
+    handshake: Record<string, string> | null;
+}
+export interface ConnectionWebhookEndpoint {
+    object: 'connection_webhook_endpoint';
+    id: string;
+    connection_id: string;
+    scheme: ConnectionWebhookScheme;
+    forward_url: string;
+    /** Give this URL to the provider. */
+    ingress_url: string;
+    options: Record<string, string>;
+    has_signing_secret: boolean;
+    enabled: boolean;
+    last_delivery_at: number | null;
+    created_at: number;
+    updated_at: number;
+    /** Only in the create response, once: verifies the Atlas-signed deliveries sent to `forward_url`. */
+    forward_secret?: string;
+}
+export interface CreateConnectionWebhookEndpointBody {
+    scheme: ConnectionWebhookScheme;
+    /** https URL that receives verified deliveries as Atlas-signed webhooks. */
+    forward_url: string;
+    /** Write-only provider signing secret for this endpoint. */
+    signing_secret?: string;
+    options?: Record<string, string>;
+}
+/** Org- or user-owned provider connections and their stored tokens. */
+export declare function connectionsResource(request: RequestFn): {
+    create(body: CreateConnectionBody, idempotencyKey?: string): Promise<Connection>;
+    list(params?: ListConnectionsParams): Promise<ListPage<Connection>>;
+    get(id: string): Promise<Connection>;
+    update(id: string, body: UpdateConnectionBody): Promise<Connection>;
+    /** Delete a connection. Pass `{ revoke: true }` to revoke at the provider first and learn what it said. */
+    delete<R extends boolean = false>(id: string, options?: {
+        revoke?: R;
+    }): Promise<R extends true ? ConnectionDeletion : void>;
+    /** Start the provider authorization; send the owner to `authorization_url`. */
+    connect(id: string, body: ConnectConnectionBody): Promise<ConnectionAuthorization>;
+    /** Revoke at the provider and forget the stored token. The answer says what the provider said (`provider_revoked`). */
+    revoke(id: string): Promise<ConnectionRevoked>;
+    /**
+     * The live token for your backend (refreshed when needed). Needs the `connections:token` scope.
+     * Reads are cached in this client until shortly before `expires_at` (and a cached read is `refreshed: false`),
+     * so calling it in a hot loop costs one request per connection per token lifetime.
+     */
+    token(id: string, options?: TokenReadOptions): Promise<ConnectionToken>;
+    /**
+     * Call this when the provider answers 401 to a token you got from here. Pass the access token you were refused with
+     * (`staleAccessToken`): if Atlas already holds a newer one, you get it back without another call to the provider.
+     */
+    refreshToken(id: string, options?: {
+        staleAccessToken?: string;
+        reason?: "provider_401" | "expired" | "manual";
+    }): Promise<ConnectionToken>;
+    /** Read up to 100 connections' tokens in one call. Each id has its own result, so one dead connection does not fail the rest. */
+    tokens(ids: string[], options?: {
+        minTtlSeconds?: number;
+    }): Promise<{
+        object: "list";
+        data: ConnectionTokenBatchItem[];
+        has_more: false;
+    }>;
+    /** Bulk-import existing provider refresh tokens (up to 500 per call). Needs the `connections:import` scope. */
+    importConnections(body: ImportConnectionsBody, idempotencyKey?: string): Promise<ImportConnectionsResult>;
+    /**
+     * Export connections. Without `include_secrets` it lists metadata. With it (scope `connections:export_secrets`) the tokens
+     * come back as one compact JWE sealed to `recipient_public_key`; open it with the matching private key.
+     */
+    exportConnections(body?: ExportConnectionsBody): Promise<ExportConnectionsResult>;
+    /** Enter the credential of a non-OAuth connection (write-only; sealed in the vault, never returned). */
+    setCredentials(id: string, body: SetConnectionCredentialsBody): Promise<Connection>;
+    /** Rotate the credential; the replaced version stays valid for `overlap_seconds`. */
+    rotateCredentials(id: string, body: RotateConnectionCredentialsBody): Promise<Connection>;
+    /** The credential's vault versions (numbers and times, never values). */
+    secretVersions(id: string): Promise<ConnectionSecretVersions>;
+    /**
+     * Read an api_key, bearer, basic, custom_header or hmac_secret credential. Needs the `connections:secret_read`
+     * scope; every read is audited. `version` is `current` (default), `previous` (inside a rotation's overlap
+     * window) or a number. With `organizationId` the connection must belong to that organization (404 otherwise).
+     */
+    secret(id: string, options?: {
+        version?: "current" | "previous" | number;
+        organizationId?: string;
+    }): Promise<ConnectionSecret>;
+    /** Have Atlas sign a request with an oauth1 connection (needs `connections:sign`). */
+    oauth1Sign(id: string, body: {
+        method?: string;
+        url: string;
+        body?: string;
+        content_type?: string;
+    }): Promise<ConnectionSignature>;
+    webhooks: {
+        /** Verify a provider webhook signature (needs `connections:webhook_verify`). */
+        verify(id: string, body: VerifyConnectionWebhookBody): Promise<ConnectionWebhookVerification>;
+        createEndpoint(id: string, body: CreateConnectionWebhookEndpointBody): Promise<ConnectionWebhookEndpoint>;
+        listEndpoints(id: string): Promise<ListPage<ConnectionWebhookEndpoint>>;
+        updateEndpoint(id: string, endpointId: string, body: {
+            forward_url?: string;
+            enabled?: boolean;
+            signing_secret?: string;
+        }): Promise<ConnectionWebhookEndpoint>;
+        deleteEndpoint(id: string, endpointId: string): Promise<void>;
+    };
+    oauthClients: {
+        set(body: SetConnectionOAuthClientBody): Promise<ConnectionOAuthClient>;
+        list(params?: {
+            owner_type?: ConnectionOwnerType;
+            owner_id?: string;
+            provider?: string;
+        }): Promise<ListPage<ConnectionOAuthClient>>;
+        get(id: string): Promise<ConnectionOAuthClient>;
+        delete(id: string): Promise<void>;
+    };
+};