docspring 4.1.0 → 4.3.0

package/AGENTS.md

@@ -69,8 +69,9 @@ keeps it.
   (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/).
+  webhook's signing secret, where `t` must be within 5 minutes
+  (https://docspring.com/docs/webhooks/verifying-signatures/). Pass the raw body exactly as received, not parsed JSON,
+  to `verifyWebhookSignature(payload, signatureHeader, secret)` (exported by the package), which returns true or false.
 - No webhook is sent when a submission starts waiting for credits.
 
 ## Signature requests
@@ -89,5 +90,5 @@ keeps it.
 
 - 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.
+  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. An enum value added after this release comes
+  back as the API sent it: handle values you don't recognize.

package/README.md

@@ -1,7 +1,8 @@
 # DocSpring JavaScript SDK
 
 The official JavaScript client for the [DocSpring API](https://docspring.com/docs/api/). DocSpring fills PDF
-templates with your data, generates PDFs from HTML templates, combines PDFs and collects e-signatures.
+forms with your data, generates PDFs and Word documents from HTML and Word templates, combines PDFs and collects
+e-signatures.
 
 [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)
@@ -9,7 +10,7 @@ templates with your data, generates PDFs from HTML templates, combines PDFs and
 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. 
+Version 4.3.0. 
 
 ## Install and configure
 
@@ -99,6 +100,7 @@ JavaScript code for every method.
 | [`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 |
+| [`createTemplatePreview`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#createtemplatepreview) | Preview a template with data |
 | [`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 |
@@ -119,6 +121,7 @@ JavaScript code for every method.
 | [`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 |
+| [`getTemplatePreview`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#gettemplatepreview) | Get a template preview |
 | [`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 |
 | [`listCombinedPdfs`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#listcombinedpdfs) | List combined PDFs |
@@ -139,11 +142,11 @@ JavaScript code for every method.
 | [`testAuthentication`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#testauthentication) | Test authentication |
 | [`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 |
+| [`updateTemplateDocument`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#updatetemplatedocument) | Replace a template's document |
 | [`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 |
+| [`uploadTemplate`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#uploadtemplate) | Create a template from an uploaded PDF or Word document |
+| [`uploadTemplateDocument`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#uploadtemplatedocument) | Replace a template's document with an uploaded file |
 | [`validateSubmission`](https://github.com/DocSpring/docspring-javascript/blob/main/docs/Client.md#validatesubmission) | Check a submission without creating it |
 
 ## Errors
@@ -161,7 +164,7 @@ existing code, such as removing or renaming a field, go in a new API version
 responses that are newer than it is:
 
 - 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.
+- An enum value added to the API after this release comes back as the API sent it: 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.
@@ -179,6 +182,7 @@ 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.
+- `verifyWebhookSignature(payload, signatureHeader, secret)` checks a webhook request's `X-DocSpring-Signature` header, with a `{ tolerance, now }` options object.
 
 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

package/dist/ApiClient.js

@@ -14,7 +14,7 @@ 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.
+ * Use DocSpring's API to fill PDF forms, generate PDFs and Word documents from HTML or Word templates, merge PDFs, and request legally binding e-signatures.
  *
  * The version of the OpenAPI document: v2
  * 
@@ -38,7 +38,7 @@ function responseInfo(response) {
 
 /**
 * @module ApiClient
-* @version 4.1.0
+* @version 4.3.0
 */
 
 /**
@@ -88,7 +88,7 @@ var ApiClient = /*#__PURE__*/function () {
             * @default {}
             */
     this.defaultHeaders = {
-      'User-Agent': 'docspring-javascript-4.1.0'
+      'User-Agent': 'docspring-javascript-4.3.0'
     };
 
     /**

package/dist/RequestSchemas.js

@@ -392,7 +392,7 @@ var _default = exports["default"] = {
             "name": {
               "type": "string",
               "minLength": 1,
-              "maxLength": 255
+              "maxLength": 512
             },
             "parent_folder_id": {
               "type": ["string", "null"],
@@ -597,7 +597,7 @@ var _default = exports["default"] = {
               "uniqueItems": true,
               "items": {
                 "type": "string",
-                "enum": ["pdf", "png"]
+                "enum": ["pdf", "docx", "odt", "png"]
               }
             },
             "expires_in": {
@@ -629,7 +629,7 @@ var _default = exports["default"] = {
                   },
                   "email": {
                     "type": ["string", "null"],
-                    "maxLength": 255
+                    "maxLength": 254
                   },
                   "fields": {
                     "type": "array",
@@ -726,7 +726,7 @@ var _default = exports["default"] = {
               "uniqueItems": true,
               "items": {
                 "type": "string",
-                "enum": ["pdf", "png"]
+                "enum": ["pdf", "docx", "odt", "png"]
               }
             },
             "submissions": {
@@ -758,7 +758,7 @@ var _default = exports["default"] = {
                     "uniqueItems": true,
                     "items": {
                       "type": "string",
-                      "enum": ["pdf", "png"]
+                      "enum": ["pdf", "docx", "odt", "png"]
                     }
                   },
                   "expires_in": {
@@ -814,14 +814,18 @@ var _default = exports["default"] = {
             "name": {
               "type": "string",
               "minLength": 1,
-              "maxLength": 255
+              "maxLength": 512
             },
             "description": {
               "type": ["string", "null"]
             },
             "template_type": {
               "type": "string",
-              "enum": ["pdf", "html"]
+              "enum": ["pdf", "html", "docx"]
+            },
+            "output_format": {
+              "type": "string",
+              "enum": ["pdf", "docx", "odt"]
             },
             "parent_folder_id": {
               "type": ["string", "null"],
@@ -1131,6 +1135,9 @@ var _default = exports["default"] = {
               },
               "additionalProperties": false
             },
+            "html_escape_data": {
+              "type": "boolean"
+            },
             "cache_id": {
               "type": "string",
               "minLength": 1,
@@ -1173,6 +1180,32 @@ var _default = exports["default"] = {
         }
       }
     },
+    "createTemplatePreview": {
+      "query": {
+        "version": {
+          "required": false,
+          "schema": {
+            "type": "string",
+            "pattern": "^(\\d+(\\.\\d+(\\.\\d+)?)?|latest|draft)$",
+            "x-pattern-message": "must be a version like 1.2.3 or 1, or latest or draft"
+          }
+        }
+      },
+      "body": {
+        "mediaType": "application/json",
+        "required": true,
+        "schema": {
+          "type": "object",
+          "required": ["data"],
+          "properties": {
+            "data": {
+              "type": "object"
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
     "createWebhook": {
       "body": {
         "mediaType": "application/json",
@@ -1182,7 +1215,7 @@ var _default = exports["default"] = {
           "properties": {
             "name": {
               "type": ["string", "null"],
-              "maxLength": 255
+              "maxLength": 512
             },
             "url": {
               "type": "string",
@@ -1285,7 +1318,7 @@ var _default = exports["default"] = {
               "uniqueItems": true,
               "items": {
                 "type": "string",
-                "enum": ["png"]
+                "enum": ["pdf", "docx", "odt", "png"]
               }
             }
           },
@@ -1348,7 +1381,13 @@ var _default = exports["default"] = {
           "required": true,
           "schema": {
             "type": "string",
-            "enum": ["typescript", "javascript", "ruby", "python", "php", "java", "csharp", "elixir", "go"]
+            "enum": ["typescript", "javascript", "ruby", "python", "php", "java", "csharp", "elixir", "go", "rust"]
+          }
+        },
+        "just_types": {
+          "required": false,
+          "schema": {
+            "type": "boolean"
           }
         }
       }
@@ -1365,6 +1404,7 @@ var _default = exports["default"] = {
         }
       }
     },
+    "getTemplatePreview": {},
     "getTemplateSchema": {
       "query": {
         "version": {
@@ -1485,6 +1525,19 @@ var _default = exports["default"] = {
           "schema": {
             "type": "string"
           }
+        },
+        "state": {
+          "required": false,
+          "schema": {
+            "type": "string",
+            "enum": ["pending", "processed", "invalid_data", "error", "image_download_failed", "image_processing_failed", "waiting_for_signature_requests", "syntax_error", "insufficient_credits", "account_suspended", "license_revoked", "accidental", "declined"]
+          }
+        },
+        "include_files": {
+          "required": false,
+          "schema": {
+            "type": "boolean"
+          }
         }
       }
     },
@@ -1541,6 +1594,19 @@ var _default = exports["default"] = {
           "schema": {
             "type": "string"
           }
+        },
+        "state": {
+          "required": false,
+          "schema": {
+            "type": "string",
+            "enum": ["pending", "processed", "invalid_data", "error", "image_download_failed", "image_processing_failed", "waiting_for_signature_requests", "syntax_error", "insufficient_credits", "account_suspended", "license_revoked", "accidental", "declined"]
+          }
+        },
+        "include_files": {
+          "required": false,
+          "schema": {
+            "type": "boolean"
+          }
         }
       }
     },
@@ -1812,11 +1878,15 @@ var _default = exports["default"] = {
             "name": {
               "type": "string",
               "minLength": 1,
-              "maxLength": 255
+              "maxLength": 512
             },
             "description": {
               "type": ["string", "null"]
             },
+            "output_format": {
+              "type": "string",
+              "enum": ["pdf", "docx", "odt"]
+            },
             "parent_folder_id": {
               "type": ["string", "null"],
               "minLength": 1
@@ -2158,6 +2228,9 @@ var _default = exports["default"] = {
                 }
               },
               "additionalProperties": false
+            },
+            "html_escape_data": {
+              "type": "boolean"
             }
           },
           "additionalProperties": false
@@ -2592,7 +2665,7 @@ var _default = exports["default"] = {
           "properties": {
             "name": {
               "type": ["string", "null"],
-              "maxLength": 255
+              "maxLength": 512
             },
             "url": {
               "type": "string",
@@ -2678,7 +2751,7 @@ var _default = exports["default"] = {
             "name": {
               "type": "string",
               "minLength": 1,
-              "maxLength": 255
+              "maxLength": 512
             },
             "description": {
               "type": "string"
@@ -2705,6 +2778,10 @@ var _default = exports["default"] = {
             "field_logic": {
               "type": "string",
               "enum": ["ai", "none"]
+            },
+            "output_format": {
+              "type": "string",
+              "enum": ["pdf", "docx", "odt"]
             }
           },
           "additionalProperties": false
@@ -2778,7 +2855,7 @@ var _default = exports["default"] = {
               "uniqueItems": true,
               "items": {
                 "type": "string",
-                "enum": ["pdf", "png"]
+                "enum": ["pdf", "docx", "odt", "png"]
               }
             },
             "expires_in": {
@@ -2810,7 +2887,7 @@ var _default = exports["default"] = {
                   },
                   "email": {
                     "type": ["string", "null"],
-                    "maxLength": 255
+                    "maxLength": 254
                   },
                   "fields": {
                     "type": "array",
@@ -2897,6 +2974,7 @@ var _default = exports["default"] = {
     "GET /templates/{template_id}/fields": "listTemplateFields",
     "GET /templates/{template_id}/model_code": "getTemplateModelCode",
     "GET /templates/{template_id}/page_images": "getTemplatePageImages",
+    "GET /templates/{template_id}/previews/{preview_id}": "getTemplatePreview",
     "GET /templates/{template_id}/schema": "getTemplateSchema",
     "GET /templates/{template_id}/submissions": "listTemplateSubmissions",
     "GET /uploads/presign": "getPresignUrl",
@@ -2919,6 +2997,7 @@ var _default = exports["default"] = {
     "POST /templates/{template_id}/fields/remove": "removeTemplateFields",
     "POST /templates/{template_id}/fields/reorder": "reorderTemplateFields",
     "POST /templates/{template_id}/move": "moveTemplate",
+    "POST /templates/{template_id}/previews": "createTemplatePreview",
     "POST /templates/{template_id}/publish_version": "publishTemplateVersion",
     "POST /templates/{template_id}/restore_version": "restoreTemplateVersion",
     "POST /templates/{template_id}/submissions": "createSubmission",

package/dist/WebhookSignature.js

@@ -0,0 +1,86 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.WEBHOOK_SIGNATURE_TOLERANCE = void 0;
+exports.verifyWebhookSignature = verifyWebhookSignature;
+var _crypto = _interopRequireDefault(require("crypto"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { "default": e }; }
+function _slicedToArray(r, e) { return _arrayWithHoles(r) || _iterableToArrayLimit(r, e) || _unsupportedIterableToArray(r, e) || _nonIterableRest(); }
+function _nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+function _unsupportedIterableToArray(r, a) { if (r) { if ("string" == typeof r) return _arrayLikeToArray(r, a); var t = {}.toString.call(r).slice(8, -1); return "Object" === t && r.constructor && (t = r.constructor.name), "Map" === t || "Set" === t ? Array.from(r) : "Arguments" === t || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t) ? _arrayLikeToArray(r, a) : void 0; } }
+function _arrayLikeToArray(r, a) { (null == a || a > r.length) && (a = r.length); for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e]; return n; }
+function _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (null != t) { var e, n, i, u, a = [], f = !0, o = !1; try { if (i = (t = t.call(r)).next, 0 === l) { if (Object(t) !== t) return; f = !1; } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0); } catch (r) { o = !0, n = r; } finally { try { if (!f && null != t["return"] && (u = t["return"](), Object(u) !== u)) return; } finally { if (o) throw n; } } return a; } }
+function _arrayWithHoles(r) { if (Array.isArray(r)) return r; }
+/**
+ * Checks webhook requests' X-DocSpring-Signature header (https://docspring.com/docs/webhooks/verifying-signatures/).
+ * @module WebhookSignature
+ */
+
+/**
+ * The number of seconds a webhook request's signature stays valid (verifyWebhookSignature)
+ * @type {Number}
+ */
+var WEBHOOK_SIGNATURE_TOLERANCE = exports.WEBHOOK_SIGNATURE_TOLERANCE = 300;
+
+/**
+ * Checks a webhook request's X-DocSpring-Signature header. Returns true when one of its v1 signatures is the
+ * HMAC-SHA256 of "{t}.{payload}" with the webhook's secret, and its timestamp t is at most `tolerance` seconds from
+ * `now`. Returns false for anything else, including a missing or malformed header.
+ * @param {String|Buffer} payload The request body exactly as it was received (Express: express.raw()), not parsed JSON.
+ * @param {String} signatureHeader The X-DocSpring-Signature header.
+ * @param {String} secret The webhook's signing secret.
+ * @param {Object} [options]
+ * @param {Number} [options.tolerance=300] How many seconds old (or early) the timestamp can be. 5 minutes by default.
+ * @param {Number} [options.now] The current Unix time in seconds, for tests. The system clock by default.
+ * @returns {Boolean}
+ */
+function verifyWebhookSignature(payload, signatureHeader, secret) {
+  var _ref = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : {},
+    _ref$tolerance = _ref.tolerance,
+    tolerance = _ref$tolerance === void 0 ? WEBHOOK_SIGNATURE_TOLERANCE : _ref$tolerance,
+    now = _ref.now;
+  var body;
+  if (typeof payload === 'string') {
+    body = Buffer.from(payload, 'utf8');
+  } else if (payload instanceof Uint8Array) {
+    body = Buffer.from(payload);
+  } else {
+    return false;
+  }
+  if (typeof signatureHeader !== 'string' || typeof secret !== 'string' || secret === '') return false;
+  var parts = signatureHeader.split(',').map(function (part) {
+    var trimmed = part.trim();
+    var separator = trimmed.indexOf('=');
+    return separator === -1 ? [trimmed, ''] : [trimmed.slice(0, separator), trimmed.slice(separator + 1)];
+  });
+  var timestampPart = parts.find(function (_ref2) {
+    var _ref3 = _slicedToArray(_ref2, 1),
+      key = _ref3[0];
+    return key === 't';
+  });
+  var signatures = parts.filter(function (_ref4) {
+    var _ref5 = _slicedToArray(_ref4, 2),
+      key = _ref5[0],
+      value = _ref5[1];
+    return key === 'v1' && value !== '';
+  }).map(function (_ref6) {
+    var _ref7 = _slicedToArray(_ref6, 2),
+      value = _ref7[1];
+    return value;
+  });
+  if (!timestampPart || !/^[0-9]+$/.test(timestampPart[1]) || signatures.length === 0) return false;
+  var timestamp = timestampPart[1];
+  var current = now === undefined || now === null ? Math.floor(Date.now() / 1000) : Number(now);
+  if (Math.abs(current - Number(timestamp)) > tolerance) return false;
+  var hmac = _crypto["default"].createHmac('sha256', secret);
+  hmac.update("".concat(timestamp, "."), 'utf8');
+  hmac.update(body);
+  var expected = Buffer.from(hmac.digest('hex'), 'utf8');
+  // Constant time, so a timing attack can't find a valid signature byte by byte
+  return signatures.some(function (signature) {
+    var actual = Buffer.from(signature, 'utf8');
+    return actual.length === expected.length && _crypto["default"].timingSafeEqual(actual, expected);
+  });
+}