inttegro 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 840b8af59190645ef6ac41b2ef017921552f43eafff04432ddfbb727084b3c80
+  data.tar.gz: 3a74759e94a33b8f7422c2c2e9ee75a8c32d96f21b58431b965e0baeb62783c8
+SHA512:
+  metadata.gz: e83ba193e1b1a1557f2c1202455c748475a09619be837f1d9d1a709b122b24b883ccb807b9ab4f57b731a0aaf94a1845019523de5f0e47ac54c570f051357557
+  data.tar.gz: 6cd7e942dff74db2a5f50eb841f8baefd2bf95d36df621fef4639b96401cdbc8ca95a8c5ae81c8441216770499cb21fc13019bd0b66ef1355d0a54c9539ed3d1

data/.dockerignore

@@ -0,0 +1,9 @@
+.git
+.github
+node_modules
+vendor
+dist
+out
+coverage
+__pycache__
+*.pyc

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+## [Unreleased]
+
+## [1.0.0] - 2026-09-01
+
+- Breaking: rename the gem, root module, require paths, and generated RBI namespace to `inttegro` and `Inttegro`.
+- Add `typed: strict` Sorbet coverage, runtime signatures, and packaged RBI
+  declarations for every client resource, endpoint method, model, and enum.
+- Remove Sorbet escape hatches from the SDK type surface, validate custom HTTP
+  adapter responses at the transport boundary, and reject generic response
+  fallbacks for documented endpoints.
+- Generate immutable `T::Struct` request and response resources plus real
+  `T::Enum` values from the public OpenAPI contract.
+- Add exact response typing for every documented JSON operation and local/CI
+  drift checks that fail when OpenAPI, generated models, or resource RBIs differ.
+- Remove the financial-account archive and verification SDK methods because the
+  current API does not implement them and exposes no successful response shape.
+- Align package metadata, examples, and the transport user agent with the public Inttegro service name.

data/Dockerfile

@@ -0,0 +1,23 @@
+# syntax=docker/dockerfile:1.7
+
+FROM ruby:3.3-alpine AS base
+WORKDIR /app
+RUN apk add --no-cache build-base git
+COPY Gemfile Gemfile.lock inttegro.gemspec Rakefile ./
+COPY lib ./lib
+COPY test ./test
+RUN bundle config set without ''
+RUN bundle install
+
+# Build gem for RubyGems distribution
+FROM base AS dist
+RUN gem build inttegro.gemspec
+RUN mkdir -p /out && mv ./*.gem /out/
+
+# CI target (use in GitHub Actions)
+FROM base AS ci
+RUN bundle exec rake test
+
+# Local/development target
+FROM base AS dev
+CMD ["sh"]

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025-present Inttegro Financial Technologies Limited
+
+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,104 @@
+# Inttegro Ruby SDK
+
+The official Ruby client for building server-side Inttegro integrations.
+
+> **Fastest, most modern path:** connect an agent to [Inttegro MCP](https://studio.inttegro.com/inttegro-mcp) at `https://mcp.inttegro.com`, then ask it to run `design_integration`. It will produce an implementation and test plan for your application. Use this SDK when you are ready to connect that plan to your Ruby service.
+
+All official Inttegro SDKs expose the same API capabilities. This gem adds strict Sorbet types and Ruby-native resource methods.
+
+## Install
+
+Requires Ruby 3.0 or newer.
+
+```bash
+bundle add inttegro
+```
+
+Store your secret key in the server environment:
+
+```bash
+export INTTEGRO_API_KEY="your_secret_key"
+```
+
+Never put the key in browser code, a mobile app, or source control. The client uses `https://api.inttegro.com` by default.
+
+## Create a hosted checkout
+
+Create and finalize an order, then send the customer to its hosted invoice URL:
+
+```ruby
+# typed: strict
+
+require "inttegro"
+
+inttegro = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
+
+begin
+  result = inttegro.orders.create(
+    request_meta: { idempotency_key: "checkout-cart-123" },
+    customer_data: {
+      name: "Akua Mensah",
+      email_address: "akua@example.com",
+      phone_number: "+233544998605"
+    },
+    finalize: true,
+    checkout_settings: {
+      redirect_url: "https://example.com/orders/complete",
+      cancel_url: "https://example.com/cart"
+    },
+    line_items: [{
+      type: "product",
+      product: {
+        type: Inttegro::Enums::ProductType::DIGITAL,
+        name: "Monthly subscription",
+        quantity: 1,
+        price: { currency: "ghs", value: 5000 }
+      }
+    }]
+  )
+
+  checkout_url = result.order.invoice&.format_value&.web&.url
+  raise "Order did not include a checkout URL" unless checkout_url
+  puts "#{result.order.id} #{checkout_url}"
+rescue Inttegro::APIError => error
+  warn "#{error.code || 'api_error'}: #{error.detail || error.message}"
+  raise
+end
+```
+
+Amounts use integer minor units: `5000` GHS is GHS 50.00. Reuse the same idempotency key when retrying the same logical write. If you omit one, the SDK generates a UUIDv7 key for mutating calls.
+
+## Work with the API
+
+The SDK covers orders and checkout, customers, products and prices, purchase intents, payment methods, balances, payouts and refunds, notifications, files, application settings, keys, and country specifications. Resources use snake-case readers such as `purchase_intents` and `payment_methods`.
+
+Ruby-specific features:
+
+- `typed: strict` throughout the gem with signatures on every method.
+- OpenAPI-generated `T::Struct` request and response models for exact resource shapes.
+- OpenAPI-generated `T::Enum` classes for public API values.
+- Typed resource methods, binary downloads, and public RBI files included in the gem.
+- Configurable connection/read timeouts and an injectable adapter for tests.
+
+Hash request payloads remain available for concise Ruby code. Sorbet applications can use the generated classes under `Inttegro::Models` when they want construction-time field checks.
+
+See the [API reference](https://studio.inttegro.com/api-reference) for request fields and lifecycle rules, [errors](https://studio.inttegro.com/errors) for recovery guidance, and [idempotency](https://studio.inttegro.com/idempotency) for safe retries.
+
+## Verify a release
+
+The GitHub release for each version is the canonical record. It contains the exact gem uploaded to RubyGems.org, SHA-256 checksums, and GitHub and RubyGems Sigstore attestations tied to the source commit and release workflow.
+
+```bash
+sha256sum --check SHA256SUMS
+gh attestation verify inttegro-1.0.0.gem \
+  --repo zebodotdev/inttegro-sdk-ruby
+```
+
+## Develop
+
+```bash
+bundle install
+bundle exec rake test
+bundle exec rake sorbet
+bundle exec rake openapi:check
+```

data/Rakefile

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+namespace :rbi do
+  desc "Regenerate Sorbet declarations for models, enums, and resources"
+  task :generate do
+    sh "bin/generate-sorbet-rbi"
+  end
+
+  desc "Verify generated Sorbet declarations are current"
+  task :check do
+    sh "bin/generate-sorbet-rbi --check"
+  end
+end
+
+namespace :openapi do
+  desc "Regenerate T::Struct, T::Enum, and operation types from the public OpenAPI contract"
+  task :generate do
+    sh "bin/generate-openapi-types"
+    sh "bin/generate-sorbet-rbi"
+  end
+
+  desc "Verify generated SDK types match the public OpenAPI contract"
+  task :check do
+    sh "bin/generate-openapi-types --check"
+    sh "bin/check-openapi-parity"
+  end
+end
+
+namespace :sorbet do
+  desc "Verify the SDK is typed: strict and contains no type escape hatches"
+  task :strict do
+    sh "bin/check-sorbet-strict"
+  end
+end
+
+desc "Type-check the SDK with Sorbet"
+task sorbet: ["sorbet:strict", "openapi:check", "rbi:check"] do
+  sh "srb tc"
+end
+
+task default: %i[test rubocop sorbet]

data/lib/inttegro/client.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+# typed: strict
+
+require_relative "http_client"
+require_relative "types"
+require_relative "resources/orders"
+require_relative "resources/otp"
+require_relative "resources/chimes"
+require_relative "resources/schedules"
+require_relative "resources/broadcasts"
+require_relative "resources/message_templates"
+require_relative "resources/payment_methods"
+require_relative "resources/payouts"
+require_relative "resources/refunds"
+require_relative "resources/balance_transactions"
+require_relative "resources/financial_accounts"
+require_relative "resources/file_references"
+require_relative "resources/files"
+require_relative "resources/file_links"
+require_relative "resources/customers"
+require_relative "resources/products"
+require_relative "resources/prices"
+require_relative "resources/purchase_intents"
+require_relative "resources/spec"
+require_relative "resources/balances"
+require_relative "resources/upload_requests"
+require_relative "resources/apps"
+require_relative "resources/keys"
+
+module Inttegro
+  # Main entry point for interacting with the Inttegro API.
+  class Client
+    extend T::Sig
+
+    sig { returns(Resources::Orders) }
+    attr_reader :orders
+
+    sig { returns(Resources::Otp) }
+    attr_reader :otp
+
+    sig { returns(Resources::Chimes) }
+    attr_reader :chimes
+
+    sig { returns(Resources::Schedules) }
+    attr_reader :schedules
+
+    sig { returns(Resources::Broadcasts) }
+    attr_reader :broadcasts
+
+    sig { returns(Resources::MessageTemplates) }
+    attr_reader :message_templates
+
+    sig { returns(Resources::PaymentMethods) }
+    attr_reader :payment_methods
+
+    sig { returns(Resources::Payouts) }
+    attr_reader :payouts
+
+    sig { returns(Resources::Refunds) }
+    attr_reader :refunds
+
+    sig { returns(Resources::BalanceTransactions) }
+    attr_reader :balance_transactions
+
+    sig { returns(Resources::FinancialAccounts) }
+    attr_reader :financial_accounts
+
+    sig { returns(Resources::FileReferences) }
+    attr_reader :file_references
+
+    sig { returns(Resources::Files) }
+    attr_reader :files
+
+    sig { returns(Resources::FileLinks) }
+    attr_reader :file_links
+
+    sig { returns(Resources::Customers) }
+    attr_reader :customers
+
+    sig { returns(Resources::Products) }
+    attr_reader :products
+
+    sig { returns(Resources::Prices) }
+    attr_reader :prices
+
+    sig { returns(Resources::PurchaseIntents) }
+    attr_reader :purchase_intents
+
+    sig { returns(Resources::Balances) }
+    attr_reader :balances
+
+    sig { returns(Resources::Apps) }
+    attr_reader :apps
+
+    sig { returns(Resources::Keys) }
+    attr_reader :keys
+
+    sig { returns(Resources::Spec) }
+    attr_reader :spec
+
+    sig { returns(Resources::UploadRequests) }
+    attr_reader :upload_requests
+
+    sig do
+      params(
+        token_value: T.nilable(String),
+        api_key: T.nilable(String),
+        token: T.nilable(String),
+        base_url: T.nilable(String),
+        read_timeout: T.nilable(Numeric),
+        open_timeout: T.nilable(Numeric),
+        adapter: T.nilable(Types::Adapter)
+      ).void
+    end
+    def initialize(
+      token_value = nil,
+      api_key: nil,
+      token: nil,
+      base_url: DEFAULT_BASE_URL,
+      read_timeout: 30,
+      open_timeout: 10,
+      adapter: nil
+    )
+      provided_token = token || token_value
+      api_key ||= provided_token
+      @http = T.let(HTTPClient.new(
+        api_key: api_key,
+        base_url: base_url,
+        read_timeout: read_timeout,
+        open_timeout: open_timeout,
+        adapter: adapter
+      ), HTTPClient)
+
+      @orders = T.let(Resources::Orders.new(@http), Resources::Orders)
+      @otp = T.let(Resources::Otp.new(@http), Resources::Otp)
+      @chimes = T.let(Resources::Chimes.new(@http), Resources::Chimes)
+      @schedules = T.let(Resources::Schedules.new(@http), Resources::Schedules)
+      @broadcasts = T.let(Resources::Broadcasts.new(@http), Resources::Broadcasts)
+      @message_templates = T.let(Resources::MessageTemplates.new(@http), Resources::MessageTemplates)
+      @payment_methods = T.let(Resources::PaymentMethods.new(@http), Resources::PaymentMethods)
+      @payouts = T.let(Resources::Payouts.new(@http), Resources::Payouts)
+      @refunds = T.let(Resources::Refunds.new(@http), Resources::Refunds)
+      @balance_transactions = T.let(Resources::BalanceTransactions.new(@http), Resources::BalanceTransactions)
+      @financial_accounts = T.let(Resources::FinancialAccounts.new(@http), Resources::FinancialAccounts)
+      @file_references = T.let(Resources::FileReferences.new(@http), Resources::FileReferences)
+      @files = T.let(Resources::Files.new(@http), Resources::Files)
+      @file_links = T.let(Resources::FileLinks.new(@http), Resources::FileLinks)
+      @customers = T.let(Resources::Customers.new(@http), Resources::Customers)
+      @products = T.let(Resources::Products.new(@http), Resources::Products)
+      @prices = T.let(Resources::Prices.new(@http), Resources::Prices)
+      @purchase_intents = T.let(Resources::PurchaseIntents.new(@http), Resources::PurchaseIntents)
+      @balances = T.let(Resources::Balances.new(@http), Resources::Balances)
+      @apps = T.let(Resources::Apps.new(@http), Resources::Apps)
+      @keys = T.let(Resources::Keys.new(@http), Resources::Keys)
+      @spec = T.let(Resources::Spec.new(@http), Resources::Spec)
+      @upload_requests = T.let(Resources::UploadRequests.new(@http), Resources::UploadRequests)
+    end
+  end
+end

data/lib/inttegro/enums.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+# typed: strict
+
+# Public enum classes are generated directly from the OpenAPI contract. Each
+# constant is a T::Enum value; call #serialize when a raw wire value is needed.
+require_relative "generated/enums"

data/lib/inttegro/errors.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+# typed: strict
+
+require "sorbet-runtime"
+
+require_relative "types"
+
+module Inttegro
+  class Error < StandardError; end
+
+  class NetworkError < Error
+    extend T::Sig
+
+    sig { returns(T.nilable(Exception)) }
+    attr_reader :original_error
+
+    sig { params(message: String, original_error: T.nilable(Exception)).void }
+    def initialize(message, original_error = nil)
+      super(message)
+      @original_error = original_error
+    end
+  end
+
+  class TimeoutError < NetworkError; end
+
+  class APIError < Error
+    extend T::Sig
+
+    sig { returns(Integer) }
+    attr_reader :status
+
+    sig { returns(T.nilable(String)) }
+    attr_reader :code, :type, :url, :detail, :fix_code, :cause, :body
+
+    sig { returns(Types::WireValue) }
+    attr_reader :data
+
+    sig do
+      params(
+        message: String,
+        status: Integer,
+        code: T.nilable(String),
+        type: T.nilable(String),
+        url: T.nilable(String),
+        detail: T.nilable(String),
+        fix_code: T.nilable(String),
+        cause: T.nilable(String),
+        body: T.nilable(String),
+        data: Types::WireValue
+      ).void
+    end
+    def initialize(
+      message,
+      status:,
+      code: nil,
+      type: nil,
+      url: nil,
+      detail: nil,
+      fix_code: nil,
+      cause: nil,
+      body: nil,
+      data: nil
+    )
+      super(message)
+      @status = status
+      @code = code
+      @type = type
+      @url = url
+      @detail = detail
+      @fix_code = fix_code
+      @cause = cause
+      @body = body
+      @data = data
+    end
+  end
+
+  class AuthenticationError < APIError; end
+
+  class RateLimitError < APIError
+    extend T::Sig
+
+    sig { returns(T.nilable(Integer)) }
+    attr_reader :retry_after
+
+    sig do
+      params(
+        message: String,
+        status: Integer,
+        code: T.nilable(String),
+        type: T.nilable(String),
+        url: T.nilable(String),
+        detail: T.nilable(String),
+        fix_code: T.nilable(String),
+        cause: T.nilable(String),
+        body: T.nilable(String),
+        data: Types::WireValue,
+        retry_after: T.nilable(Integer)
+      ).void
+    end
+    def initialize(
+      message,
+      status:,
+      code: nil,
+      type: nil,
+      url: nil,
+      detail: nil,
+      fix_code: nil,
+      cause: nil,
+      body: nil,
+      data: nil,
+      retry_after: nil
+    )
+      super(
+        message,
+        status: status,
+        code: code,
+        type: type,
+        url: url,
+        detail: detail,
+        fix_code: fix_code,
+        cause: cause,
+        body: body,
+        data: data
+      )
+      @retry_after = retry_after
+    end
+  end
+end

data/lib/inttegro/file_download.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+# typed: strict
+
+require "sorbet-runtime"
+
+require_relative "types"
+
+module Inttegro
+  class FileDownload
+    extend T::Sig
+
+    sig { returns(String) }
+    attr_reader :data
+
+    sig { returns(Types::ResponseHeaders) }
+    attr_reader :headers
+
+    sig { params(data: String, headers: Types::ResponseHeaders).void }
+    def initialize(data, headers = {})
+      @data = data
+      @headers = headers
+    end
+
+    sig { params(path: String).returns(Integer) }
+    def save_to(path)
+      File.binwrite(path, data)
+    end
+  end
+end