assinafy 1.5.0

data/lib/assinafy/resources/field_resource.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+module Assinafy
+  module Resources
+    # Field definitions (reusable input fields) and per-value validation.
+    #
+    # See https://api.assinafy.com.br/v1/docs#field-definition for the
+    # documentation of these endpoints.
+    class FieldResource < BaseResource
+      # Create a field definition.
+      #
+      # @param payload [Hash]
+      # @option payload [String]  :type        required — e.g. `text`, `cpf`, `email` — see {#types}
+      # @option payload [String]  :name        required — display label
+      # @option payload [String]  :regex       optional validation regex (text fields)
+      # @option payload [Boolean] :is_required default `true`
+      # @param account_id_override [String, nil]
+      # @return [Hash] the created field definition (envelope `data` unwrapped)
+      # @see POST /accounts/{accountId}/fields
+      # @example Create a text field
+      #   field = client.fields.create(type: 'text', name: 'audit-field-1780694479')
+      #
+      #   # Request body the SDK sends:
+      #   #   { "type": "text", "name": "audit-field-1780694479" }
+      #
+      #   # => {
+      #   #   "resource"       => "field_definition",
+      #   #   "id"             => "1032009e858cc1f859ccf3a61229",
+      #   #   "name"           => "audit-field-1780694479",
+      #   #   "type"           => "text",
+      #   #   "regex"          => nil,
+      #   #   "is_pre_defined" => false,
+      #   #   "is_active"      => true,
+      #   #   "is_required"    => true,
+      #   #   "is_standard"    => false,
+      #   #   "is_read_only"   => false,
+      #   #   "is_visible"     => true
+      #   # }
+      def create(payload, account_id_override = nil)
+        acc_id = account_id(account_id_override)
+        body   = body_params(require_payload(payload))
+
+        call('Failed to create field definition') do
+          http_post("accounts/#{acc_id}/fields", body)
+        end
+      end
+
+      # List field definitions.
+      #
+      # NOTE: this endpoint does not send pagination headers, so `meta` is always
+      # `nil` here (unlike other list endpoints which return a pagination Hash).
+      #
+      # @param params [Hash] `include_inactive`, `include_standard`
+      # @param account_id_override [String, nil]
+      # @return [Hash{Symbol=>Array,nil}] `{ data: [...], meta: nil }`
+      # @see GET /accounts/{accountId}/fields
+      # @example List including inactive fields
+      #   result = client.fields.list(include_inactive: true)
+      #
+      #   # => {
+      #   #   data: [
+      #   #     {
+      #   #       "id"             => "field-id",
+      #   #       "name"           => "Nome",
+      #   #       "type"           => "personName",
+      #   #       "regex"          => nil,
+      #   #       "is_pre_defined" => true,
+      #   #       "is_active"      => true,
+      #   #       "is_required"    => false,
+      #   #       "is_standard"    => false,
+      #   #       "is_read_only"   => false,
+      #   #       "is_visible"     => true
+      #   #     }
+      #   #     # ... (one Hash per field definition)
+      #   #   ],
+      #   #   meta: nil # this endpoint sends no pagination headers
+      #   # }
+      def list(params = {}, account_id_override = nil)
+        acc_id = account_id(account_id_override)
+
+        call_list('Failed to list field definitions') do
+          http_get("accounts/#{acc_id}/fields", params)
+        end
+      end
+
+      # Fetch a field definition by ID.
+      #
+      # @param field_id            [String]
+      # @param account_id_override [String, nil]
+      # @return [Hash] the field definition (envelope `data` unwrapped)
+      # @see GET /accounts/{accountId}/fields/{field_id}
+      # @example Fetch one field definition
+      #   field = client.fields.get('1032009e858cc1f859ccf3a61229')
+      #
+      #   # => {
+      #   #   "resource"       => "field_definition",
+      #   #   "id"             => "1032009e858cc1f859ccf3a61229",
+      #   #   "name"           => "audit-field-1780694479",
+      #   #   "type"           => "text",
+      #   #   "regex"          => nil,
+      #   #   "is_pre_defined" => false,
+      #   #   "is_active"      => true,
+      #   #   "is_required"    => true,
+      #   #   "is_standard"    => false,
+      #   #   "is_read_only"   => false,
+      #   #   "is_visible"     => true
+      #   # }
+      def get(field_id, account_id_override = nil)
+        acc_id = account_id(account_id_override)
+        fid    = require_id(field_id, 'Field ID')
+
+        call('Failed to fetch field definition') do
+          http_get("accounts/#{acc_id}/fields/#{fid}")
+        end
+      end
+
+      # Update a field definition. The update endpoint accepts only `name`,
+      # `regex`, and `is_active` (unlike {#create}, it does not accept `type`
+      # or `is_required`).
+      #
+      # @param field_id            [String]
+      # @param payload             [Hash]
+      # @option payload [String]  :name      display label
+      # @option payload [String]  :regex     validation regex (text fields)
+      # @option payload [Boolean] :is_active enable/disable the field
+      # @param account_id_override [String, nil]
+      # @return [Hash] the updated field definition (envelope `data` unwrapped)
+      # @see PUT /accounts/{account_id}/fields/{field_id}
+      # @example Rename a field definition
+      #   field = client.fields.update('1032009e858cc1f859ccf3a61229', name: 'New Field Name')
+      #
+      #   # Request body the SDK sends:
+      #   #   { "name": "New Field Name" }
+      #
+      #   # => {
+      #   #   "resource"       => "field_definition",
+      #   #   "id"             => "1032009e858cc1f859ccf3a61229",
+      #   #   "name"           => "New Field Name",
+      #   #   "type"           => "text",
+      #   #   "regex"          => nil,
+      #   #   "is_pre_defined" => false,
+      #   #   "is_active"      => true,
+      #   #   "is_required"    => true,
+      #   #   "is_standard"    => false,
+      #   #   "is_read_only"   => false,
+      #   #   "is_visible"     => true
+      #   # }
+      def update(field_id, payload, account_id_override = nil)
+        acc_id = account_id(account_id_override)
+        fid    = require_id(field_id, 'Field ID')
+        raw    = require_payload(payload)
+        body   = body_params(raw)
+        body['regex'] = nil if (raw.key?(:regex) && raw[:regex].nil?) ||
+                               (raw.key?('regex') && raw['regex'].nil?)
+
+        call('Failed to update field definition') do
+          http_put("accounts/#{acc_id}/fields/#{fid}", body)
+        end
+      end
+
+      # Delete a field definition. Fields used by any document cannot be deleted.
+      #
+      # @param field_id            [String]
+      # @param account_id_override [String, nil]
+      # @return [nil] the API returns `data: []`; the SDK normalizes this to `nil`
+      # @see DELETE /accounts/{account_id}/fields/{field_id}
+      # @example Delete a field definition
+      #   client.fields.delete('1032009e858cc1f859ccf3a61229')
+      #   # => nil
+      def delete(field_id, account_id_override = nil)
+        acc_id = account_id(account_id_override)
+        fid    = require_id(field_id, 'Field ID')
+
+        call_void('Failed to delete field definition') do
+          http_delete("accounts/#{acc_id}/fields/#{fid}")
+        end
+      end
+
+      # Validate a single value against a field definition.
+      #
+      # Either workspace Authorization or signer-access-code authentication
+      # works; pass `signer_access_code:` for the latter.
+      #
+      # @param field_id             [String]
+      # @param value                [Object]
+      # @param account_id_override  [String, nil]
+      # @param signer_access_code   [String, nil]
+      # @return [Hash{String=>Object}] `{ "type" =>, "success" =>, "error_message" => }`
+      # @see POST /accounts/{accountId}/fields/{field_id}/validate
+      # @example Validate a value (workspace auth)
+      #   result = client.fields.validate('1032009e858cc1f859ccf3a61229', 'Some text')
+      #
+      #   # Request body the SDK sends:
+      #   #   { "value": "Some text" }
+      #
+      #   # => { "type" => "text", "success" => true, "error_message" => "" }
+      #
+      # @example Validate as a signer (signer-access-code auth, sent as a query param)
+      #   client.fields.validate('field-id', 'Some text', signer_access_code: 'signer-access-code')
+      #   # => { "type" => "text", "success" => true, "error_message" => "" }
+      def validate(field_id, value, account_id_override = nil, signer_access_code: nil)
+        acc_id = account_id(account_id_override)
+        fid    = require_id(field_id, 'Field ID')
+
+        call('Failed to validate field value') do
+          http_post("accounts/#{acc_id}/fields/#{fid}/validate", body_params(value: value),
+                    signer_access_code: signer_access_code)
+        end
+      end
+
+      # Validate many `{ field_id:, value: }` pairs in a single call.
+      #
+      # @param values               [Array<Hash>]
+      # @param account_id_override  [String, nil]
+      # @param signer_access_code   [String, nil]
+      # @return [Array<Hash>] one validation Hash per input, each carrying its `field_id`
+      # @see POST /accounts/{accountId}/fields/validate-multiple
+      # @example Validate several values at once
+      #   results = client.fields.validate_multiple([
+      #     { field_id: '63488ffb7adf435aba319787', value: '1111111111111' },
+      #     { field_id: '63488ffb0461cebb70775497', value: 'user@example.com' }
+      #   ])
+      #
+      #   # Request body the SDK sends (an array, not an object):
+      #   #   [
+      #   #     { "field_id": "63488ffb7adf435aba319787", "value": "1111111111111" },
+      #   #     { "field_id": "63488ffb0461cebb70775497", "value": "user@example.com" }
+      #   #   ]
+      #
+      #   # => [
+      #   #   { "field_id" => "63488ffb7adf435aba319787", "type" => "cpf",
+      #   #     "success" => false, "error_message" => "Invalid CPF." },
+      #   #   { "field_id" => "63488ffb0461cebb70775497", "type" => "email",
+      #   #     "success" => true, "error_message" => "" }
+      #   # ]
+      def validate_multiple(values, account_id_override = nil, signer_access_code: nil)
+        acc_id = account_id(account_id_override)
+        list   = require_array(values, 'Field values')
+
+        call('Failed to validate field values') do
+          http_post("accounts/#{acc_id}/fields/validate-multiple",
+                    list.map { |item| item.is_a?(Hash) ? body_params(item) : item },
+                    signer_access_code: signer_access_code)
+        end
+      end
+
+      # List the catalog of supported field types.
+      #
+      # @return [Array<Hash{String=>String}>] each entry is `{ "type" =>, "name" => }`
+      # @see GET /field-types
+      # @example List supported field types
+      #   types = client.fields.types
+      #
+      #   # => [
+      #   #   { "type" => "personName",  "name" => "Nome" },
+      #   #   { "type" => "cpf",         "name" => "CPF" },
+      #   #   { "type" => "phoneNumber", "name" => "Número de Telefone" },
+      #   #   { "type" => "postalCode",  "name" => "CEP" },
+      #   #   { "type" => "email",       "name" => "E-mail" },
+      #   #   { "type" => "cnpj",        "name" => "CNPJ" },
+      #   #   { "type" => "companyName", "name" => "Nome da empresa" },
+      #   #   { "type" => "email",       "name" => "E-mail" }, # the live catalog lists "email" twice
+      #   #   { "type" => "text",        "name" => "Texto" },
+      #   #   { "type" => "number",      "name" => "Número" },
+      #   #   { "type" => "date",        "name" => "Data" }
+      #   # ]
+      def types
+        call('Failed to list field types') do
+          http_get('field-types')
+        end
+      end
+    end
+  end
+end

data/lib/assinafy/resources/signer_document_resource.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module Assinafy
+  module Resources
+    # Signer-authenticated views over a signer's assigned documents.
+    #
+    # Authentication varies by endpoint (verified against the live API):
+    #
+    # - {#current}/{#document}, {#sign_multiple}, {#decline_multiple} require the
+    #   `signer-access-code` URL parameter.
+    # - {#list} accepts EITHER the workspace `X-Api-Key` header OR the access
+    #   code; pass `signer_access_code:` only when authenticating as the signer.
+    # - {#download} only needs the document/artifact IDs.
+    #
+    # See https://api.assinafy.com.br/v1/docs#signer for the full
+    # documentation of these endpoints.
+    class SignerDocumentResource < BaseResource
+      # Fetch the signer's "current" document (the one referenced by the access code).
+      #
+      # Resolves the document, assignment, and current signer directly from the
+      # access code; it does not require code verification or data confirmation.
+      # The shape mirrors the signing endpoints, and `assignment.items` is
+      # filtered to only the current signer's items.
+      #
+      # @param signer_id          [String]
+      # @param signer_access_code [String]
+      # @return [Hash] the document (envelope `data` unwrapped)
+      # @see GET /signers/{signer_id}/document
+      # @example Fetch the document tied to an access code
+      #   doc = client.signer_documents.current('signer-id', signer_access_code: 'signer-access-code')
+      #
+      #   # => {
+      #   #   "id"             => "document-id",
+      #   #   "account_id"     => "account-id",
+      #   #   "name"           => "my_document.pdf",
+      #   #   "status"         => "metadata_ready",
+      #   #   "artifacts"      => { "original" => "https://...", "thumbnail" => "https://..." },
+      #   #   "is_closed"      => false,
+      #   #   "signing_url"    => "https://app.assinafy.com.br/sign/doc1",
+      #   #   "decline_reason" => nil,
+      #   #   "declined_by"    => nil,
+      #   #   "created_at"     => "2023-07-21T13:43:17Z",
+      #   #   "updated_at"     => "2023-07-21T13:43:17Z",
+      #   #   "current_signer" => { "id" => "signer-id", "full_name" => "Signer Name",
+      #   #                         "email" => "signer@example.com",
+      #   #                         "verification_method" => "Email", "notification_methods" => ["Email"] },
+      #   #   "assignment"     => { "id" => "1", "method" => "virtual", "items" => [{ ... }] }
+      #   #   # ... (see docs for full shape)
+      #   # }
+      def current(signer_id, signer_access_code:)
+        sid = require_id(signer_id, 'Signer ID')
+
+        call('Failed to fetch signer document') do
+          http_get("signers/#{sid}/document", signer_access_code: signer_access_code)
+        end
+      end
+
+      alias document current
+
+      # List all documents the signer has access to, with pagination metadata.
+      # This endpoint accepts either the workspace `X-Api-Key` header or the
+      # signer access code, so `signer_access_code:` is optional here; when nil
+      # it is omitted from the query and the header auth is used.
+      #
+      # @param signer_id          [String]
+      # @param params             [Hash] documented `page` and `per_page` query parameters
+      # @param signer_access_code [String, nil]
+      # @return [Hash{Symbol=>Array,Hash}] `{ data: [...], meta: { current_page:, per_page:, total:, last_page: } }`
+      # @see GET /signers/{signer_id}/documents
+      # @example List the signer's documents with pagination
+      #   page = client.signer_documents.list('signer-id',
+      #                                       { page: 1, per_page: 15 },
+      #                                       signer_access_code: 'signer-access-code')
+      #
+      #   # => {
+      #   #   data: [
+      #   #     {
+      #   #       "id"         => "document-id",
+      #   #       "account_id" => "account-id",
+      #   #       "name"       => "my_document.pdf",
+      #   #       "status"     => "metadata_ready",
+      #   #       "assignment" => { "id" => "1", "method" => "virtual", "signers" => [{ ... }],
+      #   #                         "items" => [{ ... }], "summary" => { "signer_count" => 2, ... } },
+      #   #       "artifacts"  => { "original" => "https://...", "thumbnail" => "https://..." },
+      #   #       "pages"      => [{ "id" => "...", "number" => 1, "height" => 1, "width" => 1,
+      #   #                          "download_url" => "https://..." }],
+      #   #       "is_closed"  => false
+      #   #       # ... (see docs for full shape)
+      #   #     }
+      #   #   ],
+      #   #   meta: { current_page: 1, per_page: 15, total: 1, last_page: 1 }
+      #   # }
+      def list(signer_id, params = {}, signer_access_code: nil)
+        sid = require_id(signer_id, 'Signer ID')
+
+        call_list('Failed to list signer documents') do
+          http_get("signers/#{sid}/documents", params.merge(signer_access_code: signer_access_code))
+        end
+      end
+
+      # Lightweight search over the signer's documents. Like {#list}, this
+      # accepts either the workspace `X-Api-Key` header or the signer access
+      # code, so `signer_access_code:` is optional.
+      #
+      # @param signer_id          [String]
+      # @param query              [String] free-text search term
+      # @param params             [Hash] optional deployment-specific query parameters
+      # @param signer_access_code [String, nil]
+      # @return [Hash{Symbol=>Array,Hash}] `{ data: [...], meta: {..} | nil }`
+      # @see GET /signers/{signer_id}/documents/search
+      # @example Search the signer's documents
+      #   page = client.signer_documents.search('signer-id', 'contract')
+      #
+      #   # Request: GET /signers/{signer_id}/documents/search?search=contract
+      #   # => {
+      #   #   data: [
+      #   #     { "id" => "document-id", "account_id" => "account-id", "name" => "contract.pdf",
+      #   #       "status" => "pending_signature", "template_id" => nil,
+      #   #       "artifacts" => { "original" => "https://...", "thumbnail" => "https://..." },
+      #   #       "is_closed" => false, "signing_url" => "https://...", "tags" => []
+      #   #       # ... search returns the lightweight document shape (no embedded assignment)
+      #   #     }
+      #   #   ],
+      #   #   meta: nil
+      #   # }
+      def search(signer_id, query, params = {}, signer_access_code: nil)
+        sid = require_id(signer_id, 'Signer ID')
+
+        call_list('Failed to search signer documents') do
+          http_get("signers/#{sid}/documents/search",
+                   params.merge(search: query, signer_access_code: signer_access_code))
+        end
+      end
+
+      # Sign multiple virtual-method documents in a single call.
+      #
+      # Each document must be prepared for the "virtual" signature method.
+      #
+      # @param document_ids       [Array<String>]
+      # @param signer_access_code [String]
+      # @return [Array] empty array on success (envelope `data` unwrapped)
+      # @see PUT /signers/documents/sign-multiple
+      # @example Sign two documents at once
+      #   client.signer_documents.sign_multiple(%w[document-1 document-2],
+      #                                             signer_access_code: 'signer-access-code')
+      #
+      #   # Request body the SDK sends:
+      #   #   { "document_ids": ["document-1", "document-2"] }
+      #
+      #   # => []
+      def sign_multiple(document_ids, signer_access_code:)
+        ids = require_array(document_ids, 'Document IDs')
+
+        call('Failed to sign documents') do
+          http_put('signers/documents/sign-multiple',
+                   body_params(document_ids: ids),
+                   signer_access_code: signer_access_code)
+        end
+      end
+
+      # Decline multiple documents in a single call.
+      #
+      # @param document_ids       [Array<String>]
+      # @param decline_reason     [String]
+      # @param signer_access_code [String]
+      # @return [Array] empty array on success (envelope `data` unwrapped)
+      # @see PUT /signers/documents/decline-multiple
+      # @example Decline two documents with a reason
+      #   client.signer_documents.decline_multiple(%w[document-1 document-2],
+      #                                            decline_reason: 'Unfavorable terms.',
+      #                                            signer_access_code: 'signer-access-code')
+      #
+      #   # Request body the SDK sends:
+      #   #   { "document_ids": ["document-1", "document-2"], "decline_reason": "Unfavorable terms." }
+      #
+      #   # => []
+      def decline_multiple(document_ids, decline_reason:, signer_access_code:)
+        ids    = require_array(document_ids, 'Document IDs')
+        reason = require_present(decline_reason, 'Decline reason')
+
+        call('Failed to decline documents') do
+          http_put('signers/documents/decline-multiple',
+                   body_params(document_ids: ids, decline_reason: reason),
+                   signer_access_code: signer_access_code)
+        end
+      end
+
+      # Download an artifact for one of the signer's documents.
+      #
+      # This endpoint is public (no auth required) — only the document and
+      # artifact IDs are needed — so `signer_access_code:` is optional and
+      # omitted from the query when nil.
+      #
+      # @param signer_id          [String]
+      # @param document_id        [String]
+      # @param artifact_name      [String] `original`, `certificated`, `certificate-page`, `pades`, or
+      #   `bundle`
+      # @param signer_access_code [String, nil] optional
+      # @return [String] binary file body (ASCII-8BIT), e.g. the raw PDF bytes
+      # @see GET /signers/{signer_id}/documents/{document_id}/download/{artifact_name}
+      # @example Download the original PDF and write it to disk (no access code needed)
+      #   pdf = client.signer_documents.download('signer-id', 'document-id', 'original')
+      #
+      #   # Response is the raw artifact body (Content-Type: application/pdf):
+      #   #   => "%PDF-1.7\n..." (binary string)
+      #   File.binwrite('document.pdf', pdf)
+      def download(signer_id, document_id, artifact_name = 'certificated', signer_access_code: nil)
+        sid = require_id(signer_id, 'Signer ID')
+        did = require_id(document_id, 'Document ID')
+        art = require_id(artifact_name, 'Artifact name')
+        unless DocumentResource::ARTIFACT_TYPES.include?(art)
+          raise ValidationError.new('Invalid artifact type', { artifact_name: artifact_name })
+        end
+
+        call_binary('Failed to download signer document') do
+          http_get("signers/#{sid}/documents/#{did}/download/#{art}",
+                   signer_access_code: signer_access_code)
+        end
+      end
+    end
+  end
+end