flashpi 0.1.0

data/lib/flashpi/resources/documents.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Flashpi
+  module Resources
+    # Issues one document type. The answer is the document: `processing` right away (202), or,
+    # with `options: { waitForAuthorization: true }`, its outcome once the SRI decides (200),
+    # unless the wait ends first (202 with `processing` or `pending_sri`; follow it with webhooks
+    # or `documents.get`).
+    class DocumentIssuer < Internal::Resource
+      # Seconds the API waits for the SRI in sync mode when `waitTimeoutSeconds` is not sent.
+      DEFAULT_WAIT_SECONDS = 15
+      # Time on top of the sync wait for Flashpi to build, sign and answer.
+      SYNC_MARGIN_SECONDS = 15
+
+      response_methods :create
+
+      # The shortest per-attempt timeout for issuing `body`, in seconds.
+      #
+      # In sync mode (`options.waitForAuthorization`) the API holds the request for up to
+      # `waitTimeoutSeconds` (15 by default) while the SRI decides, so each attempt waits at least
+      # that plus 15 seconds. Otherwise 0: the client's timeout applies.
+      #
+      # @return [Float]
+      def self.sync_timeout_floor(body)
+        settings = member(body, :options)
+        return 0.0 unless member(settings, :waitForAuthorization) == true
+
+        wait = member(settings, :waitTimeoutSeconds)
+        wait = DEFAULT_WAIT_SECONDS unless wait.is_a?(Integer) || (wait.is_a?(Float) && wait.finite?)
+        (wait + SYNC_MARGIN_SECONDS).to_f
+      end
+
+      # @api private
+      def self.member(value, name)
+        return nil unless value.is_a?(Hash)
+
+        value.key?(name) ? value[name] : value[name.to_s]
+      end
+
+      # Issues the document. Retries reuse the same Idempotency-Key, and when a retry finds the
+      # document already created by an earlier attempt, its current state is returned instead of
+      # an error.
+      #
+      # @param body [Hash] the document, with the API's camelCase keys
+      # @return [Hash{Symbol => Object}] the document
+      def create(body, **options)
+        floor = DocumentIssuer.sync_timeout_floor(body)
+        send_request(operation(:post, self.class::PATH, body:, options:, min_timeout: floor, recover_document: true))
+      end
+    end
+
+    # Invoices (facturas).
+    class Invoices < DocumentIssuer
+      PATH = "/v1/invoices"
+    end
+
+    # Credit notes (notas de crédito).
+    class CreditNotes < DocumentIssuer
+      PATH = "/v1/credit-notes"
+    end
+
+    # Debit notes (notas de débito).
+    class DebitNotes < DocumentIssuer
+      PATH = "/v1/debit-notes"
+    end
+
+    # Purchase settlements (liquidaciones de compra).
+    class PurchaseSettlements < DocumentIssuer
+      PATH = "/v1/purchase-settlements"
+    end
+
+    # Waybills (guías de remisión).
+    class Waybills < DocumentIssuer
+      PATH = "/v1/waybills"
+    end
+
+    # Withholding receipts (comprobantes de retención).
+    class Withholdings < DocumentIssuer
+      PATH = "/v1/withholdings"
+    end
+
+    # Every issued document, of any type: search, XML, RIDE (PDF) and email.
+    class Documents < Internal::Resource
+      XML_ACCEPT = "application/xml, application/problem+json"
+      PDF_ACCEPT = "application/pdf, application/problem+json"
+      XML_KINDS = %w[authorized signed unsigned].freeze
+
+      response_methods :list, :get, :xml, :pdf, :send_email
+
+      # Lists documents, newest first, with optional filters.
+      #
+      # @param params [Hash, nil] filters with the API's names (`status`, `issueDateFrom`, ...)
+      # @return [Flashpi::Page]
+      def list(params = nil, **options)
+        paginate(operation(:get, "/v1/documents", query: params, options:))
+      end
+
+      # Retrieves a document with its tax status, SRI messages, RIDE and email state.
+      #
+      # @return [Hash{Symbol => Object}]
+      def get(document_id, **options)
+        send_request(operation(:get, "/v1/documents/{}", document_id, options:))
+      end
+
+      # The document's XML: the authorized one once the SRI authorizes it, otherwise the signed or
+      # unsigned one (see `kind`).
+      #
+      # @return [Hash{Symbol => Object}] `{ xml: String, kind: "authorized" | "signed" | "unsigned" | nil }`
+      def xml(document_id, **options)
+        result = send_call(
+          operation(:get, "/v1/documents/{}/xml", document_id, accept: XML_ACCEPT, response_type: :text, options:)
+        )
+        kind = result.headers["flashpi-xml-kind"]
+        _ = { xml: result.data, kind: XML_KINDS.include?(kind) ? kind : nil }
+      end
+
+      # The RIDE (the printable PDF) of an authorized document, as a binary String. Raises a
+      # ConflictError with code `ride_not_available` while it is still being generated.
+      #
+      # @return [String]
+      def pdf(document_id, **options)
+        send_request(
+          operation(:get, "/v1/documents/{}/pdf", document_id, accept: PDF_ACCEPT, response_type: :bytes, options:)
+        )
+      end
+
+      # Emails the authorized document (RIDE and XML) again to the address of its request. The new
+      # delivery shows in `email.deliveries`; daily limits apply (RateLimitError).
+      #
+      # @return [Hash{Symbol => Object}] the document
+      def send_email(document_id, **options)
+        send_request(operation(:post, "/v1/documents/{}/email", document_id, body: {}, options:))
+      end
+    end
+  end
+end

data/lib/flashpi/resources/events.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Flashpi
+  module Resources
+    # Events: what happened to documents, certificates and email sending, newest first.
+    class Events < Internal::Resource
+      response_methods :list, :get
+
+      # Lists events, optionally by type, issuer, document or certificate.
+      #
+      # @return [Flashpi::Page]
+      def list(params = nil, **options)
+        paginate(operation(:get, "/v1/events", query: params, options:))
+      end
+
+      # Retrieves an event: the same object its webhook delivered.
+      #
+      # @return [Hash{Symbol => Object}] the event
+      def get(event_id, **options)
+        send_request(operation(:get, "/v1/events/{}", event_id, options:))
+      end
+    end
+
+    # The API's own status. It needs no API key.
+    class Status < Internal::Resource
+      response_methods :get
+
+      # Whether Flashpi is operational.
+      #
+      # @return [Hash{Symbol => Object}]
+      def get(**options)
+        send_request(operation(:get, "/v1/status", options:))
+      end
+    end
+  end
+end

data/lib/flashpi/resources/issuer_onboardings.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Flashpi
+  module Resources
+    # Creates an issuer from its .p12: upload the certificate, wait while the onboarding is
+    # `verifying` until it is `ready` (Flashpi reads the holder, RUC and SRI data) or `rejected`,
+    # review the prefill, then complete it.
+    #
+    # Needs an account-scoped API key with read_write access.
+    class IssuerOnboardings < Internal::Resource
+      response_methods :create, :get, :complete
+
+      # Starts an onboarding with a .p12 and its password. It starts `verifying`.
+      #
+      # @param upload [Hash] `{ file: String or IO, password: String, filename: String }`
+      # @return [Hash{Symbol => Object}] the onboarding
+      def create(upload, **options)
+        form = Internal::Multipart.certificate(upload)
+        send_request(operation(:post, "/v1/issuer-onboardings", multipart: form, options:))
+      end
+
+      # Retrieves an onboarding, to follow it while it is `verifying`.
+      #
+      # @return [Hash{Symbol => Object}] the onboarding
+      def get(onboarding_id, **options)
+        send_request(operation(:get, "/v1/issuer-onboardings/{}", onboarding_id, options:))
+      end
+
+      # Completes a `ready` onboarding.
+      #
+      # - For a new RUC, `body` is the issuer to create (as in `issuers.create`): `legalName`,
+      #   `headOfficeAddress` and `taxProfile` are required. Build it from `onboarding[:prefill]`;
+      #   the API does not apply the prefill by itself.
+      # - When `onboarding[:existingIssuer]` is set, `body` can be left out (`{}` is sent): the
+      #   certificate is added to that issuer for both modes (a renewal) and the issuer is left as
+      #   it is.
+      # - Send `ruc` when `onboarding[:rucNeedsConfirmation]` is true.
+      #
+      # @return [Hash{Symbol => Object}] the completed onboarding, with its issuer
+      def complete(onboarding_id, body = nil, **options)
+        send_request(
+          operation(:post, "/v1/issuer-onboardings/{}/complete", onboarding_id, body: body.nil? ? {} : body, options:)
+        )
+      end
+    end
+  end
+end

data/lib/flashpi/resources/issuers.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module Flashpi
+  module Resources
+    # Emission points (the second 3-digit series code) of an establishment.
+    class EmissionPoints < Internal::Resource
+      PATH = "/v1/issuers/{}/establishments/{}/emission-points"
+      ITEM = "/v1/issuers/{}/establishments/{}/emission-points/{}"
+
+      response_methods :create, :list, :get, :delete
+
+      # @return [Hash{Symbol => Object}] the emission point
+      def create(issuer_id, establishment_id, body, **options)
+        send_request(operation(:post, PATH, issuer_id, establishment_id, body:, options:))
+      end
+
+      # Lists the emission points of an establishment, by code.
+      #
+      # @return [Flashpi::Page]
+      def list(issuer_id, establishment_id, params = nil, **options)
+        paginate(operation(:get, PATH, issuer_id, establishment_id, query: params, options:))
+      end
+
+      # @return [Hash{Symbol => Object}] the emission point
+      def get(issuer_id, establishment_id, emission_point_id, **options)
+        send_request(operation(:get, ITEM, issuer_id, establishment_id, emission_point_id, options:))
+      end
+
+      # Deletes an emission point that has no documents.
+      #
+      # @return [nil]
+      def delete(issuer_id, establishment_id, emission_point_id, **options)
+        send_request(
+          operation(:delete, ITEM, issuer_id, establishment_id, emission_point_id, response_type: :none, options:)
+        )
+      end
+    end
+
+    # Establishments (the 3-digit series codes such as `001`) of an issuer.
+    class Establishments < Internal::Resource
+      PATH = "/v1/issuers/{}/establishments"
+      ITEM = "/v1/issuers/{}/establishments/{}"
+
+      response_methods :create, :list, :get, :update, :delete
+
+      # @return [EmissionPoints] the emission points of an establishment
+      attr_reader :emission_points
+
+      def initialize(engine)
+        super
+        @emission_points = EmissionPoints.new(engine)
+      end
+
+      # @return [Hash{Symbol => Object}] the establishment
+      def create(issuer_id, body, **options)
+        send_request(operation(:post, PATH, issuer_id, body:, options:))
+      end
+
+      # Lists the establishments of an issuer, by code.
+      #
+      # @return [Flashpi::Page]
+      def list(issuer_id, params = nil, **options)
+        paginate(operation(:get, PATH, issuer_id, query: params, options:))
+      end
+
+      # @return [Hash{Symbol => Object}] the establishment
+      def get(issuer_id, establishment_id, **options)
+        send_request(operation(:get, ITEM, issuer_id, establishment_id, options:))
+      end
+
+      # Updates an establishment (only the fields sent).
+      #
+      # @return [Hash{Symbol => Object}] the establishment
+      def update(issuer_id, establishment_id, body, **options)
+        send_request(operation(:patch, ITEM, issuer_id, establishment_id, body:, options:))
+      end
+
+      # Deletes an establishment that has no documents, with its emission points.
+      #
+      # @return [nil]
+      def delete(issuer_id, establishment_id, **options)
+        send_request(operation(:delete, ITEM, issuer_id, establishment_id, response_type: :none, options:))
+      end
+    end
+
+    # The .p12 certificates (firmas electrónicas) of an issuer.
+    class Certificates < Internal::Resource
+      PATH = "/v1/issuers/{}/certificates"
+      ITEM = "/v1/issuers/{}/certificates/{}"
+
+      response_methods :upload, :list, :get
+
+      # Uploads a .p12 for the issuer, for the mode of the API key only (test or live). To renew
+      # the certificate of both modes, start an `issuer_onboardings.create` with it instead.
+      #
+      # Flashpi checks it in the background: the certificate starts `processing`, then becomes
+      # `accepted` (event `certificate.verified`, or `certificate.pending` while its revocation
+      # status cannot be checked) or `rejected` (no event: follow it with `get` and read
+      # `rejection`).
+      #
+      # @param upload [Hash] `{ file: String or IO, password: String, filename: String }`
+      # @return [Hash{Symbol => Object}] the certificate
+      def upload(issuer_id, upload, **options)
+        form = Internal::Multipart.certificate(upload)
+        send_request(operation(:post, PATH, issuer_id, multipart: form, options:))
+      end
+
+      # Lists the certificates of an issuer, newest first.
+      #
+      # @return [Flashpi::Page]
+      def list(issuer_id, params = nil, **options)
+        paginate(operation(:get, PATH, issuer_id, query: params, options:))
+      end
+
+      # @return [Hash{Symbol => Object}] the certificate
+      def get(issuer_id, certificate_id, **options)
+        send_request(operation(:get, ITEM, issuer_id, certificate_id, options:))
+      end
+    end
+
+    # The issuers (RUCs) of the account, with their establishments, emission points and .p12
+    # certificates. Needs an account-scoped API key with read_write access, also to read.
+    class Issuers < Internal::Resource
+      PATH = "/v1/issuers"
+      ITEM = "/v1/issuers/{}"
+
+      response_methods :create, :list, :get, :update, :delete
+
+      # @return [Establishments] establishments of an issuer, with their emission points
+      attr_reader :establishments
+      # @return [Certificates] the .p12 certificates of an issuer
+      attr_reader :certificates
+
+      def initialize(engine)
+        super
+        @establishments = Establishments.new(engine)
+        @certificates = Certificates.new(engine)
+      end
+
+      # Creates an issuer. To start from its .p12 instead, see `issuer_onboardings`.
+      #
+      # @return [Hash{Symbol => Object}] the issuer
+      def create(body, **options)
+        send_request(operation(:post, PATH, body:, options:))
+      end
+
+      # Lists the issuers, newest first.
+      #
+      # @return [Flashpi::Page]
+      def list(params = nil, **options)
+        paginate(operation(:get, PATH, query: params, options:))
+      end
+
+      # Retrieves an issuer.
+      #
+      # @return [Hash{Symbol => Object}] the issuer
+      def get(issuer_id, **options)
+        send_request(operation(:get, ITEM, issuer_id, options:))
+      end
+
+      # Updates an issuer's name, tax profile, branding or defaults (only the fields sent).
+      #
+      # @return [Hash{Symbol => Object}] the issuer
+      def update(issuer_id, body, **options)
+        send_request(operation(:patch, ITEM, issuer_id, body:, options:))
+      end
+
+      # Deletes an issuer that has no documents and no certificates, with its establishments,
+      # emission points and issuer-scoped API keys. Otherwise 409 `resource_in_use`: certificates
+      # cannot be deleted, so an issuer that ever had a .p12 (one from `issuer_onboardings` too)
+      # stays.
+      #
+      # @return [nil]
+      def delete(issuer_id, **options)
+        send_request(operation(:delete, ITEM, issuer_id, response_type: :none, options:))
+      end
+    end
+  end
+end

data/lib/flashpi/resources/webhook_endpoints.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Flashpi
+  module Resources
+    # Deliveries of events to one endpoint.
+    class WebhookDeliveries < Internal::Resource
+      PATH = "/v1/webhook-endpoints/{}/deliveries"
+      ITEM = "/v1/webhook-endpoints/{}/deliveries/{}"
+
+      response_methods :list, :get, :replay
+
+      # Lists deliveries, newest first, optionally by status, event type or event.
+      #
+      # @return [Flashpi::Page]
+      def list(endpoint_id, params = nil, **options)
+        paginate(operation(:get, PATH, endpoint_id, query: params, options:))
+      end
+
+      # Retrieves a delivery with its attempts.
+      #
+      # @return [Hash{Symbol => Object}] the delivery
+      def get(endpoint_id, delivery_id, **options)
+        send_request(operation(:get, ITEM, endpoint_id, delivery_id, options:))
+      end
+
+      # Sends the delivery's event again, with the same `webhook-id`.
+      #
+      # @return [Hash{Symbol => Object}] the delivery
+      def replay(endpoint_id, delivery_id, **options)
+        send_request(operation(:post, "#{ITEM}/replay", endpoint_id, delivery_id, options:))
+      end
+    end
+
+    # The URLs Flashpi sends events to. Needs an account-scoped API key with read_write access.
+    # To check the signature of a webhook you receive, use {Flashpi::Webhooks} instead.
+    class WebhookEndpoints < Internal::Resource
+      PATH = "/v1/webhook-endpoints"
+      ITEM = "/v1/webhook-endpoints/{}"
+
+      response_methods :create, :list, :get, :update, :delete, :get_secret, :rotate_secret, :verify
+
+      # @return [WebhookDeliveries] the deliveries of an endpoint: attempts, answers and replays
+      attr_reader :deliveries
+
+      def initialize(engine)
+        super
+        @deliveries = WebhookDeliveries.new(engine)
+      end
+
+      # Creates an endpoint. It stays `pending_verification` until it answers the activation
+      # challenge; read its secret with {#get_secret} first, then call {#verify} if needed.
+      #
+      # @return [Hash{Symbol => Object}] the endpoint
+      def create(body, **options)
+        send_request(operation(:post, PATH, body:, options:))
+      end
+
+      # Lists the endpoints, newest first.
+      #
+      # @return [Flashpi::Page]
+      def list(params = nil, **options)
+        paginate(operation(:get, PATH, query: params, options:))
+      end
+
+      # Retrieves an endpoint.
+      #
+      # @return [Hash{Symbol => Object}] the endpoint
+      def get(endpoint_id, **options)
+        send_request(operation(:get, ITEM, endpoint_id, options:))
+      end
+
+      # Updates the URL, events, payload mode, description or `disabled` (only the fields sent).
+      #
+      # @return [Hash{Symbol => Object}] the endpoint
+      def update(endpoint_id, body, **options)
+        send_request(operation(:patch, ITEM, endpoint_id, body:, options:))
+      end
+
+      # Deletes an endpoint.
+      #
+      # @return [nil]
+      def delete(endpoint_id, **options)
+        send_request(operation(:delete, ITEM, endpoint_id, response_type: :none, options:))
+      end
+
+      # The signing secret (`whsec_...`) and, during a rotation, when the previous one expires.
+      #
+      # @return [Hash{Symbol => Object}]
+      def get_secret(endpoint_id, **options)
+        send_request(operation(:get, "#{ITEM}/secret", endpoint_id, options:))
+      end
+
+      # Replaces the signing secret. The previous one keeps signing for
+      # `previousSecretExpiresInHours` (24 by default, 0 to drop it at once). Read the new secret
+      # with {#get_secret}.
+      #
+      # @return [Hash{Symbol => Object}] the endpoint
+      def rotate_secret(endpoint_id, body = nil, **options)
+        send_request(operation(:post, "#{ITEM}/rotate-secret", endpoint_id, body:, options:))
+      end
+
+      # Sends the activation challenge (`webhook_endpoint.verification`) to the endpoint again.
+      #
+      # @return [Hash{Symbol => Object}] the endpoint
+      def verify(endpoint_id, **options)
+        send_request(operation(:post, "#{ITEM}/verify", endpoint_id, options:))
+      end
+    end
+  end
+end

data/lib/flashpi/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Flashpi
+  # The version of this gem, updated by release-please on every release.
+  VERSION = "0.1.0"
+end