@assinafy/sdk 2.1.2 → 2.3.0

package/dist/index.js

@@ -38,8 +38,11 @@ __export(index_exports, {
   DEFAULT_WEBHOOK_EVENTS: () => DEFAULT_WEBHOOK_EVENTS,
   DocumentResource: () => DocumentResource,
   FieldsResource: () => FieldsResource,
+  MAX_LIST_PAGE_SIZE: () => MAX_LIST_PAGE_SIZE,
   MAX_UPLOAD_BYTES: () => MAX_UPLOAD_BYTES,
   NetworkError: () => NetworkError,
+  OAuthError: () => OAuthError,
+  OAuthResource: () => OAuthResource,
   SDK_USER_AGENT: () => SDK_USER_AGENT,
   SignerDocumentsResource: () => SignerDocumentsResource,
   SignerResource: () => SignerResource,
@@ -50,7 +53,8 @@ __export(index_exports, {
   WebhookResource: () => WebhookResource,
   WebhookVerifier: () => WebhookVerifier,
   WorkspaceResource: () => WorkspaceResource,
-  buildAssignmentPayload: () => buildAssignmentPayload
+  buildAssignmentPayload: () => buildAssignmentPayload,
+  parseWwwAuthenticate: () => parseWwwAuthenticate
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -59,6 +63,12 @@ var import_axios3 = __toESM(require("axios"));
 var import_promises = require("timers/promises");
 
 // src/errors.ts
+var FALLBACK_MESSAGE = "API request failed";
+var MAX_MESSAGE_LENGTH = 500;
+function summarize(text) {
+  const collapsed = text.replaceAll(/\s+/gu, " ");
+  return collapsed.length > MAX_MESSAGE_LENGTH ? `${collapsed.slice(0, MAX_MESSAGE_LENGTH)}\u2026` : collapsed;
+}
 var AssinafyError = class extends Error {
   context;
   /**
@@ -82,6 +92,29 @@ var AssinafyError = class extends Error {
 var ApiError = class _ApiError extends AssinafyError {
   statusCode;
   responseData;
+  /**
+   * 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;
   /**
    * Create an error representing a non-success API response.
    *
@@ -100,9 +133,14 @@ var ApiError = class _ApiError extends AssinafyError {
    * Convert a status/body pair into an {@link ApiError}.
    *
    * @param statusCode - Non-success HTTP response status.
-   * @param responseData - Parsed API body. String `message` takes priority,
-   * followed by string `error`, then the stable fallback message.
-   * @returns An `ApiError` retaining the original response body.
+   * @param responseData - API body. For a JSON object, string `message` takes
+   * priority, followed by string `error`. A non-JSON body (a proxy's
+   * `text/plain` or HTML error page) is used verbatim rather than discarded —
+   * otherwise the only failures reported as the generic fallback would be the
+   * ones with no structured body to explain them. Anything else falls back to
+   * the stable message.
+   * @returns An `ApiError` retaining the original response body in
+   * {@link ApiError.responseData}; `message` is truncated for legibility.
    *
    * @example
    * ```ts
@@ -111,13 +149,66 @@ var ApiError = class _ApiError extends AssinafyError {
    * ```
    */
   static fromResponse(statusCode, responseData) {
+    if (typeof responseData === "string") {
+      const text = responseData.trim();
+      return new _ApiError(text ? summarize(text) : FALLBACK_MESSAGE, statusCode, responseData);
+    }
     const data = responseData ?? {};
     const rawMessage = data["message"];
     const rawError = data["error"];
-    const message = typeof rawMessage === "string" && rawMessage.length > 0 ? rawMessage : typeof rawError === "string" ? rawError : "API request failed";
+    const message = typeof rawMessage === "string" && rawMessage.length > 0 ? rawMessage : typeof rawError === "string" ? rawError : FALLBACK_MESSAGE;
     return new _ApiError(message, statusCode, responseData);
   }
 };
+var OAuthError = class _OAuthError extends ApiError {
+  /** RFC 6749 error code, e.g. `invalid_grant`. */
+  error;
+  /** The server's human-readable explanation, when it sent one. */
+  errorDescription;
+  /**
+   * 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, errorDescription = null, statusCode = 400, responseData = null) {
+    super(errorDescription ? `${error}: ${errorDescription}` : error, statusCode, responseData);
+    this.name = "OAuthError";
+    this.error = error;
+    this.errorDescription = errorDescription;
+  }
+  /**
+   * 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) {
+    if (!(error instanceof ApiError) || error instanceof _OAuthError) return error;
+    const body = error.responseData;
+    if (body === null || typeof body !== "object") return error;
+    const code = body["error"];
+    if (typeof code !== "string" || code.length === 0) return error;
+    const description = body["error_description"];
+    return new _OAuthError(
+      code,
+      typeof description === "string" && description.length > 0 ? description : null,
+      error.statusCode,
+      body
+    );
+  }
+};
 var ValidationError = class extends AssinafyError {
   errors;
   /**
@@ -157,6 +248,43 @@ var NetworkError = class extends AssinafyError {
 
 // src/utils.ts
 var import_axios = __toESM(require("axios"));
+
+// src/support/headers.ts
+function readHeader(headers, name) {
+  if (!headers) return void 0;
+  const lower = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === lower && value != null) {
+      const first = Array.isArray(value) ? value[0] : value;
+      if (typeof first === "string" || typeof first === "number" || typeof first === "boolean") {
+        return String(first);
+      }
+      return void 0;
+    }
+  }
+  return void 0;
+}
+var CHALLENGE_PARAM = /([A-Za-z0-9_-]+)\s*=\s*(?:"([^"]*)"|([^\s,]+))/gu;
+function parseWwwAuthenticate(value) {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  const scheme = /^[A-Za-z0-9_-]+/u.exec(trimmed)?.[0];
+  if (!scheme) return void 0;
+  const challenge = { scheme };
+  CHALLENGE_PARAM.lastIndex = 0;
+  for (const match of trimmed.slice(scheme.length).matchAll(CHALLENGE_PARAM)) {
+    const key = match[1]?.toLowerCase();
+    const paramValue = match[2] ?? match[3];
+    if (paramValue === void 0) continue;
+    if (key === "error") challenge.error = paramValue;
+    else if (key === "error_description") challenge.error_description = paramValue;
+    else if (key === "scope") challenge.scope = paramValue;
+    else if (key === "resource_metadata") challenge.resource_metadata = paramValue;
+  }
+  return challenge;
+}
+
+// src/utils.ts
 var SAFE_LOG_NUMBER_FIELDS = /* @__PURE__ */ new Set([
   "attempt",
   "attempts",
@@ -189,7 +317,7 @@ function decodeBinaryErrorBody(data) {
   try {
     return JSON.parse(text);
   } catch {
-    return text.length > 0 ? { message: text } : null;
+    return text.length > 0 ? text : null;
   }
 }
 function toSdkError(error, fallbackMessage) {
@@ -200,7 +328,12 @@ function toSdkError(error, fallbackMessage) {
     const status = error.response?.status;
     if (status) {
       const body = decodeBinaryErrorBody(error.response?.data ?? null);
-      return ApiError.fromResponse(status, body ?? null);
+      const apiError = ApiError.fromResponse(status, body ?? null);
+      const challenge = parseWwwAuthenticate(
+        readHeader(error.response?.headers, "www-authenticate")
+      );
+      if (challenge) apiError.challenge = challenge;
+      return apiError;
     }
     const cause = sanitiseNetworkCause(error);
     return new NetworkError(`${fallbackMessage}: ${cause.message}`, { cause });
@@ -270,6 +403,18 @@ function sanitiseNetworkCause(error) {
 function redactSensitiveErrorText(message) {
   return message.replace(SENSITIVE_ERROR_VALUE_RE, "$1[REDACTED]").replace(/(https?:\/\/)[^/@\s]+:[^/@\s]+@/gi, "$1[REDACTED]@");
 }
+function isEmail(value) {
+  return typeof value === "string" && /^[^\s@]+@[^\s@]+\.[^\s@]+$/u.test(value);
+}
+function assertEmail(value, label = "email") {
+  if (!isEmail(value)) {
+    throw new ValidationError(`${label} must be a valid email address`, { [label]: value });
+  }
+}
+function isE164PhoneNumber(value) {
+  return typeof value === "string" && /^\+[1-9]\d{1,14}$/u.test(value);
+}
+var MAX_LIST_PAGE_SIZE = 50;
 function assertRecord(value, label) {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
     throw new ValidationError(`${label} must be an object`);
@@ -338,22 +483,6 @@ function cleanListParams(params) {
   return out;
 }
 
-// src/support/headers.ts
-function readHeader(headers, name) {
-  if (!headers) return void 0;
-  const lower = name.toLowerCase();
-  for (const [key, value] of Object.entries(headers)) {
-    if (key.toLowerCase() === lower && value != null) {
-      const first = Array.isArray(value) ? value[0] : value;
-      if (typeof first === "string" || typeof first === "number" || typeof first === "boolean") {
-        return String(first);
-      }
-      return void 0;
-    }
-  }
-  return void 0;
-}
-
 // src/support/retry.ts
 function retryDelayFromHeaders(headers) {
   const retryAfter = readHeader(headers, "retry-after");
@@ -505,7 +634,7 @@ var import_axios2 = __toESM(require("axios"));
 // package.json
 var package_default = {
   name: "@assinafy/sdk",
-  version: "2.1.2",
+  version: "2.3.0",
   packageManager: "bun@1.4.0",
   description: "TypeScript SDK for Assinafy API - Digital signature platform",
   type: "commonjs",
@@ -592,6 +721,7 @@ var package_default = {
     "dist",
     "docs",
     "README.md",
+    "README.en.md",
     "CHANGELOG.md",
     "SECURITY.md",
     "LICENSE"
@@ -843,14 +973,34 @@ function toInt(value) {
 var ASSIGNMENT_METHODS = /* @__PURE__ */ new Set(["virtual", "collect"]);
 var VERIFICATION_METHODS = /* @__PURE__ */ new Set(["Email", "Whatsapp", "DigitalCertificate"]);
 var NOTIFICATION_METHODS = /* @__PURE__ */ new Set(["Email", "Whatsapp"]);
+var ALLOWED_NOTIFICATION_METHODS = {
+  Email: /* @__PURE__ */ new Set(["Email"]),
+  Whatsapp: /* @__PURE__ */ new Set(["Whatsapp"]),
+  DigitalCertificate: NOTIFICATION_METHODS
+};
 function validateAssignmentSignerOptions(signer, label = "signer") {
   if (signer.verification_method !== void 0 && (typeof signer.verification_method !== "string" || !VERIFICATION_METHODS.has(signer.verification_method))) {
     throw new ValidationError(`${label} has an invalid verification_method`);
   }
-  if (signer.notification_methods !== void 0 && (!Array.isArray(signer.notification_methods) || signer.notification_methods.some(
-    (method) => typeof method !== "string" || !NOTIFICATION_METHODS.has(method)
-  ))) {
-    throw new ValidationError(`${label} has invalid notification_methods`);
+  if (signer.notification_methods !== void 0) {
+    const methods = signer.notification_methods;
+    if (!Array.isArray(methods) || methods.some(
+      (method) => typeof method !== "string" || !NOTIFICATION_METHODS.has(method)
+    )) {
+      throw new ValidationError(`${label} has invalid notification_methods`);
+    }
+    if (methods.length !== 1) {
+      throw new ValidationError(`${label} allows exactly one notification method`);
+    }
+    const verification = signer.verification_method;
+    if (typeof verification === "string") {
+      const allowed = ALLOWED_NOTIFICATION_METHODS[verification];
+      if (allowed && !allowed.has(methods[0])) {
+        throw new ValidationError(
+          `${label} cannot pair ${verification} verification with ${String(methods[0])} notification`
+        );
+      }
+    }
   }
   if (signer.step !== void 0 && (typeof signer.step !== "number" || !Number.isSafeInteger(signer.step) || signer.step < 1)) {
     throw new ValidationError(`${label} step must be a positive safe integer`);
@@ -1554,7 +1704,6 @@ var FAILED_STATUSES = /* @__PURE__ */ new Set([
   "rejected_by_user",
   "expired"
 ]);
-var EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 var DocumentResource = class extends BaseResource {
   publicHttp;
   constructor(http, defaultAccountId, logger, publicHttp) {
@@ -1639,7 +1788,8 @@ var DocumentResource = class extends BaseResource {
    * @param params - Filters and pagination: `status`; `method` (`virtual` or
    * `collect`); `tags` (comma-separated IDs, all of which must match);
    * `search` (document name, signer name, or signer email); `sort` (`name` or
-   * `updated_at`); `page`; and `per-page` (maximum 100).
+   * `updated_at`); `page`; and `per-page` (the server clamps this to 50
+   * rather than rejecting a larger value).
    * @param accountId - Override the client's default account ID.
    * @returns Matching documents, with pagination in `meta`. Each item:
    * ```jsonc
@@ -2542,7 +2692,7 @@ var DocumentResource = class extends BaseResource {
     const id = this.requireId(documentId, "Document ID");
     assertNonEmptyString(recipient, "recipient");
     if (channel !== void 0) assertNonEmptyString(channel, "channel");
-    if (channel === void 0 && !EMAIL_RE.test(recipient)) {
+    if (channel === void 0 && !isEmail(recipient)) {
       throw new ValidationError("recipient must be a valid email address");
     }
     const path2 = `/public/documents/${this.pathSegment(id, "Document ID")}/send-token`;
@@ -2644,9 +2794,6 @@ function normaliseTemplateSigners(signers) {
       throw new ValidationError(`Template signer ${index + 1} requires id`);
     }
     validateAssignmentSignerOptions(signer, `Template signer ${index + 1}`);
-    if (signer.notification_methods !== void 0 && signer.notification_methods.length > 1) {
-      throw new ValidationError(`Template signer ${index + 1} allows one notification method`);
-    }
     const projected = { role_id: signer.role_id, id: signer.id };
     if (signer.verification_method !== void 0) {
       projected.verification_method = signer.verification_method;
@@ -2729,7 +2876,6 @@ function isLegacySendTokenValidation(error) {
 }
 
 // src/resources/signers.ts
-var EMAIL_RE2 = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 var SignerResource = class extends BaseResource {
   /**
    * Create a signer in the workspace (`POST /accounts/{accountId}/signers`).
@@ -2855,7 +3001,8 @@ var SignerResource = class extends BaseResource {
    * Pagination info (if any) is attached in `meta`.
    *
    * @param params - `page`, `per-page`, and `search` (matches `full_name` or
-   * `email`). The API maximum is 100 items per page.
+   * `email`). The server clamps `per-page` to {@link MAX_LIST_PAGE_SIZE}
+   * (50); a larger value is not rejected, it is silently reduced.
    * @param accountId - Override the client's default account ID.
    * @returns The matching signers, with pagination in `meta`. Each item:
    * ```jsonc
@@ -2965,10 +3112,10 @@ var SignerResource = class extends BaseResource {
    * `search` is a substring match across signer fields, so the result is
    * re-filtered here for an exact, case-insensitive email match.
    *
-   * Page size is pinned to the API's maximum of 100.
-   * An exact address realistically matches one signer, but a search term that
-   * matched more than 100 could in principle miss one — the API exposes no
-   * exact-email filter to rule that out.
+   * Page size is pinned to {@link MAX_LIST_PAGE_SIZE}, the largest page the
+   * server actually returns. An exact address realistically matches one
+   * signer, but a search term that matched more than that could in principle
+   * miss one — the API exposes no exact-email filter to rule that out.
    *
    * A `404` from the underlying list is treated as "no match" and mapped to
    * `null`; any other {@link ApiError} propagates.
@@ -2998,7 +3145,10 @@ var SignerResource = class extends BaseResource {
   async findByEmail(email, accountId) {
     this.assertEmail(email);
     try {
-      const { data } = await this.list({ search: email, "per-page": 100 }, accountId);
+      const { data } = await this.list(
+        { search: email, "per-page": MAX_LIST_PAGE_SIZE },
+        accountId
+      );
       const lower = email.toLowerCase();
       return data.find((s) => (s.email ?? "").toLowerCase() === lower) ?? null;
     } catch (err) {
@@ -3009,7 +3159,7 @@ var SignerResource = class extends BaseResource {
     }
   }
   assertEmail(email) {
-    if (!email || !EMAIL_RE2.test(email)) {
+    if (!isEmail(email)) {
       throw new ValidationError("Invalid email address", { email });
     }
   }
@@ -3022,7 +3172,7 @@ function validateCreateSignerPayload(payload) {
     throw new ValidationError("full_name is required");
   }
   const phone = payload.whatsapp_phone_number ?? payload.phone;
-  if (payload.email !== void 0 && (typeof payload.email !== "string" || !EMAIL_RE2.test(payload.email))) {
+  if (payload.email !== void 0 && !isEmail(payload.email)) {
     throw new ValidationError("Invalid email address", { email: payload.email });
   }
   validateOptionalPhone(phone);
@@ -3047,7 +3197,7 @@ function validateUpdateSignerPayload(payload) {
   if (payload.full_name !== void 0 && (typeof payload.full_name !== "string" || !payload.full_name.trim())) {
     throw new ValidationError("full_name cannot be empty");
   }
-  if (payload.email !== void 0 && (typeof payload.email !== "string" || !EMAIL_RE2.test(payload.email))) {
+  if (payload.email !== void 0 && !isEmail(payload.email)) {
     throw new ValidationError("Invalid email address", { email: payload.email });
   }
   const phone = payload.whatsapp_phone_number ?? payload.phone;
@@ -3063,7 +3213,7 @@ function validateOptionalDigits(value, field) {
 }
 function validateOptionalPhone(value) {
   if (value === void 0) return;
-  if (typeof value !== "string" || !/^\+[1-9]\d{1,14}$/u.test(value)) {
+  if (!isE164PhoneNumber(value)) {
     throw new ValidationError("whatsapp_phone_number must use E.164 format");
   }
 }
@@ -3508,7 +3658,6 @@ var DEFAULT_WEBHOOK_EVENTS = Object.freeze([
   "signer_rejected_document",
   "document_processing_failed"
 ]);
-var EMAIL_RE3 = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 var WebhookResource = class extends BaseResource {
   /**
    * Register (or replace) the workspace's single webhook subscription
@@ -3561,7 +3710,7 @@ var WebhookResource = class extends BaseResource {
       throw new ValidationError("Webhook subscription payload is required");
     }
     validateWebhookUrl(payload.url);
-    if (!payload.email || !EMAIL_RE3.test(payload.email)) {
+    if (!isEmail(payload.email)) {
       throw new ValidationError("Webhook email must be a valid email address", {
         email: payload.email
       });
@@ -4364,7 +4513,6 @@ function validateTagColor(value) {
 }
 
 // src/resources/authentication.ts
-var EMAIL_RE4 = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 var AuthenticationResource = class extends BaseResource {
   publicHttp;
   constructor(http, defaultAccountId, logger, publicHttp) {
@@ -4807,10 +4955,685 @@ var AuthenticationResource = class extends BaseResource {
     return url.toString();
   }
 };
-function assertEmail(value) {
-  if (typeof value !== "string" || !EMAIL_RE4.test(value)) {
-    throw new ValidationError("email must be a valid email address");
+
+// src/resources/oauth.ts
+var import_node_crypto = require("crypto");
+var PROTECTED_RESOURCE_PATH = "/.well-known/oauth-protected-resource";
+var AUTHORIZATION_SERVER_PATH = "/.well-known/oauth-authorization-server";
+var CODE_VERIFIER_PATTERN = /^[A-Za-z0-9\-._~]{43,128}$/u;
+var OAuthResource = class extends BaseResource {
+  publicHttp;
+  constructor(http, defaultAccountId, logger, publicHttp) {
+    super(http, defaultAccountId, logger);
+    this.publicHttp = withoutCredentials(publicHttp ?? http);
+  }
+  /**
+   * 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]);
+   * ```
+   */
+  async getProtectedResourceMetadata() {
+    return this.call(
+      "Failed to fetch OAuth protected-resource metadata",
+      () => this.publicHttp.get(`${this.apiOrigin()}${PROTECTED_RESOURCE_PATH}`)
+    );
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async getAuthorizationServerMetadata(issuer) {
+    const resolved = issuer ?? await this.defaultIssuer();
+    const base = assertHttpsUrl(resolved, "issuer").replace(/\/+$/u, "");
+    const metadata = await this.call(
+      "Failed to fetch OAuth authorization-server metadata",
+      () => this.publicHttp.get(`${base}${AUTHORIZATION_SERVER_PATH}`)
+    );
+    if (normaliseIssuer(metadata?.issuer) !== normaliseIssuer(base)) {
+      throw new ValidationError(
+        "Authorization-server metadata issuer does not match the requested issuer",
+        { expected: base, received: metadata?.issuer ?? null }
+      );
+    }
+    return metadata;
   }
+  /**
+   * 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);
+   * ```
+   */
+  async createAuthorizationUrl(options) {
+    assertRecord(options, "authorization options");
+    assertNonEmptyString(options.clientId, "clientId");
+    assertRedirectUri(options.redirectUri);
+    const scope = assertScopes(options.scopes);
+    let endpoint = options.authorizationEndpoint;
+    let issuer = options.issuer;
+    if (endpoint === void 0 || issuer === void 0) {
+      const metadata = await this.getAuthorizationServerMetadata(options.issuer);
+      endpoint ??= metadata.authorization_endpoint;
+      issuer ??= metadata.issuer;
+    }
+    assertHttpsUrl(endpoint, "authorizationEndpoint");
+    assertHttpsUrl(issuer, "issuer");
+    const codeVerifier = options.codeVerifier ?? createCodeVerifier();
+    assertCodeVerifier(codeVerifier);
+    const state = options.state ?? createRandomValue(16);
+    assertNonEmptyString(state, "state");
+    const url = new URL(endpoint);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("client_id", options.clientId);
+    url.searchParams.set("redirect_uri", options.redirectUri);
+    url.searchParams.set("scope", scope);
+    url.searchParams.set("state", state);
+    url.searchParams.set("code_challenge", codeChallengeFor(codeVerifier));
+    url.searchParams.set("code_challenge_method", "S256");
+    const { resource } = this.resourceParam(options.resource);
+    if (resource !== void 0) url.searchParams.set("resource", resource);
+    const wantsNonce = options.nonce === void 0 ? options.scopes.includes("openid") : options.nonce !== null;
+    const nonce = wantsNonce ? options.nonce ?? createRandomValue(16) : void 0;
+    if (nonce !== void 0) {
+      assertNonEmptyString(nonce, "nonce");
+      url.searchParams.set("nonce", nonce);
+    }
+    if (options.prompt !== void 0) {
+      assertNonEmptyString(options.prompt, "prompt");
+      url.searchParams.set("prompt", options.prompt);
+    }
+    this.logger.info("Built OAuth authorization URL");
+    const request = {
+      url: url.toString(),
+      state,
+      codeVerifier,
+      issuer
+    };
+    if (nonce !== void 0) request.nonce = nonce;
+    return request;
+  }
+  /**
+   * 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, expected) {
+    assertRecord(expected, "expected authorization request");
+    assertNonEmptyString(expected.state, "expected.state");
+    const query = toSearchParams(params);
+    const state = query.get("state");
+    if (state === null || !constantTimeEquals(state, expected.state)) {
+      throw new ValidationError(
+        "OAuth callback state does not match the stored authorization request"
+      );
+    }
+    const issuer = query.get("iss") ?? void 0;
+    if (expected.issuer !== void 0) {
+      if (issuer === void 0 || normaliseIssuer(issuer) !== normaliseIssuer(expected.issuer)) {
+        throw new ValidationError(
+          "OAuth callback issuer is missing or does not match the expected issuer",
+          { expected: expected.issuer, received: issuer ?? null }
+        );
+      }
+    }
+    const error = query.get("error");
+    if (error !== null && error.length > 0) {
+      throw new OAuthError(error, query.get("error_description"), 400, {
+        error,
+        error_description: query.get("error_description")
+      });
+    }
+    const code = query.get("code");
+    if (code === null || code.length === 0) {
+      throw new ValidationError("OAuth callback carries neither a code nor an error");
+    }
+    const result = { code, state };
+    if (issuer !== void 0) result.issuer = issuer;
+    return result;
+  }
+  /**
+   * 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,
+   * });
+   * ```
+   */
+  async exchangeCode(options) {
+    assertRecord(options, "code exchange options");
+    assertNonEmptyString(options.code, "code");
+    assertCodeVerifier(options.codeVerifier);
+    assertRedirectUri(options.redirectUri);
+    return this.requestToken("Failed to exchange the OAuth authorization code", {
+      grant_type: "authorization_code",
+      code: options.code,
+      redirect_uri: options.redirectUri,
+      code_verifier: options.codeVerifier,
+      ...this.clientAuth(options),
+      ...this.resourceParam(options.resource)
+    });
+  }
+  /**
+   * 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 });
+   * ```
+   */
+  async refreshToken(options) {
+    assertRecord(options, "refresh options");
+    assertNonEmptyString(options.refreshToken, "refreshToken");
+    return this.requestToken("Failed to refresh the OAuth access token", {
+      grant_type: "refresh_token",
+      refresh_token: options.refreshToken,
+      ...this.clientAuth(options),
+      ...this.resourceParam(options.resource)
+    });
+  }
+  /**
+   * 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,
+   * });
+   * ```
+   */
+  async revokeToken(options) {
+    assertRecord(options, "revocation options");
+    assertNonEmptyString(options.token, "token");
+    if (options.tokenTypeHint !== void 0 && options.tokenTypeHint !== "access_token" && options.tokenTypeHint !== "refresh_token") {
+      throw new ValidationError("tokenTypeHint must be access_token or refresh_token");
+    }
+    const body = cleanParams({
+      token: options.token,
+      token_type_hint: options.tokenTypeHint,
+      ...this.clientAuth(options)
+    });
+    try {
+      await this.callVoid(
+        "Failed to revoke the OAuth token",
+        () => this.publicHttp.post("/oauth/revoke", body)
+      );
+    } catch (error) {
+      throw OAuthError.upgrade(error);
+    }
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async getUserInfo(accessToken) {
+    if (accessToken === void 0) {
+      return this.call(
+        "Failed to fetch OAuth userinfo",
+        () => this.http.get("/oauth/userinfo")
+      );
+    }
+    assertNonEmptyString(accessToken, "accessToken");
+    return this.call(
+      "Failed to fetch OAuth userinfo",
+      () => this.publicHttp.get("/oauth/userinfo", {
+        headers: { Authorization: `Bearer ${accessToken}` }
+      })
+    );
+  }
+  /** POST the token endpoint and assert the response actually carries a token. */
+  async requestToken(label, body) {
+    let tokens;
+    try {
+      tokens = await this.call(
+        label,
+        () => this.publicHttp.post("/oauth/token", cleanParams(body))
+      );
+    } catch (error) {
+      throw OAuthError.upgrade(error);
+    }
+    if (typeof tokens?.access_token !== "string" || tokens.access_token.length === 0) {
+      throw new ValidationError(`${label}: the token endpoint returned no access_token`, {
+        response: tokens
+      });
+    }
+    return tokens;
+  }
+  /** `client_secret_post` credentials, omitting the secret for public clients. */
+  clientAuth(options) {
+    assertNonEmptyString(options.clientId, "clientId");
+    if (options.clientSecret !== void 0) {
+      assertNonEmptyString(options.clientSecret, "clientSecret");
+    }
+    return { client_id: options.clientId, client_secret: options.clientSecret };
+  }
+  /**
+   * 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`.
+   */
+  resourceParam(resource) {
+    if (resource === void 0) {
+      const origin = this.apiOrigin();
+      return origin.startsWith("https:") ? { resource: origin } : {};
+    }
+    if (resource === null) return {};
+    assertHttpsUrl(resource, "resource");
+    return { resource };
+  }
+  /** Discover which authorization server may issue tokens for this API. */
+  async defaultIssuer() {
+    const metadata = await this.getProtectedResourceMetadata();
+    const issuer = metadata?.authorization_servers?.[0];
+    if (typeof issuer !== "string" || issuer.length === 0) {
+      throw new ValidationError(
+        "Protected-resource metadata lists no authorization server",
+        { metadata }
+      );
+    }
+    return issuer;
+  }
+  /**
+   * 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`.
+   */
+  apiOrigin() {
+    const baseUrl = this.publicHttp.defaults.baseURL;
+    if (typeof baseUrl !== "string" || baseUrl.length === 0) {
+      throw new ValidationError("The client has no base URL to derive the API origin from");
+    }
+    return new URL(baseUrl).origin;
+  }
+};
+function createCodeVerifier() {
+  return (0, import_node_crypto.randomBytes)(32).toString("base64url");
+}
+function createRandomValue(bytes) {
+  return (0, import_node_crypto.randomBytes)(bytes).toString("base64url");
+}
+function codeChallengeFor(codeVerifier) {
+  return (0, import_node_crypto.createHash)("sha256").update(codeVerifier).digest("base64url");
+}
+function assertCodeVerifier(value) {
+  if (typeof value !== "string" || !CODE_VERIFIER_PATTERN.test(value)) {
+    throw new ValidationError(
+      "codeVerifier must be 43-128 characters from A-Z a-z 0-9 - . _ ~"
+    );
+  }
+}
+function assertRedirectUri(value) {
+  const uri = assertHttpsUrl(value, "redirectUri");
+  if (uri.includes("#")) {
+    throw new ValidationError("redirectUri must not contain a fragment");
+  }
+}
+function assertHttpsUrl(value, label) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new ValidationError(`${label} must be an absolute https URL`);
+  }
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new ValidationError(`${label} must be an absolute https URL`);
+  }
+  if (url.protocol !== "https:") {
+    throw new ValidationError(`${label} must be an absolute https URL`);
+  }
+  return value;
+}
+function assertScopes(scopes) {
+  if (!Array.isArray(scopes) || scopes.length === 0) {
+    throw new ValidationError("scopes must be a non-empty array of scope strings");
+  }
+  for (const scope of scopes) {
+    if (typeof scope !== "string" || scope.trim().length === 0 || /\s/u.test(scope)) {
+      throw new ValidationError("each scope must be a non-empty string without whitespace");
+    }
+  }
+  return [...new Set(scopes)].join(" ");
+}
+function normaliseIssuer(value) {
+  return typeof value === "string" ? value.replace(/\/+$/u, "") : "";
+}
+function constantTimeEquals(left, right) {
+  const a = Buffer.from(left, "utf8");
+  const b = Buffer.from(right, "utf8");
+  return a.length === b.length && (0, import_node_crypto.timingSafeEqual)(a, b);
+}
+function toSearchParams(params) {
+  if (params instanceof URLSearchParams) return params;
+  if (params instanceof URL) return params.searchParams;
+  if (typeof params === "string") {
+    return params.includes("://") ? new URL(params).searchParams : new URLSearchParams(params.replace(/^\?/u, ""));
+  }
+  assertRecord(params, "callback parameters");
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    const first = Array.isArray(value) ? value[0] : value;
+    if (typeof first === "string") search.set(key, first);
+  }
+  return search;
 }
 
 // src/resources/fields.ts
@@ -5190,8 +6013,6 @@ function validateSignerAccessCode(value) {
 }
 
 // src/resources/signer-documents.ts
-var EMAIL_RE5 = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-var E164_RE = /^\+[1-9]\d{1,14}$/u;
 var SignerDocumentsResource = class extends BaseResource {
   constructor(http, defaultAccountId, logger, publicHttp) {
     super(withoutCredentials(publicHttp ?? http), defaultAccountId, logger);
@@ -5848,10 +6669,10 @@ function validateConfirmDataPayload(payload) {
       throw new ValidationError(`${key} must be a string`);
     }
   }
-  if (payload.email !== void 0 && (typeof payload.email !== "string" || !EMAIL_RE5.test(payload.email))) {
+  if (payload.email !== void 0 && !isEmail(payload.email)) {
     throw new ValidationError("email must be a valid email address");
   }
-  if (payload.whatsapp_phone_number !== void 0 && (typeof payload.whatsapp_phone_number !== "string" || !E164_RE.test(payload.whatsapp_phone_number))) {
+  if (payload.whatsapp_phone_number !== void 0 && !isE164PhoneNumber(payload.whatsapp_phone_number)) {
     throw new ValidationError("whatsapp_phone_number must use E.164 format");
   }
   if (payload.has_accepted_terms !== void 0 && typeof payload.has_accepted_terms !== "boolean") {
@@ -6038,7 +6859,7 @@ function validateNotificationPreferences(preferences) {
 }
 
 // src/support/webhook-verifier.ts
-var import_node_crypto = require("crypto");
+var import_node_crypto2 = require("crypto");
 var WebhookVerifier = class {
   webhookSecret;
   /**
@@ -6077,10 +6898,10 @@ var WebhookVerifier = class {
     const buf = typeof payload === "string" ? Buffer.from(payload, "utf8") : payload;
     const provided = signature.trim();
     if (!/^[\da-f]{64}$/i.test(provided)) return false;
-    const expected = (0, import_node_crypto.createHmac)("sha256", this.webhookSecret).update(buf).digest();
+    const expected = (0, import_node_crypto2.createHmac)("sha256", this.webhookSecret).update(buf).digest();
     const actual = Buffer.from(provided, "hex");
     try {
-      return (0, import_node_crypto.timingSafeEqual)(expected, actual);
+      return (0, import_node_crypto2.timingSafeEqual)(expected, actual);
     } catch {
       return false;
     }
@@ -6165,6 +6986,7 @@ var AssinafyClient = class _AssinafyClient {
   templates;
   tags;
   auth;
+  oauth;
   fields;
   signerDocuments;
   users;
@@ -6271,6 +7093,12 @@ var AssinafyClient = class _AssinafyClient {
       this.logger,
       this.publicAxiosInstance
     );
+    this.oauth = new OAuthResource(
+      this.axiosInstance,
+      void 0,
+      this.logger,
+      this.publicAxiosInstance
+    );
     this.fields = new FieldsResource(this.axiosInstance, this.defaultAccountId, this.logger);
     this.signerDocuments = new SignerDocumentsResource(
       this.publicAxiosInstance,
@@ -6617,11 +7445,20 @@ function normaliseBaseUrl(raw) {
   if (url.protocol !== "https:" && url.protocol !== "http:") {
     throw new ValidationError("baseUrl must use http or https");
   }
+  if (url.protocol === "http:" && !isLoopbackHost(url.hostname)) {
+    throw new ValidationError(
+      "baseUrl must use https for a remote host; http is only allowed for localhost"
+    );
+  }
   if (url.username || url.password || raw.includes("?") || raw.includes("#")) {
     throw new ValidationError("baseUrl must not contain credentials, a query, or a fragment");
   }
   return url.href.replace(/\/+$/, "");
 }
+function isLoopbackHost(hostname) {
+  const host = hostname.replace(/^\[|\]$/gu, "");
+  return host === "localhost" || host === "::1" || /^127(?:\.\d{1,3}){3}$/u.test(host);
+}
 function installCredentialOriginGuard(http, baseURL) {
   const allowedOrigin = new URL(baseURL).origin;
   http.interceptors.request.use((config) => {
@@ -6696,8 +7533,11 @@ function hasIdempotencyKey(headers) {
   DEFAULT_WEBHOOK_EVENTS,
   DocumentResource,
   FieldsResource,
+  MAX_LIST_PAGE_SIZE,
   MAX_UPLOAD_BYTES,
   NetworkError,
+  OAuthError,
+  OAuthResource,
   SDK_USER_AGENT,
   SignerDocumentsResource,
   SignerResource,
@@ -6708,5 +7548,6 @@ function hasIdempotencyKey(headers) {
   WebhookResource,
   WebhookVerifier,
   WorkspaceResource,
-  buildAssignmentPayload
+  buildAssignmentPayload,
+  parseWwwAuthenticate
 });