sumwerk 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d38a9abf2902acc55d8f5474c36ad67db25a4482223b66ac5b9a1a2d7ce05321
+  data.tar.gz: 3b5f84316a0ba01131a9816c9b474cb8f4ca9559b4105a8f41bb96c6403a380b
+SHA512:
+  metadata.gz: 768dfd41b92ad3c4f7cfddbd19018a02c3731949e2bc2fddc73125eb9599472a4b96b11922526d1dba6cdab619e55d91d50ed6fea1b95bac9b3bf7e59613abe9
+  data.tar.gz: 5b1b8b334f57af2115f5cc7f9658a418ae672b984b4269ffa2a7c68a4b55889f962c9cc9406e42c95b29613dcb9f51cb3b31733b6cc7f31f5474dc01d5ca7640

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kitchn Venture GmbH
+
+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,84 @@
+# sumwerk for Ruby
+
+The sumwerk API for Ruby 3.2 and newer: every call with errors and retries, and your customers' billing answers from a
+local copy. Reference: https://www.sumwerk.com/docs/api
+
+```ruby
+# Gemfile
+gem "sumwerk"
+```
+
+## The API
+
+```ruby
+sumwerk = Sumwerk::Client.new(token: ENV.fetch("SUMWERK_TOKEN"))   # Account → API and exports
+
+sumwerk.customers.upsert("nordwind", org.id, name: org.name, email: org.billing_email, stripe_customer_ids: [ org.stripe_id ])
+sumwerk.customers.retrieve(org.id, source: "nordwind")
+sumwerk.customers.each(status: "paying") { |customer| puts customer["name"] }   # every page
+sumwerk.usage.report_day("nordwind", Date.yesterday.iso8601, customers: { org.id => { "ads_launched" => 12 } })
+sumwerk.notes.create(customer_id, body: "Called about the renewal", kind: "call")
+sumwerk.tasks.create(customer_id, title: "Send the proposal", due_on: "2026-10-20")
+sumwerk.mrr.retrieve(range: 12)
+
+sumwerk.billing.report_total("nordwind", org.id, "seats", org.members.count)
+sumwerk.billing.apply("nordwind", org.id, { type: "plan", plan: "business" }, idempotency_key: SecureRandom.uuid)
+sumwerk.request(:get, "/api/v1/me")          # anything the gem has no method for yet
+```
+
+Every area of the API has its object: `customers`, `contacts`, `sources`, `usage`, `usage_metrics`, `attributes`,
+`notes`, `tasks`, `research`, `conversations`, `deals`, `pipelines`, `emails`, `email_templates`, `sequences`,
+`enrollments`, `mrr`, `movements`, `restatements`, `reconciliation`, `segments`, `lifecycle`, `plans`, `at_risk`,
+`risk_rules`, `risk_exceptions`, `events`, `automations`, `log`, `webhook_requests`, `billing` (with
+`billing.overrides` and `billing.plan_assignments`). Parameters are the API's, unchanged; answers are the API's JSON as
+a Hash.
+
+Errors raise a `Sumwerk::Error` with `status`, `code` (the API's `error`) and `message`: `InvalidRequestError` (400,
+422), `AuthenticationError` (401), `PermissionError` (403), `NotFoundError` (404), `ConflictError` (409), `GoneError`
+(410), `RateLimitError` (429, `retry_after`), `APIError` (5xx), `ConnectionError`. Timeouts, lost connections, 5xx and
+429 are retried twice with growing waits for every call that is safe to send again: reads, `PUT`, `DELETE`, usage
+events (each `event_id` counts once) and `apply` with an `idempotency_key`. Sending an email or starting a trial is
+never repeated by itself.
+
+## Billing answers without a call per check
+
+Ask what an org may do in your app without a network call. sumwerk keeps a copy in your Redis current (its webhook, or
+a periodic sync); your own uses count at once and go to sumwerk in batches. When nothing can be known, each
+feature's default from your catalog answers, and sumwerk hears about it.
+
+```ruby
+ANSWERS = Sumwerk::Billing::Client.new(
+  app: "nordwind", token: ENV.fetch("SUMWERK_TOKEN"),    # an account token with read and write access
+  store: Sumwerk::Billing::RedisStore.new(Redis.new),
+  webhook_secret: ENV.fetch("SUMWERK_WEBHOOK_SECRET"), browser_secret: ENV.fetch("SUMWERK_BROWSER_SECRET")
+).start                                                   # flushes usage every few seconds
+
+ANSWERS.entitled?(org.id, :reports)                  # a feature
+ANSWERS.enabled?(org.id, :meta_languages)            # a rollout flag
+ANSWERS.allowed?(org.id, :ad_uploads, 3)             # room for three more, within the tolerance?
+ANSWERS.track(org.id, :ad_uploads, quantity: 3)      # counted now, sent with the next batch
+ANSWERS.report(org.id, :seats, org.users.count)      # a total you count yourself
+ANSWERS.upsert_customer(org.id, name: org.name, email: org.billing_email)
+                                                     # the org as a customer, under your id (true when taken)
+ANSWERS.limit(org.id, :ad_uploads)                   # used, remaining, state: within, near, over_in_tolerance, over, blocked
+ANSWERS.browser_token(org.id)                        # for your page, to read the answer live
+ANSWERS.page_token(org.id, user: user.id, email: user.email, role: "manage")
+                                                     # opens sumwerk's customer pages once, within a minute ("view": no changes)
+
+answer = ANSWERS.answer(org.id)
+answer.plan_source                                        # subscription, assignment, trial, after_cancellation, default, none
+answer.trial                                              # Trial(plan:, ends_on:) or nil: "14 days left of your Business trial"
+answer.cancellation                                       # Cancellation(plan:, ends_on:, ended_on:, until:, then:) or nil
+```
+
+Mount the webhook and, for the browser, the read-only pass-through on your own domain (ad blockers leave it alone):
+
+```ruby
+mount Sumwerk::Billing::Webhook.new(ANSWERS), at: "/sumwerk/billing/webhook"
+mount Sumwerk::Billing::BrowserProxy.new, at: "/sumwerk/billing"
+```
+
+On localhost (no webhook can reach you) run `ANSWERS.sync` every few seconds instead.
+
+The API behind it, the webhook and the retry rules: https://www.sumwerk.com/docs/api#billing-what-each-customer-may-do. The
+TypeScript package (`npm install sumwerk`) answers the same cases the same way. MIT licensed.

data/lib/sumwerk/api.rb

@@ -0,0 +1,268 @@
+module Sumwerk
+  # One class per area of the API (https://www.sumwerk.com/docs/api). Ids in a path are escaped; parameters go as the
+  # query of a read and as the JSON body of a write, unchanged, so a parameter the API learns later works at once.
+  module Api
+    class Resource
+      def initialize(client)
+        @client = client
+      end
+
+      private
+        def get(path, query = {}) = @client.request(:get, path, query: compact(query))
+        def post(path, body = {}, **options) = @client.request(:post, path, body: compact(body), **options)
+        def put(path, body = {}) = @client.request(:put, path, body: compact(body))
+        def patch(path, body = {}) = @client.request(:patch, path, body: compact(body))
+        def delete(path, body = nil) = @client.request(:delete, path, body: body && compact(body))
+        def compact(hash) = hash.to_h.reject { |_, value| value.nil? }
+        def id(value) = Client.escape(value)
+
+        # A customer by our UUID or a Stripe id, or with source: by your id in that source.
+        def customer_path(customer, source) = source ? "/api/v1/sources/#{id(source)}/customers/#{id(customer)}" : "/api/v1/customers/#{id(customer)}"
+    end
+
+    # GET /me: the account, its mode (live or a sandbox) and the token's scope.
+    class Me < Resource
+      def retrieve = get("/api/v1/me")
+    end
+
+    # Your applications and other id sources.
+    class Sources < Resource
+      def list = get("/api/v1/sources")
+      def create(**params) = post("/api/v1/sources", params, idempotent: true) # a second create of the same slug is refused, nothing doubles
+      def update(slug, **params) = patch("/api/v1/sources/#{id(slug)}", params)
+    end
+
+    class Customers < Resource
+      # One page: { "customers" => [...], "pagination" => { "page", "per_page", "next_page" } }.
+      def list(**params) = get("/api/v1/customers", params)
+
+      # Every customer of every page, one by one.
+      def each(**params)
+        return enum_for(:each, **params) unless block_given?
+
+        page = params.fetch(:page, 1)
+        while page
+          answer = list(**params, page:)
+          answer.fetch("customers").each { |customer| yield customer }
+          page = answer.dig("pagination", "next_page")
+        end
+      end
+
+      # By our UUID or a Stripe id; with source: by your id in that source.
+      def retrieve(customer, source: nil) = get(customer_path(customer, source))
+      # Creates (201) or updates (200) the customer of your id in your source: the call your app makes for each org.
+      def upsert(source, external_id, **params) = put(customer_path(external_id, source), params)
+      # Profile fields of a customer by our UUID.
+      def update(customer, **params) = patch(customer_path(customer, nil), params)
+      # A customer that holds nothing but ids (otherwise 422 not_empty).
+      def delete(customer) = super(customer_path(customer, nil))
+      # Another id of yours for the same customer (a second workspace).
+      def add_id(customer, source:, external_id:) = post("/api/v1/customers/#{id(customer)}/external-references", { source:, external_id: }, idempotent: true)
+      def remove_id(customer, value) = @client.request(:delete, "/api/v1/customers/#{id(customer)}/ids/#{id(value)}")
+    end
+
+    # The people of a customer, created or updated by email or external_id.
+    class Contacts < Resource
+      def create(customer, source: nil, **params) = post("#{customer_path(customer, source)}/contacts", params, idempotent: true)
+    end
+
+    # Usage over time: what your app counts per customer and day.
+    class Usage < Resource
+      def retrieve(customer, **params) = get("#{customer_path(customer, nil)}/usage", params)
+      # Some days of one id: days: { "2026-10-08" => { "ads_launched" => 12 } }.
+      def report(source, external_id, days:) = put("#{customer_path(external_id, source)}/usage", { days: })
+      # The whole day of a source, every id at once: customers: { "org_1" => { "ads_launched" => 12 } }.
+      def report_day(source, date, **params) = put("/api/v1/sources/#{id(source)}/usage/#{id(date)}", params)
+    end
+
+    class UsageMetrics < Resource
+      def list = get("/api/v1/usage-metrics")
+      def update(key, **params) = patch("/api/v1/usage-metrics/#{id(key)}", params)
+    end
+
+    class Attributes < Resource
+      def list = get("/api/v1/attributes")
+      def update(key, **params) = patch("/api/v1/attributes/#{id(key)}", params)
+    end
+
+    # Notes and logged calls. An external_id makes a create safe to send again.
+    class Notes < Resource
+      def list(customer, **params) = get("#{customer_path(customer, nil)}/notes", params)
+      def create(customer, **params) = post("#{customer_path(customer, nil)}/notes", params, idempotent: params.key?(:external_id))
+    end
+
+    class Tasks < Resource
+      # A customer's tasks, or with no customer the account's.
+      def list(customer = nil, **params) = get(customer ? "#{customer_path(customer, nil)}/tasks" : "/api/v1/tasks", params)
+      def create(customer, **params) = post("#{customer_path(customer, nil)}/tasks", params, idempotent: params.key?(:external_id))
+      # By our id or your external_id; completed: true ticks it off.
+      def update(task, **params) = patch("/api/v1/tasks/#{id(task)}", params)
+    end
+
+    class Research < Resource
+      def create(customer, **params) = post("#{customer_path(customer, nil)}/research", params)
+      def retrieve(customer) = get("#{customer_path(customer, nil)}/research")
+    end
+
+    class Conversations < Resource
+      def list(customer, **params) = get("#{customer_path(customer, nil)}/conversations", params)
+    end
+
+    class Deals < Resource
+      def list(**params) = get("/api/v1/deals", params)
+      def retrieve(deal) = get("/api/v1/deals/#{id(deal)}")
+      def create(**params) = post("/api/v1/deals", params, idempotent: params.key?(:external_id))
+      def update(deal, **params) = patch("/api/v1/deals/#{id(deal)}", params)
+    end
+
+    class Pipelines < Resource
+      def list = get("/api/v1/pipelines")
+    end
+
+    # Sends an email at once: not retried by itself (a second call is a second email).
+    class Emails < Resource
+      def list(customer, **params) = get("#{customer_path(customer, nil)}/emails", params)
+      def create(customer, **params) = post("#{customer_path(customer, nil)}/emails", params)
+    end
+
+    class EmailTemplates < Resource
+      def list = get("/api/v1/email_templates")
+      def retrieve(template) = get("/api/v1/email_templates/#{id(template)}")
+      def create(**params) = post("/api/v1/email_templates", params)
+      def update(template, **params) = patch("/api/v1/email_templates/#{id(template)}", params)
+      def delete(template) = super("/api/v1/email_templates/#{id(template)}")
+    end
+
+    class Sequences < Resource
+      def list = get("/api/v1/sequences")
+      def retrieve(sequence) = get("/api/v1/sequences/#{id(sequence)}")
+      def create(**params) = post("/api/v1/sequences", params)
+      def update(sequence, **params) = patch("/api/v1/sequences/#{id(sequence)}", params)
+      def delete(sequence) = super("/api/v1/sequences/#{id(sequence)}")
+    end
+
+    class Enrollments < Resource
+      def list(customer) = get("#{customer_path(customer, nil)}/enrollments")
+      def create(customer, **params) = post("#{customer_path(customer, nil)}/enrollments", params)
+      def delete(enrollment) = super("/api/v1/enrollments/#{id(enrollment)}")
+    end
+
+    class Mrr < Resource
+      def retrieve(**params) = get("/api/v1/mrr", params)
+    end
+
+    class Movements < Resource
+      def list(**params) = get("/api/v1/movements", params)
+    end
+
+    class Restatements < Resource
+      def list(**params) = get("/api/v1/restatements", params)
+    end
+
+    class Reconciliation < Resource
+      def retrieve(**params) = get("/api/v1/reconciliation", params)
+    end
+
+    class Segments < Resource
+      def list(**params) = get("/api/v1/segments", params)
+    end
+
+    class Lifecycle < Resource
+      def retrieve(**params) = get("/api/v1/lifecycle", params)
+    end
+
+    # Your plan names for Stripe products.
+    class Plans < Resource
+      def list = get("/api/v1/plans")
+      def history(**params) = get("/api/v1/plans/history", params)
+      def add_products(name, product_ids:) = put("/api/v1/plans/#{id(name)}", { product_ids: })
+      def rename(name, to:) = patch("/api/v1/plans/#{id(name)}", { name: to })
+      # Dissolves the plan, or with product_id: takes that one product out.
+      def delete(name, product_id: nil) = super("/api/v1/plans/#{id(name)}", product_id ? { product_id: } : nil)
+    end
+
+    class AtRisk < Resource
+      def list(**params) = get("/api/v1/at-risk", params)
+    end
+
+    # Your own at-risk rules (signals).
+    class RiskRules < Resource
+      def retrieve = get("/api/v1/risk-rules")
+      def create(**params) = post("/api/v1/risk-rules/signals", params)
+      def update(signal, **params) = patch("/api/v1/risk-rules/signals/#{id(signal)}", params)
+      def delete(signal) = super("/api/v1/risk-rules/signals/#{id(signal)}")
+    end
+
+    # A rule that does not apply to one customer, with a reason.
+    class RiskExceptions < Resource
+      def list(**params) = get("/api/v1/risk-exceptions", params)
+      def set(customer, signal, **params) = put("#{customer_path(customer, nil)}/risk-exceptions/#{id(signal)}", params)
+      def delete(customer, signal) = super("#{customer_path(customer, nil)}/risk-exceptions/#{id(signal)}")
+    end
+
+    class Events < Resource
+      def list(**params) = get("/api/v1/events", params)
+    end
+
+    class Automations < Resource
+      def list = get("/api/v1/automations")
+      def retrieve(automation) = get("/api/v1/automations/#{id(automation)}")
+      def create(**params) = post("/api/v1/automations", params)
+      def update(automation, **params) = patch("/api/v1/automations/#{id(automation)}", params)
+      def delete(automation) = super("/api/v1/automations/#{id(automation)}")
+      def runs(automation, **params) = get("/api/v1/automations/#{id(automation)}/runs", params)
+    end
+
+    class Log < Resource
+      def list(**params) = get("/api/v1/log", params)
+    end
+
+    class WebhookRequests < Resource
+      def list(**params) = get("/api/v1/webhook-requests", params)
+    end
+
+    # What each org may do in your app, and billing management. app is your application source's slug, org your id.
+    class Billing < Resource
+      def overrides = @overrides ||= Overrides.new(@client)
+      def plan_assignments = @plan_assignments ||= PlanAssignments.new(@client)
+
+      def answer(app, org) = get("#{base(app)}/orgs/#{id(org)}")
+      def catalog(app) = get("#{base(app)}/catalog")
+      # Answers and removals newer than a version, 500 a page: { "snapshots", "removed", "next_after_version" }.
+      def changes(app, after_version: 0) = get(base(app), { after_version: })
+      # events: [{ event_id:, org:, feature:, quantity:, occurred_at:, sequence: }], at most 1,000. Each event_id counts once.
+      def report_usage(app, events) = post("#{base(app)}/usage", { events: }, idempotent: true)
+      # The current total of a limit you count yourself (seats); replaces the last one.
+      def report_total(app, org, feature, total) = put("#{base(app)}/totals/#{id(org)}/#{id(feature)}", { total: })
+      def report_fallbacks(app, fallbacks) = post("#{base(app)}/fallbacks", { fallbacks: }, idempotent: true)
+      def start_trial(app, org, **params) = post("#{base(app)}/orgs/#{id(org)}/trial", params)
+
+      # Billing management (switched on by an owner in sumwerk). change: { type: "plan", plan: "business" } and the others.
+      def preview(app, org, change) = post("#{base(app)}/orgs/#{id(org)}/preview", { change: }, idempotent: true)
+      # Pass an idempotency_key (one per intended change): sent again, it answers with the first change and changes nothing.
+      def apply(app, org, change, reason: nil, preview: nil, idempotency_key: nil)
+        headers = idempotency_key ? { "Idempotency-Key" => idempotency_key.to_s } : {}
+        @client.request(:post, "#{base(app)}/orgs/#{id(org)}/apply", body: compact({ change:, reason:, preview: }), headers:)
+      end
+      def checkout(app, org, **params) = post("#{base(app)}/orgs/#{id(org)}/checkout", params, idempotent: true)
+      def portal(app, org, return_url:) = post("#{base(app)}/orgs/#{id(org)}/portal", { return_url: }, idempotent: true)
+
+      private
+        def base(app) = "/api/v1/billing/#{id(app)}"
+    end
+
+    # Free exceptions for one customer (by our id, or with source: by your id).
+    class Overrides < Resource
+      def list(customer, source: nil) = get("#{customer_path(customer, source)}/overrides")
+      def create(customer, source: nil, **params) = post("#{customer_path(customer, source)}/overrides", params)
+      def revoke(customer, override, source: nil) = delete("#{customer_path(customer, source)}/overrides/#{id(override)}")
+    end
+
+    # Plans given by hand, with dates and a reason.
+    class PlanAssignments < Resource
+      def list(customer) = get("#{customer_path(customer, nil)}/plan-assignments")
+      def create(customer, **params) = post("#{customer_path(customer, nil)}/plan-assignments", params)
+      def revoke(customer, assignment) = delete("#{customer_path(customer, nil)}/plan-assignments/#{id(assignment)}")
+    end
+  end
+end

data/lib/sumwerk/billing/answer.rb

@@ -0,0 +1,116 @@
+module Sumwerk
+  module Billing
+    # The answers for one org, from the catalog, the org's snapshot (nil when nothing is known) and the uses this app
+    # counted since. Pure: no network, no store, no clock of its own. Every client answers the same
+    # (clients/conformance/cases.json).
+    class Answer
+      Limit = Data.define(:limit, :tolerance, :used, :remaining, :state, :beyond) do
+        def unlimited? = limit.nil?
+      end
+      Use = Data.define(:feature, :quantity, :sequence, :occurred_at)
+      # A trial that runs: of which plan, until which day.
+      Trial = Data.define(:plan, :ends_on)
+      # A cancellation: scheduled (ends_on) or happened (ended_on, the plan kept until a day or for good), and the
+      # plan that comes after.
+      Cancellation = Data.define(:plan, :ends_on, :ended_on, :until, :then)
+      # A plan change waiting for the end of the period (a downgrade): which plan, from which day.
+      ScheduledChange = Data.define(:plan, :on)
+
+      NEAR = 0.8
+
+      # snapshot: the hash sumwerk published, nil (nothing known), or :unknown_org (sumwerk says it has no such org).
+      def initialize(catalog:, snapshot:, pending: [])
+        @catalog, @pending = catalog || {}, pending
+        @unknown_org = snapshot == :unknown_org
+        @snapshot = snapshot.is_a?(Hash) ? snapshot : nil
+      end
+
+      # When an answer was a default: "unreachable", "unknown_org" or "unknown_feature", else nil.
+      def fallback(key)
+        return "unknown_feature" unless catalog_entry(key) || feature(key)
+        return "unknown_org" if @unknown_org
+        "unreachable" unless @snapshot
+      end
+
+      def entitled?(key)
+        value = feature(key)
+        return default(key, "feature") unless value
+
+        value["kind"] == "limit" ? allowed?(key) : value["enabled"] == true
+      end
+
+      def enabled?(key)
+        value = feature(key)
+        value ? value["enabled"] == true : false # an unknown rollout flag is off
+      end
+
+      def limit(key)
+        value = feature(key) or return nil
+        limit, tolerance, beyond = value["limit"], value["tolerance"].to_i, value["beyond"] || "block"
+        used = value["used"].to_i + own_uses(key, value)
+        remaining = (limit && beyond == "block") ? [ limit + tolerance - used, 0 ].max : nil
+        Limit.new(limit:, tolerance:, used:, remaining:, state: state_of(limit, tolerance, used, beyond), beyond:)
+      end
+
+      # May the org use quantity more of this limit?
+      def allowed?(key, quantity = 1)
+        found = limit(key)
+        return default(key, "limit") unless found
+        return true if found.unlimited? || found.beyond == "notify"
+
+        found.used + quantity <= found.limit + found.tolerance
+      end
+
+      def plan = @snapshot&.dig("plan", "key")
+      # Why the org has its plan: "subscription", "assignment", "unmapped" (a running subscription no plan is mapped
+      # for: no plan, every feature answers its when_unknown), "trial", "after_cancellation", "default" or "none".
+      def plan_source = @snapshot&.dig("plan", "source")
+
+      def trial
+        value = @snapshot&.fetch("trial", nil) or return nil
+        Trial.new(plan: value["plan"], ends_on: date(value["ends_on"]))
+      end
+
+      def scheduled_change
+        value = @snapshot&.fetch("scheduled_change", nil) or return nil
+        ScheduledChange.new(plan: value["plan"], on: date(value["on"]))
+      end
+
+      def cancellation
+        value = @snapshot&.fetch("cancellation", nil) or return nil
+        Cancellation.new(plan: value["plan"], ends_on: date(value["ends_on"]), ended_on: date(value["ended_on"]), until: date(value["until"]), then: value["then"])
+      end
+      def access = @snapshot&.fetch("access", nil)
+      def version = @snapshot&.fetch("version", nil)
+
+      private
+        def date(value) = value && Date.iso8601(value)
+
+        def feature(key) = @snapshot&.dig("features", key.to_s)
+        def catalog_entry(key) = @catalog.dig("features", key.to_s)
+
+        # Nothing known: the catalog says; a feature the catalog does not know is allowed, never a rollout flag.
+        def default(key, kind)
+          entry = catalog_entry(key)
+          return kind != "rollout" unless entry
+
+          entry["when_unknown"] == "allow" && !entry["strict"] && entry["kind"] != "rollout"
+        end
+
+        # The app's own uses the snapshot has not counted yet, in the snapshot's period.
+        def own_uses(key, value)
+          counted = value["counted_through"].to_i
+          since = value["period_start"] && Time.iso8601(value["period_start"])
+          @pending.select { |use| use.feature == key.to_s && use.sequence > counted && (since.nil? || use.occurred_at >= since) }.sum(&:quantity)
+        end
+
+        def state_of(limit, tolerance, used, beyond)
+          return "within" if limit.nil? || (used <= limit && (limit.zero? || used < limit * NEAR))
+          return "near" if used <= limit
+          return "over_in_tolerance" if used <= limit + tolerance
+
+          beyond == "block" ? "blocked" : "over"
+        end
+    end
+  end
+end

data/lib/sumwerk/billing/client.rb

@@ -0,0 +1,195 @@
+module Sumwerk
+  module Billing
+    # One app's view of sumwerk entitlements.
+    #
+    #   client = Sumwerk::Billing::Client.new(app: "nordwind", token: ENV["SUMWERK_TOKEN"],
+    #                                               store: Sumwerk::Billing::RedisStore.new(Redis.new), webhook_secret: ENV["SUMWERK_WEBHOOK_SECRET"])
+    #   client.entitled?(org.id, :reports)
+    #   client.allowed?(org.id, :ad_uploads, 3)   # room for three more?
+    #   client.track(org.id, :ad_uploads, quantity: 3)
+    #
+    # Answers come from the store; an org the store does not know is asked for at the edge (or sumwerk) once, with a
+    # short timeout. When nothing can be known the catalog's default answers, and the client tells sumwerk it had to.
+    class Client
+      attr_reader :store
+
+      def initialize(app:, token:, edge_url: nil, api_url: "https://www.sumwerk.com", store: MemoryStore.new, webhook_secret: nil,
+                     browser_secret: nil, timeout: 0.3, batch: 100, transport: nil, clock: -> { Time.now }, logger: nil)
+        @app, @token, @edge_url, @api_url, @store = app.to_s, token, edge_url&.chomp("/"), api_url.chomp("/"), store
+        @webhook_secret, @browser_secret, @timeout, @batch, @clock, @logger = webhook_secret, browser_secret, timeout, batch, clock, logger
+        @transport = transport || method(:http)
+        @buffer, @fallbacks, @mutex = [], Hash.new(0), Mutex.new
+      end
+
+      def answer(org) = Answer.new(catalog:, snapshot: snapshot(org.to_s), pending: @store.uses(org.to_s))
+
+      def entitled?(org, key) = ask(org, key) { |answer| answer.entitled?(key) }
+      def enabled?(org, key) = ask(org, key) { |answer| answer.enabled?(key) }
+      def allowed?(org, key, quantity = 1) = ask(org, key) { |answer| answer.allowed?(key, quantity) }
+      def limit(org, key) = answer(org).limit(key)
+
+      # Counts a use at once (the next check sees it) and sends it with the next batch.
+      def track(org, key, quantity: 1, event_id: SecureRandom.uuid, at: @clock.call)
+        org = org.to_s
+        sequence = @store.next_sequence(org)
+        @store.add_use(org, Answer::Use.new(feature: key.to_s, quantity:, sequence:, occurred_at: at))
+        full = @mutex.synchronize do
+          @buffer << { event_id:, org:, feature: key.to_s, quantity:, sequence:, occurred_at: at.utc.iso8601 }
+          @buffer.size >= @batch
+        end
+        flush if full
+        sequence
+      end
+
+      # The current total of a limit the app counts itself (seats).
+      # One of the app's customers, under the app's own id, as it signs up or changes: name, email, company, country,
+      # owner_email, tags, custom attributes. True when sumwerk took it; a failed call is logged, never raised.
+      def upsert_customer(org, attributes)
+        status, = request(:put, "#{@api_url}/api/v1/sources/#{@app}/customers/#{escape(org)}", attributes, timeout: 5)
+        status.to_i.between?(200, 299)
+      end
+
+      def report(org, key, total)
+        request(:put, "#{@api_url}/api/v1/billing/#{@app}/totals/#{escape(org)}/#{key}", { total: }, timeout: 5)
+      end
+
+      # Sends what was counted and the defaults used since the last flush. What could not be sent stays for the next.
+      def flush
+        events, fallbacks = @mutex.synchronize { [ @buffer.shift(500), @fallbacks.dup.tap { @fallbacks.clear } ] }
+        if events.any?
+          status, = post_usage("usage", { events: })
+          @mutex.synchronize { @buffer.unshift(*events) } unless status&.between?(200, 299) || status == 422
+        end
+        if fallbacks.any?
+          items = fallbacks.map { |(org, feature, reason), count| { org:, feature:, reason:, count: } }
+          status, = post_usage("fallbacks", { fallbacks: items })
+          @mutex.synchronize { fallbacks.each { |found, count| @fallbacks[found] += count } } unless status&.between?(200, 299)
+        end
+        @buffer.size
+      end
+
+      # Flushes in the background every few seconds; call once at boot.
+      def start(every: 5)
+        @worker ||= Thread.new { loop { sleep every; safely { flush } } }
+        at_exit { safely { flush } }
+        self
+      end
+
+      # A billing.changed webhook: true when the signature held and the snapshots and removals were taken.
+      def receive(body, signature)
+        return false unless @webhook_secret && Tokens.valid_webhook?(@webhook_secret, body, signature, now: @clock.call)
+
+        take(JSON.parse(body))
+        true
+      end
+
+      # Asks sumwerk for every answer newer than the last one seen: for apps without a webhook (on localhost) and as a
+      # periodic check that nothing was missed.
+      def sync
+        loop do
+          status, body = request(:get, "#{@api_url}/api/v1/billing/#{@app}?after_version=#{@store.read("cursor").to_i}", timeout: 10)
+          break unless status == 200
+
+          page = JSON.parse(body)
+          newest = take(page)
+          @store.write("cursor", newest) if newest
+          break unless page["next_after_version"]
+        end
+      end
+
+      # For the app's own page: a token its browser uses to read this org's answer (through the app's domain).
+      def browser_token(org, ttl: 600)
+        raise Error, "browser_secret is not configured" unless @browser_secret
+
+        Tokens.browser(@browser_secret, account: catalog.fetch("account"), app: @app, org: org.to_s, ttl:, now: @clock.call)
+      end
+
+      # For a link to sumwerk's customer pages: once, within a minute, for this user of the org (role: "manage" or "view").
+      #   redirect_to "#{pages_url}/account?token=#{ANSWERS.page_token(org.id, user: current_user.id, email: current_user.email, role: "manage")}"
+      def page_token(org, user:, email: nil, role: "manage", ttl: 60)
+        raise Error, "browser_secret is not configured" unless @browser_secret
+
+        Tokens.page(@browser_secret, account: catalog.fetch("account"), app: @app, org: org.to_s, user:, email:, role:, ttl:, now: @clock.call)
+      end
+
+      def catalog
+        cached = @store.read("catalog")&.then { |raw| JSON.parse(raw) }
+        return cached if cached && cached["fetched_at"].to_i > @clock.call.to_i - 600
+
+        status, body = request(:get, "#{base}/catalog")
+        return cached || {} unless status == 200
+
+        JSON.parse(body).merge("fetched_at" => @clock.call.to_i).tap { |fresh| @store.write("catalog", fresh.to_json) }
+      end
+
+      private
+        def ask(org, key)
+          found = answer(org)
+          reason = found.fallback(key)
+          @mutex.synchronize { @fallbacks[[ org.to_s, key.to_s, reason ]] += 1 } if reason
+          yield found
+        end
+
+        # The stored copy, else the edge (or sumwerk) once; :unknown_org when sumwerk has no such org, nil when unreachable.
+        def snapshot(org)
+          stored = @store.snapshot(org)
+          return :unknown_org if stored&.dig("removed")
+
+          stored || begin
+            status, body = request(:get, "#{base}/orgs/#{escape(org)}")
+            case status
+            when 200 then JSON.parse(body).tap { |fetched| keep(fetched) }
+            when 404 then :unknown_org
+            end
+          end
+        end
+
+        # Snapshots and removals of a feed page or a webhook; the highest version among them.
+        def take(page)
+          page["snapshots"].to_a.each { |snapshot| keep(snapshot) }
+          # A removal stays as a marker with its version, so that an older answer arriving late does not bring the org back.
+          page["removed"].to_a.each { |removal| @store.put_snapshot(removal["org"], { "orgs" => [ removal["org"] ], "removed" => true, "version" => removal["version"] }) }
+          (page["snapshots"].to_a + page["removed"].to_a).map { |entry| entry["version"].to_i }.max
+        end
+
+        def keep(snapshot)
+          snapshot["orgs"].to_a.each do |org|
+            next unless @store.put_snapshot(org, snapshot)
+
+            counted = snapshot["features"].to_h.filter_map { |key, value| [ key, value["counted_through"].to_i ] if value["kind"] == "limit" }.to_h
+            @store.forget_counted(org, counted)
+          end
+        end
+
+        def base = @edge_url ? "#{@edge_url}/v1/#{@app}" : "#{@api_url}/api/v1/billing/#{@app}"
+
+        def post_usage(kind, body)
+          url = @edge_url ? "#{@edge_url}/v1/#{@app}/#{kind}" : "#{@api_url}/api/v1/billing/#{@app}/#{kind}"
+          request(:post, url, body, timeout: 5)
+        end
+
+        def request(verb, url, body = nil, timeout: @timeout)
+          @transport.call(verb, url, { "Authorization" => "Bearer #{@token}", "Content-Type" => "application/json" }, body&.to_json, timeout)
+        rescue StandardError => error
+          @logger&.warn("sumwerk billing: #{verb.upcase} #{url}: #{error.class}")
+          nil
+        end
+
+        def http(verb, url, headers, body, timeout)
+          uri = URI(url)
+          request = { get: Net::HTTP::Get, post: Net::HTTP::Post, put: Net::HTTP::Put }.fetch(verb).new(uri, headers)
+          request.body = body if body
+          response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: timeout, read_timeout: timeout) { |connection| connection.request(request) }
+          [ response.code.to_i, response.body ]
+        end
+
+        def escape(value) = URI.encode_www_form_component(value.to_s)
+
+        def safely
+          yield
+        rescue StandardError => error
+          @logger&.warn("sumwerk billing: #{error.class}: #{error.message}")
+        end
+    end
+  end
+end

data/lib/sumwerk/billing/rack.rb

@@ -0,0 +1,44 @@
+module Sumwerk
+  module Billing
+    # Two small Rack apps to mount in the app:
+    #   mount Sumwerk::Billing::Webhook.new(client), at: "/sumwerk/billing/webhook"
+    #   mount Sumwerk::Billing::BrowserProxy.new, at: "/sumwerk/billing"
+    class Webhook
+      def initialize(client)
+        @client = client
+      end
+
+      def call(env)
+        request = ::Rack::Request.new(env)
+        return [ 405, {}, [] ] unless request.post?
+
+        @client.receive(request.body.read, env["HTTP_X_SUMWERK_SIGNATURE"]) ? [ 204, {}, [] ] : [ 401, {}, [] ]
+      end
+    end
+
+    # Passes the browser's reads (GET …/v1/:app/orgs/:org with a browser token) to sumwerk, from the app's own domain:
+    # ad blockers do not block an app's own domain. Only reads, only that path. To sumwerk's API by default, or to an
+    # edge when one is given.
+    class BrowserProxy
+      def initialize(api_url: "https://www.sumwerk.com", edge_url: nil, timeout: 2)
+        @api_url, @edge_url, @timeout = api_url.chomp("/"), edge_url&.chomp("/"), timeout
+      end
+
+      def call(env)
+        path = env["PATH_INFO"].to_s
+        return [ 404, {}, [] ] unless env["REQUEST_METHOD"] == "GET" && path.match?(%r{\A/v1/[a-z][a-z0-9-]*/orgs/[^/]+\z})
+
+        uri = target(path)
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: @timeout, read_timeout: @timeout) do |http|
+          http.request(Net::HTTP::Get.new(uri, "Authorization" => env["HTTP_AUTHORIZATION"].to_s))
+        end
+        [ response.code.to_i, { "content-type" => "application/json", "cache-control" => "no-store" }, [ response.body.to_s ] ]
+      rescue StandardError
+        [ 502, { "content-type" => "application/json" }, [ { error: "unreachable" }.to_json ] ]
+      end
+
+      # /v1/:app/orgs/:org at the edge, /api/v1/billing/:app/orgs/:org at sumwerk's API.
+      def target(path) = URI(@edge_url ? "#{@edge_url}#{path}" : "#{@api_url}/api/v1/billing#{path.delete_prefix("/v1")}")
+    end
+  end
+end

data/lib/sumwerk/billing/stores.rb

@@ -0,0 +1,116 @@
+module Sumwerk
+  module Billing
+    # Where a client keeps snapshots, the catalog and its own uncounted uses. MemoryStore for one process (tests,
+    # small apps); RedisStore so every process of the app shares one copy and one count.
+    class MemoryStore
+      def initialize
+        @mutex = Mutex.new
+        @snapshots, @pending, @sequences, @values = {}, Hash.new { |hash, key| hash[key] = [] }, Hash.new(0), {}
+      end
+
+      def snapshot(org) = @mutex.synchronize { @snapshots[org] }
+
+      # Keeps the copy with the higher version; true when this one was newer.
+      def put_snapshot(org, snapshot)
+        @mutex.synchronize do
+          current = @snapshots[org]
+          next false if current && current["version"].to_i >= snapshot["version"].to_i
+
+          @snapshots[org] = snapshot
+          true
+        end
+      end
+
+      def delete_snapshot(org) = @mutex.synchronize { @snapshots.delete(org) }
+      def next_sequence(org) = @mutex.synchronize { @sequences[org] += 1 }
+      def add_use(org, use) = @mutex.synchronize { @pending[org] << use }
+      def uses(org) = @mutex.synchronize { @pending[org].dup }
+
+      # Forget the uses the snapshot has counted (per feature: sequence up to counted_through).
+      def forget_counted(org, counted_through_by_feature)
+        @mutex.synchronize { @pending[org].reject! { |use| use.sequence <= counted_through_by_feature.fetch(use.feature, 0) } }
+      end
+
+      def read(key) = @mutex.synchronize { @values[key] }
+      def write(key, value) = @mutex.synchronize { @values[key] = value }
+    end
+
+    # redis: a redis-rb (or compatible) client the app already has.
+    class RedisStore
+      PUT_IF_NEWER = <<~LUA.freeze
+        local current = redis.call("GET", KEYS[1])
+        if current and tonumber(cjson.decode(current)["version"] or 0) >= tonumber(ARGV[2]) then return 0 end
+        redis.call("SET", KEYS[1], ARGV[1])
+        return 1
+      LUA
+
+      def initialize(redis, namespace: "sumwerk")
+        @redis, @namespace = redis, namespace
+      end
+
+      def snapshot(org) = @redis.get(key("snap", org))&.then { |raw| JSON.parse(raw) }
+      def put_snapshot(org, snapshot) = @redis.eval(PUT_IF_NEWER, keys: [ key("snap", org) ], argv: [ snapshot.to_json, snapshot["version"].to_i ]) == 1
+      def delete_snapshot(org) = @redis.del(key("snap", org))
+      def next_sequence(org) = @redis.incr(key("seq", org))
+
+      def add_use(org, use)
+        @redis.zadd(key("uses", org), use.sequence, [ use.feature, use.quantity, use.sequence, use.occurred_at.utc.iso8601 ].to_json)
+      end
+
+      def uses(org)
+        @redis.zrange(key("uses", org), 0, -1).map do |raw|
+          feature, quantity, sequence, at = JSON.parse(raw)
+          Answer::Use.new(feature:, quantity:, sequence:, occurred_at: Time.iso8601(at))
+        end
+      end
+
+      def forget_counted(org, counted_through_by_feature)
+        counted = uses(org).select { |use| use.sequence <= counted_through_by_feature.fetch(use.feature, 0) }
+        counted.each { |use| @redis.zrem(key("uses", org), [ use.feature, use.quantity, use.sequence, use.occurred_at.utc.iso8601 ].to_json) }
+      end
+
+      def read(name) = @redis.get(key("value", name))
+      def write(name, value) = @redis.set(key("value", name), value)
+
+      private
+        def key(kind, name) = "#{@namespace}:#{kind}:#{name}"
+    end
+
+    # For a Rails app without Redis: its shared cache (Solid Cache, Memcached, …) as the store, so every process sees
+    # the same copy. Keeping the newer version is read-then-write here, not one atomic step: two webhooks racing can
+    # briefly leave the older copy, and the next sync or webhook puts the newer one back.
+    class CacheStore
+      def initialize(cache, namespace: "sumwerk", expires_in: 7 * 24 * 3600)
+        @cache, @namespace, @expires_in = cache, namespace, expires_in
+      end
+
+      def snapshot(org) = @cache.read(key("snap", org))
+
+      def put_snapshot(org, snapshot)
+        current = snapshot(org)
+        return false if current && current["version"].to_i >= snapshot["version"].to_i
+
+        @cache.write(key("snap", org), snapshot, expires_in: @expires_in)
+        true
+      end
+
+      def delete_snapshot(org) = @cache.delete(key("snap", org))
+      def next_sequence(org) = @cache.increment(key("seq", org), 1, expires_in: @expires_in) || raise(Error, "the cache cannot count")
+
+      def add_use(org, use) = @cache.write(key("uses", org), stored_uses(org) + [ use.to_h ], expires_in: @expires_in)
+      def uses(org) = stored_uses(org).map { |raw| Answer::Use.new(**raw.transform_keys(&:to_sym)) }
+
+      def forget_counted(org, counted_through_by_feature)
+        kept = uses(org).reject { |use| use.sequence <= counted_through_by_feature.fetch(use.feature, 0) }
+        @cache.write(key("uses", org), kept.map(&:to_h), expires_in: @expires_in)
+      end
+
+      def read(name) = @cache.read(key("value", name))
+      def write(name, value) = @cache.write(key("value", name), value, expires_in: @expires_in)
+
+      private
+        def stored_uses(org) = Array(@cache.read(key("uses", org)))
+        def key(kind, name) = "#{@namespace}:#{kind}:#{name}"
+    end
+  end
+end

data/lib/sumwerk/billing/tokens.rb

@@ -0,0 +1,39 @@
+module Sumwerk
+  module Billing
+    # The two signed things an app handles: webhooks from sumwerk (checked) and tokens for its browser (made).
+    module Tokens
+      TOLERANCE = 300 # seconds a webhook's timestamp may be off
+
+      # X-Sumwerk-Signature: t=<unix time>,v1=<HMAC-SHA256 of "<t>.<body>">
+      def self.valid_webhook?(secret, body, header, now: Time.now)
+        timestamp, signature = header.to_s.scan(/t=(\d+),v1=(\h+)/).first
+        return false unless timestamp && (now.to_i - timestamp.to_i).abs <= TOLERANCE
+
+        expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.#{body}")
+        OpenSSL.fixed_length_secure_compare(expected, signature)
+      rescue ArgumentError
+        false
+      end
+
+      # swb_<base64url payload>.<base64url HMAC-SHA256>, for one org and a few minutes; checked by sumwerk's edge.
+      def self.browser(secret, account:, app:, org:, ttl: 600, now: Time.now)
+        sign(secret, { a: account, p: app, o: org, e: now.to_i + ttl })
+      end
+
+      ROLES = %w[manage view].freeze
+
+      # Opens sumwerk's customer pages (account, billing, checkout) for one of the app's users, once, within a minute:
+      # make it only for a user who belongs to the org; role "view" sees billing without changing it.
+      def self.page(secret, account:, app:, org:, user:, email: nil, role: "manage", ttl: 60, now: Time.now)
+        raise ArgumentError, "role is manage or view" unless ROLES.include?(role)
+
+        sign(secret, { a: account, p: app, o: org, e: now.to_i + ttl, x: "page", j: SecureRandom.hex(12), u: user.to_s, m: email, r: role }.compact)
+      end
+
+      def self.sign(secret, claims)
+        payload = Base64.urlsafe_encode64(claims.to_json, padding: false)
+        "swb_#{payload}.#{Base64.urlsafe_encode64(OpenSSL::HMAC.digest("SHA256", secret, payload), padding: false)}"
+      end
+    end
+  end
+end

data/lib/sumwerk/billing.rb

@@ -0,0 +1,20 @@
+require "json"
+require "openssl"
+require "securerandom"
+require "net/http"
+require "time"
+require "base64"
+
+module Sumwerk
+  # Ask "may this org do this?" without a network call: answers come from a local copy that sumwerk keeps current
+  # (webhooks, the edge, a periodic sync), and the app's own uses count at once. See README.md.
+  module Billing
+    Error = Class.new(StandardError)
+  end
+end
+
+require_relative "billing/answer"
+require_relative "billing/stores"
+require_relative "billing/tokens"
+require_relative "billing/client"
+require_relative "billing/rack"

data/lib/sumwerk/client.rb

@@ -0,0 +1,113 @@
+module Sumwerk
+  # The whole sumwerk API, one object per area, like Stripe's:
+  #
+  #   sumwerk = Sumwerk::Client.new(token: ENV.fetch("SUMWERK_TOKEN"))
+  #   sumwerk.customers.list(status: "paying")
+  #   sumwerk.customers.upsert("nordwind", org.id, name: org.name, stripe_customer_ids: [ org.stripe_id ])
+  #   sumwerk.notes.create(customer_id, body: "Called about the renewal")
+  #   sumwerk.billing.apply("nordwind", org.id, { type: "plan", plan: "business" }, idempotency_key: request_id)
+  #   sumwerk.request(:get, "/api/v1/me")          # anything the client has no method for yet
+  #
+  # Each call answers the API's JSON as a Hash with string keys, or raises a Sumwerk::Error. Timeouts, lost
+  # connections, 5xx and 429 are retried with growing waits (429: the seconds in Retry-After) for every call that is
+  # safe to send twice: reads, PUT, DELETE, and POSTs the API makes idempotent (usage events by event_id, apply with
+  # an idempotency key). For an org's billing answers without a call per check, see Sumwerk::Billing::Client.
+  class Client
+    attr_reader :api_url
+
+    def initialize(token:, api_url: "https://www.sumwerk.com", timeout: 30, max_retries: 2, transport: nil, sleeper: ->(seconds) { sleep(seconds) })
+      @token, @api_url, @timeout, @max_retries, @sleeper = token, api_url.chomp("/"), timeout, max_retries, sleeper
+      @transport = transport || method(:http)
+    end
+
+    def me = @me ||= Api::Me.new(self)
+    def sources = @sources ||= Api::Sources.new(self)
+    def customers = @customers ||= Api::Customers.new(self)
+    def contacts = @contacts ||= Api::Contacts.new(self)
+    def usage = @usage ||= Api::Usage.new(self)
+    def usage_metrics = @usage_metrics ||= Api::UsageMetrics.new(self)
+    def attributes = @attributes ||= Api::Attributes.new(self)
+    def notes = @notes ||= Api::Notes.new(self)
+    def tasks = @tasks ||= Api::Tasks.new(self)
+    def research = @research ||= Api::Research.new(self)
+    def conversations = @conversations ||= Api::Conversations.new(self)
+    def deals = @deals ||= Api::Deals.new(self)
+    def pipelines = @pipelines ||= Api::Pipelines.new(self)
+    def emails = @emails ||= Api::Emails.new(self)
+    def email_templates = @email_templates ||= Api::EmailTemplates.new(self)
+    def sequences = @sequences ||= Api::Sequences.new(self)
+    def enrollments = @enrollments ||= Api::Enrollments.new(self)
+    def mrr = @mrr ||= Api::Mrr.new(self)
+    def movements = @movements ||= Api::Movements.new(self)
+    def restatements = @restatements ||= Api::Restatements.new(self)
+    def reconciliation = @reconciliation ||= Api::Reconciliation.new(self)
+    def segments = @segments ||= Api::Segments.new(self)
+    def lifecycle = @lifecycle ||= Api::Lifecycle.new(self)
+    def plans = @plans ||= Api::Plans.new(self)
+    def at_risk = @at_risk ||= Api::AtRisk.new(self)
+    def risk_rules = @risk_rules ||= Api::RiskRules.new(self)
+    def risk_exceptions = @risk_exceptions ||= Api::RiskExceptions.new(self)
+    def events = @events ||= Api::Events.new(self)
+    def automations = @automations ||= Api::Automations.new(self)
+    def log = @log ||= Api::Log.new(self)
+    def webhook_requests = @webhook_requests ||= Api::WebhookRequests.new(self)
+    def billing = @billing ||= Api::Billing.new(self)
+
+    # One call: path from /api/v1 on, query (a Hash) and body (a Hash, sent as JSON). idempotent: true marks a POST as safe
+    # to send twice (it is retried like a read). Answers the parsed JSON (nil for 204).
+    def request(verb, path, query: nil, body: nil, headers: {}, idempotent: nil)
+      verb = verb.to_sym
+      url = "#{@api_url}#{path}"
+      url += "?#{encode(query)}" if query && !query.empty?
+      safe = idempotent.nil? ? (verb != :post || headers.key?("Idempotency-Key")) : idempotent
+      headers = { "Authorization" => "Bearer #{@token}", "Accept" => "application/json", "User-Agent" => "sumwerk-ruby/#{VERSION}" }
+                .merge(body ? { "Content-Type" => "application/json" } : {}).merge(headers)
+      attempt = 0
+      begin
+        attempt += 1
+        status, raw, answer_headers = call(verb, url, headers, body&.to_json)
+        parsed = parse(raw)
+        return parsed if status.between?(200, 299)
+
+        raise Error.for(status, parsed, answer_headers.to_h.transform_keys { |key| key.to_s.downcase })
+      rescue RateLimitError, APIError, ConnectionError => error
+        retriable = safe || error.is_a?(RateLimitError) # a 429 counted nothing
+        raise unless retriable && attempt <= @max_retries
+
+        @sleeper.call(error.is_a?(RateLimitError) && error.retry_after.positive? ? [ error.retry_after, 60 ].min : 0.5 * (2**(attempt - 1)))
+        retry
+      end
+    end
+
+    # Escapes one id for a path: an org id may hold any character.
+    def self.escape(value) = URI.encode_www_form_component(value.to_s).gsub("+", "%20")
+
+    private
+      def call(verb, url, headers, body)
+        @transport.call(verb, url, headers, body, @timeout)
+      rescue Timeout::Error, SystemCallError, SocketError, IOError, OpenSSL::SSL::SSLError => error
+        raise ConnectionError.new("#{verb.upcase} #{url}: #{error.class}: #{error.message}")
+      end
+
+      def parse(raw)
+        return nil if raw.nil? || raw.strip.empty?
+
+        JSON.parse(raw)
+      rescue JSON::ParserError
+        { "error" => "invalid_answer", "message" => raw.to_s[0, 200] }
+      end
+
+      def encode(query)
+        query.flat_map { |key, value| Array(value).map { |each| [ value.is_a?(Array) ? "#{key}[]" : key.to_s, each.to_s ] } }.then { |pairs| URI.encode_www_form(pairs) }
+      end
+
+      def http(verb, url, headers, body, timeout)
+        uri = URI(url)
+        klass = { get: Net::HTTP::Get, post: Net::HTTP::Post, put: Net::HTTP::Put, patch: Net::HTTP::Patch, delete: Net::HTTP::Delete }.fetch(verb)
+        request = klass.new(uri, headers)
+        request.body = body if body
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: timeout, read_timeout: timeout) { |connection| connection.request(request) }
+        [ response.code.to_i, response.body, response.each_header.to_h ]
+      end
+  end
+end

data/lib/sumwerk/errors.rb

@@ -0,0 +1,33 @@
+module Sumwerk
+  # Everything the API answers with an error, with its status, the API's `error` code, `message` and the whole body.
+  class Error < StandardError
+    attr_reader :status, :code, :body, :headers
+
+    def initialize(message = nil, status: nil, code: nil, body: nil, headers: {})
+      super(message || code || "sumwerk answered #{status}")
+      @status, @code, @body, @headers = status, code, body, headers
+    end
+
+    # The error class for an answer: AuthenticationError for 401, NotFoundError for 404 and so on.
+    def self.for(status, body, headers = {})
+      parsed = body.is_a?(Hash) ? body : {}
+      klass = { 400 => InvalidRequestError, 401 => AuthenticationError, 403 => PermissionError, 404 => NotFoundError, 409 => ConflictError,
+                410 => GoneError, 422 => InvalidRequestError, 429 => RateLimitError }.fetch(status) { status >= 500 ? APIError : Error }
+      klass.new(parsed["message"] || parsed["error"], status:, code: parsed["error"], body: parsed, headers:)
+    end
+  end
+
+  InvalidRequestError = Class.new(Error)  # 400, 422: the request cannot be right; `message` says why
+  AuthenticationError = Class.new(Error)  # 401: no token, or an unknown or revoked one
+  PermissionError = Class.new(Error)      # 403: a read-only token wrote, or billing management is off
+  NotFoundError = Class.new(Error)        # 404
+  ConflictError = Class.new(Error)        # 409: the id belongs to another customer
+  GoneError = Class.new(Error)            # 410: a call that no longer exists
+  APIError = Class.new(Error)             # 5xx: on sumwerk's side; retried before it is raised
+  ConnectionError = Class.new(Error)      # no answer: timeout, refused, DNS; retried before it is raised
+
+  # 429: more than 600 requests a minute with this token. `retry_after` is the seconds to wait.
+  class RateLimitError < Error
+    def retry_after = headers["retry-after"].to_i
+  end
+end

data/lib/sumwerk/version.rb

@@ -0,0 +1,3 @@
+module Sumwerk
+  VERSION = "0.2.0".freeze
+end

data/lib/sumwerk.rb

@@ -0,0 +1,14 @@
+require "json"
+require "net/http"
+require "uri"
+
+# The sumwerk API for Ruby: Sumwerk::Client for every call (customers, usage, notes, revenue, billing), and
+# Sumwerk::Billing for answering "may this org do this?" from a local copy. See README.md.
+module Sumwerk
+end
+
+require_relative "sumwerk/version"
+require_relative "sumwerk/errors"
+require_relative "sumwerk/client"
+require_relative "sumwerk/api"
+require_relative "sumwerk/billing"

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: sumwerk
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Kitchn Venture GmbH
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Every call of the sumwerk API (customers, usage, notes, tasks, revenue,
+  billing) with errors and retries, and billing answers (features, limits, rollout
+  flags) from a local copy kept current by sumwerk.
+email:
+- hello@sumwerk.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/sumwerk.rb
+- lib/sumwerk/api.rb
+- lib/sumwerk/billing.rb
+- lib/sumwerk/billing/answer.rb
+- lib/sumwerk/billing/client.rb
+- lib/sumwerk/billing/rack.rb
+- lib/sumwerk/billing/stores.rb
+- lib/sumwerk/billing/tokens.rb
+- lib/sumwerk/client.rb
+- lib/sumwerk/errors.rb
+- lib/sumwerk/version.rb
+homepage: https://www.sumwerk.com
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://www.sumwerk.com/docs/api
+  changelog_uri: https://www.sumwerk.com/changelog
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: The sumwerk API for Ruby
+test_files: []