factpulse 0.1.0

data/lib/factpulse/api_model_base.rb

@@ -0,0 +1,88 @@
+=begin
+#FactPulse REST API
+
+# REST API for electronic invoicing in France: Factur-X, AFNOR PDP/PA, electronic signatures.  ## 🎯 Main Features  ### 📄 Factur-X - Generation - **Formats**: XML only or PDF/A-3 with embedded XML - **Profiles**: MINIMUM, BASIC, EN16931, EXTENDED - **Standards**: EN 16931 (EU directive 2014/55), ISO 19005-3 (PDF/A-3), CII (UN/CEFACT) - **🆕 Simplified Format**: Generation from SIRET + auto-enrichment (Chorus Pro API + Business Search)  ### ✅ Factur-X - Validation - **XML Validation**: Schematron (45 to 210+ rules depending on profile) - **PDF Validation**: PDF/A-3, Factur-X XMP metadata - **VeraPDF**: Strict PDF/A validation (146+ ISO 19005-3 rules)  ### ✍️ Electronic Signature - **Standards**: PAdES-B-B, PAdES-B-T (RFC 3161 timestamping), PAdES-B-LT (long-term archival) - **eIDAS Levels**: SES (self-signed), AdES (commercial CA), QES (QTSP) - **Validation**: Cryptographic integrity and certificate verification  ### 📋 Flux 6 - Invoice Lifecycle (CDAR) - **CDAR Messages**: Acknowledgements, invoice statuses - **PPF Statuses**: REFUSED (210), PAID (212)  ### 📊 Flux 10 - E-Reporting - **Tax Declarations**: International B2B, B2C - **Flow Types**: 10.1 (B2B transactions), 10.2 (B2B payments), 10.3 (B2C transactions), 10.4 (B2C payments)  ### 📡 AFNOR PDP/PA (XP Z12-013) - **Flow Service**: Submit and search flows to PDPs - **Directory Service**: Company search (SIREN/SIRET) - **Multi-client**: Support for multiple PDP configs per user  ### 🏛️ Chorus Pro - **Public Sector Invoicing**: Complete API for Chorus Pro  ### ⏳ Async Tasks - **Celery**: Asynchronous generation, validation and signing - **Polling**: Status tracking via `/tasks/{task_id}/status` - **Webhooks**: Automatic notifications when tasks complete  ## 🔒 Authentication  All requests require a **JWT token** in the Authorization header: ``` Authorization: Bearer YOUR_JWT_TOKEN ```  ### How to obtain a JWT token?  #### 🔑 Method 1: `/api/token/` API (Recommended)  **URL:** `https://factpulse.fr/api/token/`  This method is **recommended** for integration in your applications and CI/CD workflows.  **Prerequisites:** Having set a password on your account  **For users registered via email/password:** - You already have a password, use it directly  **For users registered via OAuth (Google/GitHub):** - You must first set a password at: https://factpulse.fr/accounts/password/set/ - Once the password is created, you can use the API  **Request example:** ```bash curl -X POST https://factpulse.fr/api/token/ \\   -H \"Content-Type: application/json\" \\   -d '{     \"username\": \"your_email@example.com\",     \"password\": \"your_password\"   }' ```  **Optional `client_uid` parameter:**  To select credentials for a specific client (PA/PDP, Chorus Pro, signing certificates), add `client_uid`:  ```bash curl -X POST https://factpulse.fr/api/token/ \\   -H \"Content-Type: application/json\" \\   -d '{     \"username\": \"your_email@example.com\",     \"password\": \"your_password\",     \"client_uid\": \"550e8400-e29b-41d4-a716-446655440000\"   }' ```  The `client_uid` will be included in the JWT and allow the API to automatically use: - AFNOR/PDP credentials configured for this client - Chorus Pro credentials configured for this client - Electronic signature certificates configured for this client  **Response:** ```json {   \"access\": \"eyJ0eXAiOiJKV1QiLCJhbGc...\",  // Access token (validity: 30 min)   \"refresh\": \"eyJ0eXAiOiJKV1QiLCJhbGc...\"  // Refresh token (validity: 7 days) } ```  **Advantages:** - ✅ Full automation (CI/CD, scripts) - ✅ Programmatic token management - ✅ Refresh token support for automatic access renewal - ✅ Easy integration in any language/tool  #### 🖥️ Method 2: Dashboard Generation (Alternative)  **URL:** https://factpulse.fr/api/dashboard/  This method is suitable for quick tests or occasional use via the graphical interface.  **How it works:** - Log in to the dashboard - Use the \"Generate Test Token\" or \"Generate Production Token\" buttons - Works for **all** users (OAuth and email/password), without requiring a password  **Token types:** - **Test Token**: 24h validity, 1000 calls/day quota (free) - **Production Token**: 7 days validity, quota based on your plan  **Advantages:** - ✅ Quick for API testing - ✅ No password required - ✅ Simple visual interface  **Disadvantages:** - ❌ Requires manual action - ❌ No refresh token - ❌ Less suited for automation  ### 📚 Full Documentation  For more information on authentication and API usage: https://factpulse.fr/documentation-api/     
+
+The version of the OpenAPI document: 1.0.0
+Contact: contact@factpulse.fr
+Generated by: https://openapi-generator.tech
+Generator version: 7.20.0-SNAPSHOT
+
+=end
+
+module FactPulse
+  class ApiModelBase
+    # Deserializes the data based on type
+    # @param string type Data type
+    # @param string value Value to be deserialized
+    # @return [Object] Deserialized data
+    def self._deserialize(type, value)
+      case type.to_sym
+      when :Time
+        Time.parse(value)
+      when :Date
+        Date.parse(value)
+      when :String
+        value.to_s
+      when :Integer
+        value.to_i
+      when :Float
+        value.to_f
+      when :Boolean
+        if value.to_s =~ /\A(true|t|yes|y|1)\z/i
+          true
+        else
+          false
+        end
+      when :Object
+        # generic object (usually a Hash), return directly
+        value
+      when /\AArray<(?<inner_type>.+)>\z/
+        inner_type = Regexp.last_match[:inner_type]
+        value.map { |v| _deserialize(inner_type, v) }
+      when /\AHash<(?<k_type>.+?), (?<v_type>.+)>\z/
+        k_type = Regexp.last_match[:k_type]
+        v_type = Regexp.last_match[:v_type]
+        {}.tap do |hash|
+          value.each do |k, v|
+            hash[_deserialize(k_type, k)] = _deserialize(v_type, v)
+          end
+        end
+      else # model
+        # models (e.g. Pet) or oneOf
+        klass = FactPulse.const_get(type)
+        klass.respond_to?(:openapi_any_of) || klass.respond_to?(:openapi_one_of) ? klass.build(value) : klass.build_from_hash(value)
+      end
+    end
+
+    # Returns the string representation of the object
+    # @return [String] String presentation of the object
+    def to_s
+      to_hash.to_s
+    end
+
+    # to_body is an alias to to_hash (backward compatibility)
+    # @return [Hash] Returns the object in the form of hash
+    def to_body
+      to_hash
+    end
+
+    # Outputs non-array value in the form of hash
+    # For object, use to_hash. Otherwise, just return the value
+    # @param [Object] value Any valid value
+    # @return [Hash] Returns the value in the form of hash
+    def _to_hash(value)
+      if value.is_a?(Array)
+        value.compact.map { |v| _to_hash(v) }
+      elsif value.is_a?(Hash)
+        {}.tap do |hash|
+          value.each { |k, v| hash[k] = _to_hash(v) }
+        end
+      elsif value.respond_to? :to_hash
+        value.to_hash
+      else
+        value
+      end
+    end
+  end
+end

data/lib/factpulse/configuration.rb

@@ -0,0 +1,319 @@
+=begin
+#FactPulse REST API
+
+# REST API for electronic invoicing in France: Factur-X, AFNOR PDP/PA, electronic signatures.  ## 🎯 Main Features  ### 📄 Factur-X - Generation - **Formats**: XML only or PDF/A-3 with embedded XML - **Profiles**: MINIMUM, BASIC, EN16931, EXTENDED - **Standards**: EN 16931 (EU directive 2014/55), ISO 19005-3 (PDF/A-3), CII (UN/CEFACT) - **🆕 Simplified Format**: Generation from SIRET + auto-enrichment (Chorus Pro API + Business Search)  ### ✅ Factur-X - Validation - **XML Validation**: Schematron (45 to 210+ rules depending on profile) - **PDF Validation**: PDF/A-3, Factur-X XMP metadata - **VeraPDF**: Strict PDF/A validation (146+ ISO 19005-3 rules)  ### ✍️ Electronic Signature - **Standards**: PAdES-B-B, PAdES-B-T (RFC 3161 timestamping), PAdES-B-LT (long-term archival) - **eIDAS Levels**: SES (self-signed), AdES (commercial CA), QES (QTSP) - **Validation**: Cryptographic integrity and certificate verification  ### 📋 Flux 6 - Invoice Lifecycle (CDAR) - **CDAR Messages**: Acknowledgements, invoice statuses - **PPF Statuses**: REFUSED (210), PAID (212)  ### 📊 Flux 10 - E-Reporting - **Tax Declarations**: International B2B, B2C - **Flow Types**: 10.1 (B2B transactions), 10.2 (B2B payments), 10.3 (B2C transactions), 10.4 (B2C payments)  ### 📡 AFNOR PDP/PA (XP Z12-013) - **Flow Service**: Submit and search flows to PDPs - **Directory Service**: Company search (SIREN/SIRET) - **Multi-client**: Support for multiple PDP configs per user  ### 🏛️ Chorus Pro - **Public Sector Invoicing**: Complete API for Chorus Pro  ### ⏳ Async Tasks - **Celery**: Asynchronous generation, validation and signing - **Polling**: Status tracking via `/tasks/{task_id}/status` - **Webhooks**: Automatic notifications when tasks complete  ## 🔒 Authentication  All requests require a **JWT token** in the Authorization header: ``` Authorization: Bearer YOUR_JWT_TOKEN ```  ### How to obtain a JWT token?  #### 🔑 Method 1: `/api/token/` API (Recommended)  **URL:** `https://factpulse.fr/api/token/`  This method is **recommended** for integration in your applications and CI/CD workflows.  **Prerequisites:** Having set a password on your account  **For users registered via email/password:** - You already have a password, use it directly  **For users registered via OAuth (Google/GitHub):** - You must first set a password at: https://factpulse.fr/accounts/password/set/ - Once the password is created, you can use the API  **Request example:** ```bash curl -X POST https://factpulse.fr/api/token/ \\   -H \"Content-Type: application/json\" \\   -d '{     \"username\": \"your_email@example.com\",     \"password\": \"your_password\"   }' ```  **Optional `client_uid` parameter:**  To select credentials for a specific client (PA/PDP, Chorus Pro, signing certificates), add `client_uid`:  ```bash curl -X POST https://factpulse.fr/api/token/ \\   -H \"Content-Type: application/json\" \\   -d '{     \"username\": \"your_email@example.com\",     \"password\": \"your_password\",     \"client_uid\": \"550e8400-e29b-41d4-a716-446655440000\"   }' ```  The `client_uid` will be included in the JWT and allow the API to automatically use: - AFNOR/PDP credentials configured for this client - Chorus Pro credentials configured for this client - Electronic signature certificates configured for this client  **Response:** ```json {   \"access\": \"eyJ0eXAiOiJKV1QiLCJhbGc...\",  // Access token (validity: 30 min)   \"refresh\": \"eyJ0eXAiOiJKV1QiLCJhbGc...\"  // Refresh token (validity: 7 days) } ```  **Advantages:** - ✅ Full automation (CI/CD, scripts) - ✅ Programmatic token management - ✅ Refresh token support for automatic access renewal - ✅ Easy integration in any language/tool  #### 🖥️ Method 2: Dashboard Generation (Alternative)  **URL:** https://factpulse.fr/api/dashboard/  This method is suitable for quick tests or occasional use via the graphical interface.  **How it works:** - Log in to the dashboard - Use the \"Generate Test Token\" or \"Generate Production Token\" buttons - Works for **all** users (OAuth and email/password), without requiring a password  **Token types:** - **Test Token**: 24h validity, 1000 calls/day quota (free) - **Production Token**: 7 days validity, quota based on your plan  **Advantages:** - ✅ Quick for API testing - ✅ No password required - ✅ Simple visual interface  **Disadvantages:** - ❌ Requires manual action - ❌ No refresh token - ❌ Less suited for automation  ### 📚 Full Documentation  For more information on authentication and API usage: https://factpulse.fr/documentation-api/     
+
+The version of the OpenAPI document: 1.0.0
+Contact: contact@factpulse.fr
+Generated by: https://openapi-generator.tech
+Generator version: 7.20.0-SNAPSHOT
+
+=end
+
+module FactPulse
+  class Configuration
+    # Defines url scheme
+    attr_accessor :scheme
+
+    # Defines url host
+    attr_accessor :host
+
+    # Defines url base path
+    attr_accessor :base_path
+
+    # Define server configuration index
+    attr_accessor :server_index
+
+    # Define server operation configuration index
+    attr_accessor :server_operation_index
+
+    # Default server variables
+    attr_accessor :server_variables
+
+    # Default server operation variables
+    attr_accessor :server_operation_variables
+
+    # Defines API keys used with API Key authentications.
+    #
+    # @return [Hash] key: parameter name, value: parameter value (API key)
+    #
+    # @example parameter name is "api_key", API key is "xxx" (e.g. "api_key=xxx" in query string)
+    #   config.api_key['api_key'] = 'xxx'
+    attr_accessor :api_key
+
+    # Defines API key prefixes used with API Key authentications.
+    #
+    # @return [Hash] key: parameter name, value: API key prefix
+    #
+    # @example parameter name is "Authorization", API key prefix is "Token" (e.g. "Authorization: Token xxx" in headers)
+    #   config.api_key_prefix['api_key'] = 'Token'
+    attr_accessor :api_key_prefix
+
+    # Defines the username used with HTTP basic authentication.
+    #
+    # @return [String]
+    attr_accessor :username
+
+    # Defines the password used with HTTP basic authentication.
+    #
+    # @return [String]
+    attr_accessor :password
+
+    # Defines the access token (Bearer) used with OAuth2.
+    attr_accessor :access_token
+
+    # Defines a Proc used to fetch or refresh access tokens (Bearer) used with OAuth2.
+    # Overrides the access_token if set
+    # @return [Proc]
+    attr_accessor :access_token_getter
+
+    # Set this to return data as binary instead of downloading a temp file. When enabled (set to true)
+    # HTTP responses with return type `File` will be returned as a stream of binary data.
+    # Default to false.
+    attr_accessor :return_binary_data
+
+    # Set this to enable/disable debugging. When enabled (set to true), HTTP request/response
+    # details will be logged with `logger.debug` (see the `logger` attribute).
+    # Default to false.
+    #
+    # @return [true, false]
+    attr_accessor :debugging
+
+    # Set this to ignore operation servers for the API client. This is useful when you need to
+    # send requests to a different server than the one specified in the OpenAPI document.
+    # Will default to the base url defined in the spec but can be overridden by setting
+    # `scheme`, `host`, `base_path` directly.
+    # Default to false.
+    # @return [true, false]
+    attr_accessor :ignore_operation_servers
+
+    # Defines the logger used for debugging.
+    # Default to `Rails.logger` (when in Rails) or logging to STDOUT.
+    #
+    # @return [#debug]
+    attr_accessor :logger
+
+    # Defines the temporary folder to store downloaded files
+    # (for API endpoints that have file response).
+    # Default to use `Tempfile`.
+    #
+    # @return [String]
+    attr_accessor :temp_folder_path
+
+    # The time limit for HTTP request in seconds.
+    # Default to 0 (never times out).
+    attr_accessor :timeout
+
+    # Set this to false to skip client side validation in the operation.
+    # Default to true.
+    # @return [true, false]
+    attr_accessor :client_side_validation
+
+    ### TLS/SSL setting
+    # Set this to false to skip verifying SSL certificate when calling API from https server.
+    # Default to true.
+    #
+    # @note Do NOT set it to false in production code, otherwise you would face multiple types of cryptographic attacks.
+    #
+    # @return [true, false]
+    attr_accessor :verify_ssl
+
+    ### TLS/SSL setting
+    # Set this to false to skip verifying SSL host name
+    # Default to true.
+    #
+    # @note Do NOT set it to false in production code, otherwise you would face multiple types of cryptographic attacks.
+    #
+    # @return [true, false]
+    attr_accessor :verify_ssl_host
+
+    ### TLS/SSL setting
+    # Set this to customize the certificate file to verify the peer.
+    #
+    # @return [String] the path to the certificate file
+    #
+    # @see The `cainfo` option of Typhoeus, `--cert` option of libcurl. Related source code:
+    # https://github.com/typhoeus/typhoeus/blob/master/lib/typhoeus/easy_factory.rb#L145
+    attr_accessor :ssl_ca_cert
+
+    ### TLS/SSL setting
+    # Client certificate file (for client certificate)
+    attr_accessor :cert_file
+
+    ### TLS/SSL setting
+    # Client private key file (for client certificate)
+    attr_accessor :key_file
+
+    # Set this to customize parameters encoding of array parameter with multi collectionFormat.
+    # Default to nil.
+    #
+    # @see The params_encoding option of Ethon. Related source code:
+    # https://github.com/typhoeus/ethon/blob/master/lib/ethon/easy/queryable.rb#L96
+    attr_accessor :params_encoding
+
+
+    attr_accessor :inject_format
+
+    attr_accessor :force_ending_format
+
+    def initialize
+      @scheme = 'https'
+      @host = 'factpulse.fr'
+      @base_path = ''
+      @server_index = nil
+      @server_operation_index = {}
+      @server_variables = {}
+      @server_operation_variables = {}
+      @api_key = {}
+      @api_key_prefix = {}
+      @client_side_validation = true
+      @verify_ssl = true
+      @verify_ssl_host = true
+      @cert_file = nil
+      @key_file = nil
+      @timeout = 0
+      @params_encoding = nil
+      @debugging = false
+      @ignore_operation_servers = false
+      @inject_format = false
+      @force_ending_format = false
+      @logger = defined?(Rails) ? Rails.logger : Logger.new(STDOUT)
+
+      yield(self) if block_given?
+    end
+
+    # The default Configuration object.
+    def self.default
+      @@default ||= Configuration.new
+    end
+
+    def configure
+      yield(self) if block_given?
+    end
+
+    def scheme=(scheme)
+      # remove :// from scheme
+      @scheme = scheme.sub(/:\/\//, '')
+    end
+
+    def host=(host)
+      # remove http(s):// and anything after a slash
+      @host = host.sub(/https?:\/\//, '').split('/').first
+    end
+
+    def base_path=(base_path)
+      # Add leading and trailing slashes to base_path
+      @base_path = "/#{base_path}".gsub(/\/+/, '/')
+      @base_path = '' if @base_path == '/'
+    end
+
+    # Returns base URL for specified operation based on server settings
+    def base_url(operation = nil)
+      return "#{scheme}://#{[host, base_path].join('/').gsub(/\/+/, '/')}".sub(/\/+\z/, '') if ignore_operation_servers
+      if operation_server_settings.key?(operation) then
+        index = server_operation_index.fetch(operation, server_index)
+        server_url(index.nil? ? 0 : index, server_operation_variables.fetch(operation, server_variables), operation_server_settings[operation])
+      else
+        server_index.nil? ? "#{scheme}://#{[host, base_path].join('/').gsub(/\/+/, '/')}".sub(/\/+\z/, '') : server_url(server_index, server_variables, nil)
+      end
+    end
+
+    # Gets API key (with prefix if set).
+    # @param [String] param_name the parameter name of API key auth
+    def api_key_with_prefix(param_name, param_alias = nil)
+      key = @api_key[param_name]
+      key = @api_key.fetch(param_alias, key) unless param_alias.nil?
+      if @api_key_prefix[param_name]
+        "#{@api_key_prefix[param_name]} #{key}"
+      else
+        key
+      end
+    end
+
+    # Gets access_token using access_token_getter or uses the static access_token
+    def access_token_with_refresh
+      return access_token if access_token_getter.nil?
+      access_token_getter.call
+    end
+
+    # Gets Basic Auth token string
+    def basic_auth_token
+      'Basic ' + ["#{username}:#{password}"].pack('m').delete("\r\n")
+    end
+
+    # Returns Auth Settings hash for api client.
+    def auth_settings
+      {
+        'HTTPBearer' =>
+          {
+            type: 'bearer',
+            in: 'header',
+            key: 'Authorization',
+            value: "Bearer #{access_token_with_refresh}"
+          },
+        'APIKeyHeader' =>
+          {
+            type: 'api_key',
+            in: 'header',
+            key: 'X-API-Key',
+            value: api_key_with_prefix('X-API-Key')
+          },
+      }
+    end
+
+    # Returns an array of Server setting
+    def server_settings
+      [
+        {
+          url: "https://factpulse.fr",
+          description: "Production",
+        },
+        {
+          url: "http://localhost:8001",
+          description: "Local development",
+        }
+      ]
+    end
+
+    def operation_server_settings
+      {
+      }
+    end
+
+    # Returns URL based on server settings
+    #
+    # @param index array index of the server settings
+    # @param variables hash of variable and the corresponding value
+    def server_url(index, variables = {}, servers = nil)
+      servers = server_settings if servers == nil
+
+      # check array index out of bound
+      if (index.nil? || index < 0 || index >= servers.size)
+        fail ArgumentError, "Invalid index #{index} when selecting the server. Must not be nil and must be less than #{servers.size}"
+      end
+
+      server = servers[index]
+      url = server[:url]
+
+      return url unless server.key? :variables
+
+      # go through variable and assign a value
+      server[:variables].each do |name, variable|
+        if variables.key?(name)
+          if (!server[:variables][name].key?(:enum_values) || server[:variables][name][:enum_values].include?(variables[name]))
+            url.gsub! "{" + name.to_s + "}", variables[name]
+          else
+            fail ArgumentError, "The variable `#{name}` in the server URL has invalid value #{variables[name]}. Must be #{server[:variables][name][:enum_values]}."
+          end
+        else
+          # use default value
+          url.gsub! "{" + name.to_s + "}", server[:variables][name][:default_value]
+        end
+      end
+
+      url
+    end
+
+
+  end
+end

data/lib/factpulse/helpers/client.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+#
+# FactPulse SDK - Thin HTTP wrapper with auto-polling.
+#
+# Usage:
+#   client = FactPulseClient.new('email', 'password', 'client_uid')
+#
+#   # POST /api/v1/processing/invoices/submit-complete-async
+#   result = client.post('processing/invoices/submit-complete-async',
+#     invoiceData: {...},
+#     destination: { type: 'afnor' }
+#   )
+#   pdf_bytes = result['content'] # auto-decoded, auto-polled
+
+require 'net/http'
+require 'json'
+require 'base64'
+require 'uri'
+
+module FactPulse
+  class Error < StandardError
+    attr_reader :status_code, :details
+
+    def initialize(message, status_code: nil, details: [])
+      super(message)
+      @status_code = status_code
+      @details = details
+    end
+  end
+
+  class Client
+    DEFAULT_API_URL = 'https://factpulse.fr'
+
+    def initialize(email, password, client_uid, api_url: DEFAULT_API_URL, timeout: 60, polling_timeout: 120)
+      @email = email
+      @password = password
+      @client_uid = client_uid
+      @api_url = api_url.chomp('/')
+      @timeout = timeout
+      @polling_timeout = polling_timeout
+      @token = nil
+      @token_expires_at = 0
+      @token_mutex = Mutex.new
+    end
+
+    # POST request to /api/v1/{path} (JSON body)
+    def post(path, **data)
+      request('POST', path, data, retry_auth: true)
+    end
+
+    # POST request with multipart/form-data (for file uploads)
+    def post_multipart(path, data: {}, files: {})
+      request_multipart(path, data, files, retry_auth: true)
+    end
+
+    # GET request to /api/v1/{path}
+    def get(path, **params)
+      request('GET', path, params, retry_auth: true)
+    end
+
+    private
+
+    def request(method, path, data, retry_auth:)
+      ensure_auth
+      url = "#{@api_url}/api/v1/#{path}"
+      uri = URI(url)
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.read_timeout = @timeout
+
+      if method == 'POST'
+        req = Net::HTTP::Post.new(uri)
+        req['Content-Type'] = 'application/json'
+        req.body = JSON.generate(data)
+      else
+        uri.query = URI.encode_www_form(data) unless data.empty?
+        req = Net::HTTP::Get.new(uri)
+      end
+      req['Authorization'] = "Bearer #{@token}"
+
+      response = http.request(req)
+
+      if response.code == '401' && retry_auth
+        invalidate_token
+        return request(method, path, data, retry_auth: false)
+      end
+
+      result = parse_response(response)
+
+      # Auto-poll: support both taskId (camelCase) and task_id (snake_case)
+      if result.is_a?(Hash)
+        task_id = result['taskId'] || result['task_id']
+        result = poll(task_id) if task_id
+      end
+
+      # Auto-decode: support both content_b64 and contentB64
+      if result.is_a?(Hash)
+        b64_content = result.delete('content_b64') || result.delete('contentB64')
+        result['content'] = Base64.decode64(b64_content) if b64_content
+      end
+
+      result
+    end
+
+    def request_multipart(path, data, files, retry_auth:)
+      ensure_auth
+      url = "#{@api_url}/api/v1/#{path}"
+      uri = URI(url)
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.read_timeout = @timeout
+
+      # Build multipart body
+      boundary = "----RubyFormBoundary#{rand(1_000_000)}"
+      body = []
+
+      data.each do |key, value|
+        body << "--#{boundary}\r\n"
+        body << "Content-Disposition: form-data; name=\"#{key}\"\r\n\r\n"
+        body << "#{value}\r\n"
+      end
+
+      files.each do |key, content|
+        body << "--#{boundary}\r\n"
+        body << "Content-Disposition: form-data; name=\"#{key}\"; filename=\"#{key}\"\r\n"
+        body << "Content-Type: application/octet-stream\r\n\r\n"
+        body << content
+        body << "\r\n"
+      end
+
+      body << "--#{boundary}--\r\n"
+
+      req = Net::HTTP::Post.new(uri)
+      req['Authorization'] = "Bearer #{@token}"
+      req['Content-Type'] = "multipart/form-data; boundary=#{boundary}"
+      req.body = body.join
+
+      response = http.request(req)
+
+      if response.code == '401' && retry_auth
+        invalidate_token
+        return request_multipart(path, data, files, retry_auth: false)
+      end
+
+      result = parse_response(response)
+
+      # Auto-poll
+      if result.is_a?(Hash)
+        task_id = result['taskId'] || result['task_id']
+        result = poll(task_id) if task_id
+      end
+
+      # Auto-decode
+      if result.is_a?(Hash)
+        b64_content = result.delete('content_b64') || result.delete('contentB64')
+        result['content'] = Base64.decode64(b64_content) if b64_content
+      end
+
+      result
+    end
+
+    def parse_response(response)
+      body = response.body
+      data = body && !body.empty? ? JSON.parse(body) : {}
+
+      return data if response.is_a?(Net::HTTPSuccess)
+
+      msg = "HTTP #{response.code}"
+      details = []
+
+      if data.is_a?(Hash)
+        if data['detail'].is_a?(Array)
+          details = data['detail']
+          msgs = data['detail'].map do |e|
+            loc = e['loc'] || []
+            "#{loc.last || '?'}: #{e['msg'] || '?'}"
+          end
+          msg = "Validation error: #{msgs.join('; ')}"
+        elsif data['detail'].is_a?(String)
+          msg = data['detail']
+        elsif data['errorMessage'].is_a?(String)
+          msg = data['errorMessage']
+        end
+      end
+
+      raise Error.new(msg, status_code: response.code.to_i, details: details)
+    end
+
+    def poll(task_id)
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      interval = 1.0
+
+      loop do
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+        if elapsed >= @polling_timeout
+          raise Error.new("Polling timeout after #{@polling_timeout}s for task #{task_id}")
+        end
+
+        ensure_auth
+        uri = URI("#{@api_url}/api/v1/processing/tasks/#{task_id}/status")
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == 'https'
+        http.read_timeout = @timeout
+
+        req = Net::HTTP::Get.new(uri)
+        req['Authorization'] = "Bearer #{@token}"
+        response = http.request(req)
+
+        if response.code == '401'
+          invalidate_token
+          next
+        end
+
+        data = parse_response(response)
+        status = data['status']
+
+        if status == 'SUCCESS'
+          result = data['result'] || {}
+          # Support both content_b64 and contentB64
+          b64_content = result.delete('content_b64') || result.delete('contentB64')
+          result['content'] = Base64.decode64(b64_content) if b64_content
+          return result
+        end
+
+        if status == 'FAILURE'
+          res = data['result'] || {}
+          raise Error.new(res['errorMessage'] || 'Task failed', details: res['details'] || [])
+        end
+
+        sleep([interval, @polling_timeout - elapsed].min)
+        interval = [interval * 1.5, 10].min
+      end
+    end
+
+    def ensure_auth
+      @token_mutex.synchronize do
+        if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= @token_expires_at
+          refresh_token
+        end
+      end
+    end
+
+    def refresh_token
+      uri = URI("#{@api_url}/api/token/")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.read_timeout = @timeout
+
+      req = Net::HTTP::Post.new(uri)
+      req['Content-Type'] = 'application/json'
+      req.body = JSON.generate(username: @email, password: @password, client_uid: @client_uid)
+
+      response = http.request(req)
+
+      unless response.is_a?(Net::HTTPSuccess)
+        raise Error.new("Authentication failed: HTTP #{response.code}", status_code: response.code.to_i)
+      end
+
+      data = JSON.parse(response.body)
+      @token = data['access'] || raise(Error.new('Invalid auth response'))
+      @token_expires_at = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 28 * 60
+    end
+
+    def invalidate_token
+      @token_mutex.synchronize do
+        @token_expires_at = 0
+      end
+    end
+  end
+end