marginfuse 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6594a128c2a5670e8eef2c8da7e21a96c305c3e13f66d4262889169c95df5a8a
-  data.tar.gz: 96e931bd8cf686b799f306483043c965f81f683eba6d377ce3d5d4bd18d2297e
+  metadata.gz: ed4b052cde767f31778131e10df10f850d206c4db7f2215040de98faec393af0
+  data.tar.gz: 428cb94a4937c73876d998db48026aea9b2f8b69730b1149bd5e3947051a19c9
 SHA512:
-  metadata.gz: 139be111ee7a9d54f9c93fd4b2a00712c27c7c2a8ddf0407a7806cd05a43c230dd1714be49654b053cdf3b4db756503f1516ccb42a9f54b859b63acf6924b9c2
-  data.tar.gz: 45f3c6d52858f692f327c7be010b7a082d7ee457f027c028c7d1cec7d8128eea825600d3d40b0e1fe0f5ef3065a8c9bdea2e648f2fc8f7f7ce4730e9fb0700c4
+  metadata.gz: e7d968bfd7aa9d82acaa132b72402396cca466b6940d825da506326b7a508376dcbacf203cc16529a7f8d98c0a52f9e3b6d04ba3341820ca1eea8541b0443bb5
+  data.tar.gz: 2cd18e81de9e717d56607177da46c46c758bb46a443c9bebe2298e16ad68873156bd1e5123d3b09c24460f68823d53ec7064d942be43da0938d52e07fa2b1a5e

data/CHANGELOG.md

@@ -4,6 +4,36 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project
 follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0]
+
+### Added
+
+- `identify`: tell MarginFuse who a customer is and which plan they are on.
+
+  MarginFuse can now compute margin without a revenue source connected, from
+  plans you declare in Settings and a plan assigned per customer. This call is
+  how your application assigns that plan itself.
+
+  ```ruby
+  mf.identify(customer_id: "user_8x2m91", plan: "pro", name: "Acme Studio")
+  ```
+
+  `plan` is the key of a plan declared in MarginFuse, not a Stripe price id.
+  Safe to call on every sign-in: sending the plan the customer is already on
+  changes nothing. `period_start` backdates the cycle, `clear_plan` ends it.
+
+  Unlike `track`, this one reports failure instead of failing quietly. A wrong
+  plan is a wrong margin, and there is no safe default for "I could not record
+  what this customer pays". Check `result.ok?`; `on_error` is called too. It
+  still never raises into your code.
+
+- `plan` on `track`, `guard` and `decide`, so a plan can ride along with usage
+  rather than needing its own call. There it is a hint: a key that does not
+  resolve is ignored rather than failing your event, because usage must never
+  be lost to a plan note.
+
+Both are additive. Existing code keeps working unchanged.
+
 ## [0.1.0]
 
 First release. Ruby 3.2+, zero dependencies, standard library only.

data/README.md

@@ -96,6 +96,37 @@ There is no failure a caller should branch on. A decision that times out or
 errors is an *allow* with `degraded?` true, because MarginFuse being unreachable
 must never become your outage. Transport failures go to `on_error`.
 
+## Tell MarginFuse what a customer pays
+
+Margin needs a revenue side. With Stripe connected it comes from there. Without
+one, you declare your plans in MarginFuse and say which plan each customer is
+on:
+
+```ruby
+result = mf.identify(
+  customer_id: "user_8x2m91",
+  plan: "pro", # the key of a plan you declared in Settings
+  name: "Acme Studio",
+  metadata: { "tier" => "legacy" } # labels segment policies can match on
+)
+
+warn "MarginFuse identify: #{result.error}" unless result.ok?
+```
+
+Safe to call on every sign-in: sending the plan the customer is already on
+changes nothing. Sending a different one ends the current cycle and prorates
+what accrued. `period_start` backdates the cycle for a customer who has been
+paying since an earlier date; `clear_plan: true` takes them off plans.
+
+This is the one call that does not fail open. `track` retries later and
+`decide` allows, because both have a safe default; "I could not record what
+this customer pays" has none, and a wrong plan is a wrong margin. So it reports
+the failure to you instead of swallowing it. It still never raises.
+
+`track`, `guard` and `decide` also accept a `plan`, so it can ride along with
+usage rather than needing its own call. There it is a hint: a key that does not
+resolve is ignored rather than failing your event.
+
 ## OpenRouter and other gateways
 
 Gateways report the real cost of every call. Forward it and your figures are

data/lib/marginfuse/client.rb

@@ -63,9 +63,10 @@ module MarginFuse
     # outage.
     #
     # @return [Decision]
-    def decide(customer_id:, provider:, model:, feature: nil, expected_usage: nil)
+    def decide(customer_id:, provider:, model:, plan: nil, feature: nil, expected_usage: nil)
       body = {
         "customerId" => customer_id,
+        "plan" => plan,
         "feature" => feature,
         "provider" => provider,
         "model" => model,
@@ -106,12 +107,14 @@ module MarginFuse
     # Call {#flush} before the process exits, or the last events go with it.
     #
     # @return [void]
-    def track(customer_id:, provider:, model:, usage: nil, feature: nil, requested_model: nil,
-              cost_usd: nil, event_id: nil, occurred_at: nil, outcome: :success,
-              decision_id: nil, retry_of_event_id: nil, corrects_event_id: nil)
+    def track(customer_id:, provider:, model:, usage: nil, plan: nil, feature: nil,
+              requested_model: nil, cost_usd: nil, event_id: nil, occurred_at: nil,
+              outcome: :success, decision_id: nil, retry_of_event_id: nil,
+              corrects_event_id: nil)
       event = {
         "eventId" => event_id || "evt_#{SecureRandom.uuid}",
         "customerId" => customer_id,
+        "plan" => plan,
         "feature" => feature,
         "provider" => provider,
         "model" => model,
@@ -128,6 +131,58 @@ module MarginFuse
       background { send_event(event) }
     end
 
+    # Tells MarginFuse who a customer is and what plan they are on.
+    #
+    # +plan+ is the key of a plan you declared in MarginFuse Settings, not a
+    # Stripe price id. MarginFuse derives that customer's revenue from the
+    # plan's price for every cycle, which is what makes margin per customer and
+    # margin policies work with no revenue source connected. Those figures are
+    # labeled as a declared price wherever they appear, because nobody
+    # confirmed collection.
+    #
+    # Safe to call on every sign-in: sending the plan the customer is already
+    # on changes nothing. Sending a different one ends the current cycle at
+    # that moment and prorates what accrued. +period_start+ backdates the cycle;
+    # +clear_plan+ takes the customer off plans entirely.
+    #
+    # Unlike {#track}, this waits and reports failure. track has a safe default
+    # - retry later - and "I could not record what this customer pays" has
+    # none, because a wrong plan is a wrong margin. It still never raises:
+    # check +result.ok?+, and +on_error+ is called too.
+    #
+    # @return [IdentifyResult]
+    def identify(customer_id:, plan: nil, clear_plan: false, period_start: nil,
+                 name: nil, email: nil, metadata: nil)
+      body = {
+        "customerId" => customer_id,
+        "plan" => plan,
+        "clearPlan" => (true if clear_plan),
+        "periodStart" => period_start&.utc&.iso8601(6),
+        "name" => name,
+        "email" => email,
+        "metadata" => metadata
+      }.compact
+
+      response = post("/v1/identify", body, 5.0)
+      unless (200..299).cover?(response.code.to_i)
+        error = RuntimeError.new("identify: HTTP #{response.code}")
+        report(error, "identify")
+        return IdentifyResult.new(ok: false, error: error.message)
+      end
+
+      parsed = JSON.parse(response.body)
+      IdentifyResult.new(
+        ok: true,
+        customer_id: parsed["customerId"],
+        plan: parsed["plan"],
+        period_start: parsed["periodStart"],
+        period_end: parsed["periodEnd"]
+      )
+    rescue StandardError => e
+      report(e, "identify")
+      IdentifyResult.new(ok: false, error: e.message)
+    end
+
     # {#track} for jobs and scripts that must not exit early.
     # @return [void]
     def track_and_wait(**params)
@@ -164,9 +219,9 @@ module MarginFuse
     # provider may still have charged for it.
     #
     # @return [GuardOutcome]
-    def guard(customer_id:, provider:, model:, feature: nil, expected_usage: nil)
+    def guard(customer_id:, provider:, model:, plan: nil, feature: nil, expected_usage: nil)
       decision = decide(customer_id: customer_id, provider: provider, model: model,
-                        feature: feature, expected_usage: expected_usage)
+                        plan: plan, feature: feature, expected_usage: expected_usage)
 
       # Enforcement depends on the ACTION alone. A missing id costs an
       # acknowledgment; it must never turn a block into a provider call.
@@ -184,7 +239,7 @@ module MarginFuse
       begin
         call = yield(decision)
       rescue Exception => e # rubocop:disable Lint/RescueException
-        track(customer_id: customer_id, feature: feature, provider: provider,
+        track(customer_id: customer_id, plan: plan, feature: feature, provider: provider,
               model: model_used, requested_model: model, usage: {},
               outcome: :provider_error, decision_id: decision.id)
         acknowledge(decision.id, :proceeded_as_requested) if decision.id
@@ -192,7 +247,7 @@ module MarginFuse
       end
 
       call ||= {}
-      track(customer_id: customer_id, feature: feature, provider: provider,
+      track(customer_id: customer_id, plan: plan, feature: feature, provider: provider,
             model: model_used, requested_model: model, usage: call[:usage],
             cost_usd: call[:cost_usd], outcome: call[:outcome] || :success,
             decision_id: decision.id)

data/lib/marginfuse/types.rb

@@ -29,6 +29,23 @@ module MarginFuse
     end
   end
 
+  # What {Client#identify} recorded, or why it could not.
+  #
+  # +ok+ is the only field to branch on. When it is false the call changed
+  # nothing and +error+ says what happened; the SDK still did not raise.
+  #
+  # Unlike {Client#track}, identify reports its failures. track has a safe
+  # default - retry later - and "I could not record what this customer pays"
+  # has none: a wrong plan is a wrong margin.
+  IdentifyResult = Struct.new(
+    :ok, :customer_id, :plan, :period_start, :period_end, :error,
+    keyword_init: true
+  ) do
+    def ok?
+      !!ok
+    end
+  end
+
   # The result of the whole guard loop. +kind+ is :completed, :blocked or
   # :topup_required. +result+ is your block's own return value.
   GuardOutcome = Struct.new(:kind, :decision, :result, keyword_init: true) do

data/lib/marginfuse/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module MarginFuse
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 
   # The version of the shared SDK contract this build was verified against.
   #

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: marginfuse
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Pemira Labs
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-02 00:00:00.000000000 Z
+date: 2026-09-03 00:00:00.000000000 Z
 dependencies: []
 description: |-
   MarginFuse server-side SDK. Connect revenue to per-request AI cost, see gross