docspring 4.1.0 → 4.2.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

package/README.md

@@ -9,7 +9,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.2.0. 
 
 ## Install and configure
 
@@ -99,6 +99,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 +120,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 |
@@ -179,6 +181,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

@@ -38,7 +38,7 @@ function responseInfo(response) {
 
 /**
 * @module ApiClient
-* @version 4.1.0
+* @version 4.2.0
 */
 
 /**
@@ -88,7 +88,7 @@ var ApiClient = /*#__PURE__*/function () {
             * @default {}
             */
     this.defaultHeaders = {
-      'User-Agent': 'docspring-javascript-4.1.0'
+      'User-Agent': 'docspring-javascript-4.2.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"],
@@ -629,7 +629,7 @@ var _default = exports["default"] = {
                   },
                   "email": {
                     "type": ["string", "null"],
-                    "maxLength": 255
+                    "maxLength": 254
                   },
                   "fields": {
                     "type": "array",
@@ -814,7 +814,7 @@ var _default = exports["default"] = {
             "name": {
               "type": "string",
               "minLength": 1,
-              "maxLength": 255
+              "maxLength": 512
             },
             "description": {
               "type": ["string", "null"]
@@ -1131,6 +1131,9 @@ var _default = exports["default"] = {
               },
               "additionalProperties": false
             },
+            "html_escape_data": {
+              "type": "boolean"
+            },
             "cache_id": {
               "type": "string",
               "minLength": 1,
@@ -1173,6 +1176,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 +1211,7 @@ var _default = exports["default"] = {
           "properties": {
             "name": {
               "type": ["string", "null"],
-              "maxLength": 255
+              "maxLength": 512
             },
             "url": {
               "type": "string",
@@ -1350,6 +1379,12 @@ var _default = exports["default"] = {
             "type": "string",
             "enum": ["typescript", "javascript", "ruby", "python", "php", "java", "csharp", "elixir", "go"]
           }
+        },
+        "just_types": {
+          "required": false,
+          "schema": {
+            "type": "boolean"
+          }
         }
       }
     },
@@ -1365,6 +1400,7 @@ var _default = exports["default"] = {
         }
       }
     },
+    "getTemplatePreview": {},
     "getTemplateSchema": {
       "query": {
         "version": {
@@ -1485,6 +1521,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 +1590,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,7 +1874,7 @@ var _default = exports["default"] = {
             "name": {
               "type": "string",
               "minLength": 1,
-              "maxLength": 255
+              "maxLength": 512
             },
             "description": {
               "type": ["string", "null"]
@@ -2158,6 +2220,9 @@ var _default = exports["default"] = {
                 }
               },
               "additionalProperties": false
+            },
+            "html_escape_data": {
+              "type": "boolean"
             }
           },
           "additionalProperties": false
@@ -2592,7 +2657,7 @@ var _default = exports["default"] = {
           "properties": {
             "name": {
               "type": ["string", "null"],
-              "maxLength": 255
+              "maxLength": 512
             },
             "url": {
               "type": "string",
@@ -2678,7 +2743,7 @@ var _default = exports["default"] = {
             "name": {
               "type": "string",
               "minLength": 1,
-              "maxLength": 255
+              "maxLength": 512
             },
             "description": {
               "type": "string"
@@ -2810,7 +2875,7 @@ var _default = exports["default"] = {
                   },
                   "email": {
                     "type": ["string", "null"],
-                    "maxLength": 255
+                    "maxLength": 254
                   },
                   "fields": {
                     "type": "array",
@@ -2897,6 +2962,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 +2985,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);
+  });
+}