@assinafy/sdk 2.1.2 → 2.2.0

package/CHANGELOG.md

@@ -7,6 +7,102 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.2.0] - 2026-08-27
+
+### Security
+
+- **`baseUrl` now requires `https` for any remote host.** Every request on the
+  authenticated transport carries the caller's `X-Api-Key` or bearer token, so
+  a plaintext `http://` base URL put a long-lived credential on the wire in
+  cleartext. `http` remains accepted when the host is loopback (`localhost`,
+  the `127.0.0.0/8` block, or `::1`) so local mock servers and the packed
+  consumer smoke test keep working; anything else is rejected with a
+  `ValidationError` at construction time. `SECURITY.md` already required HTTPS
+  endpoints — the client now enforces it rather than trusting configuration.
+  - Callers pointing at a remote `http://` host must switch to `https://`.
+
+### Fixed
+
+- **`signers.findByEmail()` requested 100 rows per page and received 50.** The
+  API clamps `per-page` to 50 and answers `200`, so the lookup scanned half the
+  window its documentation claimed. It now pins the real maximum, and the
+  method and `signers.list()` documentation state the clamp instead of naming
+  100 as the API maximum. `documents.list()` carried the same incorrect claim.
+- **Unstructured error bodies were reported as the generic "API request
+  failed".** A gateway or proxy in front of the API answers with `text/plain`
+  or HTML rather than the Assinafy JSON envelope. `ApiError.fromResponse()`
+  only read `message`/`error` off an object, so exactly the failures with no
+  structured body to explain them lost their only explanation. A non-JSON body
+  is now used as the message, with whitespace collapsed and the text capped at
+  500 characters; the untouched body remains on `ApiError.responseData`.
+
+### Added
+
+- **`MAX_LIST_PAGE_SIZE`** — the largest page any list endpoint returns (50).
+  Exported so callers can size pagination loops against the value the server
+  actually honours rather than the one they request.
+
+### Changed
+
+- The email and E.164 phone-number patterns had five and two copies across the
+  resource files. They are now `isEmail()`, `assertEmail()`, and
+  `isE164PhoneNumber()` in `src/utils.ts`, so the accepted shape of a contact
+  value is defined in one place. Validation behaviour and error messages are
+  unchanged.
+- `decodeBinaryErrorBody()` returns a non-JSON binary body as a string instead
+  of wrapping it in `{ message }`, so both unstructured-body paths converge on
+  the single rule in `ApiError.fromResponse()`.
+- GitLab CI reads the Bun version from `package.json`'s `packageManager` field
+  instead of repeating the literal, matching how GitHub Actions' `setup-bun`
+  resolves it. Both CIs now move together when that field is bumped.
+- README gained a contents map linking the setup, end-to-end workflow, and
+  per-resource sections; list examples use the `per-page` spelling the API
+  reads and document the page-size clamp.
+
+## [2.1.2] - 2026-08-26
+
+### Added
+
+- `SDK_USER_AGENT` — every transport, including public and signer-access-code
+  requests, now identifies itself as `Assinafy-Typescript-SDK/v<VERSION>`.
+- `scripts/node-consumer-smoke.mjs`, exercised by CI and the release workflow:
+  it installs the packed tarball into an isolated consumer and drives the real
+  Node HTTP, auth, and multipart paths through both CJS and ESM entrypoints.
+- A manual **Sandbox integration** workflow with `read-only` and
+  `disposable-full` modes, gated on a protected environment.
+
+### Security
+
+- Requests on the authenticated transport are pinned to the configured API
+  origin. A cross-origin URL is rejected before dispatch, and `Authorization`
+  and `X-Api-Key` are marked redirect-sensitive so the redirect stack strips
+  them.
+- Cross-origin redirects are blocked unless they are a `GET`/`HEAD` to an
+  `https` target whose source URL carries no sensitive query parameter.
+- Public, login, and signer-access-code flows run on a transport whose
+  credential headers are removed at construction, so a configured API key
+  cannot reach a public endpoint.
+- `AxiosError` is no longer attached as an SDK error `cause`. It retains the
+  full request config, including credentials and body, which error reporters
+  commonly serialize. Transport failures now carry a sanitized cause with
+  credential-shaped values redacted from the message.
+- Caller-supplied loggers receive an allowlist of numeric operational counters
+  only. Logger exceptions and rejected promises are swallowed so telemetry
+  cannot change request semantics.
+
+### Fixed
+
+- `AssinafyClient.create()` no longer let its options bag override the
+  `apiKey`/`accountId` passed positionally, and it rejects missing or malformed
+  credentials instead of constructing an unusable client.
+- Constructor options are validated up front: a non-object bag, a blank
+  credential, or an invalid `timeout`/`maxRetries` throws `ValidationError`.
+- `uploadAndRequestSignatures()` validates every signer before uploading, so an
+  invalid later signer no longer leaves an orphaned document behind, and it no
+  longer waits for `metadata_ready` before creating a virtual assignment.
+- HTTP 429 replay is limited to `GET`, `HEAD`, `OPTIONS`, and `DELETE`, with
+  `GET /sign` excluded because that read records a signer view.
+
 ## [2.1.1] - 2026-08-06
 
 Maintenance only. The published `dist/` is byte-identical to 2.1.0; no runtime,
@@ -457,7 +553,9 @@ fields (`cpf`, `whatsapp_phone_number`) with the PHP SDK and n8n node.
 - High-level `uploadAndRequestSignatures` helper on `AssinafyClient`.
 - `PaginatedResult<T>` with parsed `X-Pagination-*` header meta.
 
-[Unreleased]: https://github.com/assinafy/typescript-sdk/compare/v2.1.1...HEAD
+[Unreleased]: https://github.com/assinafy/typescript-sdk/compare/v2.2.0...HEAD
+[2.2.0]: https://github.com/assinafy/typescript-sdk/compare/v2.1.2...v2.2.0
+[2.1.2]: https://github.com/assinafy/typescript-sdk/compare/v2.1.1...v2.1.2
 [2.1.1]: https://github.com/assinafy/typescript-sdk/compare/v2.1.0...v2.1.1
 [2.1.0]: https://github.com/assinafy/typescript-sdk/compare/v2.0.0...v2.1.0
 [2.0.0]: https://github.com/assinafy/typescript-sdk/releases/tag/v2.0.0

package/README.md

@@ -13,6 +13,37 @@ See [API coverage](docs/API_COVERAGE.md) for the operation map and
 [compatibility notes](docs/COMPATIBILITY.md) for deployment-specific request
 and response variants.
 
+## Contents
+
+This document runs from setup to a complete signature workflow, then to
+per-resource detail. Read it in order the first time; use it as a reference
+afterwards.
+
+**Getting set up** — [Requirements](#requirements) ·
+[Installation](#installation) · [Quick start](#quick-start) ·
+[Authentication](#authentication) · [Configuration](#configuration)
+([rate limiting](#rate-limiting), [factories](#factories)) ·
+[Endpoint coverage](#endpoint-coverage)
+
+**The end-to-end flow** — [Document lifecycle](#document-lifecycle):
+[upload](#1-upload-the-pdf) → [signers](#2-create-or-reuse-the-email-signers) →
+[price and request signatures](#3-price-then-request-signatures) →
+[the signer's side](#4-complete-the-email-signer-flow) →
+[completion and artifacts](#5-observe-completion-and-download-artifacts)
+
+**Per-resource detail** — [Resource reference](#resource-reference):
+[documents](#documents) · [signers](#signers) · [assignments](#assignments) ·
+[paid signing branches](#paid-signing-branches) · [templates](#templates) ·
+[tags](#tags) · [workspaces](#workspaces) ·
+[field definitions](#field-definitions) ·
+[auth and API keys](#authentication--api-key-management) ·
+[the current user](#authenticated-user) · [webhooks](#webhooks)
+([verification](#webhook-verification)) ·
+[signer-side endpoints](#signer-side-endpoints)
+
+**Everything else** — [High-level helper](#high-level-helper) ·
+[Errors](#errors) · [Development](#development) · [License](#license)
+
 ## Requirements
 
 - Node.js 22+ for the built-in `FormData` / `Blob` APIs used by uploads. Packed
@@ -105,7 +136,7 @@ installed package version. The exact value is also exported as
 | `apiKey`        | string   | —                                       | Preferred credential (sent as `X-Api-Key`).   |
 | `token`         | string   | —                                       | Access token (sent as `Authorization: Bearer`). |
 | `accountId`     | string   | —                                       | Default workspace/account ID.                  |
-| `baseUrl`       | string   | `https://api.assinafy.com.br/v1`        | Absolute HTTP(S) API base without credentials, query, or fragment. |
+| `baseUrl`       | string   | `https://api.assinafy.com.br/v1`        | Absolute API base without credentials, query, or fragment. Must be `https` unless the host is loopback. |
 | `webhookSecret` | string   | —                                       | Opt-in HMAC secret used by `WebhookVerifier`; see its [contract caveat](docs/COMPATIBILITY.md#webhook-signature-verification-is-not-in-the-openapi-contract). |
 | `timeout`       | number   | `30000`                                 | Request timeout in milliseconds.               |
 | `maxRetries`    | number   | `2`                                     | Auto-retries eligible HTTP 429 responses, honoring `Retry-After`. `0` disables. |
@@ -441,7 +472,7 @@ const doc = await client.documents.upload(
 await client.documents.upload({ buffer, fileName: 'contract.pdf' });
 
 // List → { data: IDocumentListItem[], meta?: { current_page, per_page, total, last_page } }
-const { data, meta } = await client.documents.list({ page: 1, per_page: 20, sort: 'updated_at' });
+const { data, meta } = await client.documents.list({ page: 1, 'per-page': 20, sort: 'updated_at' });
 
 // Search is the lightweight alternative to list: same item shape, but the API
 // skips the expanded `assignment`/`pages`. Prefer it for name lookups.
@@ -501,7 +532,17 @@ account authentication as their download operations. Prefer
 credential and returns a `Buffer`. `bundle` contains `original`, `certificated`,
 and `certificate-page`, plus `pades` when available.
 
-List endpoints return `{ data, meta }` where `meta` is populated from the `X-Pagination-*` headers returned by the API.
+List endpoints return `{ data, meta }`, where `meta` is populated from the
+`X-Pagination-*` response headers. Two API behaviours are worth knowing because
+both are silent rather than errors:
+
+- Only the hyphenated `per-page` is read. `per_page` is accepted and ignored,
+  falling back to 20 rows — so the SDK rewrites `per_page` to `per-page` on
+  every list method, and an explicit `per-page` wins when both are given.
+- `per-page` is clamped to **50**. Asking for 100 returns 50 rows with a `200`.
+  The exported `MAX_LIST_PAGE_SIZE` constant is that ceiling; page through with
+  `page` rather than requesting a larger page, and trust `meta.per_page` over
+  the value you asked for.
 
 ### Signers
 
@@ -525,7 +566,7 @@ await client.signers.create({
 });
 
 await client.signers.get(signerId);
-await client.signers.list({ page: 1, per_page: 50, search: 'john' });
+await client.signers.list({ page: 1, 'per-page': 50, search: 'john' });
 await client.signers.update(signerId, {
   full_name: 'Johnny Doe',
   government_id: '390.533.447-05', // official update field; sent as digits
@@ -718,7 +759,7 @@ const created = await client.templates.create(
 //   pages: [], tags: [], created_at: '2026-…', updated_at: '2026-…'
 // }
 
-const { data, meta } = await client.templates.list({ search: 'NDA', per_page: 20 });
+const { data, meta } = await client.templates.list({ search: 'NDA', 'per-page': 20 });
 const template = await client.templates.get(created.id);   // includes pages[] + default_document_tags
 await client.templates.update(created.id, { name: 'NDA v2', message: 'Please sign' });
 const firstPage = template.pages?.[0];
@@ -1053,7 +1094,7 @@ await client.signerDocuments.self(accessCode);
 await client.signerDocuments.verifyEmail({ signerAccessCode: accessCode, verificationCode: '123456' });
 
 await client.signerDocuments.getCurrent(signerId, accessCode);
-const { data } = await client.signerDocuments.list(signerId, accessCode, { per_page: 20 });
+const { data } = await client.signerDocuments.list(signerId, accessCode, { 'per-page': 20 });
 // Signer-side counterpart of documents.search(), authorised by the access code.
 const found = await client.signerDocuments.search(signerId, accessCode, 'invoice');
 await client.signerDocuments.download(signerId, documentId, 'original');

package/SECURITY.md

@@ -44,8 +44,10 @@ opportunity to upgrade.
   authentication, and signer-access-code flows use an auth-free transport so
   configured account credentials are not sent to public endpoints.
 - Consumers must use HTTPS endpoints and protect all SDK configuration as
-  secrets. Debug logging and error telemetry must be reviewed for response data
-  before being enabled in production.
+  secrets. The client enforces this: a `baseUrl` using plaintext `http` is
+  rejected unless its host is loopback, so a credential cannot be sent in the
+  clear to a remote host. Debug logging and error telemetry must be reviewed
+  for response data before being enabled in production.
 - The webhook HMAC helper is an opt-in utility, not proof of an official
   Assinafy signing contract. Confirm the header, algorithm, encoding, and secret
   delivery mechanism with Assinafy before enforcing it. See

package/dist/index.d.mts

@@ -1261,7 +1261,8 @@ declare class DocumentResource 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
@@ -2099,7 +2100,8 @@ declare class SignerResource 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
@@ -2181,10 +2183,10 @@ declare class SignerResource 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.
@@ -5287,9 +5289,14 @@ declare 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
@@ -5331,6 +5338,15 @@ declare class NetworkError extends AssinafyError {
     constructor(message: string, options?: ErrorOptions);
 }
 
+/**
+ * Largest page the list endpoints actually return.
+ *
+ * The API silently clamps `per-page` to this value rather than rejecting a
+ * larger one, so a caller asking for 100 receives 50 and no error. Methods that
+ * need "as many rows as one request can give" pin this instead of guessing.
+ */
+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_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 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 };

package/dist/index.d.ts

@@ -1261,7 +1261,8 @@ declare class DocumentResource 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
@@ -2099,7 +2100,8 @@ declare class SignerResource 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
@@ -2181,10 +2183,10 @@ declare class SignerResource 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.
@@ -5287,9 +5289,14 @@ declare 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
@@ -5331,6 +5338,15 @@ declare class NetworkError extends AssinafyError {
     constructor(message: string, options?: ErrorOptions);
 }
 
+/**
+ * Largest page the list endpoints actually return.
+ *
+ * The API silently clamps `per-page` to this value rather than rejecting a
+ * larger one, so a caller asking for 100 receives 50 and no error. Methods that
+ * need "as many rows as one request can give" pin this instead of guessing.
+ */
+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_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 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 };

package/dist/index.js

@@ -38,6 +38,7 @@ __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,
   SDK_USER_AGENT: () => SDK_USER_AGENT,
@@ -59,6 +60,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;
   /**
@@ -100,9 +107,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,10 +123,14 @@ 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);
   }
 };
@@ -189,7 +205,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) {
@@ -270,6 +286,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`);
@@ -505,7 +533,7 @@ var import_axios2 = __toESM(require("axios"));
 // package.json
 var package_default = {
   name: "@assinafy/sdk",
-  version: "2.1.2",
+  version: "2.2.0",
   packageManager: "bun@1.4.0",
   description: "TypeScript SDK for Assinafy API - Digital signature platform",
   type: "commonjs",
@@ -1554,7 +1582,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 +1666,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 +2570,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`;
@@ -2729,7 +2757,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 +2882,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 +2993,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 +3026,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 +3040,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 +3053,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 +3078,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 +3094,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 +3539,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 +3591,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 +4394,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,11 +4836,6 @@ 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/fields.ts
 var FieldsResource = class extends BaseResource {
@@ -5190,8 +5214,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 +5870,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") {
@@ -6617,11 +6639,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,6 +6727,7 @@ function hasIdempotencyKey(headers) {
   DEFAULT_WEBHOOK_EVENTS,
   DocumentResource,
   FieldsResource,
+  MAX_LIST_PAGE_SIZE,
   MAX_UPLOAD_BYTES,
   NetworkError,
   SDK_USER_AGENT,

package/dist/index.mjs

@@ -3,6 +3,12 @@ import axios3 from "axios";
 import { setTimeout as delay } from "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;
   /**
@@ -44,9 +50,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
@@ -55,10 +66,14 @@ 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);
   }
 };
@@ -133,7 +148,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) {
@@ -214,6 +229,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`);
@@ -449,7 +476,7 @@ import axios2 from "axios";
 // package.json
 var package_default = {
   name: "@assinafy/sdk",
-  version: "2.1.2",
+  version: "2.2.0",
   packageManager: "bun@1.4.0",
   description: "TypeScript SDK for Assinafy API - Digital signature platform",
   type: "commonjs",
@@ -1498,7 +1525,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) {
@@ -1583,7 +1609,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
@@ -2486,7 +2513,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`;
@@ -2673,7 +2700,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`).
@@ -2799,7 +2825,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
@@ -2909,10 +2936,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.
@@ -2942,7 +2969,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) {
@@ -2953,7 +2983,7 @@ var SignerResource = class extends BaseResource {
     }
   }
   assertEmail(email) {
-    if (!email || !EMAIL_RE2.test(email)) {
+    if (!isEmail(email)) {
       throw new ValidationError("Invalid email address", { email });
     }
   }
@@ -2966,7 +2996,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);
@@ -2991,7 +3021,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;
@@ -3007,7 +3037,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");
   }
 }
@@ -3452,7 +3482,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
@@ -3505,7 +3534,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
       });
@@ -4308,7 +4337,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) {
@@ -4751,11 +4779,6 @@ 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/fields.ts
 var FieldsResource = class extends BaseResource {
@@ -5134,8 +5157,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);
@@ -5792,10 +5813,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") {
@@ -6561,11 +6582,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) => {
@@ -6639,6 +6669,7 @@ export {
   DEFAULT_WEBHOOK_EVENTS,
   DocumentResource,
   FieldsResource,
+  MAX_LIST_PAGE_SIZE,
   MAX_UPLOAD_BYTES,
   NetworkError,
   SDK_USER_AGENT,

package/docs/COMPATIBILITY.md

@@ -58,6 +58,29 @@ method counters. Notification counters are not mutually exclusive.
 are mutually exclusive and sum to `signature_requests`. Older unsuffixed email
 and WhatsApp counters remain optional.
 
+## List pagination
+
+Two behaviours of the list endpoints are silent rather than loud, so neither
+surfaces as an error a caller could react to:
+
+- Only the hyphenated `per-page` is read. `per_page` is accepted and discarded,
+  and the response falls back to the default of 20 rows. The SDK normalizes
+  `per_page` to `per-page` on every list method, and an explicit `per-page`
+  wins if both are supplied.
+- `per-page` is clamped to **50**. A request for 100 returns 50 rows with a
+  `200`, so page-size arithmetic based on the requested value is wrong by half.
+  That maximum is exported as `MAX_LIST_PAGE_SIZE`.
+
+```ts
+import { MAX_LIST_PAGE_SIZE } from '@assinafy/sdk';
+
+const { data, meta } = await client.documents.list({ 'per-page': MAX_LIST_PAGE_SIZE });
+// meta is read from the X-Pagination-* response headers, so it reports the
+// page size the server actually applied — prefer it over the requested value.
+```
+
+`signers.findByEmail()` pins this maximum for its single lookup request.
+
 ## Assignment list account context
 
 `GET /v1/assignments` requires the workspace in the camel-case `accountId`

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@assinafy/sdk",
-    "version": "2.1.2",
+    "version": "2.2.0",
     "packageManager": "bun@1.4.0",
     "description": "TypeScript SDK for Assinafy API - Digital signature platform",
     "type": "commonjs",