chargezen 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9042991df178156dda472065dcd4f384ea83f15b2bdd0ef7b0de7b9fa9db9821
+  data.tar.gz: 61dea04fd191f9162095747695ae4890407176f112b2034a37b2914bc5e76590
+SHA512:
+  metadata.gz: 5a681d05535c3a540ee64f889f704131d2613ae4e5a3070c69d380faa36d7672777e6934ba6caebaf0c6d3a04be67602024f0efef2d99a97139684be9df9ef00
+  data.tar.gz: 8615a7288dd9fa1f909abd0b836d3e9a8494c8357fb89fd276bda6917c11900ca5f25136a3fa023d8d5a6f38ee383a25a2530e2aee15a8cc9b613308562bd9d5

data/README.md

@@ -0,0 +1,32 @@
+# Chargezen Ruby SDK
+
+The Chargezen API (`https://api.chargezen.com/v1`) from your backend: customers, subscriptions, products,
+plans and email. Plain Ruby, no dependencies. Keys are secret; never use them in a browser.
+
+```ruby
+require "chargezen"
+require "securerandom"
+
+chargezen = Chargezen::Client.new(key_id: ENV.fetch("CHARGEZEN_KEY_ID"), secret: ENV.fetch("CHARGEZEN_SECRET"))
+
+customers = chargezen.get("/customers", query: { query: "ada@example.com" })
+customer_id = customers["customers"].first.dig("customer_ref", "id")
+
+# Every change takes an Idempotency-Key. Keep it: sending the same key again retries safely.
+chargezen.post("/customers/#{customer_id}/subscriptions/123/pause", { resume_on: "2027-01-12" },
+               idempotency_key: SecureRandom.uuid)
+```
+
+Answers are the parsed JSON bodies. A refusal raises `Chargezen::Error` with `status`, `code`, `message`
+and `failure`; `failure == "temporary"` means a retry with the same Idempotency-Key can succeed.
+
+`order_now` repeats Order now while the charge is still processing, and `wait_for_subscription_creation`
+follows a new subscription until it is ready.
+
+Every path, parameter and body is in the API contract, `Chargezen/public_api/openapi.yaml`.
+
+## Development
+
+The journey test runs this SDK against a real Chargezen API on Factory:
+`../scripts/cz-test playwright --config playwright.journey.config.js`. The gem build:
+`../scripts/cz-test playwright --config playwright.build-check.config.js`.

data/lib/chargezen/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Chargezen
+  VERSION = "0.1.0"
+end

data/lib/chargezen.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require_relative "chargezen/version"
+
+# The Chargezen API (https://api.chargezen.com/v1) from a merchant's backend. Paths, parameters and bodies
+# are the ones in the API contract, Chargezen/public_api/openapi.yaml.
+module Chargezen
+  # A refusal from the API. `failure` is "temporary" when a retry (with the same Idempotency-Key) can succeed.
+  class Error < StandardError
+    attr_reader :status, :code, :failure
+
+    def initialize(status:, message:, code: nil, failure: nil)
+      super(message)
+      @status = status
+      @code = code
+      @failure = failure
+    end
+  end
+
+  # One API answer: the HTTP status and the parsed JSON body.
+  Response = Struct.new(:status, :body)
+
+  class Client
+    def initialize(key_id:, secret:, base_url: "https://api.chargezen.com/v1")
+      @key_id = key_id
+      @secret = secret
+      @base_url = base_url.chomp("/")
+    end
+
+    # chargezen.get("/customers", query: { query: "ada@example.com" }) returns the parsed JSON body.
+    def get(path, query: {})
+      request(Net::HTTP::Get, path, query: query).body
+    end
+
+    # Every change takes an Idempotency-Key: make one per change (SecureRandom.uuid) and send the same key
+    # again to retry it safely. Returns the parsed JSON body.
+    def post(path, body = {}, idempotency_key:)
+      request(Net::HTTP::Post, path, body: body, headers: { "Idempotency-Key" => idempotency_key }).body
+    end
+
+    # Places the subscription's next coming order now. While the charge is still settling the API answers
+    # 202 "processing"; this repeats the request with the same Idempotency-Key, which never charges twice,
+    # until the order is placed or needs the customer's payment approval, or `timeout` seconds pass (then
+    # it returns the last "processing" answer: call again with the same key to keep waiting).
+    def order_now(customer_id:, subscription_id:, billing_occurrence:, idempotency_key:, interval:, timeout:)
+      path = "/customers/#{customer_id}/subscriptions/#{subscription_id}/order_now"
+      poll(interval: interval, timeout: timeout) do
+        response = request(Net::HTTP::Post, path, body: { billing_occurrence: billing_occurrence },
+                                                  headers: { "Idempotency-Key" => idempotency_key })
+        [response.body, response.status == 202]
+      end
+    end
+
+    # Follows a subscription creation (the id POST /customers/{customer_id}/subscriptions returned) until it
+    # is "ready", or `timeout` seconds pass (then it returns the last "pending" answer).
+    def wait_for_subscription_creation(creation_id, interval:, timeout:)
+      poll(interval: interval, timeout: timeout) do
+        body = get("/subscription_creations/#{creation_id}")
+        [body, body["status"] == "pending"]
+      end
+    end
+
+    private
+
+    # Repeats the block, which returns [answer, still_waiting], until it stops waiting or time runs out.
+    def poll(interval:, timeout:)
+      deadline = monotonic_now + timeout
+      loop do
+        answer, still_waiting = yield
+        return answer unless still_waiting && monotonic_now + interval <= deadline
+
+        sleep interval
+      end
+    end
+
+    def request(method, path, query: {}, body: nil, headers: {})
+      uri = URI("#{@base_url}#{path}")
+      uri.query = encode_query(query) unless query.empty?
+      http_request = method.new(uri, headers.merge("X-Chargezen-Key-Id" => @key_id, "Authorization" => "Bearer #{@secret}",
+                                                   "Accept" => "application/json"))
+      if body
+        http_request["Content-Type"] = "application/json"
+        http_request.body = JSON.generate(body)
+      end
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(http_request) }
+      answer(response)
+    end
+
+    def answer(response)
+      status = response.code.to_i
+      body = response.body.to_s.empty? ? {} : JSON.parse(response.body)
+      return Response.new(status, body) if status < 400
+
+      # The email API refuses with { "error": "message" }; every other path with { "error": { code, message, failure } }.
+      error = body["error"].is_a?(Hash) ? body["error"] : { "message" => body["error"].to_s }
+      raise Error.new(status: status, code: error["code"], message: error["message"], failure: error["failure"])
+    end
+
+    # Nested hashes become key[child]=value, the way the API reads product_selection and plan_ref.
+    def encode_query(params, prefix = nil)
+      params.flat_map do |key, value|
+        name = prefix ? "#{prefix}[#{key}]" : key.to_s
+        value.is_a?(Hash) ? encode_query(value, name) : URI.encode_www_form([[name, value]])
+      end.join("&")
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

metadata

@@ -0,0 +1,46 @@
+--- !ruby/object:Gem::Specification
+name: chargezen
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Chargezen
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-11-09 00:00:00.000000000 Z
+dependencies: []
+description:
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/chargezen.rb
+- lib/chargezen/version.rb
+homepage: https://github.com/Chargezen/chargezen-ruby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/Chargezen/chargezen-ruby
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for the Chargezen API
+test_files: []