coss 0.1.0 → 0.2.0

data/lib/coss/sign/documents/types/upload_sign_document_request.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Coss
+  module Sign
+    module Documents
+      module Types
+        class UploadSignDocumentRequest < Internal::Types::Model
+          field :filename, -> { String }, optional: false, nullable: false
+
+          field :content, -> { String }, optional: false, nullable: false
+        end
+      end
+    end
+  end
+end

data/lib/coss/sign/requests/client.rb

@@ -0,0 +1,409 @@
+# frozen_string_literal: true
+
+module Coss
+  module Sign
+    module Requests
+      class Client
+        # @param client [Coss::Internal::Http::RawClient]
+        #
+        # @return [void]
+        def initialize(client:)
+          @client = client
+        end
+
+        # Signature requests of the API key's environment, newest first. Pass the last `id` as `after` to get the next
+        # page while `has_more` is true.
+        #
+        # @param request_options [Hash]
+        # @param params [Hash]
+        # @option request_options [String] :base_url
+        # @option request_options [Hash{String => Object}] :additional_headers
+        # @option request_options [Hash{String => Object}] :additional_query_parameters
+        # @option request_options [Hash{String => Object}] :additional_body_parameters
+        # @option request_options [Integer] :timeout_in_seconds
+        # @option params [String, nil] :status
+        # @option params [Integer, nil] :limit
+        # @option params [String, nil] :after
+        #
+        # @example
+        #   client.sign.requests.list
+        #
+        # @return [Coss::Types::SignRequestList]
+        def list(request_options: {}, **params)
+          params = Coss::Internal::Types::Utils.normalize_keys(params)
+          query_params = {}
+          query_params["status"] = params[:status] if params.key?(:status)
+          query_params["limit"] = params[:limit] if params.key?(:limit)
+          query_params["after"] = params[:after] if params.key?(:after)
+
+          request = Coss::Internal::JSON::Request.new(
+            base_url: request_options[:base_url],
+            method: "GET",
+            path: "v1/sign/requests",
+            query: query_params,
+            request_options: request_options
+          )
+          begin
+            response = @client.send(request)
+          rescue Net::HTTPRequestTimeout
+            raise Coss::Errors::TimeoutError
+          end
+          code = response.code.to_i
+          if code.between?(200, 299)
+            (response.body.to_s.empty? ? nil : Coss::Types::SignRequestList.load(response.body))
+          else
+            error_class = Coss::Errors::ResponseError.subclass_for_code(code)
+            raise error_class.new(response.body, code: code)
+          end
+        end
+
+        # Asks one or more signers to sign one or more PDFs. Give documents by id (uploaded) or inline, and each
+        # signer's fields by position (`page`, `x`, `y`, `width`, `height` in PDF points from the page's top left) or by
+        # text anchor (`{{signature:signer_1}}`). Every signer needs a `signature` field. Sent at once unless `send` is
+        # `false` (a `draft`). Each signer signs by email (`delivery: "email"`, the default) or in your app
+        # (`"embedded"`).
+        #
+        # @param request_options [Hash]
+        # @param params [Coss::Sign::Requests::Types::CreateSignRequestRequest]
+        # @option request_options [String] :base_url
+        # @option request_options [Hash{String => Object}] :additional_headers
+        # @option request_options [Hash{String => Object}] :additional_query_parameters
+        # @option request_options [Hash{String => Object}] :additional_body_parameters
+        # @option request_options [Integer] :timeout_in_seconds
+        # @option params [String, nil] :idempotency_key
+        #
+        # @example
+        #   client.sign.requests.create(
+        #     idempotency_key: "welcome-user-123",
+        #     title: "Services agreement",
+        #     documents: [{
+        #       document_id: "sdoc_01k7c8m4q2f3e9v6t5r1n0p8yz"
+        #     }],
+        #     signers: [{
+        #       name: "Ada Lovelace",
+        #       email: "ada@example.com",
+        #       fields: [{
+        #         type: "signature",
+        #         anchor: "{{signature:signer_1}}",
+        #         page: 1,
+        #         x: 1.1,
+        #         y: 1.1,
+        #         width: 1.1,
+        #         height: 1.1
+        #       }, {
+        #         type: "date_signed",
+        #         page: 2,
+        #         x: 320,
+        #         y: 640,
+        #         width: 120,
+        #         height: 18
+        #       }]
+        #     }]
+        #   )
+        #
+        # @return [Coss::Types::SignRequest]
+        def create(request_options: {}, **params)
+          params = Coss::Internal::Types::Utils.normalize_keys(params)
+          request_data = Coss::Sign::Requests::Types::CreateSignRequestRequest.new(params).to_h
+          non_body_param_names = %w[Idempotency-Key]
+          body = request_data.except(*non_body_param_names)
+
+          headers = {}
+          headers["Idempotency-Key"] = params[:idempotency_key] if params[:idempotency_key]
+
+          request = Coss::Internal::JSON::Request.new(
+            base_url: request_options[:base_url],
+            method: "POST",
+            path: "v1/sign/requests",
+            headers: headers,
+            body: body,
+            request_options: request_options
+          )
+          begin
+            response = @client.send(request)
+          rescue Net::HTTPRequestTimeout
+            raise Coss::Errors::TimeoutError
+          end
+          code = response.code.to_i
+          if code.between?(200, 299)
+            (response.body.to_s.empty? ? nil : Coss::Types::SignRequest.load(response.body))
+          else
+            error_class = Coss::Errors::ResponseError.subclass_for_code(code)
+            raise error_class.new(response.body, code: code)
+          end
+        end
+
+        # @param request_options [Hash]
+        # @param params [Hash]
+        # @option request_options [String] :base_url
+        # @option request_options [Hash{String => Object}] :additional_headers
+        # @option request_options [Hash{String => Object}] :additional_query_parameters
+        # @option request_options [Hash{String => Object}] :additional_body_parameters
+        # @option request_options [Integer] :timeout_in_seconds
+        # @option params [String] :id
+        #
+        # @example
+        #   client.sign.requests.get(id: "sreq_01k7c8m4q2f3e9v6t5r1n0p8yz")
+        #
+        # @return [Coss::Types::SignRequest]
+        def get(request_options: {}, **params)
+          params = Coss::Internal::Types::Utils.normalize_keys(params)
+          request = Coss::Internal::JSON::Request.new(
+            base_url: request_options[:base_url],
+            method: "GET",
+            path: "v1/sign/requests/#{URI.encode_uri_component(params[:id].to_s)}",
+            request_options: request_options
+          )
+          begin
+            response = @client.send(request)
+          rescue Net::HTTPRequestTimeout
+            raise Coss::Errors::TimeoutError
+          end
+          code = response.code.to_i
+          if code.between?(200, 299)
+            (response.body.to_s.empty? ? nil : Coss::Types::SignRequest.load(response.body))
+          else
+            error_class = Coss::Errors::ResponseError.subclass_for_code(code)
+            raise error_class.new(response.body, code: code)
+          end
+        end
+
+        # Deletes a request that isn't `sent` (cancel it first) with its signers, fields, audit trail, signatures and
+        # signed document, for good. Its documents stay (delete them on their own). Keep the signed document first if
+        # you need it: it is your record.
+        #
+        # @param request_options [Hash]
+        # @param params [Hash]
+        # @option request_options [String] :base_url
+        # @option request_options [Hash{String => Object}] :additional_headers
+        # @option request_options [Hash{String => Object}] :additional_query_parameters
+        # @option request_options [Hash{String => Object}] :additional_body_parameters
+        # @option request_options [Integer] :timeout_in_seconds
+        # @option params [String] :id
+        #
+        # @example
+        #   client.sign.requests.remove(id: "sreq_01k7c8m4q2f3e9v6t5r1n0p8yz")
+        #
+        # @return [Coss::Types::DeletedSignRequest]
+        def remove(request_options: {}, **params)
+          params = Coss::Internal::Types::Utils.normalize_keys(params)
+          request = Coss::Internal::JSON::Request.new(
+            base_url: request_options[:base_url],
+            method: "DELETE",
+            path: "v1/sign/requests/#{URI.encode_uri_component(params[:id].to_s)}",
+            request_options: request_options
+          )
+          begin
+            response = @client.send(request)
+          rescue Net::HTTPRequestTimeout
+            raise Coss::Errors::TimeoutError
+          end
+          code = response.code.to_i
+          if code.between?(200, 299)
+            (response.body.to_s.empty? ? nil : Coss::Types::DeletedSignRequest.load(response.body))
+          else
+            error_class = Coss::Errors::ResponseError.subclass_for_code(code)
+            raise error_class.new(response.body, code: code)
+          end
+        end
+
+        # Sends a `draft`. An already sent request is returned as is.
+        #
+        # @param request_options [Hash]
+        # @param params [Hash]
+        # @option request_options [String] :base_url
+        # @option request_options [Hash{String => Object}] :additional_headers
+        # @option request_options [Hash{String => Object}] :additional_query_parameters
+        # @option request_options [Hash{String => Object}] :additional_body_parameters
+        # @option request_options [Integer] :timeout_in_seconds
+        # @option params [String] :id
+        #
+        # @example
+        #   client.sign.requests.send_(id: "sreq_01k7c8m4q2f3e9v6t5r1n0p8yz")
+        #
+        # @return [Coss::Types::SignRequest]
+        def send_(request_options: {}, **params)
+          params = Coss::Internal::Types::Utils.normalize_keys(params)
+          headers = { "Idempotency-Key" => Coss::Internal::IdempotencyKey.generate }
+          request = Coss::Internal::JSON::Request.new(
+            base_url: request_options[:base_url],
+            method: "POST",
+            path: "v1/sign/requests/#{URI.encode_uri_component(params[:id].to_s)}/send",
+            headers: headers,
+            request_options: request_options
+          )
+          begin
+            response = @client.send(request)
+          rescue Net::HTTPRequestTimeout
+            raise Coss::Errors::TimeoutError
+          end
+          code = response.code.to_i
+          if code.between?(200, 299)
+            (response.body.to_s.empty? ? nil : Coss::Types::SignRequest.load(response.body))
+          else
+            error_class = Coss::Errors::ResponseError.subclass_for_code(code)
+            raise error_class.new(response.body, code: code)
+          end
+        end
+
+        # Cancels a `draft` or `sent` request: its signers can no longer sign. An already canceled request is returned
+        # as is.
+        #
+        # @param request_options [Hash]
+        # @param params [Hash]
+        # @option request_options [String] :base_url
+        # @option request_options [Hash{String => Object}] :additional_headers
+        # @option request_options [Hash{String => Object}] :additional_query_parameters
+        # @option request_options [Hash{String => Object}] :additional_body_parameters
+        # @option request_options [Integer] :timeout_in_seconds
+        # @option params [String] :id
+        #
+        # @example
+        #   client.sign.requests.cancel(id: "sreq_01k7c8m4q2f3e9v6t5r1n0p8yz")
+        #
+        # @return [Coss::Types::SignRequest]
+        def cancel(request_options: {}, **params)
+          params = Coss::Internal::Types::Utils.normalize_keys(params)
+          headers = { "Idempotency-Key" => Coss::Internal::IdempotencyKey.generate }
+          request = Coss::Internal::JSON::Request.new(
+            base_url: request_options[:base_url],
+            method: "POST",
+            path: "v1/sign/requests/#{URI.encode_uri_component(params[:id].to_s)}/cancel",
+            headers: headers,
+            request_options: request_options
+          )
+          begin
+            response = @client.send(request)
+          rescue Net::HTTPRequestTimeout
+            raise Coss::Errors::TimeoutError
+          end
+          code = response.code.to_i
+          if code.between?(200, 299)
+            (response.body.to_s.empty? ? nil : Coss::Types::SignRequest.load(response.body))
+          else
+            error_class = Coss::Errors::ResponseError.subclass_for_code(code)
+            raise error_class.new(response.body, code: code)
+          end
+        end
+
+        # Everything that happened to the request, oldest first: who did it, from which address, the documents' SHA-256
+        # when it mattered, and a hash chain (`previous_hash`, `hash`) that shows the trail is complete and unchanged.
+        #
+        # @param request_options [Hash]
+        # @param params [Hash]
+        # @option request_options [String] :base_url
+        # @option request_options [Hash{String => Object}] :additional_headers
+        # @option request_options [Hash{String => Object}] :additional_query_parameters
+        # @option request_options [Hash{String => Object}] :additional_body_parameters
+        # @option request_options [Integer] :timeout_in_seconds
+        # @option params [String] :id
+        #
+        # @example
+        #   client.sign.requests.audit_trail(id: "sreq_01k7c8m4q2f3e9v6t5r1n0p8yz")
+        #
+        # @return [Coss::Types::SignEventList]
+        def audit_trail(request_options: {}, **params)
+          params = Coss::Internal::Types::Utils.normalize_keys(params)
+          request = Coss::Internal::JSON::Request.new(
+            base_url: request_options[:base_url],
+            method: "GET",
+            path: "v1/sign/requests/#{URI.encode_uri_component(params[:id].to_s)}/audit_trail",
+            request_options: request_options
+          )
+          begin
+            response = @client.send(request)
+          rescue Net::HTTPRequestTimeout
+            raise Coss::Errors::TimeoutError
+          end
+          code = response.code.to_i
+          if code.between?(200, 299)
+            (response.body.to_s.empty? ? nil : Coss::Types::SignEventList.load(response.body))
+          else
+            error_class = Coss::Errors::ResponseError.subclass_for_code(code)
+            raise error_class.new(response.body, code: code)
+          end
+        end
+
+        # Emails a reminder, with a fresh link, to every email signer of a sent request who hasn't signed and whose turn
+        # it is, unless they were emailed in the last hour. Embedded signers are yours to remind. Sent within seconds;
+        # each is a `reminded` event in the audit trail.
+        #
+        # @param request_options [Hash]
+        # @param params [Hash]
+        # @option request_options [String] :base_url
+        # @option request_options [Hash{String => Object}] :additional_headers
+        # @option request_options [Hash{String => Object}] :additional_query_parameters
+        # @option request_options [Hash{String => Object}] :additional_body_parameters
+        # @option request_options [Integer] :timeout_in_seconds
+        # @option params [String] :id
+        #
+        # @example
+        #   client.sign.requests.remind(id: "sreq_01k7c8m4q2f3e9v6t5r1n0p8yz")
+        #
+        # @return [Coss::Types::SignRequest]
+        def remind(request_options: {}, **params)
+          params = Coss::Internal::Types::Utils.normalize_keys(params)
+          headers = { "Idempotency-Key" => Coss::Internal::IdempotencyKey.generate }
+          request = Coss::Internal::JSON::Request.new(
+            base_url: request_options[:base_url],
+            method: "POST",
+            path: "v1/sign/requests/#{URI.encode_uri_component(params[:id].to_s)}/remind",
+            headers: headers,
+            request_options: request_options,
+            max_retries: 0
+          )
+          begin
+            response = @client.send(request)
+          rescue Net::HTTPRequestTimeout
+            raise Coss::Errors::TimeoutError
+          end
+          code = response.code.to_i
+          if code.between?(200, 299)
+            (response.body.to_s.empty? ? nil : Coss::Types::SignRequest.load(response.body))
+          else
+            error_class = Coss::Errors::ResponseError.subclass_for_code(code)
+            raise error_class.new(response.body, code: code)
+          end
+        end
+
+        # The completed request's sealed PDF: every document with the signatures and values filled in, then a
+        # certificate of completion (signers, how they were identified, what they agreed to, the documents' SHA-256 and
+        # the audit trail). coss.com's seal makes any later change visible in PDF viewers. Ready once `signed_document`
+        # is set, which the `sign_request.completed` webhook announces.
+        #
+        # @param request_options [Hash]
+        # @param params [Hash]
+        # @option request_options [String] :base_url
+        # @option request_options [Hash{String => Object}] :additional_headers
+        # @option request_options [Hash{String => Object}] :additional_query_parameters
+        # @option request_options [Hash{String => Object}] :additional_body_parameters
+        # @option request_options [Integer] :timeout_in_seconds
+        # @option params [String] :id
+        #
+        # @example
+        #   client.sign.requests.signed_document(id: "id")
+        #
+        # @return [untyped]
+        def signed_document(request_options: {}, **params)
+          params = Coss::Internal::Types::Utils.normalize_keys(params)
+          request = Coss::Internal::JSON::Request.new(
+            base_url: request_options[:base_url],
+            method: "GET",
+            path: "v1/sign/requests/#{URI.encode_uri_component(params[:id].to_s)}/signed_document",
+            request_options: request_options
+          )
+          begin
+            response = @client.send(request)
+          rescue Net::HTTPRequestTimeout
+            raise Coss::Errors::TimeoutError
+          end
+          code = response.code.to_i
+          return response.body if code.between?(200, 299)
+
+          error_class = Coss::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+    end
+  end
+end

data/lib/coss/sign/requests/types/audit_trail_requests_request.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Coss
+  module Sign
+    module Requests
+      module Types
+        class AuditTrailRequestsRequest < Internal::Types::Model
+          field :id, -> { String }, optional: false, nullable: false
+        end
+      end
+    end
+  end
+end

data/lib/coss/sign/requests/types/cancel_requests_request.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Coss
+  module Sign
+    module Requests
+      module Types
+        class CancelRequestsRequest < Internal::Types::Model
+          field :id, -> { String }, optional: false, nullable: false
+        end
+      end
+    end
+  end
+end

data/lib/coss/sign/requests/types/create_sign_request_request.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Coss
+  module Sign
+    module Requests
+      module Types
+        class CreateSignRequestRequest < Internal::Types::Model
+          field :idempotency_key, -> { String }, optional: true, nullable: false, api_name: "Idempotency-Key"
+
+          field :title, -> { String }, optional: false, nullable: false
+
+          field :message, -> { String }, optional: true, nullable: false
+
+          field :documents, -> { Internal::Types::Array[Coss::Sign::Requests::Types::CreateSignRequestRequestDocumentsItem] }, optional: false, nullable: false
+
+          field :signers, -> { Internal::Types::Array[Coss::Sign::Requests::Types::CreateSignRequestRequestSignersItem] }, optional: false, nullable: false
+
+          field :signing_order, -> { Coss::Sign::Requests::Types::CreateSignRequestRequestSigningOrder }, optional: true, nullable: false
+
+          field :expires_at, -> { String }, optional: true, nullable: false
+
+          field :metadata, -> { Internal::Types::Hash[String, String] }, optional: true, nullable: false
+
+          field :reminder_interval_days, -> { Integer }, optional: true, nullable: false
+
+          field :send_, -> { Internal::Types::Boolean }, optional: true, nullable: false, api_name: "send"
+        end
+      end
+    end
+  end
+end

data/lib/coss/sign/requests/types/create_sign_request_request_documents_item.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Coss
+  module Sign
+    module Requests
+      module Types
+        class CreateSignRequestRequestDocumentsItem < Internal::Types::Model
+          extend Coss::Internal::Types::Union
+
+          member -> { Coss::Sign::Requests::Types::CreateSignRequestRequestDocumentsItemDocumentID }
+
+          member -> { Coss::Sign::Requests::Types::CreateSignRequestRequestDocumentsItemContent }
+        end
+      end
+    end
+  end
+end

data/lib/coss/sign/requests/types/create_sign_request_request_documents_item_content.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Coss
+  module Sign
+    module Requests
+      module Types
+        class CreateSignRequestRequestDocumentsItemContent < Internal::Types::Model
+          field :filename, -> { String }, optional: false, nullable: false
+
+          field :content, -> { String }, optional: false, nullable: false
+        end
+      end
+    end
+  end
+end

data/lib/coss/sign/requests/types/create_sign_request_request_documents_item_document_id.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Coss
+  module Sign
+    module Requests
+      module Types
+        class CreateSignRequestRequestDocumentsItemDocumentID < Internal::Types::Model
+          field :document_id, -> { String }, optional: false, nullable: false
+        end
+      end
+    end
+  end
+end

data/lib/coss/sign/requests/types/create_sign_request_request_signers_item.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Coss
+  module Sign
+    module Requests
+      module Types
+        class CreateSignRequestRequestSignersItem < Internal::Types::Model
+          field :name, -> { String }, optional: false, nullable: false
+
+          field :email, -> { String }, optional: false, nullable: false
+
+          field :delivery, -> { Coss::Sign::Requests::Types::CreateSignRequestRequestSignersItemDelivery }, optional: true, nullable: false
+
+          field :order, -> { Integer }, optional: true, nullable: false
+
+          field :client_ref, -> { String }, optional: true, nullable: false
+
+          field :fields, -> { Internal::Types::Array[Coss::Types::SignFieldInput] }, optional: false, nullable: false
+        end
+      end
+    end
+  end
+end

data/lib/coss/sign/requests/types/create_sign_request_request_signers_item_delivery.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Coss
+  module Sign
+    module Requests
+      module Types
+        module CreateSignRequestRequestSignersItemDelivery
+          extend Coss::Internal::Types::Enum
+
+          EMBEDDED = "embedded"
+          EMAIL = "email"
+        end
+      end
+    end
+  end
+end

data/lib/coss/sign/requests/types/create_sign_request_request_signing_order.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Coss
+  module Sign
+    module Requests
+      module Types
+        module CreateSignRequestRequestSigningOrder
+          extend Coss::Internal::Types::Enum
+
+          PARALLEL = "parallel"
+          SEQUENTIAL = "sequential"
+        end
+      end
+    end
+  end
+end

data/lib/coss/sign/requests/types/get_requests_request.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Coss
+  module Sign
+    module Requests
+      module Types
+        class GetRequestsRequest < Internal::Types::Model
+          field :id, -> { String }, optional: false, nullable: false
+        end
+      end
+    end
+  end
+end

data/lib/coss/sign/requests/types/list_requests_request.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Coss
+  module Sign
+    module Requests
+      module Types
+        class ListRequestsRequest < Internal::Types::Model
+          field :status, -> { String }, optional: true, nullable: false
+
+          field :limit, -> { Integer }, optional: true, nullable: false
+
+          field :after, -> { String }, optional: true, nullable: false
+        end
+      end
+    end
+  end
+end

data/lib/coss/sign/requests/types/remind_requests_request.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Coss
+  module Sign
+    module Requests
+      module Types
+        class RemindRequestsRequest < Internal::Types::Model
+          field :id, -> { String }, optional: false, nullable: false
+        end
+      end
+    end
+  end
+end

data/lib/coss/sign/requests/types/remove_requests_request.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Coss
+  module Sign
+    module Requests
+      module Types
+        class RemoveRequestsRequest < Internal::Types::Model
+          field :id, -> { String }, optional: false, nullable: false
+        end
+      end
+    end
+  end
+end

data/lib/coss/sign/requests/types/send_requests_request.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Coss
+  module Sign
+    module Requests
+      module Types
+        class SendRequestsRequest < Internal::Types::Model
+          field :id, -> { String }, optional: false, nullable: false
+        end
+      end
+    end
+  end
+end