@assinafy/sdk 2.2.0 → 2.4.0

package/dist/index.d.ts

@@ -22,9 +22,41 @@ type SignatureImageType = 'signature' | 'initial' | AnyString;
 type AnyString = string & {};
 /** Assignment methods supported by the API. */
 type AssignmentMethod = 'virtual' | 'collect';
-/** Verification methods accepted by assignment signer entries. */
+/**
+ * How a signer proves who they are before signing.
+ *
+ * | Value | How the signer is verified | Requirements | Cost per signer |
+ * | --- | --- | --- | --- |
+ * | `Email` | One-time code sent by e-mail (the default). | An `email`. | 0 credits |
+ * | `Whatsapp` | One-time code sent over WhatsApp. | A `whatsapp_phone_number`; paid plan. | 0.45 credits |
+ * | `DigitalCertificate` | The signer signs with their own ICP-Brasil certificate — **A1** (software, a file on the machine) or **A3** (hardware, a token or smartcard) — through the Web PKI browser extension, producing a qualified PAdES signature. | Digital Certificate feature (Standard/Pro); `government_id` (CPF, or CNPJ naming the signer as legal representative); the signer must be alone in their signing step. | 2 credits + notification |
+ *
+ * A1 and A3 are certificate *media*, chosen by the signer in their browser at
+ * signing time. The API models both as the single `DigitalCertificate` value —
+ * there is no separate `A1`/`A3` field to send, and the resulting PAdES
+ * signature is qualified either way.
+ *
+ * Verification is coupled to {@link AssignmentNotificationMethod}: the
+ * verification code travels on the notification channel, so `Email` pairs only
+ * with `Email` and `Whatsapp` only with `Whatsapp`. `DigitalCertificate`
+ * carries no code and may be announced over either channel. The SDK rejects an
+ * invalid pairing before the request; the API answers `400`.
+ *
+ * Send neither field to get `Email`/`Email`; send one and the other is
+ * inferred from it.
+ */
 type AssignmentVerificationMethod = 'Email' | 'Whatsapp' | 'DigitalCertificate';
-/** Notification methods accepted by assignment signer entries. */
+/**
+ * How the signing invitation reaches the signer. Exactly one per signer.
+ *
+ * | Value | Requirements | Cost per signer |
+ * | --- | --- | --- |
+ * | `Email` | An `email`. | 0 credits |
+ * | `Whatsapp` | A `whatsapp_phone_number`; paid plan. | 0.45 credits |
+ *
+ * Notifications are charged when the assignment is created and again on every
+ * resend. See {@link AssignmentVerificationMethod} for the pairing rules.
+ */
 type AssignmentNotificationMethod = 'Email' | 'Whatsapp';
 /** Minimal logger contract (compatible with console, pino, winston, etc.). */
 interface Logger {
@@ -271,9 +303,13 @@ interface IAssignmentCostSigner {
  */
 interface IEstimateAssignmentCostPayload {
     method?: AssignmentMethod;
-    /** Required for `virtual`; `{}` prices the default Email channel. */
-    signers?: IAssignmentCostSigner[];
-    /** Required for `collect`; signer descriptors are optional in that mode. */
+    /**
+     * Required for both methods — the API rejects an estimate without it, and
+     * per-signer `verification_method` is what the estimate prices. `{}` prices
+     * the default Email channel.
+     */
+    signers: IAssignmentCostSigner[];
+    /** Required for `collect`. */
     entries?: IAssignmentEntry[];
 }
 /** A signer as embedded inside an assignment (richer than the bare {@link ISigner}). */
@@ -1110,6 +1146,129 @@ interface IUpdateTagPayload {
     /** Pass `null` to clear the color; omit to leave unchanged. */
     color?: string | null;
 }
+/**
+ * Permission an OAuth application can request.
+ *
+ * Known literals stay suggested in editors while any server-added scope still
+ * type-checks (see {@link AnyString}). The authoritative list is
+ * `scopes_supported` in
+ * {@link IOAuthAuthorizationServerMetadata}.
+ */
+type OAuthScope = 'documents:read' | 'documents:write' | 'templates:read' | 'templates:write' | 'account:read' | 'openid' | 'profile' | 'email' | 'offline_access' | AnyString;
+/**
+ * RFC 9728 protected-resource metadata served at
+ * `https://api.assinafy.com.br/.well-known/oauth-protected-resource`.
+ *
+ * Served bare, without the `{ status, message, data }` envelope, as RFC 8615
+ * requires. `scopes_supported` omits `offline_access`, which is a request-time
+ * signal to the authorization server rather than a permission this API checks.
+ */
+interface IOAuthProtectedResourceMetadata {
+    /** Canonical identifier of this API, e.g. `https://api.assinafy.com.br`. */
+    resource: string;
+    /** Issuers allowed to mint tokens for it, e.g. `['https://auth.assinafy.com.br']`. */
+    authorization_servers: string[];
+    /** Scopes this API accepts. */
+    scopes_supported: string[];
+    /** How a token may be presented; Assinafy accepts `header` only. */
+    bearer_methods_supported: string[];
+}
+/**
+ * RFC 8414 authorization-server metadata served at
+ * `{issuer}/.well-known/oauth-authorization-server`.
+ *
+ * The browser-facing `authorization_endpoint` lives on the authorization server
+ * while `token_endpoint` and friends live on this API, so read the URLs from
+ * here rather than deriving them from one host.
+ */
+interface IOAuthAuthorizationServerMetadata {
+    /** Issuer identifier; must equal the URL the document was fetched from. */
+    issuer: string;
+    /** Browser-facing consent URL. */
+    authorization_endpoint: string;
+    /** Token endpoint, on the API host. */
+    token_endpoint: string;
+    revocation_endpoint?: string;
+    userinfo_endpoint?: string;
+    jwks_uri?: string;
+    scopes_supported?: string[];
+    response_types_supported?: string[];
+    grant_types_supported?: string[];
+    /** Assinafy supports `S256` only; plain PKCE is rejected. */
+    code_challenge_methods_supported?: string[];
+    token_endpoint_auth_methods_supported?: string[];
+    /** RFC 9207. `true` means the callback carries `iss` and clients must check it. */
+    authorization_response_iss_parameter_supported?: boolean;
+    client_id_metadata_document_supported?: boolean;
+}
+/**
+ * Everything one authorization attempt needs, returned by
+ * {@link OAuthResource.createAuthorizationUrl}.
+ *
+ * Store every field except `url` in the user's session: the callback handler
+ * needs `state` and `issuer` to prove the response is yours, the token exchange
+ * needs `codeVerifier`, and `nonce` validates the `id_token`.
+ */
+interface IOAuthAuthorizationRequest {
+    /** Absolute URL to send the browser to with a full page navigation. */
+    url: string;
+    /** Single-use CSRF value echoed back on the redirect URI. */
+    state: string;
+    /** RFC 7636 code verifier; never leaves your server after this. */
+    codeVerifier: string;
+    /** Issuer expected in the callback's `iss` parameter. */
+    issuer: string;
+    /** Present when `openid` was requested; compare it to the `id_token` claim. */
+    nonce?: string;
+}
+/**
+ * Validated authorization response read off the redirect URI by
+ * {@link OAuthResource.readAuthorizationCallback}.
+ */
+interface IOAuthAuthorizationCallback {
+    /** Single-use authorization code. Expires 60 seconds after approval. */
+    code: string;
+    /** The `state` value, already checked against the stored one. */
+    state: string;
+    /** The `iss` value, already checked against the expected issuer. */
+    issuer?: string;
+}
+/**
+ * RFC 6749 §5.1 token response. Returned flat, without this API's
+ * `{ status, message, data }` envelope.
+ */
+interface IOAuthTokenResponse {
+    access_token: string;
+    /** Always `Bearer`. */
+    token_type: string;
+    /** Access-token lifetime in seconds; Assinafy issues 3600. */
+    expires_in: number;
+    /**
+     * Present only when `offline_access` was requested and granted. Every
+     * refresh returns a new one and retires the old one — persist it before
+     * using the access token.
+     */
+    refresh_token?: string | null;
+    /**
+     * Scopes actually granted to the access token. Read this instead of
+     * assuming the request was honoured in full; `offline_access` never appears
+     * here because it is a request-time signal, not a permission.
+     */
+    scope?: string;
+    /** Signed OIDC identity token (RS256). Present only when `openid` was granted. */
+    id_token?: string | null;
+}
+/** OpenID Connect claims returned by `GET /oauth/userinfo`. */
+interface IOAuthUserInfo {
+    /** Stable user identifier. Always present. */
+    sub: string;
+    /** Requires the `profile` scope. */
+    name?: string | null;
+    /** Requires the `email` scope. */
+    email?: string | null;
+    /** Requires the `email` scope. */
+    email_verified?: boolean | null;
+}
 
 /** Maximum upload size accepted by the API (hard limit, 25 MB). */
 declare const MAX_UPLOAD_BYTES: number;
@@ -2778,7 +2937,8 @@ declare class AssignmentResource extends BaseResource {
      * }
      * ```
      * @throws {ValidationError} If `documentId` is missing, a `virtual` request
-     * has no signer entry, or a `collect` request has no field-placement entry.
+     * has no signer entry, or a `collect` request has no signer entry or no
+     * field-placement entry.
      * @throws {ApiError} If the API rejects the request.
      *
      * @example
@@ -3988,6 +4148,506 @@ declare class AuthenticationResource extends BaseResource {
     private absoluteUrl;
 }
 
+/** Token-endpoint client authentication methods Assinafy accepts. */
+type TokenEndpointAuthOptions = {
+    /** The application's `client_id` from Settings → OAuth applications. */
+    clientId: string;
+    /**
+     * The application's `client_secret`. Confidential applications only —
+     * public ones authenticate with PKCE and are never issued a secret. Never
+     * ship it in browser, mobile, or repository code.
+     */
+    clientSecret?: string;
+};
+/**
+ * OAuth 2.1 + OpenID Connect endpoints for applications acting inside *other
+ * people's* workspaces.
+ *
+ * Use this resource only when your product is connected by its users. To
+ * automate your own workspace, keep using an API key and ignore everything
+ * here.
+ *
+ * Two hosts are involved on purpose: the consent page lives on the
+ * authorization server (`https://auth.assinafy.com.br`) while the token,
+ * revocation and userinfo endpoints live on this API. Both are published by
+ * {@link OAuthResource.getAuthorizationServerMetadata}, so nothing needs
+ * hardcoding.
+ *
+ * The full round trip:
+ *
+ * 1. {@link OAuthResource.createAuthorizationUrl} — mint PKCE + `state`, build
+ *    the consent URL, store the returned request in the user's session.
+ * 2. Redirect the browser there; the user picks **one** workspace and approves.
+ * 3. {@link OAuthResource.readAuthorizationCallback} — check `state` and `iss`
+ *    on your redirect URI, and surface a declined consent as an
+ *    {@link OAuthError}.
+ * 4. {@link OAuthResource.exchangeCode} — swap the 60-second code for tokens.
+ * 5. Build a per-connection client with that token and read the one workspace
+ *    it covers:
+ *    ```ts
+ *    const connected = new AssinafyClient({ token: tokens.access_token });
+ *    const { data } = await connected.workspaces.list();
+ *    const accountId = data[0]?.id;
+ *    ```
+ * 6. {@link OAuthResource.refreshToken} before the hour is up (requires
+ *    `offline_access`), and {@link OAuthResource.revokeToken} when the user
+ *    disconnects.
+ *
+ * Two facts that cause most integration bugs: a token works for exactly one
+ * workspace (any other answers `403`), and a connection expires 30 days after
+ * approval no matter how often it is refreshed.
+ *
+ * @example
+ * ```ts
+ * const client = new AssinafyClient();               // no credentials needed
+ *
+ * // Step 1 — before redirecting the user
+ * const request = await client.oauth.createAuthorizationUrl({
+ *   clientId: process.env.ASSINAFY_CLIENT_ID!,
+ *   redirectUri: 'https://myapp.com/oauth/callback',
+ *   scopes: ['documents:read', 'documents:write', 'offline_access'],
+ * });
+ * session.oauth = request;                           // state + codeVerifier + issuer
+ * response.redirect(request.url);
+ *
+ * // Step 3/4 — on https://myapp.com/oauth/callback
+ * const { code } = client.oauth.readAuthorizationCallback(query, session.oauth);
+ * const tokens = await client.oauth.exchangeCode({
+ *   code,
+ *   codeVerifier: session.oauth.codeVerifier,
+ *   redirectUri: 'https://myapp.com/oauth/callback',
+ *   clientId: process.env.ASSINAFY_CLIENT_ID!,
+ *   clientSecret: process.env.ASSINAFY_CLIENT_SECRET,
+ * });
+ * ```
+ */
+declare class OAuthResource extends BaseResource {
+    private readonly publicHttp;
+    constructor(http: AxiosInstance, defaultAccountId?: string, logger?: Logger, publicHttp?: AxiosInstance);
+    /**
+     * Read this API's protected-resource metadata
+     * (`GET /.well-known/oauth-protected-resource`).
+     *
+     * Served at the API host root — not under `/v1` — and bare, without the
+     * `{ status, message, data }` envelope, as RFC 8615 requires. Use it to
+     * discover which authorization server may issue tokens for this API and
+     * which scopes it accepts.
+     *
+     * Request body: none. Authentication: none.
+     *
+     * @returns The metadata document:
+     * ```jsonc
+     * {
+     *   "resource": "https://api.assinafy.com.br",
+     *   "authorization_servers": ["https://auth.assinafy.com.br"],
+     *   "scopes_supported": [
+     *     "documents:read", "documents:write",
+     *     "templates:read", "templates:write",
+     *     "account:read", "openid", "profile", "email"
+     *   ],
+     *   "bearer_methods_supported": ["header"]
+     * }
+     * ```
+     * `offline_access` is deliberately absent: it is a request-time signal to
+     * the authorization server, not a permission this API enforces.
+     * @throws {ApiError} If the host does not publish the document.
+     *
+     * @example
+     * ```ts
+     * const metadata = await client.oauth.getProtectedResourceMetadata();
+     * console.log(metadata.authorization_servers[0]);
+     * ```
+     */
+    getProtectedResourceMetadata(): Promise<IOAuthProtectedResourceMetadata>;
+    /**
+     * Read the authorization server's metadata
+     * (`GET {issuer}/.well-known/oauth-authorization-server`, RFC 8414).
+     *
+     * Every endpoint URL an OAuth client needs comes from here, so nothing has
+     * to be hardcoded. The document is served by the authorization server, a
+     * different host from this API.
+     *
+     * @param issuer - Issuer to read. Defaults to the first entry of
+     * {@link OAuthResource.getProtectedResourceMetadata}, which costs one extra
+     * request — pass the issuer to skip it.
+     * @returns The metadata document:
+     * ```jsonc
+     * {
+     *   "issuer": "https://auth.assinafy.com.br",
+     *   "authorization_endpoint": "https://auth.assinafy.com.br/oauth/authorize",
+     *   "token_endpoint": "https://api.assinafy.com.br/v1/oauth/token",
+     *   "revocation_endpoint": "https://api.assinafy.com.br/v1/oauth/revoke",
+     *   "userinfo_endpoint": "https://api.assinafy.com.br/v1/oauth/userinfo",
+     *   "jwks_uri": "https://auth.assinafy.com.br/.well-known/jwks.json",
+     *   "scopes_supported": ["documents:read", "documents:write", "templates:read",
+     *                        "templates:write", "account:read", "openid",
+     *                        "profile", "email", "offline_access"],
+     *   "response_types_supported": ["code"],
+     *   "grant_types_supported": ["authorization_code", "refresh_token"],
+     *   "code_challenge_methods_supported": ["S256"],
+     *   "token_endpoint_auth_methods_supported": ["client_secret_post", "none"],
+     *   "authorization_response_iss_parameter_supported": true,
+     *   "client_id_metadata_document_supported": true
+     * }
+     * ```
+     * @throws {ValidationError} If `issuer` is not an absolute `https://` URL,
+     * or the document's own `issuer` disagrees with where it was fetched from
+     * (RFC 8414 §3.3 — a mismatch means the document is not authoritative).
+     * @throws {ApiError} If the authorization server rejects the request.
+     *
+     * @example
+     * ```ts
+     * const as = await client.oauth.getAuthorizationServerMetadata();
+     * console.log(as.authorization_endpoint);
+     * ```
+     */
+    getAuthorizationServerMetadata(issuer?: string): Promise<IOAuthAuthorizationServerMetadata>;
+    /**
+     * Mint a PKCE pair and a `state`, then build the consent URL to send the
+     * user's browser to (`GET {authorization_endpoint}`).
+     *
+     * Call this once per connection attempt and keep the whole returned object
+     * in the user's session: reusing a verifier or a `state` across attempts
+     * defeats both PKCE and CSRF protection. Navigate the browser to `url` with
+     * a full page load — an `fetch`/XHR cannot show a consent screen.
+     *
+     * PKCE is mandatory for confidential applications too, and Assinafy accepts
+     * only the `S256` challenge method.
+     *
+     * @param options - Authorization-request options.
+     * @param options.clientId - The application's `client_id`.
+     * @param options.redirectUri - One of the application's registered redirect
+     * URIs, matched character for character (`…/callback` and `…/callback/` are
+     * different). Must be `https://` and carry no fragment.
+     * @param options.scopes - Permissions to request, e.g.
+     * `['documents:read', 'documents:write', 'offline_access']`. Ask for the
+     * minimum: the user approves all of them or none. Add `offline_access` to
+     * receive a refresh token and `openid` to receive an `id_token`.
+     * @param options.authorizationEndpoint - Skip discovery by supplying the
+     * endpoint yourself. Defaults to the discovered
+     * `authorization_endpoint`.
+     * @param options.issuer - Issuer to discover from, and the value the
+     * callback's `iss` must equal. Defaults to the discovered issuer.
+     * @param options.resource - RFC 8707 resource indicator. Defaults to this
+     * API's origin; pass `null` to omit it. It must match the value sent to the
+     * token endpoint, or the exchange fails with `invalid_target`.
+     * @param options.state - Supply your own CSRF value instead of a generated
+     * one. Must be unique per attempt.
+     * @param options.codeVerifier - Supply your own RFC 7636 verifier (43–128
+     * characters from `A-Z a-z 0-9 - . _ ~`) instead of a generated one.
+     * @param options.nonce - OIDC nonce echoed in the `id_token`. Generated
+     * automatically when `openid` is requested; pass a string to set it or
+     * `null` to omit it.
+     * @param options.prompt - Forwarded as the OIDC `prompt` parameter, e.g.
+     * `'consent'` to force the approval screen again.
+     * @returns The request to store and redirect with:
+     * ```jsonc
+     * {
+     *   "url": "https://auth.assinafy.com.br/oauth/authorize?response_type=code&client_id=…&redirect_uri=https%3A%2F%2Fmyapp.com%2Foauth%2Fcallback&scope=documents%3Aread+offline_access&state=8Xv…&code_challenge=E9M…&code_challenge_method=S256&resource=https%3A%2F%2Fapi.assinafy.com.br",
+     *   "state": "8Xv2rQ7mJt0aLpKcWn4dZg",
+     *   "codeVerifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
+     *   "issuer": "https://auth.assinafy.com.br",
+     *   "nonce": "n-0S6_WzA2Mj"
+     * }
+     * ```
+     * @throws {ValidationError} If `clientId` is empty, `redirectUri` is not an
+     * absolute `https://` URL without a fragment, `scopes` is empty or contains
+     * a value with whitespace, or a supplied `codeVerifier`/`state` is invalid.
+     * @throws {ApiError} If discovery is needed and fails.
+     *
+     * @example
+     * ```ts
+     * const request = await client.oauth.createAuthorizationUrl({
+     *   clientId: process.env.ASSINAFY_CLIENT_ID!,
+     *   redirectUri: 'https://myapp.com/oauth/callback',
+     *   scopes: ['documents:read', 'documents:write', 'offline_access'],
+     * });
+     * session.oauth = request;
+     * response.redirect(request.url);
+     * ```
+     */
+    createAuthorizationUrl(options: {
+        clientId: string;
+        redirectUri: string;
+        scopes: OAuthScope[];
+        authorizationEndpoint?: string;
+        issuer?: string;
+        resource?: string | null;
+        state?: string;
+        codeVerifier?: string;
+        nonce?: string | null;
+        prompt?: string;
+    }): Promise<IOAuthAuthorizationRequest>;
+    /**
+     * Validate the authorization response that lands on your redirect URI and
+     * return the code to exchange.
+     *
+     * Checks, in order and before anything else is trusted: `state` equals the
+     * value from {@link OAuthResource.createAuthorizationUrl} (constant-time),
+     * `iss` is present and equals the expected issuer, and only then whether
+     * the server reported an error. A declined consent arrives as
+     * `?error=access_denied`, not as a failed HTTP request.
+     *
+     * The `iss` check is strict because the authorization server advertises
+     * RFC 9207 support and always sends the parameter: a missing `iss` is
+     * treated exactly like a wrong one. Omit `expected.issuer` only if
+     * something between the browser and your handler strips query parameters.
+     *
+     * This performs no network I/O.
+     *
+     * @param params - The callback's query parameters. Accepts an Express-style
+     * `req.query` record, a `URLSearchParams`, a `URL`, a full callback URL
+     * string, or a bare `a=b&c=d` query string.
+     * @param expected - The stored {@link IOAuthAuthorizationRequest} (or any
+     * object carrying its `state` and `issuer`).
+     * @returns The validated response:
+     * ```jsonc
+     * {
+     *   "code": "def50200a1b2c3…",
+     *   "state": "8Xv2rQ7mJt0aLpKcWn4dZg",
+     *   "issuer": "https://auth.assinafy.com.br"
+     * }
+     * ```
+     * @throws {ValidationError} If `state` is missing or does not match, `iss`
+     * is absent or disagrees with the expected issuer, or a successful response
+     * carries no `code`. In every case the response is not yours — stop, do not
+     * exchange.
+     * @throws {OAuthError} If the server returned `error` (e.g.
+     * `access_denied`, `invalid_scope`, `invalid_request`,
+     * `unsupported_response_type`, `invalid_target`).
+     *
+     * @example
+     * ```ts
+     * app.get('/oauth/callback', async (req, res) => {
+     *   const stored = req.session.oauth;
+     *   const { code } = client.oauth.readAuthorizationCallback(req.query, stored);
+     *   const tokens = await client.oauth.exchangeCode({
+     *     code,
+     *     codeVerifier: stored.codeVerifier,
+     *     redirectUri: 'https://myapp.com/oauth/callback',
+     *     clientId: process.env.ASSINAFY_CLIENT_ID!,
+     *     clientSecret: process.env.ASSINAFY_CLIENT_SECRET,
+     *   });
+     * });
+     * ```
+     */
+    readAuthorizationCallback(params: string | URL | URLSearchParams | Record<string, unknown>, expected: {
+        state: string;
+        issuer?: string;
+    }): IOAuthAuthorizationCallback;
+    /**
+     * Exchange an authorization code for tokens
+     * (`POST /oauth/token`, `grant_type=authorization_code`).
+     *
+     * Run this on your server: the code is single-use and expires **60 seconds**
+     * after approval, and a confidential application's secret must never reach
+     * a browser. Every value must match the authorization request exactly, or
+     * the API answers `invalid_grant`.
+     *
+     * @param options - Exchange options.
+     * @param options.code - The code from
+     * {@link OAuthResource.readAuthorizationCallback}.
+     * @param options.codeVerifier - The verifier stored alongside the request.
+     * @param options.redirectUri - The same redirect URI that was authorized.
+     * @param options.clientId - The application's `client_id`.
+     * @param options.clientSecret - The `client_secret`, for confidential
+     * applications only. Public applications omit it and rely on PKCE.
+     * @param options.resource - The same RFC 8707 resource indicator sent to
+     * the authorization endpoint. Defaults to this API's origin; pass `null` to
+     * omit it. A value disagreeing with the authorized one fails with
+     * `invalid_target`.
+     * @returns The token set — a flat object, **not** the API's usual envelope:
+     * ```jsonc
+     * {
+     *   "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…",
+     *   "token_type": "Bearer",
+     *   "expires_in": 3600,
+     *   "scope": "documents:read documents:write",
+     *   "refresh_token": "def5020088c2…",   // only with offline_access
+     *   "id_token": "eyJraWQiOiJEQlR0S0…"   // only with openid
+     * }
+     * ```
+     * Read `scope` rather than assuming every requested permission was granted.
+     * @throws {ValidationError} If an argument is missing or malformed, or a
+     * `2xx` response carries no `access_token`.
+     * @throws {OAuthError} `invalid_grant` for a spent, expired, replayed or
+     * mismatched code; `invalid_client` for a bad `client_id`/`client_secret`;
+     * `invalid_target` for a `resource` mismatch.
+     *
+     * @example
+     * ```ts
+     * const tokens = await client.oauth.exchangeCode({
+     *   code,
+     *   codeVerifier: session.oauth.codeVerifier,
+     *   redirectUri: 'https://myapp.com/oauth/callback',
+     *   clientId: process.env.ASSINAFY_CLIENT_ID!,
+     *   clientSecret: process.env.ASSINAFY_CLIENT_SECRET,
+     * });
+     * ```
+     */
+    exchangeCode(options: TokenEndpointAuthOptions & {
+        code: string;
+        codeVerifier: string;
+        redirectUri: string;
+        resource?: string | null;
+    }): Promise<IOAuthTokenResponse>;
+    /**
+     * Renew an access token (`POST /oauth/token`, `grant_type=refresh_token`).
+     *
+     * Access tokens last one hour; refresh tokens are available only when
+     * `offline_access` was requested and granted.
+     *
+     * **Refresh tokens rotate.** Every call returns a new one and retires the
+     * one you sent, and a replayed refresh token cannot be told apart from a
+     * stolen one — so the server ends the entire connection and the user must
+     * reconnect. Therefore: persist `refresh_token` from the response before
+     * doing anything else with it, treat a timeout as "it may have succeeded"
+     * and re-read your stored token instead of retrying blindly, and never run
+     * two refreshes concurrently for one connection.
+     *
+     * Refreshing does not extend the connection's 30-day life.
+     *
+     * @param options - Refresh options.
+     * @param options.refreshToken - The current refresh token.
+     * @param options.clientId - The application's `client_id`.
+     * @param options.clientSecret - The `client_secret`, for confidential
+     * applications only.
+     * @param options.resource - RFC 8707 resource indicator. Defaults to this
+     * API's origin; pass `null` to omit it.
+     * @returns A fresh token set, identical in shape to
+     * {@link OAuthResource.exchangeCode}:
+     * ```jsonc
+     * {
+     *   "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…",
+     *   "token_type": "Bearer",
+     *   "expires_in": 3600,
+     *   "scope": "documents:read documents:write",
+     *   "refresh_token": "def50200f1e2…"    // NEW — persist it immediately
+     * }
+     * ```
+     * @throws {ValidationError} If an argument is missing, or a `2xx` response
+     * carries no `access_token`.
+     * @throws {OAuthError} `invalid_grant` when the refresh token was already
+     * used, expired, or the user reconnected with different permissions — ask
+     * the user to reconnect. `invalid_client` for bad client credentials.
+     *
+     * @example
+     * ```ts
+     * const tokens = await client.oauth.refreshToken({
+     *   refreshToken: connection.refreshToken,
+     *   clientId: process.env.ASSINAFY_CLIENT_ID!,
+     *   clientSecret: process.env.ASSINAFY_CLIENT_SECRET,
+     * });
+     * await connection.save({ refreshToken: tokens.refresh_token });
+     * ```
+     */
+    refreshToken(options: TokenEndpointAuthOptions & {
+        refreshToken: string;
+        resource?: string | null;
+    }): Promise<IOAuthTokenResponse>;
+    /**
+     * Revoke an access or refresh token (`POST /oauth/revoke`, RFC 7009).
+     *
+     * Call this when a user disconnects your app, instead of only deleting your
+     * copy of the token. Revoking a refresh token ends the whole connection.
+     *
+     * Every token outcome answers `200` — unknown, malformed and
+     * already-revoked included — so the endpoint cannot be used to probe
+     * whether a token exists. Only failed client authentication returns `401`.
+     *
+     * @param options - Revocation options.
+     * @param options.token - The access or refresh token to revoke.
+     * @param options.clientId - The application's `client_id`.
+     * @param options.clientSecret - The `client_secret`, for confidential
+     * applications only.
+     * @param options.tokenTypeHint - Optional `access_token` or
+     * `refresh_token` hint that lets the server skip a lookup.
+     * @returns Nothing; resolves once the API acknowledges the request.
+     * Request body:
+     * ```jsonc
+     * {
+     *   "token": "def50200f1e2…",
+     *   "token_type_hint": "refresh_token",
+     *   "client_id": "cli_1a2b3c",
+     *   "client_secret": "…"
+     * }
+     * ```
+     * @throws {ValidationError} If `token` or `clientId` is missing, or
+     * `tokenTypeHint` is not one of the two documented values.
+     * @throws {OAuthError} `invalid_client` when client authentication fails.
+     *
+     * @example
+     * ```ts
+     * await client.oauth.revokeToken({
+     *   token: connection.refreshToken,
+     *   tokenTypeHint: 'refresh_token',
+     *   clientId: process.env.ASSINAFY_CLIENT_ID!,
+     *   clientSecret: process.env.ASSINAFY_CLIENT_SECRET,
+     * });
+     * ```
+     */
+    revokeToken(options: TokenEndpointAuthOptions & {
+        token: string;
+        tokenTypeHint?: 'access_token' | 'refresh_token';
+    }): Promise<void>;
+    /**
+     * Read the OpenID Connect claims of the user who authorized a token
+     * (`GET /oauth/userinfo`).
+     *
+     * Requires the `openid` scope; `name` additionally requires `profile` and
+     * `email`/`email_verified` require `email`. Per OIDC Core §5.3.2 the
+     * response is a flat claims object, not this API's usual envelope.
+     *
+     * @param accessToken - Token to introspect. Omit to use the credential the
+     * client was constructed with (`token` or `apiKey`).
+     * @returns The claims the granted scopes allow:
+     * ```jsonc
+     * {
+     *   "sub": "d6zqpbyog2v3xvxerwn8la94",
+     *   "name": "Maria Silva",
+     *   "email": "maria@example.com",
+     *   "email_verified": true
+     * }
+     * ```
+     * `sub` is the stable user identifier; the rest are `null` when their scope
+     * was not granted.
+     * @throws {ValidationError} If `accessToken` is supplied but empty.
+     * @throws {ApiError} `401` when the token is missing, expired or revoked;
+     * `403` when the `openid` scope was not granted — its `WWW-Authenticate`
+     * header names the scope to reconnect with.
+     *
+     * @example
+     * ```ts
+     * const who = await client.oauth.getUserInfo(tokens.access_token);
+     * console.log(who.sub, who.email);
+     * ```
+     */
+    getUserInfo(accessToken?: string): Promise<IOAuthUserInfo>;
+    /** POST the token endpoint and assert the response actually carries a token. */
+    private requestToken;
+    /** `client_secret_post` credentials, omitting the secret for public clients. */
+    private clientAuth;
+    /**
+     * Resolve the optional RFC 8707 `resource` indicator.
+     *
+     * Defaults to the configured API origin, which is what this API publishes
+     * as its `resource`. A loopback `http://` base URL — the shape used by mock
+     * servers and the packed-consumer smoke test — has no valid resource
+     * identifier, so the parameter is simply omitted rather than rejected; an
+     * explicitly supplied value is still required to be `https`.
+     */
+    private resourceParam;
+    /** Discover which authorization server may issue tokens for this API. */
+    private defaultIssuer;
+    /**
+     * Origin of the configured API host.
+     *
+     * The `.well-known` document and the RFC 8707 resource indicator both sit
+     * at the host root, while `baseUrl` points at `/v1`.
+     */
+    private apiOrigin;
+}
+
 /**
  * Custom field definitions used by `collect` assignments.
  *
@@ -5038,6 +5698,7 @@ declare class AssinafyClient {
     readonly templates: TemplateResource;
     readonly tags: TagResource;
     readonly auth: AuthenticationResource;
+    readonly oauth: OAuthResource;
     readonly fields: FieldsResource;
     readonly signerDocuments: SignerDocumentsResource;
     readonly users: UserResource;
@@ -5255,6 +5916,40 @@ declare class AssinafyClient {
     getAxiosInstance(): AxiosInstance;
 }
 
+/**
+ * One parsed `WWW-Authenticate` challenge.
+ *
+ * Assinafy answers an OAuth request that is missing a scope with
+ * `403` and `WWW-Authenticate: Bearer error="insufficient_scope",
+ * scope="documents:write", resource_metadata="…"`. `scope` names the permission
+ * to request on the next authorization round-trip, so the challenge is the only
+ * machine-readable way to tell "reconnect asking for more" apart from "this
+ * token can never reach that surface".
+ */
+interface IAuthenticateChallenge {
+    /** Authentication scheme, e.g. `Bearer`. */
+    scheme: string;
+    /** RFC 6750 error code, e.g. `insufficient_scope` or `invalid_token`. */
+    error?: string;
+    /** Human-readable explanation, when the server sends one. */
+    error_description?: string;
+    /** Space-separated scopes required by the rejected operation. */
+    scope?: string;
+    /** RFC 9728 URL of the protected-resource metadata document. */
+    resource_metadata?: string;
+}
+/**
+ * Parse a `WWW-Authenticate` header into its scheme and auth-param map.
+ *
+ * Only the first challenge is read: Assinafy sends exactly one, and a parser
+ * that split on commas would corrupt quoted values containing them.
+ *
+ * @param value - Raw header value, or `undefined` when absent.
+ * @returns The parsed challenge, or `undefined` when there is no header or it
+ * carries no scheme.
+ */
+declare function parseWwwAuthenticate(value: string | undefined): IAuthenticateChallenge | undefined;
+
 /** Base class for all Assinafy SDK errors. */
 declare class AssinafyError extends Error {
     readonly context: Record<string, unknown>;
@@ -5276,6 +5971,29 @@ declare class AssinafyError extends Error {
 declare class ApiError extends AssinafyError {
     readonly statusCode: number;
     readonly responseData: unknown;
+    /**
+     * Parsed `WWW-Authenticate` challenge, when the response carried one.
+     *
+     * A `403` whose challenge is `{ error: 'insufficient_scope', scope: '…' }`
+     * means the OAuth token is valid but was never granted that permission:
+     * send the user through the authorization flow again asking for the scope
+     * named in `scope`. A `403` without a challenge has a different cause —
+     * another workspace, the user's role, or a surface OAuth tokens never
+     * reach — and reconnecting will not fix it.
+     *
+     * @example
+     * ```ts
+     * try {
+     *   await connected.documents.upload({ filePath: './contract.pdf' });
+     * } catch (error) {
+     *   if (error instanceof ApiError && error.challenge?.error === 'insufficient_scope') {
+     *     return reconnect(error.challenge.scope);   // 'documents:write'
+     *   }
+     *   throw error;
+     * }
+     * ```
+     */
+    challenge?: IAuthenticateChallenge;
     /**
      * Create an error representing a non-success API response.
      *
@@ -5306,6 +6024,59 @@ declare class ApiError extends AssinafyError {
      */
     static fromResponse(statusCode: number, responseData: unknown): ApiError;
 }
+/**
+ * Thrown when an OAuth endpoint returns an RFC 6749 error object, or when an
+ * authorization response comes back on the redirect URI carrying `?error=`.
+ *
+ * The OAuth endpoints answer with a flat `{ error, error_description }` body
+ * instead of this API's `{ status, message, data }` envelope, because no
+ * standard OAuth client would look for `error` inside a `data` key. This class
+ * still extends {@link ApiError}, so existing `catch (err) { if (err instanceof
+ * ApiError) … }` blocks keep matching.
+ *
+ * Branch on {@link OAuthError.error}, not on the message:
+ *
+ * | `error` | What to do |
+ * | --- | --- |
+ * | `invalid_grant` | The code or refresh token is spent, expired, or bound to other parameters. Send the user through the authorization flow again. |
+ * | `invalid_client` | Wrong `client_id`/`client_secret`, or the application was disabled. Fix the configuration; retrying will not help. |
+ * | `invalid_target` | The `resource` does not match the one that was authorized. |
+ * | `unsupported_grant_type` | Only `authorization_code` and `refresh_token` exist. |
+ * | `access_denied` | The user declined on the consent screen. |
+ * | `invalid_scope` | A scope the application is not registered for. |
+ * | `invalid_request` | Missing or malformed PKCE / request parameters. |
+ */
+declare class OAuthError extends ApiError {
+    /** RFC 6749 error code, e.g. `invalid_grant`. */
+    readonly error: string;
+    /** The server's human-readable explanation, when it sent one. */
+    readonly errorDescription: string | null;
+    /**
+     * Create an OAuth protocol error.
+     *
+     * @param error - RFC 6749 error code.
+     * @param errorDescription - Server-provided explanation, or `null`.
+     * @param statusCode - HTTP status that carried it. Authorization responses
+     * arrive as redirect query parameters rather than an HTTP response, so
+     * {@link OAuthResource.readAuthorizationCallback} reports them as `400`.
+     * @param responseData - The raw error object.
+     *
+     * @example
+     * ```ts
+     * throw new OAuthError('invalid_grant', 'Authorization code expired.', 400);
+     * ```
+     */
+    constructor(error: string, errorDescription?: string | null, statusCode?: number, responseData?: unknown);
+    /**
+     * Upgrade an {@link ApiError} to an {@link OAuthError} when its body is an
+     * RFC 6749 error object; otherwise return the value untouched.
+     *
+     * @param error - Any thrown value.
+     * @returns An `OAuthError` when the body carries a non-empty string
+     * `error`, else the original value.
+     */
+    static upgrade(error: unknown): unknown;
+}
 /** Thrown when SDK validation fails, including invalid input or workflow state. */
 declare class ValidationError extends AssinafyError {
     readonly errors: Record<string, unknown>;
@@ -5349,4 +6120,4 @@ declare const MAX_LIST_PAGE_SIZE = 50;
 
 declare const SDK_USER_AGENT: string;
 
-export { type AccountLogoUploadSource, type AnyString, ApiError, type AssignmentDisplaySettings, type AssignmentMethod, type AssignmentNotificationMethod, AssignmentResource, type AssignmentVerificationMethod, AssinafyClient, type AssinafyClientOptions, AssinafyError, AuthenticationResource, type ClientConfigInput, DEFAULT_WEBHOOK_EVENTS, type DocumentArtifactName, DocumentResource, type DocumentStatsGranularity, type DocumentStatus, type DocumentUploadSource, FieldsResource, type IAccountTheme, type IApiKeyResponse, type IAssignment, type IAssignmentCostSigner, type IAssignmentEntry, type IAssignmentItem, type IAssignmentListParams, type IAssignmentListResponse, type IAssignmentSigner, type IAuthenticatedUser, type IConfirmSignerDataPayload, type ICostEstimate, type ICreateAssignmentPayload, type ICreateAssignmentResponse, type ICreateDocumentFromTemplateOptions, type ICreateFieldPayload, type ICreateSignerPayload, type ICreateSignerResponse, type ICreateTagPayload, type ICreateWorkspacePayload, type IDeleteTagResponse, type IDetachDocumentTagResponse, type IDisplaySettings, type IDocumentActivity, type IDocumentDetailsResponse, type IDocumentListItem, type IDocumentListParams, type IDocumentListResponse, type IDocumentSearchParams, type IDocumentStatsParams, type IDocumentStatsRow, type IDocumentStatusInfo, type IDocumentUploadOptions, type IDocumentUploadResponse, type IDocumentVerification, type IEstimateAssignmentCostPayload, type IFieldDefinition, type IFieldType, type IFieldValidateMultipleEntry, type IFieldValidationMultipleResult, type IFieldValidationResponse, type IFieldValidationResult, type IInlineTag, type ILegacyConfirmSignerDataPayload, type ILegacyResendCostEstimate, type ILegacyUploadSignatureOptions, type IListParams, type ILoginResponse, type IMaskedApiKeyResponse, type INotificationHistoryEntry, type INotificationPreferences, type IPage, type IPaginatedResponse, type IPublicDocumentInfo, type IRenameDocumentResponse, type IResendCostEstimate, type IResendEmailResponse, type ISignFieldEntry, type ISigner, type ISignerListParams, type ISignerListResponse, type ISignerSelf, type ISigningProgress, type ITag, type ITemplateCostSigner, type ITemplateDetailsResponse, type ITemplateFieldPlacement, type ITemplateListItem, type ITemplateListParams, type ITemplateListResponse, type ITemplateRole, type ITemplateSigner, type IUpdateFieldPayload, type IUpdateNotificationPreferences, type IUpdateSignerPayload, type IUpdateTagPayload, type IUpdateTemplatePayload, type IUpdateWorkspacePayload, type IUploadAndRequestSignaturesResult, type IUploadAndRequestSignaturesSigner, type IUploadSignatureOptions, type IWebhookDispatch, type IWebhookDispatchListParams, type IWebhookEventTypeInfo, type IWebhookPayload, type IWebhookRegisterPayload, type IWebhookSubscription, type IWhatsAppNotification, type IWorkspaceListItem, type IWorkspaceListResponse, type IWorkspaceResponse, type Logger, MAX_LIST_PAGE_SIZE, MAX_UPLOAD_BYTES, NetworkError, type NotificationSenderType, type PaginatedResult, type PaginationMeta, SDK_USER_AGENT, type SendTokenChannel, type SignatureImageType, SignerDocumentsResource, type SignerReference, SignerResource, TagResource, TemplateResource, UserResource, ValidationError, type WebhookEventType, WebhookResource, WebhookVerifier, WorkspaceResource, buildAssignmentPayload };
+export { type AccountLogoUploadSource, type AnyString, ApiError, type AssignmentDisplaySettings, type AssignmentMethod, type AssignmentNotificationMethod, AssignmentResource, type AssignmentVerificationMethod, AssinafyClient, type AssinafyClientOptions, AssinafyError, AuthenticationResource, type ClientConfigInput, DEFAULT_WEBHOOK_EVENTS, type DocumentArtifactName, DocumentResource, type DocumentStatsGranularity, type DocumentStatus, type DocumentUploadSource, FieldsResource, type IAccountTheme, type IApiKeyResponse, type IAssignment, type IAssignmentCostSigner, type IAssignmentEntry, type IAssignmentItem, type IAssignmentListParams, type IAssignmentListResponse, type IAssignmentSigner, type IAuthenticateChallenge, type IAuthenticatedUser, type IConfirmSignerDataPayload, type ICostEstimate, type ICreateAssignmentPayload, type ICreateAssignmentResponse, type ICreateDocumentFromTemplateOptions, type ICreateFieldPayload, type ICreateSignerPayload, type ICreateSignerResponse, type ICreateTagPayload, type ICreateWorkspacePayload, type IDeleteTagResponse, type IDetachDocumentTagResponse, type IDisplaySettings, type IDocumentActivity, type IDocumentDetailsResponse, type IDocumentListItem, type IDocumentListParams, type IDocumentListResponse, type IDocumentSearchParams, type IDocumentStatsParams, type IDocumentStatsRow, type IDocumentStatusInfo, type IDocumentUploadOptions, type IDocumentUploadResponse, type IDocumentVerification, type IEstimateAssignmentCostPayload, type IFieldDefinition, type IFieldType, type IFieldValidateMultipleEntry, type IFieldValidationMultipleResult, type IFieldValidationResponse, type IFieldValidationResult, type IInlineTag, type ILegacyConfirmSignerDataPayload, type ILegacyResendCostEstimate, type ILegacyUploadSignatureOptions, type IListParams, type ILoginResponse, type IMaskedApiKeyResponse, type INotificationHistoryEntry, type INotificationPreferences, type IOAuthAuthorizationCallback, type IOAuthAuthorizationRequest, type IOAuthAuthorizationServerMetadata, type IOAuthProtectedResourceMetadata, type IOAuthTokenResponse, type IOAuthUserInfo, type IPage, type IPaginatedResponse, type IPublicDocumentInfo, type IRenameDocumentResponse, type IResendCostEstimate, type IResendEmailResponse, type ISignFieldEntry, type ISigner, type ISignerListParams, type ISignerListResponse, type ISignerSelf, type ISigningProgress, type ITag, type ITemplateCostSigner, type ITemplateDetailsResponse, type ITemplateFieldPlacement, type ITemplateListItem, type ITemplateListParams, type ITemplateListResponse, type ITemplateRole, type ITemplateSigner, type IUpdateFieldPayload, type IUpdateNotificationPreferences, type IUpdateSignerPayload, type IUpdateTagPayload, type IUpdateTemplatePayload, type IUpdateWorkspacePayload, type IUploadAndRequestSignaturesResult, type IUploadAndRequestSignaturesSigner, type IUploadSignatureOptions, type IWebhookDispatch, type IWebhookDispatchListParams, type IWebhookEventTypeInfo, type IWebhookPayload, type IWebhookRegisterPayload, type IWebhookSubscription, type IWhatsAppNotification, type IWorkspaceListItem, type IWorkspaceListResponse, type IWorkspaceResponse, type Logger, MAX_LIST_PAGE_SIZE, MAX_UPLOAD_BYTES, NetworkError, type NotificationSenderType, OAuthError, OAuthResource, type OAuthScope, type PaginatedResult, type PaginationMeta, SDK_USER_AGENT, type SendTokenChannel, type SignatureImageType, SignerDocumentsResource, type SignerReference, SignerResource, TagResource, TemplateResource, UserResource, ValidationError, type WebhookEventType, WebhookResource, WebhookVerifier, WorkspaceResource, buildAssignmentPayload, parseWwwAuthenticate };