marginfuse 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6594a128c2a5670e8eef2c8da7e21a96c305c3e13f66d4262889169c95df5a8a
-  data.tar.gz: 96e931bd8cf686b799f306483043c965f81f683eba6d377ce3d5d4bd18d2297e
+  metadata.gz: c0b1ac060efeb37a1cff83a21bfec10f5e5972c67622a637100b00746a9defbe
+  data.tar.gz: '0058b2089e6d46488e0db908ad66e675f83e1b4a8116abdb2edef4a557e7445f'
 SHA512:
-  metadata.gz: 139be111ee7a9d54f9c93fd4b2a00712c27c7c2a8ddf0407a7806cd05a43c230dd1714be49654b053cdf3b4db756503f1516ccb42a9f54b859b63acf6924b9c2
-  data.tar.gz: 45f3c6d52858f692f327c7be010b7a082d7ee457f027c028c7d1cec7d8128eea825600d3d40b0e1fe0f5ef3065a8c9bdea2e648f2fc8f7f7ce4730e9fb0700c4
+  metadata.gz: 79059326eec63bb75f28c62b93d144d236d14450d477100be60423b7a6a655dfba9556277f9452ae55f204b8c90e60bb43fcc9008fe3bfedc5b4dbf8f0c334a8
+  data.tar.gz: 0f8bea6add4ee66ac6badb04073b362b08f1ab22524479407b9cd1b475b7d2f152e69d020a41c712eadef3dcf5fd667bc82ce005edb8e39b3682bc4f7734ceb9

data/CHANGELOG.md

@@ -4,6 +4,58 @@ 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.3.0]
+
+### Fixed
+
+- A downgrade that crosses vendors is reported against the vendor that actually
+  ran it. `guard()` already ran the model the server chose, but the usage event
+  still named the requested provider, so the call was priced from the wrong
+  catalog and the saving the downgrade exists to prove was computed against the
+  wrong basis. An `allow` is unchanged, because the decision already defaults
+  its provider to the requested one.
+- A downgrade whose provider call then fails is acknowledged as
+  `used_downgrade_model` rather than `proceeded_as_requested`. The cheaper model
+  did run; what failed came after. Reporting otherwise told reconciliation the
+  policy never applied, which skewed realized-savings attribution on the error
+  path.
+
+### Changed
+
+- Pinned contract v2, whose new scenarios cover both corrections above and add
+  a privacy check that hands the SDK content-bearing fields and scans the bytes
+  that actually leave the process.
+
+## [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)
@@ -153,7 +208,8 @@ module MarginFuse
     #
     # Yields the decision to the block, which must return a hash with +:usage+
     # and optionally +:result+, +:cost_usd+ and +:outcome+. Use
-    # +decision.model+: a downgrade verdict changes it.
+    # +decision.model+ and +decision.provider+: a downgrade verdict changes
+    # them, and it can send you to another vendor.
     #
     # It yields rather than returning a decision for you to act on, because
     # enforcement must not depend on the caller remembering to check anything.
@@ -164,9 +220,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.
@@ -179,27 +235,34 @@ module MarginFuse
         return GuardOutcome.new(kind: :topup_required, decision: decision)
       end
 
+      # A downgrade can cross vendors, so the vendor that ran the call comes
+      # from the decision exactly as the model does. Reporting the caller's
+      # would price the call from the wrong catalog and credit the saving to the
+      # wrong vendor. The decision defaults both to what was asked for, so
+      # anything but a downgrade reports what it always did.
       model_used = decision.action == :downgrade ? decision.model : model
+      provider_used = decision.action == :downgrade ? decision.provider : provider
+      # A downgrade whose provider call then fails is still a downgrade: the
+      # cheaper model is the one that ran, so both paths acknowledge the same.
+      acknowledgment =
+        decision.action == :downgrade ? :used_downgrade_model : :proceeded_as_requested
 
       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_used,
               model: model_used, requested_model: model, usage: {},
               outcome: :provider_error, decision_id: decision.id)
-        acknowledge(decision.id, :proceeded_as_requested) if decision.id
+        acknowledge(decision.id, acknowledgment) if decision.id
         raise e
       end
 
       call ||= {}
-      track(customer_id: customer_id, feature: feature, provider: provider,
+      track(customer_id: customer_id, plan: plan, feature: feature, provider: provider_used,
             model: model_used, requested_model: model, usage: call[:usage],
             cost_usd: call[:cost_usd], outcome: call[:outcome] || :success,
             decision_id: decision.id)
-      if decision.id
-        acknowledge(decision.id,
-                    decision.action == :downgrade ? :used_downgrade_model : :proceeded_as_requested)
-      end
+      acknowledge(decision.id, acknowledgment) if decision.id
 
       GuardOutcome.new(kind: :completed, decision: decision, result: call[:result])
     end

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.3.0"
 
   # The version of the shared SDK contract this build was verified against.
   #
@@ -12,5 +12,5 @@ module MarginFuse
   # same vectors.
   #
   # See github.com/marginfuse/sdk-contract
-  CONTRACT_VERSION = 1
+  CONTRACT_VERSION = 2
 end

metadata

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