docspring 3.3.0 → 4.1.0

package/AGENTS.md

@@ -1,15 +1,15 @@
 # AGENTS.md
 
-Notes for AI coding agents working with the DocSpring JavaScript SDK (`docspring`), in this repository or
-as a dependency of an app.
+Notes for AI coding agents working with the DocSpring JavaScript SDK (`docspring`): integrating it into an
+app, or working in this repository.
 
 ## This code is generated
 
 Every file here is generated from DocSpring's OpenAPI spec by
 [DocSpring's fork of OpenAPI Generator](https://github.com/DocSpring/openapi-generator/tree/docspring/all_patches), and each release replaces
-all of it. Don't edit it or open pull requests that change it, and don't patch an installed copy: the next release
-overwrites the change. Report bugs at https://github.com/DocSpring/docspring-javascript/issues or to support@docspring.com, and DocSpring fixes them in
-the generator.
+all of it. Don't patch an installed copy: the next release overwrites the change. Issues and pull requests are welcome
+at https://github.com/DocSpring/docspring-javascript (or email support@docspring.com), and DocSpring makes the fix in the generator so that every release
+keeps it.
 
 ## Where to look
 
@@ -17,17 +17,77 @@ the generator.
 - [docs/Client.md](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md): every method, with its parameters and return type.
 - [docs/](https://github.com/DocSpring/docspring-javascript/tree/main/docs): every model and its fields.
 - https://docspring.com/docs/llms.txt: DocSpring's documentation for LLMs (`llms-small.txt`, `llms-full.txt`).
-- https://docspring.com/docs/api/: the API reference, with JavaScript code for every method.
-- https://docspring.com/api-docs/v1/openapi.json: the OpenAPI spec this SDK is generated from.
-
-## Using it in an app
-
-- Credentials come from `DOCSPRING_TOKEN_ID` and `DOCSPRING_TOKEN_SECRET`. Keep them in the environment or a secret
-  store, never in code. Accounts in the EU region also need `DOCSPRING_REGION=EU`.
-- Template IDs look like `tpl_...` and submission IDs like `sub_...`.
-- Pass `test: true` when you generate PDFs during development: test PDFs are free and watermarked.
-- Generating a PDF waits for it, for up to 95 seconds. For many PDFs or slow templates, set `wait` to false and use
-  webhooks or check the submission later (https://docspring.com/docs/api-guide/synchronous-requests/).
-- Errors: The callback gets `(error, data, response)`. For an error response, `error.status` is the HTTP status and `response.body` the parsed body.
-- Responses can be newer than this SDK, because DocSpring adds fields and enum values to API v1 without a new
-  version. The model object keeps a response field added to the API after this release as a property. An enum value added to the API after this release comes back as a string, so handle values you don't recognize.
+- https://docspring.com/docs/: the guides. https://docspring.com/docs/api/: the API reference, with JavaScript code
+  for every method.
+- https://docspring.com/api-docs/v2/openapi.json: the OpenAPI spec this SDK is generated from.
+
+## Set up
+
+- Credentials come from `DOCSPRING_TOKEN_ID` and `DOCSPRING_TOKEN_SECRET` (an API token from
+  https://app.docspring.com/api_tokens). Keep them in the environment or a secret store, never in code. An account in
+  the EU region also needs `DOCSPRING_REGION=EU`.
+- Call DocSpring from your server. The token secret gives full access to the account, so it must never reach a browser
+  or a mobile app. Signers use signing links or the embedded signing form instead (see Signature requests).
+- `testAuthentication` checks the credentials.
+
+## Generate PDFs
+
+- Read a template's data shape before writing the request: `getTemplateSchema` returns the
+  JSON Schema of its submission data (its field names and types), and `getTemplateModelCode`
+  generates typed code for it. The keys of `data` are the template's field names. Date fields take `YYYY-MM-DD`.
+- Template IDs look like `tpl_...` and submission IDs like `sub_...`. Store the submission ID with your own record.
+- Pass `test: true` while you build: test PDFs are free and watermarked. Live PDFs use credits.
+- A submission uses the template's latest published version (its draft when nothing has been published yet). Pass
+  `version` (`draft`, `1.2.0`, or `1` for the latest 1.x.x) to use another one.
+- `createSubmission` waits for the PDF, for up to 95 seconds, and returns the submission in
+  its final state: check its `state` (`processed`, or a failure state with an `error_message`). If the PDF takes longer,
+  the call fails with a 504 `polling_timeout` error that has the submission's ID. The submission exists and is still
+  being made, so don't send the request again (that makes a second one): get it with
+  `getSubmission` until its state isn't `pending`. For slow templates or many PDFs, set
+  `wait` to false and use webhooks (https://docspring.com/docs/api-guide/synchronous-requests/).
+  `createSubmissionBatch` sends up to 50 submissions in one request.
+- `files.pdf.download_url` is a temporary link. Keep the submission ID (or `files.pdf.permanent_url`, which needs your
+  API token) and get a fresh link when someone downloads the PDF.
+- Submission data is often personal data: don't log request or response bodies. `expires_in` deletes a submission's PDF
+  and data that many seconds after it's created, and `expireSubmission` deletes them now.
+
+## Errors
+
+- Each method returns a promise. For an error response it rejects with an object whose `status` is the HTTP status and `body` the parsed body.
+- Every error response has one body: `{"error": {"code", "message", "details", "request_id"}}`. Branch on `code`, not
+  on the message. Each detail has a `pointer` to the request body value it's about, or the query `parameter`.
+- 422 `invalid_data`: the data doesn't match the template. The submission is saved anyway, as `invalid_data`, and the
+  error has its `submission_id`.
+- 402 `insufficient_credits`: the submission is saved and is made automatically once the account has credits. Don't
+  send it again (https://docspring.com/docs/api-guide/credits-and-rate-limits/).
+- 429 `rate_limited`: wait for the seconds in the `Retry-After` header, then retry.
+- Requests are checked against the API's request schemas before they're sent. A request the API would reject fails with a `ValidationError` (exported by the package), whose `details` are objects with `code`, `message` and a `pointer` into the body (or a `parameter`). Turn the check off with `client.apiClient.validateRequests = false`.
+
+## Webhooks
+
+- Webhooks tell your server when a submission is processed or fails, instead of polling
+  (https://docspring.com/docs/webhooks/overview/). A webhook created with API v2 sends events in API v2's format
+  (version 4).
+- Verify each request's `X-DocSpring-Signature` header before acting on it: an HMAC-SHA256 of `{t}.{raw body}` with the
+  webhook's signing secret, computed over the raw body exactly as received
+  (https://docspring.com/docs/webhooks/verifying-signatures/).
+- No webhook is sent when a submission starts waiting for credits.
+
+## Signature requests
+
+- To have people fill in fields and sign before the PDF is made, create the submission with `signature_requests`. Each
+  one has the `fields` its signer fills in (a field belongs to one signature request), and their `name` and `email`.
+  The PDF is made when every signer has finished
+  (https://docspring.com/docs/api-guide/create-signature-requests/).
+- Send a signer to the `signature_request_url` of a token from
+  `createSignatureRequestToken`. An `api` token's link opens the form for 24 hours and an
+  `email` token's for 7 days (`expires_at`), so create a new token when a signer comes back later.
+- To show the signing form on your own site, use Signature Requests JS, and add the site's domain to the template's
+  Embed Domains (https://docspring.com/docs/guides/embedded-forms/embedded-signature-requests/).
+
+## Responses
+
+- List methods return `data` and `next_cursor`: pass `next_cursor` as `cursor` to get the next page.
+- Responses can be newer than this SDK, because DocSpring adds fields and enum values to API v2 without a new
+  version. The model object keeps a response field added to the API after this release as a property. The objects defined inside a model, such as a template's `document`, leave it out. Enum values in responses are strings, so a
+  value added after this release comes back as it is: handle values you don't recognize.

package/README.md

@@ -6,7 +6,10 @@ templates with your data, generates PDFs from HTML templates, combines PDFs and
 [Documentation](https://docspring.com/docs/) · [API reference](https://docspring.com/docs/api/) ·
 [npm](https://www.npmjs.com/package/docspring) · [Changelog](https://github.com/DocSpring/docspring-javascript/blob/main/CHANGELOG.md)
 
-Version 3.3.0. 
+The code in this repository is generated from DocSpring's OpenAPI spec ([About this SDK](#about-this-sdk)). Issues and
+pull requests are welcome.
+
+Version 4.1.0. 
 
 ## Install and configure
 
@@ -59,32 +62,22 @@ Fill a template with data (use your template's ID in place of `tpl_1234567890abc
 
 ```javascript
 const templateId = 'tpl_1234567890abcdef01'
-const submission = {
+const body = {
   data: {
     first_name: 'John',
     last_name: 'Smith',
     phone_number: '+11234567890',
   },
-  metadata: { foo: 123, bar: 'baz' },
+  metadata: { user_id: 42 },
+  test: true,
 }
-const wait = undefined
-
-apiInstance.generatePdf(
-  templateId,
-  submission,
-  { wait: wait },
-  (error, data, response) => {
-    if (error) {
-      console.error('Error calling generatePdf:', error)
-    } else {
-      console.log('API call completed successfully:', data)
-    }
-  }
-)
+
+const result = await apiInstance.createSubmission(templateId, body)
+console.log(result)
 ```
 
-By default the call waits for the PDF, for up to 95 seconds, and the submission in the response has its
-`download_url`. Set `wait` to false to get a pending submission straight away.
+By default the call waits for the PDF, for up to 95 seconds, and the submission in the response has a link to
+download it (`files.pdf.download_url`). Set `wait` to false to get a pending submission straight away.
 [Sync vs. async processing](https://docspring.com/docs/api-guide/synchronous-requests/) covers the time limit, status
 checks and webhooks.
 
@@ -96,83 +89,101 @@ JavaScript code for every method.
 
 | Method | Description |
 | ------ | ----------- |
-| [`addFieldsToTemplate`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#addfieldstotemplate) | Add new fields to a Template |
-| [`batchGeneratePdfs`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#batchgeneratepdfs) | Generate multiple PDFs |
-| [`combinePdfs`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#combinepdfs) | Merge submission PDFs, template PDFs, or custom files |
+| [`addTemplateFields`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#addtemplatefields) | Add fields to a template |
 | [`copyTemplate`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#copytemplate) | Copy a template |
-| [`createCustomFileFromUpload`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#createcustomfilefromupload) | Create a new custom file from a cached S3 upload |
-| [`createDataRequestEvent`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#createdatarequestevent) | Create a new event for emailing a signee a request for signature |
-| [`createDataRequestToken`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#createdatarequesttoken) | Create a new data request token for form authentication |
+| [`createCombinedPdf`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#createcombinedpdf) | Combine PDFs |
+| [`createCustomFileFromUpload`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#createcustomfilefromupload) | Create a custom file from an upload |
 | [`createFolder`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#createfolder) | Create a folder |
-| [`createHtmlTemplate`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#createhtmltemplate) | Create a new HTML template |
-| [`createPdfTemplate`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#createpdftemplate) | Create a new PDF template with a form POST file upload |
-| [`createPdfTemplateFromUpload`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#createpdftemplatefromupload) | Create a new PDF template from a cached S3 file upload |
+| [`createSignatureRequestEvent`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#createsignaturerequestevent) | Record a signature request event |
+| [`createSignatureRequestToken`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#createsignaturerequesttoken) | Create a signature request token |
+| [`createSubmission`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#createsubmission) | Generate a PDF |
+| [`createSubmissionBatch`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#createsubmissionbatch) | Generate PDFs in a batch |
+| [`createTemplate`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#createtemplate) | Create a template |
 | [`createWebhook`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#createwebhook) | Create a webhook |
+| [`deleteCustomFile`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#deletecustomfile) | Delete a custom file |
 | [`deleteFolder`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#deletefolder) | Delete a folder |
 | [`deleteTemplate`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#deletetemplate) | Delete a template |
 | [`deleteWebhook`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#deletewebhook) | Delete a webhook |
-| [`expireCombinedSubmission`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#expirecombinedsubmission) | Expire a combined submission |
-| [`expireSubmission`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#expiresubmission) | Expire a PDF submission |
-| [`generatePdf`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#generatepdf) | Generate a PDF |
-| [`generatePreview`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#generatepreview) | Generate a preview PDF for partially completed data requests |
-| [`getCombinedSubmission`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#getcombinedsubmission) | Check the status of a combined submission (merged PDFs) |
-| [`getDataRequest`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#getdatarequest) | Look up a submission data request |
-| [`getFullTemplate`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#getfulltemplate) | Fetch the full attributes for a PDF template |
-| [`getPresignUrl`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#getpresignurl) | Get a presigned S3 URL for direct file upload |
-| [`getSubmission`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#getsubmission) | Check the status of a PDF |
-| [`getSubmissionBatch`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#getsubmissionbatch) | Check the status of a submission batch job |
-| [`getTemplate`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#gettemplate) | Check the status of an uploaded template |
-| [`getTemplateModelCode`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#gettemplatemodelcode) | Generate typed model code for a template |
-| [`getTemplateSchema`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#gettemplateschema) | Fetch the JSON schema for a template |
+| [`expireCombinedPdf`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#expirecombinedpdf) | Expire a combined PDF |
+| [`expireSubmission`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#expiresubmission) | Expire a submission |
+| [`generateSubmissionFiles`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#generatesubmissionfiles) | Generate more files |
+| [`generateSubmissionPreview`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#generatesubmissionpreview) | Generate a preview PDF |
+| [`getCombinedPdf`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#getcombinedpdf) | Get a combined PDF |
+| [`getCustomFile`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#getcustomfile) | Get a custom file |
+| [`getFolder`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#getfolder) | Get a folder |
+| [`getPresignUrl`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#getpresignurl) | Get a presigned URL to upload a file |
+| [`getSignatureRequest`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#getsignaturerequest) | Get a signature request |
+| [`getSubmission`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#getsubmission) | Get a submission |
+| [`getSubmissionBatch`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#getsubmissionbatch) | Get a batch |
+| [`getTemplate`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#gettemplate) | Get a template |
+| [`getTemplateDiff`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#gettemplatediff) | Compare a version of a template with the one before it |
+| [`getTemplateModelCode`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#gettemplatemodelcode) | Generate typed code for a template's submission data |
+| [`getTemplatePageImages`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#gettemplatepageimages) | Get images of a template's pages |
+| [`getTemplateSchema`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#gettemplateschema) | Get the JSON Schema of a template's submission data |
 | [`getWebhook`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#getwebhook) | Get a webhook |
-| [`listCombinedSubmissions`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#listcombinedsubmissions) | Get a list of all combined submissions |
-| [`listFolders`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#listfolders) | Get a list of all folders |
-| [`listSubmissions`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#listsubmissions) | List all submissions |
-| [`listTemplates`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#listtemplates) | Get a list of all templates |
-| [`listTemplateSubmissions`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#listtemplatesubmissions) | List all submissions for a given template |
-| [`listWebhooks`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#listwebhooks) | Get a list of all webhooks |
-| [`moveFolderToFolder`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#movefoldertofolder) | Move a folder |
-| [`moveTemplateToFolder`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#movetemplatetofolder) | Move Template to folder |
+| [`listCombinedPdfs`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#listcombinedpdfs) | List combined PDFs |
+| [`listCustomFiles`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#listcustomfiles) | List custom files |
+| [`listFolders`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#listfolders) | List folders |
+| [`listSubmissions`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#listsubmissions) | List submissions |
+| [`listTemplateFields`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#listtemplatefields) | List a template's fields |
+| [`listTemplates`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#listtemplates) | List templates |
+| [`listTemplateSubmissions`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#listtemplatesubmissions) | List a template's submissions |
+| [`listWebhooks`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#listwebhooks) | List webhooks |
+| [`moveFolder`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#movefolder) | Move a folder |
+| [`moveTemplate`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#movetemplate) | Move a template to a folder |
 | [`publishTemplateVersion`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#publishtemplateversion) | Publish a template version |
+| [`removeTemplateFields`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#removetemplatefields) | Remove fields from a template |
 | [`renameFolder`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#renamefolder) | Rename a folder |
+| [`reorderTemplateFields`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#reordertemplatefields) | Reorder a template's fields |
 | [`restoreTemplateVersion`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#restoretemplateversion) | Restore a template version |
 | [`testAuthentication`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#testauthentication) | Test authentication |
-| [`updateDataRequest`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#updatedatarequest) | Update a submission data request |
-| [`updateTemplate`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#updatetemplate) | Update a Template |
-| [`updateTemplateDocument`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#updatetemplatedocument) | Update a template's document with a form POST file upload |
-| [`updateTemplateDocumentFromUpload`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#updatetemplatedocumentfromupload) | Update a template's document with a cached S3 file upload |
+| [`updateSignatureRequest`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#updatesignaturerequest) | Update a signature request |
+| [`updateTemplate`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#updatetemplate) | Update a template |
+| [`updateTemplateDocument`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#updatetemplatedocument) | Replace a template's PDF |
+| [`updateTemplateFields`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#updatetemplatefields) | Update a template's fields |
 | [`updateWebhook`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#updatewebhook) | Update a webhook |
+| [`uploadTemplate`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#uploadtemplate) | Create a PDF template from an uploaded PDF |
+| [`uploadTemplateDocument`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#uploadtemplatedocument) | Replace a template's PDF with an uploaded PDF |
+| [`validateSubmission`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#validatesubmission) | Check a submission without creating it |
 
 ## Errors
 
-The callback gets `(error, data, response)`. For an error response, `error.status` is the HTTP status and `response.body` the parsed body.
+Each method returns a promise. For an error response it rejects with an object whose `status` is the HTTP status and `body` the parsed body.
+
+The client checks each request against the API's request schemas before sending it. A request the API would reject fails with a `ValidationError` (exported by the package), whose `details` are objects with `code`, `message` and a `pointer` into the body (or a `parameter`). Turn the check off with `client.apiClient.validateRequests = false`.
+The details are the ones the API's 422 response would have, so you get them without a round trip.
 
 ## API changes
 
-DocSpring adds fields and enum values to API v1 without releasing a new API version. Changes that would break
+DocSpring adds fields and enum values to API v2 without releasing a new API version. Changes that would break
 existing code, such as removing or renaming a field, go in a new API version
 ([API changes](https://docspring.com/docs/api-guide/openapi-schema/#api-changes)). So this SDK keeps working with
 responses that are newer than it is:
 
-- The model object keeps a response field added to the API after this release as a property.
-- An enum value added to the API after this release comes back as a string, so handle values you don't recognize.
+- The model object keeps a response field added to the API after this release as a property. The objects defined inside a model, such as a template's `document`, leave it out.
+- Enum values in responses are strings, so a value added to the API after this release comes back as it is: handle values you don't recognize.
 
 Upgrade the SDK to read new fields and enum values. The [changelog](https://github.com/DocSpring/docspring-javascript/blob/main/CHANGELOG.md) lists
 what each release adds.
 
 ## About this SDK
 
-This SDK is generated from DocSpring's [OpenAPI spec](https://docspring.com/api-docs/v1/openapi.json) with
-[DocSpring's fork of OpenAPI Generator](https://github.com/DocSpring/openapi-generator/tree/docspring/all_patches) 7.16.0.
-The fork doesn't change the JavaScript generator.
+This SDK is generated from DocSpring's [OpenAPI spec](https://docspring.com/api-docs/v2/openapi.json) with
+[DocSpring's fork of OpenAPI Generator](https://github.com/DocSpring/openapi-generator/tree/docspring/all_patches) 7.26.0.
+The fork changes the JavaScript generator:
+
+- Enum types have static constants (`SubmissionState.processed`). Stock OpenAPI Generator makes them instance fields.
 
 On top of the generated code, we add:
 
 - A client constructor that reads your credentials, region and host from the environment.
+- A nested object that's null in a response is `null` (stock OpenAPI Generator makes it `undefined`).
+- A rejected call's `response` is an object with the response's status, headers and body. Stock OpenAPI Generator attaches superagent's response, which holds the request's `Authorization` header, so logging the error printed the API token.
 
-Because the code is generated, we can't merge pull requests that change it. Please
-[open an issue](https://github.com/DocSpring/docspring-javascript/issues) or email [support@docspring.com](mailto:support@docspring.com) instead, and
-we'll fix it in the generator. [AGENTS.md](https://github.com/DocSpring/docspring-javascript/blob/main/AGENTS.md) is a short guide for AI coding agents.
+Each release regenerates every file, so a change made only here would be lost in the next one. Issues and pull
+requests are welcome all the same: [open an issue](https://github.com/DocSpring/docspring-javascript/issues) or a pull request, or email
+[support@docspring.com](mailto:support@docspring.com), and we'll make the fix in the generator so that every release
+keeps it. [AGENTS.md](https://github.com/DocSpring/docspring-javascript/blob/main/AGENTS.md) is a guide for AI coding agents that integrate this SDK.
 
 ## License
 

package/dist/ApiClient.js

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports["default"] = void 0;
 var _superagent = _interopRequireDefault(require("superagent"));
+var _RequestValidator = require("./RequestValidator");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { "default": e }; }
 function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
 function _classCallCheck(a, n) { if (!(a instanceof n)) throw new TypeError("Cannot call a class as a function"); }
@@ -13,9 +14,9 @@ function _createClass(e, r, t) { return r && _defineProperties(e.prototype, r),
 function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == _typeof(i) ? i : i + ""; }
 function _toPrimitive(t, e) { if ("object" != _typeof(t) || !t) return t; var r; if ("undefined" != typeof Symbol && void 0 !== (r = t[Symbol.toPrimitive])) { var i = r.call(t, e || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === e ? String : Number)(t); } /**
  * DocSpring API
- * Use DocSpring's API to programmatically fill out PDF forms, convert HTML to PDFs, merge PDFs, or request legally binding e-signatures. Requests are rate limited per account, and live PDFs use credits: a request over the limit returns 429 with a Retry-After header, and one your credits can't cover returns 402. See [Credits & Rate Limits](https://docspring.com/docs/api-guide/credits-and-rate-limits/).
+ * Use DocSpring's API to programmatically fill out PDF forms, convert HTML to PDFs, merge PDFs, or request legally binding e-signatures.
  *
- * The version of the OpenAPI document: v1
+ * The version of the OpenAPI document: v2
  * 
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -23,10 +24,23 @@ function _toPrimitive(t, e) { if ("object" != _typeof(t) || !t) return t; var r;
  * Do not edit the class manually.
  *
  */
+// The parts of a superagent response a caller needs. Its own response holds the request and the Authorization
+// header, which logging the response would print.
+function responseInfo(response) {
+  return {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers,
+    body: response.body,
+    text: response.text
+  };
+}
+
 /**
 * @module ApiClient
-* @version 3.3.0
+* @version 4.1.0
 */
+
 /**
 * Manages low level client-server communications, parameter marshalling, etc. There should not be any need for an
 * application to use this class directly - the *Api and model classes provide the public API for the service. The
@@ -41,15 +55,23 @@ var ApiClient = /*#__PURE__*/function () {
    * @param {String} basePath
    */
   function ApiClient() {
-    var basePath = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 'https://sync.api.docspring.com/api/v1';
+    var basePath = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 'https://sync.api.docspring.com/api/v2';
     _classCallCheck(this, ApiClient);
     /**
      * The base URL against which to resolve every API call's (relative) path.
      * @type {String}
-     * @default https://sync.api.docspring.com/api/v1
+     * @default https://sync.api.docspring.com/api/v2
      */
     this.basePath = basePath.replace(/\/+$/, '');
 
+    /**
+     * Check each request against the API's request schemas before sending it, and reject one the API would reject
+     * with a ValidationError that has the API's error details.
+     * @type {Boolean}
+     * @default true
+     */
+    this.validateRequests = true;
+
     /**
      * The authentication methods to be included for all API calls.
      * @type {Array.<String>}
@@ -66,7 +88,7 @@ var ApiClient = /*#__PURE__*/function () {
             * @default {}
             */
     this.defaultHeaders = {
-      'User-Agent': 'docspring-javascript-3.3.0'
+      'User-Agent': 'docspring-javascript-4.1.0'
     };
 
     /**
@@ -376,14 +398,6 @@ var ApiClient = /*#__PURE__*/function () {
       return ApiClient.convertToType(data, returnType);
     }
 
-    /**
-     * Callback function to receive the result of the operation.
-     * @callback module:ApiClient~callApiCallback
-     * @param {String} error Error message, if any.
-     * @param data The data returned by the service call.
-     * @param {String} response The complete HTTP response.
-     */
-
     /**
      * Invokes the REST service using the supplied settings and parameters.
      * @param {String} path The base URL to invoke.
@@ -399,13 +413,19 @@ var ApiClient = /*#__PURE__*/function () {
      * @param {(String|Array|ObjectFunction)} returnType The required type to return; can be a string for simple types or the
      * constructor for a complex type.
      * @param {String} apiBasePath base path defined in the operation/path level to override the default one
-     * @param {module:ApiClient~callApiCallback} callback The callback function.
-     * @returns {Object} The SuperAgent request object.
+     * @returns {Promise} A {@link https://www.promisejs.org/|Promise} object.
      */
   }, {
     key: "callApi",
-    value: function callApi(path, httpMethod, pathParams, queryParams, headerParams, formParams, bodyParam, authNames, contentTypes, accepts, returnType, apiBasePath, callback) {
+    value: function callApi(path, httpMethod, pathParams, queryParams, headerParams, formParams, bodyParam, authNames, contentTypes, accepts, returnType, apiBasePath) {
       var _this3 = this;
+      if (this.validateRequests) {
+        var hasForm = formParams && Object.keys(formParams).length > 0;
+        var validationError = (0, _RequestValidator.requestError)(httpMethod, path, queryParams, hasForm ? formParams : bodyParam, function (value) {
+          return _this3.isFileParam(value);
+        });
+        if (validationError) return Promise.reject(validationError);
+      }
       var url = this.buildUrl(path, pathParams, apiBasePath);
       var request = (0, _superagent["default"])(httpMethod, url);
       if (this.plugins !== null) {
@@ -489,23 +509,35 @@ var ApiClient = /*#__PURE__*/function () {
           request.withCredentials();
         }
       }
-      request.end(function (error, response) {
-        if (callback) {
-          var data = null;
-          if (!error) {
+      return new Promise(function (resolve, reject) {
+        request.end(function (error, response) {
+          if (error) {
+            var err = {};
+            if (response) {
+              err.status = response.status;
+              err.statusText = response.statusText;
+              err.body = response.body;
+              err.response = responseInfo(response);
+            }
+            delete error.response;
+            err.error = error;
+            reject(err);
+          } else {
             try {
-              data = _this3.deserialize(response, returnType);
+              var data = _this3.deserialize(response, returnType);
               if (_this3.enableCookies && typeof window === 'undefined') {
                 _this3.agent._saveCookies(response);
               }
+              resolve({
+                data: data,
+                response: responseInfo(response)
+              });
             } catch (err) {
-              error = err;
+              reject(err);
             }
           }
-          callback(error, data, response);
-        }
+        });
       });
-      return request;
     }
 
     /**
@@ -522,8 +554,11 @@ var ApiClient = /*#__PURE__*/function () {
       */
     function hostSettings() {
       return [{
-        'url': "https://sync.api.docspring.com/api/v1",
-        'description': "No description provided"
+        'url': "https://sync.api.docspring.com/api/v2",
+        'description': "US region"
+      }, {
+        'url': "https://sync.api-eu.docspring.com/api/v2",
+        'description': "EU region"
       }];
     }
   }, {