docspring 4.0.0 → 4.2.0

data/lib/docspring/models/create_template_request.rb

@@ -49,7 +49,7 @@ module DocSpring
     # Generate PDFs whose text and check fields stay fillable ("Generate Editable PDFs"). A submission's `editable` overrides it.
     attr_accessor :editable_submissions
 
-    # The sites where the template's signature requests, forms and embedded template editor can be loaded: a host such as `app.example.com`, with an optional leading wildcard (`*.example.com`), port (`localhost:3000`) or scheme (`https://app.example.com`; without one, `http` and `https` both work). When it's empty, live signature requests don't load on any site, and the embedded template editor loads on every site.
+    # The sites that can embed the template's live signature requests and its embedded template editor: a host such as `app.example.com`, with an optional leading wildcard (`*.example.com`), port (`localhost:3000`) or scheme (`https://app.example.com`; without one, `http` and `https` both work). Browsers open a live signature request in a frame only on these sites (and DocSpring's), so with an empty list it can't be embedded anywhere; a test signature request can be embedded on any site. The embedded template editor loads only for a page on one of these sites (by its Referer or Origin header), and on any site when the list is empty. Forms embedded on a page (Visual Forms JS and the simple form) aren't restricted.
     attr_accessor :embed_domains
 
     # Allow the embedded template editor to change sensitive template settings (webhooks, redirect URL, encryption, public access, expiration and so on).
@@ -100,6 +100,12 @@ module DocSpring
     # The template's conditional logic rules. Setting them replaces all of the rules.
     attr_accessor :field_dependencies
 
+    # The field names that people using the embedded template editor choose from, each with the data type and settings a field gets when it's given that name. Setting it replaces the whole list; an empty list turns them off.
+    attr_accessor :predefined_fields
+
+    # Sample submission data that sets `predefined_fields`: each value becomes a predefined field, with a type that fits it (`string`, `number`, `boolean`, `date`, `email` or `url`) and `required_in_template` true. Nested objects and arrays become names with `/`, such as `customer/email`. Without `predefined_fields` in the same request, it replaces them; with them, it adds to them and sets the types of the ones it has values for.
+    attr_accessor :predefined_fields_sample_data
+
     # The HTML of an HTML template, as a Liquid template. Null for PDF templates.
     attr_accessor :html
 
@@ -115,10 +121,19 @@ module DocSpring
     # Null resets the options to their defaults.
     attr_accessor :html_engine_options
 
-    # A PDF template's document: the `fields.key` of a file you uploaded with the presigned upload (GET /uploads/presign). Required for a PDF template. To upload the PDF with the request, use POST /templates/upload.
+    # Whether an HTML template HTML-escapes the values it prints. When true, `{{ value }}` prints a value as text, so a `<` or `&` in it is printed as that character, and `{{ value | raw }}` prints a value as HTML. New HTML templates default to true. Templates created before October 2026, or with API v1, default to false, which prints every value as HTML. Null for PDF templates.
+    attr_accessor :html_escape_data
+
+    # A PDF template's document: the `fields.key` of a file you uploaded with the presigned upload (GET /uploads/presign). A PDF template needs one of `cache_id`, `document_url` and `document_base64`. To upload the PDF with the request, use POST /templates/upload.
     attr_accessor :cache_id
 
-    # The PDF's file name, for a `cache_id` (presigned uploads don't send one).
+    # An https:// link to the template's PDF (up to 100 MB), instead of `cache_id`. DocSpring downloads it after responding, following redirects to other https:// links: the template's `document.state` is `downloading` until then (sync.api hosts wait for it). If it can't be downloaded, the state is `download_failed` and `document.error_message` says why.
+    attr_accessor :document_url
+
+    # The template's PDF, encoded as base64 (a `data:` URI works too), instead of `cache_id`. Up to 7 MB before it's encoded: send a larger file with `cache_id` or `document_url`.
+    attr_accessor :document_base64
+
+    # The PDF's file name, for a `cache_id` (presigned uploads don't send one) or `document_base64`. A `document_url`'s is the last part of its path unless you set it.
     attr_accessor :filename
 
     # Set up the PDF's fields as DocSpring's "Automatically detect fields" upload option does: import or detect the fields, name them with AI, and set up conditional logic. `field_source`, `field_naming` and `field_logic` choose how. Default false. `document.page_processing_statuses` and `document.field_logic_status` show how it's going, and `document.state` becomes `processed` once every page's fields are set up.
@@ -186,12 +201,17 @@ module DocSpring
         :'slack_webhook_url' => :'slack_webhook_url',
         :'defaults' => :'defaults',
         :'field_dependencies' => :'field_dependencies',
+        :'predefined_fields' => :'predefined_fields',
+        :'predefined_fields_sample_data' => :'predefined_fields_sample_data',
         :'html' => :'html',
         :'scss' => :'scss',
         :'header_html' => :'header_html',
         :'footer_html' => :'footer_html',
         :'html_engine_options' => :'html_engine_options',
+        :'html_escape_data' => :'html_escape_data',
         :'cache_id' => :'cache_id',
+        :'document_url' => :'document_url',
+        :'document_base64' => :'document_base64',
         :'filename' => :'filename',
         :'detect_fields' => :'detect_fields',
         :'field_source' => :'field_source',
@@ -241,12 +261,17 @@ module DocSpring
         :'slack_webhook_url' => :'String',
         :'defaults' => :'TemplateDefaultsInput',
         :'field_dependencies' => :'Array<TemplateFieldDependencyInput>',
+        :'predefined_fields' => :'Array<PredefinedFieldInput>',
+        :'predefined_fields_sample_data' => :'Hash<String, Object>',
         :'html' => :'String',
         :'scss' => :'String',
         :'header_html' => :'String',
         :'footer_html' => :'String',
         :'html_engine_options' => :'HtmlEngineOptionsInput',
+        :'html_escape_data' => :'Boolean',
         :'cache_id' => :'String',
+        :'document_url' => :'String',
+        :'document_base64' => :'String',
         :'filename' => :'String',
         :'detect_fields' => :'Boolean',
         :'field_source' => :'FieldSetupSource',
@@ -263,6 +288,7 @@ module DocSpring
         :'encrypt_pdfs_password',
         :'redirect_url',
         :'slack_webhook_url',
+        :'predefined_fields_sample_data',
         :'html',
         :'scss',
         :'header_html',
@@ -415,6 +441,18 @@ module DocSpring
         end
       end
 
+      if attributes.key?(:'predefined_fields')
+        if (value = attributes[:'predefined_fields']).is_a?(Array)
+          self.predefined_fields = value
+        end
+      end
+
+      if attributes.key?(:'predefined_fields_sample_data')
+        if (value = attributes[:'predefined_fields_sample_data']).is_a?(Hash) || value.nil?
+          self.predefined_fields_sample_data = value
+        end
+      end
+
       if attributes.key?(:'html')
         self.html = attributes[:'html']
       end
@@ -435,10 +473,22 @@ module DocSpring
         self.html_engine_options = attributes[:'html_engine_options']
       end
 
+      if attributes.key?(:'html_escape_data')
+        self.html_escape_data = attributes[:'html_escape_data']
+      end
+
       if attributes.key?(:'cache_id')
         self.cache_id = attributes[:'cache_id']
       end
 
+      if attributes.key?(:'document_url')
+        self.document_url = attributes[:'document_url']
+      end
+
+      if attributes.key?(:'document_base64')
+        self.document_base64 = attributes[:'document_base64']
+      end
+
       if attributes.key?(:'filename')
         self.filename = attributes[:'filename']
       end
@@ -523,12 +573,17 @@ module DocSpring
           slack_webhook_url == o.slack_webhook_url &&
           defaults == o.defaults &&
           field_dependencies == o.field_dependencies &&
+          predefined_fields == o.predefined_fields &&
+          predefined_fields_sample_data == o.predefined_fields_sample_data &&
           html == o.html &&
           scss == o.scss &&
           header_html == o.header_html &&
           footer_html == o.footer_html &&
           html_engine_options == o.html_engine_options &&
+          html_escape_data == o.html_escape_data &&
           cache_id == o.cache_id &&
+          document_url == o.document_url &&
+          document_base64 == o.document_base64 &&
           filename == o.filename &&
           detect_fields == o.detect_fields &&
           field_source == o.field_source &&
@@ -545,7 +600,7 @@ module DocSpring
     # Calculates hash code according to all attributes.
     # @return [Integer] Hash code
     def hash
-      [name, description, template_type, parent_folder_id, locked, add_signature_request_submission_id_footers, ai_field_naming_language, allow_additional_properties, allow_skipping_optional_fields, default_form_mode, editable_submissions, embed_domains, embed_edit_allow_settings, embed_edit_allow_versioning, embed_edit_allow_document_replacement, encrypt_pdfs, encrypt_pdfs_password, expire_submissions, expire_after, expiration_interval, merge_audit_trail_pdf, parse_dates_using_template_date_format, public_submissions, public_web_form, redirect_url, slack_webhook_url, defaults, field_dependencies, html, scss, header_html, footer_html, html_engine_options, cache_id, filename, detect_fields, field_source, field_naming, field_logic].hash
+      [name, description, template_type, parent_folder_id, locked, add_signature_request_submission_id_footers, ai_field_naming_language, allow_additional_properties, allow_skipping_optional_fields, default_form_mode, editable_submissions, embed_domains, embed_edit_allow_settings, embed_edit_allow_versioning, embed_edit_allow_document_replacement, encrypt_pdfs, encrypt_pdfs_password, expire_submissions, expire_after, expiration_interval, merge_audit_trail_pdf, parse_dates_using_template_date_format, public_submissions, public_web_form, redirect_url, slack_webhook_url, defaults, field_dependencies, predefined_fields, predefined_fields_sample_data, html, scss, header_html, footer_html, html_engine_options, html_escape_data, cache_id, document_url, document_base64, filename, detect_fields, field_source, field_naming, field_logic].hash
     end
 
     # Builds the object from hash

data/lib/docspring/models/error_code.rb

@@ -36,9 +36,11 @@ module DocSpring
     SERVICE_UNAVAILABLE = "service_unavailable".freeze
     UPSTREAM_TIMEOUT = "upstream_timeout".freeze
     POLLING_TIMEOUT = "polling_timeout".freeze
+    IDEMPOTENCY_KEY_IN_USE = "idempotency_key_in_use".freeze
+    IDEMPOTENCY_KEY_REUSED = "idempotency_key_reused".freeze
 
     def self.all_vars
-      @all_vars ||= [INVALID_REQUEST, UNAUTHORIZED, PAYMENT_REQUIRED, INSUFFICIENT_CREDITS, FORBIDDEN, UPGRADE_REQUIRED, ACCOUNT_SUSPENDED, NOT_FOUND, METHOD_NOT_ALLOWED, CONFLICT, GONE, REQUEST_TOO_LARGE, UNSUPPORTED_MEDIA_TYPE, VALIDATION_FAILED, INVALID_DATA, RATE_LIMITED, INTERNAL_ERROR, BAD_GATEWAY, SERVICE_UNAVAILABLE, UPSTREAM_TIMEOUT, POLLING_TIMEOUT].freeze
+      @all_vars ||= [INVALID_REQUEST, UNAUTHORIZED, PAYMENT_REQUIRED, INSUFFICIENT_CREDITS, FORBIDDEN, UPGRADE_REQUIRED, ACCOUNT_SUSPENDED, NOT_FOUND, METHOD_NOT_ALLOWED, CONFLICT, GONE, REQUEST_TOO_LARGE, UNSUPPORTED_MEDIA_TYPE, VALIDATION_FAILED, INVALID_DATA, RATE_LIMITED, INTERNAL_ERROR, BAD_GATEWAY, SERVICE_UNAVAILABLE, UPSTREAM_TIMEOUT, POLLING_TIMEOUT, IDEMPOTENCY_KEY_IN_USE, IDEMPOTENCY_KEY_REUSED].freeze
     end
 
     # Builds the enum from string

data/lib/docspring/models/error_detail.rb

@@ -25,7 +25,7 @@ module DocSpring
     # A JSON pointer to the value in the request body (RFC 6901). An empty string means the whole body. In a submission's `data_errors`, it points into the request that created the submission.
     attr_accessor :pointer
 
-    # The query parameter the detail is about.
+    # The query parameter or header the detail is about.
     attr_accessor :parameter
 
     # For a batch item that failed validation, the ID of the submission recorded for it.

data/lib/docspring/models/error_info.rb

@@ -16,7 +16,7 @@ require 'time'
 module DocSpring
   # What went wrong.
   class ErrorInfo < ApiModelBase
-    # A machine-readable error code. Clients should handle codes they don't know: new codes can be added. `invalid_data`: a submission's data doesn't match its template's fields. The submission is still recorded. `insufficient_credits` (402): your credit balance can't cover a live PDF. The record was saved and waits for credits in the `insufficient_credits` state: its ID is in `submission_id`, `submission_batch_id` or `combined_pdf_id`. `upgrade_required` (403): your plan doesn't include this, such as more templates or the embedded template editor. `account_suspended` (403): the account is suspended, so it can't create submissions. `polling_timeout`: on a sync.api host, the PDF wasn't ready in time. The record was created and is still being processed: its ID is in `submission_id`, `submission_batch_id`, `combined_pdf_id` or `template_id`. Without one of these IDs, the request itself got no answer in time, and the record may or may not have been created.
+    # A machine-readable error code. Clients should handle codes they don't know: new codes can be added. `invalid_data`: a submission's data doesn't match its template's fields. The submission is still recorded. `insufficient_credits` (402): your credit balance can't cover a live PDF. The record was saved and waits for credits in the `insufficient_credits` state: its ID is in `submission_id`, `submission_batch_id` or `combined_pdf_id`. `upgrade_required` (403): your plan doesn't include this, such as more templates or the embedded template editor. `account_suspended` (403): the account is suspended, so it can't create submissions. `polling_timeout`: on a sync.api host, the PDF wasn't ready in time. The record was created and is still being processed: its ID is in `submission_id`, `submission_batch_id`, `combined_pdf_id` or `template_id`. Without one of these IDs, the request itself got no answer in time, and the record may or may not have been created. `idempotency_key_in_use` (409): a request with the same Idempotency-Key is still being processed. Send the request again in a few seconds; when the first request has already created its record, its ID is in `submission_id`, `submission_batch_id` or `combined_pdf_id`. `idempotency_key_reused` (422): the Idempotency-Key was already used for a different request.
     attr_accessor :code
 
     # A human-readable explanation, safe to show to developers.
@@ -28,13 +28,13 @@ module DocSpring
     # The ID of the request. Include it when you contact support.
     attr_accessor :request_id
 
-    # When a submission's data fails validation, the submission is still recorded (state `invalid_data`) so you can see it in the dashboard. This is its ID. With `insufficient_credits`, the submission that waits for credits. With `polling_timeout`, the submission that's still being processed.
+    # When a submission's data fails validation, the submission is still recorded (state `invalid_data`) so you can see it in the dashboard. This is its ID. With `insufficient_credits`, the submission that waits for credits. With `polling_timeout` or `idempotency_key_in_use`, the submission that's still being processed.
     attr_accessor :submission_id
 
-    # The ID of the recorded batch, when items in a batch fail validation. With `insufficient_credits`, the batch whose submissions wait for credits. With `polling_timeout`, the batch that's still being processed.
+    # The ID of the recorded batch, when items in a batch fail validation. With `insufficient_credits`, the batch whose submissions wait for credits. With `polling_timeout` or `idempotency_key_in_use`, the batch that's still being processed.
     attr_accessor :submission_batch_id
 
-    # With `insufficient_credits`, the combined PDF that waits for credits. With `polling_timeout`, the combined PDF that's still being processed.
+    # With `insufficient_credits`, the combined PDF that waits for credits. With `polling_timeout` or `idempotency_key_in_use`, the combined PDF that's still being processed.
     attr_accessor :combined_pdf_id
 
     # With `polling_timeout`, the template whose PDF is still being processed.