einvoicing-connect 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54ce574178b7dcbed5b437a34f88672ae3d0d5923f7262d679cbc927d582265e
-  data.tar.gz: 96f661a9749c2b1c41b79bc5f52c9c48823bef8d314a7432e783137c560be7c8
+  metadata.gz: a3d4d4580d842a03b65af1d21a25c888685ad7fa8f69e3ee2b8b537c51bab015
+  data.tar.gz: bc35697fb4f88aa875b9460a106bffc2dc2578a57b0d8a19b32065a71bfb1c30
 SHA512:
-  metadata.gz: 4d32efd286fb9e98e0b3e9038e409e40f4f44f9d3b641e4dccb94584e4866daa076146799d8d2985dfbe5799966d8f3c8af43332d9f70a8daafeeface89c9909
-  data.tar.gz: 03df43147ea54a77683c0775bfda4f94c0e492cfca4427c8e7a1ded0215d266f79fe845984fb7864ef70f783cf13fb93d80f848ed8656860ebb5787a4ed47c90
+  metadata.gz: '080192ef85f10fe22030b187abadcebcb44efc726c9438af82235d6e6e81a9df38c932ccbbf22bcc43941bad9165103c29620d8ef5f297bb545aa38a37ab90a7'
+  data.tar.gz: eafe755d1d350e52efb9096170030a417e4db99d6dd420d0f773cbd8ace143482e561669bf2fe13791d47c910b307ab7229fb67862b4eb9cf713b8d1f3b39bc4

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SXN Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,220 @@
+# einvoicing-connect
+
+Platform connectors for the [einvoicing](https://www.sxnlabs.com/en/gems/einvoicing/) gem — Pennylane, PPF/Chorus Pro, and SIRET lookup for French e-invoicing.
+
+→ **[Full documentation and guides](https://www.sxnlabs.com/en/gems/einvoicing/)**
+
+## Installation
+
+```ruby
+gem "einvoicing-connect"
+```
+
+`hexapdf` is required for Factur-X PDF generation (Pennylane connector):
+
+```ruby
+gem "hexapdf"
+```
+
+## Connectors
+
+### Pennylane (`Connect::FR::Pennylane`)
+
+Submits invoices to [Pennylane](https://www.pennylane.com/) via the Factur-X e-invoice import API. The gem generates a standards-compliant CII XML document, embeds it into your PDF (producing a Factur-X PDF/A-3), and uploads it to Pennylane.
+
+#### Authentication
+
+**Companies and Firms** use a personal access token generated in Pennylane account settings:
+
+```ruby
+creds = Einvoicing::Connect::FR::Pennylane::Credentials.api_key("tok_xxx")
+```
+
+**Integration Partners** use OAuth2 with an access token + refresh token obtained via the authorization code flow:
+
+```ruby
+creds = Einvoicing::Connect::FR::Pennylane::Credentials.oauth(
+  access_token:  "...",
+  refresh_token: "...",
+  client_id:     "...",
+  client_secret: "...",
+  expires_at:    Time.now + 3600  # optional
+)
+```
+
+OAuth credentials are mutable — when an expired token is refreshed automatically, `creds.access_token`, `creds.refresh_token`, and `creds.expires_at` are updated in place so you can persist the new values.
+
+#### Submitting an e-invoice
+
+```ruby
+require "hexapdf"
+
+creds     = Einvoicing::Connect::FR::Pennylane::Credentials.api_key(ENV["PENNYLANE_API_KEY"])
+submitter = Einvoicing::Connect::FR::Pennylane::EInvoiceSubmitter.new(credentials: creds)
+
+invoice = Einvoicing::Invoice.new(
+  invoice_number: "INV-2025-001",
+  issue_date:     Date.today,
+  due_date:       Date.today + 30,
+  currency:       "EUR",
+  seller:         Einvoicing::Party.new(name: "Acme SAS", siret: "35600000000048"),
+  buyer:          Einvoicing::Party.new(
+    name:        "Client SA",
+    siret:       "55203253400017",
+    street:      "1 rue de la Paix",
+    city:        "Paris",
+    postal_code: "75001"
+  ),
+  lines: [
+    Einvoicing::LineItem.new(description: "Consulting", quantity: 5,
+                             unit_price: 800.00, vat_rate: 0.20),
+    Einvoicing::LineItem.new(description: "Licence ERP", quantity: 1,
+                             unit_price: 1_200.00, vat_rate: 0.20),
+    Einvoicing::LineItem.new(description: "Remise fidélité", quantity: 1,
+                             unit_price: -200.00, vat_rate: 0.20),
+  ]
+)
+
+# pdf is the binary content of a PDF (your human-readable invoice document)
+pdf    = File.binread("invoice.pdf")
+result = submitter.submit(invoice, pdf: pdf)
+
+puts result["id"]  # Pennylane invoice ID
+puts result["url"] # Pennylane invoice URL
+```
+
+#### Checking invoice status
+
+```ruby
+client = Einvoicing::Connect::FR::Pennylane::Client.new(credentials: creds)
+status = client.invoice_status(result["id"])
+puts status["status"]  # e.g. "processing", "sent"
+```
+
+#### Sandbox
+
+Pennylane's sandbox environment uses a separate subdomain:
+
+```ruby
+submitter = Einvoicing::Connect::FR::Pennylane::EInvoiceSubmitter.new(
+  credentials: creds,
+  sandbox:     true
+)
+```
+
+---
+
+### PPF / Chorus Pro (`Connect::FR::PPF`)
+
+Submits invoices to the French government's Chorus Pro platform (PPF) via the PISTE API.
+
+#### Authentication
+
+Chorus Pro uses OAuth2 client credentials:
+
+```ruby
+client = Einvoicing::Connect::FR::PPF::Client.new(
+  client_id:     ENV["CPP_CLIENT_ID"],
+  client_secret: ENV["CPP_CLIENT_SECRET"],
+  sandbox:       true
+)
+```
+
+For **technical account** (compte technique) submission, add the optional credentials:
+
+```ruby
+client = Einvoicing::Connect::FR::PPF::Client.new(
+  client_id:          ENV["CPP_CLIENT_ID"],
+  client_secret:      ENV["CPP_CLIENT_SECRET"],
+  technical_login:    ENV["CPP_TECHNICAL_LOGIN"],
+  technical_password: ENV["CPP_TECHNICAL_PASSWORD"]
+)
+```
+
+#### Submitting an invoice
+
+```ruby
+submitter = Einvoicing::Connect::FR::PPF::Submitter.new(client)
+result    = submitter.submit(invoice)
+
+puts result["numeroFlux"]  # submission reference
+puts result["statut"]      # e.g. "A_TRAITER"
+```
+
+Optional parameters:
+
+```ruby
+submitter.submit(invoice,
+  code_service:      "SRV001",   # Chorus Pro service code
+  engagement_number: "ENG-2025"  # buyer engagement/PO number
+)
+```
+
+The submitter automatically resolves the buyer's `idStructureCPP` from their SIRET via `find_structure` before submitting.
+
+---
+
+### SIRET Lookup (`Connect::FR::SiretLookup`)
+
+Enriches a `Party` with a SIRET from the French government company search API, given only a SIREN.
+
+```ruby
+buyer   = Einvoicing::Party.new(name: "Client SA", siren: "552032534")
+enriched = Einvoicing::Connect::FR::SiretLookup.enrich!(buyer)
+enriched.siret  # => "55203253400017"
+```
+
+Returns a new `Party` instance (non-destructive). Returns the original party unchanged if SIRET is already present or the lookup fails.
+
+---
+
+### E-invoicing directory (`Connect::FR::Directory`)
+
+Resolves **where to deliver an invoice** for a French company. Under the 2026 reform, every invoice is routed through the central directory (the PPF directory operated by DGFiP/AIFE): the issuing platform looks up the recipient's SIREN/SIRET to obtain the registered reception platform (PDP) and its technical routing code.
+
+```ruby
+routing = Einvoicing::Connect::FR::Directory.lookup("55203253400017")
+routing[:routing_code]  # => "PDP000123"  (technical routing code)
+routing[:platform_name] # => "Acme PDP"
+routing[:level]         # => "SIRET" (or "SIREN")
+
+# Or directly from a Party (prefers SIRET, falls back to SIREN):
+buyer   = Einvoicing::Party.new(name: "Client SA", siret: "55203253400017")
+routing = Einvoicing::Connect::FR::Directory.route(buyer)
+```
+
+Both methods return `nil` on any error or when the recipient is not found in the directory.
+
+> ⚠️ **Preview.** The official DGFiP/AIFE directory API specification is not yet final (reform pilot opened 2026‑02‑27, general availability 2026‑09‑01). The endpoint and response shape are expected to evolve — set `Einvoicing::Connect::FR::Directory.api_url = "..."` (or pass `api_url:` per call) to point at the production endpoint once confirmed.
+
+---
+
+## Error handling
+
+Each connector defines its own error hierarchy:
+
+```
+Pennylane::Error
+├── Pennylane::AuthError       # invalid API key (401)
+├── Pennylane::OAuthError      # token refresh failed
+└── Pennylane::SubmissionError # other API errors (4xx/5xx)
+
+PPF::Error
+├── PPF::AuthenticationError   # OAuth token request failed
+├── PPF::AuthorizationError    # 403 Forbidden
+├── PPF::NotFoundError         # 404 Not Found
+├── PPF::APIError              # other API errors
+└── PPF::ValidationError       # e.g. buyer SIRET not found in Chorus Pro
+```
+
+## Re-recording integration test cassettes
+
+Integration tests use VCR cassettes (committed to the repo, token scrubbed). To re-record against the real API:
+
+```bash
+PENNYLANE_API_KEY=your_token bundle exec rspec spec/integration/
+```
+
+## License
+
+MIT

data/config/locales/en.yml

@@ -8,6 +8,12 @@ en:
         not_found: "Not found: %{body}"
         api_error: "API error %{code}: %{body}"
         structure_not_found: "Buyer SIRET %{siret} not found in Chorus Pro"
+        missing_technical_account: "Chorus Pro technical account (login/password) is required for API submission"
+      pennylane:
+        auth_failed: "Pennylane authentication failed — check your API key"
+        oauth_failed: "Pennylane OAuth token refresh failed (HTTP %{code}): %{body}"
+        submission_failed: "Pennylane invoice submission failed: %{code} %{body}"
+        invalid_invoice: "Invoice is missing required fields for Pennylane submission"
       fr:
         siret_api_error: "SIRET lookup failed: %{message}"
         siret_not_found: "No company found for SIREN: %{siren}"

data/config/locales/fr.yml

@@ -8,6 +8,12 @@ fr:
         not_found: "Non trouvé : %{body}"
         api_error: "Erreur API %{code} : %{body}"
         structure_not_found: "SIRET acheteur %{siret} non trouvé dans Chorus Pro"
+        missing_technical_account: "Le compte technique Chorus Pro (identifiant/mot de passe) est requis pour la soumission API"
+      pennylane:
+        auth_failed: "Échec de l'authentification Pennylane — vérifiez votre clé API"
+        oauth_failed: "Échec du renouvellement du jeton OAuth Pennylane (HTTP %{code}) : %{body}"
+        submission_failed: "Échec de la soumission de la facture Pennylane : %{code} %{body}"
+        invalid_invoice: "La facture est incomplète pour la soumission Pennylane"
       fr:
         siret_api_error: "Échec de la recherche SIRET : %{message}"
         siret_not_found: "Aucune entreprise trouvée pour le SIREN : %{siren}"

data/lib/einvoicing/connect/fr/directory.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module Einvoicing
+  module Connect
+    module FR
+      # Consultation of the central French e-invoicing directory (the PPF
+      # directory operated by DGFiP/AIFE).
+      #
+      # Given a French SIREN or SIRET, resolves the recipient's e-invoicing
+      # routing information: the registered reception platform (PDP) and its
+      # technical routing code. This is the lookup an issuing platform performs
+      # to know *where* to deliver an invoice for a company.
+      #
+      # NOTE: The official DGFiP/AIFE directory API specification is not yet
+      # final. The reform pilot opened on 2026-02-27, with general availability
+      # on 2026-09-01. The endpoint and response shape below follow the published
+      # interoperability framework and are expected to evolve — point
+      # +Directory.api_url=+ at the production endpoint once it is confirmed.
+      module Directory
+        # Placeholder endpoint, overridable via Directory.api_url= or per call.
+        DEFAULT_API_URL = "https://annuaire.facturation.gouv.fr/api/v1/destinataires" unless defined?(DEFAULT_API_URL)
+
+        class << self
+          attr_writer :api_url
+
+          def api_url
+            @api_url ||= DEFAULT_API_URL
+          end
+        end
+
+        # Look up the routing information for a recipient identified by SIREN
+        # (9 digits) or SIRET (14 digits).
+        #
+        # Returns a Hash on success, or nil on any error / no match:
+        #   {
+        #     identifier:    "55203253400017",
+        #     level:         "SIRET",          # or "SIREN"
+        #     routing_code:  "PDP000123",      # technical routing code
+        #     platform_id:   "0000000000000",  # PDP registration id
+        #     platform_name: "Acme PDP",
+        #     status:        "active"
+        #   }
+        def self.lookup(identifier, api_url: self.api_url)
+          id = identifier.to_s.gsub(/\s/, "")
+          return nil unless id.match?(/\A\d{9}(\d{5})?\z/)
+
+          uri = URI(api_url)
+          uri.query = URI.encode_www_form(identifiant: id)
+
+          response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                     open_timeout: 5, read_timeout: 10) do |http|
+            http.get(uri.request_uri)
+          end
+
+          return nil unless response.code == "200"
+
+          parse(JSON.parse(response.body))
+        rescue StandardError
+          nil
+        end
+
+        # Resolve the routing information for a Party, preferring its SIRET and
+        # falling back to its SIREN. Returns the routing Hash or nil.
+        def self.route(party, api_url: self.api_url)
+          identifier = party.siret.to_s.strip
+          identifier = party.siren.to_s.strip if identifier.empty? && party.respond_to?(:siren)
+          return nil if identifier.empty?
+
+          lookup(identifier, api_url: api_url)
+        end
+
+        # Internal: map a directory API payload to our routing Hash. The string
+        # keys below are the external API field names (kept in their original
+        # form, as with SiretLookup's Sirene keys).
+        def self.parse(data)
+          entry = data.is_a?(Hash) ? (data["destinataire"] || data["results"]&.first || data) : nil
+          return nil unless entry.is_a?(Hash)
+
+          routing_code = entry["codeRoutage"]
+          platform_id  = entry["idPlateforme"]
+          # An entry is routable as long as it provides a delivery target:
+          # either a technical routing code or the recipient's registered
+          # platform. SIREN/SIRET-level entries may expose only the platform,
+          # with no codeRoutage sub-address — keep those instead of dropping them.
+          return nil if routing_code.to_s.empty? && platform_id.to_s.empty?
+
+          {
+            identifier:    entry["identifiant"],
+            level:         entry["maille"],
+            routing_code:  routing_code,
+            platform_id:   platform_id,
+            platform_name: entry["nomPlateforme"],
+            status:        entry["statut"]
+          }
+        end
+        private_class_method :parse
+      end
+    end
+  end
+end

data/lib/einvoicing/connect/fr/pennylane/adapter.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Einvoicing
+  module Connect
+    module FR
+      module Pennylane
+        class Adapter
+          def initialize(invoice)
+            @invoice = invoice
+          end
+
+          # Maps Einvoicing::Invoice to Pennylane customer_invoices payload
+          def to_payload
+            {
+              customer_invoice: {
+                date:                  @invoice.issue_date.iso8601,
+                deadline:              @invoice.due_date&.iso8601,
+                invoice_number:        @invoice.invoice_number,
+                currency:              @invoice.currency || "EUR",
+                line_items_attributes: line_items,
+                customer_attributes:   customer
+              }
+            }
+          end
+
+          private
+
+          def line_items
+            @invoice.lines.map do |line|
+              {
+                label:      line.description,
+                quantity:   line.quantity,
+                unit_price: line.unit_price,
+                vat_rate:   (line.vat_rate * 100).round(2).to_s
+              }
+            end
+          end
+
+          def customer
+            b = @invoice.buyer
+            {
+              name:           b.name,
+              reg_no:         b.siret || b.siren,
+              address:        b.street,
+              city:           b.city,
+              postal_code:    b.postal_code,
+              country_alpha2: b.country_code || "FR"
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/einvoicing/connect/fr/pennylane/client.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+require "securerandom"
+
+module Einvoicing
+  module Connect
+    module FR
+      module Pennylane
+        class Client
+          BASE_URL    = "https://app.pennylane.com/api/external/v2"
+          SANDBOX_URL = "https://sandbox.pennylane.com/api/external/v2"
+
+          OAUTH_TOKEN_PATH  = "/oauth/token"
+          OAUTH_BASE_URL    = "https://app.pennylane.com"
+          OAUTH_SANDBOX_URL = "https://sandbox.pennylane.com"
+
+          def initialize(credentials:, sandbox: false)
+            @credentials = credentials
+            @base_url    = sandbox ? SANDBOX_URL : BASE_URL
+            @oauth_base  = sandbox ? OAUTH_SANDBOX_URL : OAUTH_BASE_URL
+          end
+
+          # Submit a Factur-X PDF binary to the e-invoice import endpoint.
+          # invoice_options: optional Hash pre-filling customer/line data.
+          def submit_einvoice(facturx_pdf, filename: "factur-x.pdf", invoice_options: nil)
+            post_multipart("/customer_invoices/e_invoices/imports",
+                           file: facturx_pdf, filename: filename,
+                           invoice_options: invoice_options)
+          end
+
+          # Get invoice status by Pennylane invoice ID.
+          def invoice_status(id)
+            get("/customer_invoices/#{id}")
+          end
+
+          private
+
+          def current_token
+            case @credentials
+            when Credentials::OAuth
+              refresh_oauth_token! if @credentials.expired?
+              @credentials.access_token
+            when Credentials::ApiKey
+              @credentials.api_key
+            end
+          end
+
+          def refresh_oauth_token!
+            uri = URI("#{@oauth_base}#{OAUTH_TOKEN_PATH}")
+            req = Net::HTTP::Post.new(uri)
+            req["Content-Type"] = "application/x-www-form-urlencoded"
+            req.body = URI.encode_www_form(
+              grant_type:    "refresh_token",
+              refresh_token: @credentials.refresh_token,
+              client_id:     @credentials.client_id,
+              client_secret: @credentials.client_secret
+            )
+            res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
+            unless res.is_a?(Net::HTTPSuccess)
+              raise OAuthError, ::I18n.t("einvoicing.connect.pennylane.oauth_failed",
+                                         code: res.code, body: res.body.to_s[0, 200])
+            end
+
+            data = JSON.parse(res.body)
+            @credentials.access_token  = data["access_token"]
+            @credentials.refresh_token = data["refresh_token"] if data["refresh_token"]
+            @credentials.expires_at    = Time.now + data.fetch("expires_in", 3600).to_i - 60
+          end
+
+          def post(path, body)
+            uri  = URI("#{@base_url}#{path}")
+            http = Net::HTTP.new(uri.host, uri.port)
+            http.use_ssl = true
+            req = Net::HTTP::Post.new(uri)
+            req["Authorization"] = "Bearer #{current_token}"
+            req["Content-Type"]  = "application/json"
+            req.body = JSON.generate(body)
+            handle_response(http.request(req))
+          end
+
+          def post_multipart(path, file:, filename:, invoice_options: nil)
+            boundary = "RubyBoundary#{SecureRandom.hex(16)}"
+            uri      = URI("#{@base_url}#{path}")
+            http     = Net::HTTP.new(uri.host, uri.port)
+            http.use_ssl = true
+            req = Net::HTTP::Post.new(uri)
+            req["Authorization"] = "Bearer #{current_token}"
+            req["Content-Type"]  = "multipart/form-data; boundary=#{boundary}"
+            req.body = build_multipart_body(boundary, file: file, filename: filename,
+                                            invoice_options: invoice_options)
+            handle_response(http.request(req))
+          end
+
+          def build_multipart_body(boundary, file:, filename:, invoice_options:)
+            body = +""
+            body << "--#{boundary}\r\n"
+            body << "Content-Disposition: form-data; name=\"file\"; filename=\"#{filename}\"\r\n"
+            body << "Content-Type: application/pdf\r\n\r\n"
+            body << file.b
+            body << "\r\n"
+            if invoice_options
+              body << "--#{boundary}\r\n"
+              body << "Content-Disposition: form-data; name=\"invoice_options\"\r\n"
+              body << "Content-Type: application/json\r\n\r\n"
+              body << JSON.generate(invoice_options)
+              body << "\r\n"
+            end
+            body << "--#{boundary}--\r\n"
+            body.force_encoding("BINARY")
+          end
+
+          def get(path)
+            uri  = URI("#{@base_url}#{path}")
+            http = Net::HTTP.new(uri.host, uri.port)
+            http.use_ssl = true
+            req = Net::HTTP::Get.new(uri)
+            req["Authorization"] = "Bearer #{current_token}"
+            handle_response(http.request(req))
+          end
+
+          def handle_response(response)
+            body = JSON.parse(response.body) rescue {}
+            case response.code.to_i
+            when 200..299
+              body
+            when 401
+              raise AuthError, ::I18n.t("einvoicing.connect.pennylane.auth_failed")
+            else
+              raise SubmissionError, ::I18n.t("einvoicing.connect.pennylane.submission_failed",
+                                              code: response.code,
+                                              body: response.body.to_s[0, 200])
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/einvoicing/connect/fr/pennylane/credentials.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Einvoicing
+  module Connect
+    module FR
+      module Pennylane
+        # Encapsulates Pennylane API authentication credentials.
+        #
+        # Two modes are supported:
+        #
+        # 1. Static API key — for Companies and Firms using a personal access token:
+        #      creds = Pennylane::Credentials.api_key("tok_xxx")
+        #
+        # 2. OAuth2 — for Integration Partners using the authorization code flow:
+        #      creds = Pennylane::Credentials.oauth(
+        #        access_token:  "...",
+        #        refresh_token: "...",
+        #        client_id:     "...",
+        #        client_secret: "...",
+        #        expires_at:    Time.now + 3600   # optional
+        #      )
+        #
+        # OAuth credentials are mutable: when the Client refreshes an expired access
+        # token it updates the object in place. The calling application can read back
+        # the updated tokens after any API call and persist them.
+        module Credentials
+          def self.api_key(key)
+            ApiKey.new(key)
+          end
+
+          def self.oauth(access_token:, refresh_token:, client_id:, client_secret:,
+                         expires_at: nil)
+            OAuth.new(
+              access_token:  access_token,
+              refresh_token: refresh_token,
+              client_id:     client_id,
+              client_secret: client_secret,
+              expires_at:    expires_at
+            )
+          end
+
+          # Static personal access token — never expires.
+          class ApiKey
+            attr_reader :api_key
+
+            def initialize(key)
+              @api_key = key
+            end
+          end
+
+          # OAuth2 access + refresh token pair. Mutable so the Client can update
+          # tokens in place after a refresh, making the new values available to the
+          # caller for persistence.
+          class OAuth
+            attr_reader   :client_id, :client_secret
+            attr_accessor :access_token, :refresh_token, :expires_at
+
+            def initialize(access_token:, refresh_token:, client_id:, client_secret:,
+                           expires_at: nil)
+              @access_token  = access_token
+              @refresh_token = refresh_token
+              @client_id     = client_id
+              @client_secret = client_secret
+              @expires_at    = expires_at
+            end
+
+            def expired?
+              expires_at.nil? || Time.now >= expires_at
+            end
+          end
+        end
+      end
+    end
+  end
+end