openhub-bo-core 0.1.0-x86_64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a67a9391c368677c150636065e2ddb0c9255305919e43d06106879e6bb86ee1c
+  data.tar.gz: 298e16c0b9e41b9aaf92eca45601ce33cfb9d79b34e7f7f8cc3c4c46bafc178e
+SHA512:
+  metadata.gz: b43eb5a5fd708efee02452e4a3821431725a7bdd5b315fc4e9ca353b2bf213baa1a8c48a1c991f302341bf57ccd8f3b9c8614f1df59bf96e7b480cb046451a8c
+  data.tar.gz: 55e992a3dfebcb499733c22556e4fe0cc787eb556e2e45f8b13dea9739e8f5599e9d25e91323337b9edf9fec755e4f38a8c1d40726f104b1aedcf7ecbcce86f3

data/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/NOTICE

@@ -0,0 +1,8 @@
+openhub-bo
+Copyright 2026 Felix Daniel Coca Calvimontes
+
+Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+This is an unofficial integration. "Red Enlace", "ATC" and "OpenHub" are names
+and trademarks of their respective owners; this project is not affiliated with,
+endorsed by or supported by them.

data/README.md

@@ -0,0 +1,21 @@
+# openhub-bo-core
+
+Base compartida de las gemas `openhub-bo` para **Red Enlace (ATC) OpenHub**, Bolivia:
+sesión OAuth2 con caché de token (thread-safe), transporte HTTP (`Net::HTTP`, sin
+dependencias), errores tipados y tipos comunes. Normalmente llega como dependencia
+de cada producto.
+
+```ruby
+require "openhub_bo/core"
+
+session = OpenhubBo::Core::Session.new(ENV["CLIENT_ID"], ENV["CLIENT_SECRET"], environment: :sandbox)
+# pásala a OpenhubBo::Qr::QrClient.new(session), etc. Todos comparten el token.
+```
+
+- Errores: `Core::Error` → `ValidationError#field`, `AuthenticationError#status`,
+  `ApiError#status/#code/#errors/#retryable?`, `TransportError#maybe_sent`,
+  `AmbiguousOutcomeError#operation/#code` (una operación no idempotente pudo
+  aplicarse), `DecodeError`, `WebhookAuthError`.
+- Montos: entradas `BigDecimal`, `Integer` o `String` (`Float` → `TypeError`); salidas `BigDecimal`.
+- Transporte propio: cualquier objeto con `perform(request) -> Core::Response`.
+- Tests: `require "openhub_bo/core/testing"` → `Core::Testing::MockGateway`.

data/lib/openhub_bo/core/errors.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module OpenhubBo
+  module Core
+    ApiFieldError = Data.define(:message, :field, :code)
+
+    # Base class for every error raised by openhub-bo.
+    class Error < StandardError
+      # Whether repeating the same call later may succeed.
+      def retryable? = false
+    end
+
+    # Input rejected locally, before calling OpenHub.
+    class ValidationError < Error
+      attr_reader :field
+
+      def initialize(message, field:)
+        super("invalid `#{field}`: #{message}")
+        @field = field
+      end
+    end
+
+    # Credentials or access token rejected by OpenHub.
+    class AuthenticationError < Error
+      attr_reader :status
+
+      def initialize(message, status:)
+        super("authentication failed (HTTP #{status}): #{message}")
+        @status = status
+      end
+    end
+
+    # OpenHub answered with an error.
+    class ApiError < Error
+      attr_reader :status, :errors
+
+      def initialize(message, status:, errors: [], retryable: false)
+        super("OpenHub error (HTTP #{status}): #{message}")
+        @status = status
+        @errors = errors
+        @retryable = retryable
+      end
+
+      def retryable? = @retryable
+
+      # Code of the first field error, e.g. "TRANSACCION_NO_ENCONTRADA".
+      def code = errors.map(&:code).compact.first
+    end
+
+    # The response could not be understood.
+    class DecodeError < Error; end
+
+    # Incoming webhook did not carry the expected secret.
+    class WebhookAuthError < Error; end
+
+    # Network failure. `maybe_sent` is false when the request never left
+    # (connection refused, connect timeout): retrying is then always safe.
+    class TransportError < Error
+      attr_reader :maybe_sent
+
+      def initialize(message, maybe_sent:)
+        super(message)
+        @maybe_sent = maybe_sent
+      end
+
+      def retryable? = true
+    end
+
+    # A non-idempotent call (generating a QR, paying a payout...) may or may not
+    # have been applied: the response was lost, or OpenHub reported the result as
+    # unconfirmed (payout codes 94/96). Deliberately not a TransportError so
+    # generic retry loops do not repeat it. Query the status before retrying.
+    class AmbiguousOutcomeError < Error
+      attr_reader :operation, :errors
+
+      def initialize(operation, cause, errors: [])
+        super("outcome of `#{operation}` is unknown: #{cause}")
+        @operation = operation
+        @errors = errors
+      end
+
+      def code = errors.map(&:code).compact.first
+    end
+
+    # Contract violation between a gem and its native extension (a bug).
+    class CoreError < Error; end
+
+    module_function
+
+    # Maps an error from the native core; `op` is the native op name
+    # (e.g. "payouts.pay.parse").
+    def error_from_core(data, op = "")
+      kind = data["kind"]
+      message = data.fetch("message", "unknown error")
+      errors = Array(data["errors"]).map do |e|
+        ApiFieldError.new(message: e["message"], field: e["field"], code: e["code"])
+      end
+      case kind
+      when "validation" then ValidationError.new(message, field: data["field"])
+      when "authentication" then AuthenticationError.new(message, status: data["status"])
+      when "api"
+        ApiError.new(message, status: data["status"], errors: errors, retryable: data["retryable"] == true)
+      when "ambiguous"
+        AmbiguousOutcomeError.new(op.sub(/\.(build|parse)\z/, ""), message, errors: errors)
+      when "decode" then DecodeError.new(message)
+      when "webhook_auth" then WebhookAuthError.new(message)
+      else CoreError.new(message)
+      end
+    end
+  end
+end

data/lib/openhub_bo/core/models.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+module OpenhubBo
+  module Core
+    module Environment
+      DEVELOPMENT = :development
+      SANDBOX = :sandbox
+      PRODUCTION = :production
+      ALL = [DEVELOPMENT, SANDBOX, PRODUCTION].freeze
+    end
+
+    # Status shared by every product family (symbols); `raw_status` keeps the original.
+    module PaymentStatus
+      ALL = %i[pending processing paid cancelled expired rejected reversed error unknown].freeze
+      NOT_FINAL = %i[pending processing unknown].freeze
+
+      def self.final?(status) = !NOT_FINAL.include?(status)
+    end
+
+    # OpenHub timestamps carry no offset: they are Bolivia time.
+    BOLIVIA_OFFSET = "-04:00"
+
+    # Where ATC must POST notifications. ATC sends `key: value` as a header; it is
+    # the only authentication, so use a long random value.
+    Webhook = Data.define(:url, :value, :key) do
+      def initialize(url:, value:, key: "x-api-key") = super
+
+      def to_wire = { "url" => url, "key" => key, "value" => value }
+
+      def inspect = "#<#{self.class.name} url=#{url.inspect} key=#{key.inspect} value=[FILTERED]>"
+      alias_method :to_s, :inspect
+    end
+
+    module_function
+
+    # Amounts cross the native boundary as exact decimal strings.
+    def amount(value)
+      case value
+      when BigDecimal then value.to_s("F")
+      when Integer then value.to_s
+      when String then value
+      else
+        raise TypeError,
+              "amount must be BigDecimal, Integer or String, not #{value.class} " \
+              "(floats are rejected to avoid rounding errors)"
+      end
+    end
+
+    def seconds(value)
+      raise TypeError, "expected Integer seconds, not #{value.class}" unless value.is_a?(Integer)
+
+      value
+    end
+
+    def iso_date(value) = value.is_a?(Date) ? value.iso8601 : value
+
+    def decimal(value) = value.nil? ? nil : BigDecimal(value)
+
+    # Parses an OpenHub timestamp, assuming Bolivia time when it has no offset.
+    def local_time(value)
+      return nil if value.nil? || value.empty?
+
+      has_offset = value.match?(/(Z|[+-]\d{2}:?\d{2})\z/)
+      Time.iso8601(has_offset ? value : value.tr(" ", "T") + BOLIVIA_OFFSET)
+    rescue ArgumentError
+      nil
+    end
+
+    # Defines an immutable value class from the core's snake_case JSON.
+    #
+    #   Payer = Core.model(:name, :document_id)
+    #   Qr = Core.model(:reference, :amount, :payer, casts: { amount: :decimal, payer: Payer })
+    #
+    # Casts: :decimal (BigDecimal), :symbol, :time (Bolivia time), a model class,
+    # or [ModelClass] for lists.
+    def model(*fields, casts: {}, &block)
+      klass = Data.define(*fields, &block)
+      klass.define_singleton_method(:from_h) do |hash|
+        return nil if hash.nil?
+
+        attrs = fields.to_h { |field| [field, Core.cast(hash[field.to_s], casts[field])] }
+        new(**attrs)
+      end
+      klass
+    end
+
+    def cast(value, how)
+      return value if how.nil? || value.nil?
+
+      case how
+      when :decimal then BigDecimal(value.to_s)
+      when :symbol then value.to_sym
+      when :time then local_time(value)
+      when Array then value.map { |item| how.first.from_h(item) }
+      else how.from_h(value)
+      end
+    end
+  end
+end

data/lib/openhub_bo/core/native_bridge.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module OpenhubBo
+  module Core
+    # A native extension exposing `call(op, payload) -> String`. Checks the
+    # protocol on load and caches the operation catalog from `describe`, so
+    # declared operations are validated when the gem is required.
+    class NativeBridge
+      attr_reader :operations, :version
+
+      def initialize(mod)
+        protocol = mod.protocol_version
+        unless protocol == SUPPORTED_PROTOCOL
+          raise LoadError,
+                "#{mod} speaks core protocol #{protocol}, this gem expects #{SUPPORTED_PROTOCOL}; " \
+                "install matching openhub-bo versions"
+        end
+        @mod = mod
+        @version = mod.version
+        @operations = invoke("describe", {}).to_h { |entry| [entry["name"], entry] }.freeze
+      end
+
+      def invoke(op, payload)
+        result = JSON.parse(@mod.call(op, JSON.generate(payload)))
+        return result["value"] if result["ok"]
+
+        raise Core.error_from_core(result["error"], op)
+      end
+    end
+  end
+end

data/lib/openhub_bo/core/op.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module OpenhubBo
+  module Core
+    # An HTTP endpoint implemented by a native extension. Declaring one with a
+    # name the extension does not know raises LoadError at require time.
+    class Op
+      attr_reader :native, :name
+
+      def initialize(native, name, &decode)
+        info = native.operations[name]
+        raise LoadError, "native extension has no operation `#{name}`" unless info && info["kind"] == "operation"
+
+        @native = native
+        @name = name
+        @decode = decode || ->(value) { value }
+        @info = info
+      end
+
+      def idempotent? = @info["idempotent"] == true
+
+      # Client timeout (seconds) recommended by ATC for this endpoint, if any.
+      def timeout = @info["timeout_secs"]
+
+      def build(config, token, input)
+        request = native.invoke("#{name}.build", { "config" => config, "token" => token, "input" => input })
+        request["timeout"] = timeout if timeout
+        request
+      end
+
+      def parse(input, response)
+        @decode.call(native.invoke("#{name}.parse", { "input" => input, "response" => response.to_wire }))
+      end
+    end
+
+    # A pure native function (no HTTP), e.g. webhook parsing.
+    class Handler
+      def initialize(native, name, &decode)
+        info = native.operations[name]
+        raise LoadError, "native extension has no handler `#{name}`" unless info && info["kind"] == "handler"
+
+        @native = native
+        @name = name
+        @decode = decode || ->(value) { value }
+      end
+
+      def call(input) = @decode.call(@native.invoke(@name, input))
+    end
+  end
+end

data/lib/openhub_bo/core/session.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module OpenhubBo
+  module Core
+    NATIVE = NativeBridge.new(Native)
+    TOKEN = Op.new(NATIVE, "token")
+
+    # Credentials, token cache and execution of operations. Share one session
+    # between product clients (QrClient.new(session), PixClient.new(session)...)
+    # so they reuse the OAuth token. Thread-safe.
+    class Session
+      attr_reader :environment
+
+      def initialize(client_id, client_secret = nil, basic_token: nil, environment: Environment::SANDBOX,
+                     base_url: nil, timeout: 30, transport: nil)
+        @environment = environment.to_sym
+        unless Environment::ALL.include?(@environment)
+          raise ValidationError.new("must be one of #{Environment::ALL.join(', ')}", field: "environment")
+        end
+
+        @config = {
+          "client_id" => client_id,
+          "client_secret" => client_secret,
+          "basic_token" => basic_token,
+          "environment" => @environment.to_s,
+          "base_url" => base_url
+        }
+        @transport = transport || NetHttpTransport.new(timeout: timeout)
+        @token = nil
+        @lock = Mutex.new
+        # Fail fast on missing credentials instead of at the first request.
+        TOKEN.build(@config, nil, token_input)
+      end
+
+      # Runs `op`: token, build, send, parse; refreshes a rejected token once.
+      def execute(op, input)
+        2.times do |attempt|
+          token = ensure_token
+          response = deliver(op, op.build(@config, token, input))
+          begin
+            return op.parse(input, response)
+          rescue AuthenticationError
+            raise if attempt == 1
+
+            invalidate(token)
+          end
+        end
+      end
+
+      def close = @transport.close
+
+      def inspect = "#<#{self.class.name} client_id=#{@config['client_id'].inspect} environment=#{@environment}>"
+      alias_method :to_s, :inspect
+
+      private
+
+      def ensure_token
+        @lock.synchronize do
+          token = @token
+          return token if token && Time.now.to_i < token["expires_at"]
+
+          @token = TOKEN.parse(token_input, deliver(TOKEN, TOKEN.build(@config, nil, token_input)))
+        end
+      end
+
+      def invalidate(token)
+        @lock.synchronize { @token = nil if @token && @token["access_token"] == token["access_token"] }
+      end
+
+      def deliver(op, request)
+        @transport.perform(request)
+      rescue TransportError => e
+        raise AmbiguousOutcomeError.new(op.name, e) if e.maybe_sent && !op.idempotent?
+
+        raise
+      end
+
+      def token_input = { "now" => Time.now.to_i }
+    end
+  end
+end

data/lib/openhub_bo/core/testing.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "openhub_bo/core"
+
+module OpenhubBo
+  module Core
+    module Testing
+      # In-memory fake of the OpenHub gateway (Sensedia): handles the OAuth token
+      # and the access_token/client_id check like the real gateway; tests or
+      # product gems register routes on top. Use it as a Session transport:
+      #
+      #   gateway = MockGateway.new
+      #   gateway.route("GET", %r{/qr/simple/v2/verify/(\d+)\z}) { |req, m| Response.new(status: 200, body: "...") }
+      #   session = gateway.session
+      class MockGateway
+        BASE_URL = "https://openhub.mock"
+        TOKEN_PATH = "/oauth-client-credentials/access-token"
+
+        attr_reader :client_id, :client_secret, :requests, :token_requests
+
+        def initialize(client_id: "test-client", client_secret: "test-secret", token_ttl: 3600)
+          @client_id = client_id
+          @client_secret = client_secret
+          @token_ttl = token_ttl
+          @requests = []
+          @token_requests = 0
+          @tokens = []
+          @routes = []
+        end
+
+        def route(method, pattern, &handler)
+          @routes << [method.to_s.upcase, pattern, handler]
+          self
+        end
+
+        # Answers matching requests with a fixed status and body.
+        def stub(method, pattern, status:, body:)
+          route(method, pattern) { Response.new(status: status, body: body) }
+        end
+
+        def session(client_secret: @client_secret, **kwargs)
+          Session.new(@client_id, client_secret, base_url: BASE_URL, transport: self, **kwargs)
+        end
+
+        def revoke_tokens = @tokens.clear
+
+        def perform(request)
+          @requests << request
+          path = URI(request["url"]).path
+          return token_response(request) if path.end_with?(TOKEN_PATH)
+          return Response.new(status: 401, body: "Access Token in the request, identified by HEADER access_token, is invalid.") unless authorized?(request)
+
+          @routes.each do |method, pattern, handler|
+            next unless request["method"] == method && (match = pattern.match(path))
+
+            return handler.call(request, match)
+          end
+          Response.new(status: 404, body: JSON.generate({ "success" => false, "message" => "Not found", "errors" => [] }))
+        end
+
+        def close; end
+
+        private
+
+        def token_response(request)
+          @token_requests += 1
+          expected = "Basic #{["#{@client_id}:#{@client_secret}"].pack("m0")}"
+          unless request["headers"]["Authorization"] == expected
+            return Response.new(status: 401, body: JSON.generate({ "error" => "invalid_client", "error_description" => "Bad credentials" }))
+          end
+
+          token = SecureRandom.uuid
+          @tokens << token
+          # Sandbox answers 201 with token_type "access_token" and no scope.
+          Response.new(status: 201, body: JSON.generate({ "access_token" => token, "token_type" => "access_token", "expires_in" => @token_ttl }))
+        end
+
+        def authorized?(request)
+          @tokens.include?(request["headers"]["access_token"]) && request["headers"]["client_id"] == @client_id
+        end
+      end
+    end
+  end
+end

data/lib/openhub_bo/core/transport.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+
+module OpenhubBo
+  module Core
+    Response = Data.define(:status, :body) do
+      def to_wire = { "status" => status, "body" => body }
+    end
+
+    # Sends requests built by the native core. Any object responding to
+    # `perform(request) -> Response` works: inject your own for proxies,
+    # logging or fakes. `request` is {"method", "url", "headers", "body",
+    # "timeout"?}; raise TransportError on network failures.
+    class NetHttpTransport
+      # Failures where the request provably never reached the server.
+      NOT_SENT = [
+        Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ENETUNREACH, Net::OpenTimeout, SocketError
+      ].freeze
+      MAYBE_SENT = [
+        Net::ReadTimeout, Net::WriteTimeout, EOFError, IOError, Errno::ECONNRESET, Errno::EPIPE,
+        OpenSSL::SSL::SSLError
+      ].freeze
+
+      def initialize(timeout: 30, open_timeout: 10)
+        @timeout = timeout
+        @open_timeout = open_timeout
+      end
+
+      def perform(request)
+        uri = URI(request["url"])
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = @open_timeout
+        http.read_timeout = request["timeout"] || @timeout
+        http.write_timeout = request["timeout"] || @timeout
+        body = request["body"]
+        message = Net::HTTPGenericRequest.new(
+          request["method"], !body.nil?, true, uri.request_uri, request["headers"]
+        )
+        message.body = body if body
+        response = http.start { |conn| conn.request(message) }
+        Response.new(status: response.code.to_i, body: response.body.to_s.dup.force_encoding(Encoding::UTF_8))
+      rescue *NOT_SENT => e
+        raise TransportError.new("#{e.class}: #{e.message}", maybe_sent: false)
+      rescue *MAYBE_SENT => e
+        raise TransportError.new("#{e.class}: #{e.message}", maybe_sent: true)
+      end
+
+      def close; end
+    end
+  end
+end

data/lib/openhub_bo/core/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module OpenhubBo
+  module Core
+    VERSION = "0.1.0"
+    # Core FFI protocol this Ruby code speaks (see `openhub_bo_core::ffi`).
+    SUPPORTED_PROTOCOL = 2
+  end
+end

data/lib/openhub_bo/core.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Shared foundation of the openhub-bo gems: session, transport, errors and
+# common types for the Red Enlace (ATC) OpenHub APIs.
+require "bigdecimal"
+require "json"
+
+require_relative "core/version"
+require_relative "core/errors"
+require_relative "core/models"
+require_relative "core/native_bridge"
+require_relative "core/op"
+require_relative "core/transport"
+begin
+  # Precompiled gems ship one binary per Ruby minor version.
+  require "openhub_bo/core/#{RUBY_VERSION[/\d+\.\d+/]}/openhub_bo_core"
+rescue LoadError
+  require "openhub_bo/core/openhub_bo_core"
+end
+require_relative "core/session"

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: openhub-bo-core
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: x86_64-linux
+authors:
+- Felix Daniel Coca Calvimontes
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-10-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+description: Sesión OAuth, transporte, errores y tipos compartidos de los clientes
+  openhub-bo para Red Enlace (ATC) OpenHub, Bolivia. Núcleo en Rust compartido con
+  los paquetes openhub-bo de Python y TypeScript. Integración no oficial, sin afiliación
+  con Red Enlace (ATC).
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- NOTICE
+- README.md
+- lib/openhub_bo/core.rb
+- lib/openhub_bo/core/3.2/openhub_bo_core.so
+- lib/openhub_bo/core/3.3/openhub_bo_core.so
+- lib/openhub_bo/core/3.4/openhub_bo_core.so
+- lib/openhub_bo/core/4.0/openhub_bo_core.so
+- lib/openhub_bo/core/errors.rb
+- lib/openhub_bo/core/models.rb
+- lib/openhub_bo/core/native_bridge.rb
+- lib/openhub_bo/core/op.rb
+- lib/openhub_bo/core/session.rb
+- lib/openhub_bo/core/testing.rb
+- lib/openhub_bo/core/transport.rb
+- lib/openhub_bo/core/version.rb
+homepage: https://github.com/drkpkg/openhub-bo-integration
+licenses:
+- Apache-2.0
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/drkpkg/openhub-bo-integration
+  bug_tracker_uri: https://github.com/drkpkg/openhub-bo-integration/issues
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Sesión OAuth, transporte, errores y tipos compartidos de los clientes openhub-bo
+  para Red Enlace (ATC) OpenHub, Bolivia
+test_files: []