zeroclick-sellers 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49a5e89b4a453d1bc17ba628fe6a1c15bcddf4b326425d039e00c9f44189089f
-  data.tar.gz: bb98323586f2a706fcb0371b22635c990a67f70271b74f6f733c105884ff9f62
+  metadata.gz: 21a687776a099cffab368909929c6181de3425e83d6fe94bcfaba52cc40e76a8
+  data.tar.gz: 15b009873e6410a7703a6385ebdfc0d737f1be8d3d475b18ed22e96683117904
 SHA512:
-  metadata.gz: 0e1196572a7e5077fd756f76f334201c10b4665c6d24085932228d84850dd9980bec5a9d535235fe6ce973a32252499dafbf5c8c9953e1f63ab6ec28d0a6b2c8
-  data.tar.gz: e7ac43462966f8b769a79abce4330378ad276af8d44a6f4e5f82c8e1151ba9ee9ac5a8b9a0d578a1530615954baffba7eed660a53563842d0260e39e82d68fc0
+  metadata.gz: 10cc75f795e921fa55d77b5dce9f101d1f3c4afadb191fe70546db9bd01dd309fe8453cfedd24de1d1991e1716567de26378b17cb87fb8338866f1132d4e96bd
+  data.tar.gz: 82a1860e38b1a2b53195b1aa0c17830b60f2c7ad5cdc80efc280c6547678f74771ed799a42ddabaf405c1df3f00f36de6344402e3c104c03078cc94e2d00f90e

data/lib/zeroclick/sellers/stateful/contracts.rb

@@ -6,7 +6,9 @@ require_relative "money"
 module ZeroClick
   module Sellers
     module Stateful
-      ACCESS_STATUSES = %w[active suspended].freeze
+      # suspended is recoverable; closed is terminal — revoke live keys, stop
+      # serving, keep your records.
+      ACCESS_STATUSES = %w[active suspended closed].freeze
 
       # zod v4's `iso.datetime({offset: true})` grammar, transcribed verbatim —
       # as the Python and Go SDKs also transcribe it. Seconds and the fraction
@@ -31,8 +33,8 @@ module ZeroClick
       ParsedEntitlement = Struct.new(
         :access_id, :agent_id, :buyer_id, :buyer_email, :idempotency_key,
         :state_version, :plan, :period, :status,
-        :credit_granted_usd, :credit_reversed_usd,
-        :base_price_usd_micros, :credit_granted_usd_micros, :credit_reversed_usd_micros,
+        :lifetime_credit_granted_usd, :lifetime_credit_reversed_usd,
+        :base_price_usd_micros, :lifetime_credit_granted_usd_micros, :lifetime_credit_reversed_usd_micros,
         keyword_init: true
       )
 
@@ -60,9 +62,11 @@ module ZeroClick
           nil
         end
 
-        # Absent and null both mean "not present"; an empty string is invalid.
+        # Required but nullable: a missing key is an error, null is not.
         # Returns [value, ok].
-        def optional_id(container, key)
+        def nullable_id(container, key)
+          return [nil, false] unless container.key?(key)
+
           value = container[key]
           return [nil, true] if value.nil?
           return [value, true] if non_empty_string?(value)
@@ -73,7 +77,7 @@ module ZeroClick
         def parse_mint_key_request(body)
           return nil unless body.is_a?(Hash) && non_empty_string?(body["agentId"])
 
-          buyer_id, ok = optional_id(body, "buyerId")
+          buyer_id, ok = nullable_id(body, "buyerId")
           return nil unless ok
 
           MintKeyRequest.new(agent_id: body["agentId"], buyer_id: buyer_id)
@@ -118,9 +122,9 @@ module ZeroClick
           AccessPeriod.new(start: start, end: finish)
         end
 
-        def parse_money_field(container, key, required:, issues:)
+        def parse_money_field(container, key, issues:)
           unless container.key?(key)
-            issues << "state.#{key}: required (may be null)" if required
+            issues << "state.#{key}: required (may be null)"
             return nil
           end
 

data/lib/zeroclick/sellers/stateful/entitlement.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "time"
+
 require_relative "../errors"
 require_relative "contracts"
 require_relative "money"
@@ -7,8 +9,8 @@ require_relative "money"
 module ZeroClick
   module Sellers
     module Stateful
-      StoredCreditGrant = Struct.new(:state_version, :credit_granted_usd_micros, :credit_reversed_usd_micros,
-                                     keyword_init: true)
+      StoredCreditGrant = Struct.new(:state_version, :lifetime_credit_granted_usd_micros,
+                                     :lifetime_credit_reversed_usd_micros, keyword_init: true)
 
       class ParseOk
         attr_reader :entitlement
@@ -74,10 +76,10 @@ module ZeroClick
             issues << "#{key}: expected a non-empty string" unless Contracts.non_empty_string?(body[key])
           end
 
-          buyer_id, buyer_ok = Contracts.optional_id(body, "buyerId")
-          issues << "buyerId: expected a non-empty string or null" unless buyer_ok
-          buyer_email, buyer_email_ok = Contracts.optional_id(body, "buyerEmail")
-          issues << "buyerEmail: expected a non-empty string or null" unless buyer_email_ok
+          buyer_id, buyer_ok = Contracts.nullable_id(body, "buyerId")
+          issues << "buyerId: required, a non-empty string or null" unless buyer_ok
+          buyer_email, buyer_email_ok = Contracts.nullable_id(body, "buyerEmail")
+          issues << "buyerEmail: required, a non-empty string or null" unless buyer_email_ok
 
           state_version = Contracts.as_version(body["stateVersion"])
           issues << "stateVersion: expected a non-negative integer" if state_version.nil?
@@ -96,11 +98,11 @@ module ZeroClick
           period = Contracts.parse_period(state["period"], period_issues)
           issues.concat(period_issues)
 
-          credit_granted = Contracts.parse_money_field(state, "creditGrantedUsd", required: true, issues: issues)
-          credit_reversed = Contracts.parse_money_field(state, "creditReversedUsd", required: false, issues: issues)
+          credit_granted = Contracts.parse_money_field(state, "lifetimeCreditGrantedUsd", issues: issues)
+          credit_reversed = Contracts.parse_money_field(state, "lifetimeCreditReversedUsd", issues: issues)
 
           status = state["status"]
-          issues << "state.status: expected active or suspended" unless ACCESS_STATUSES.include?(status)
+          issues << "state.status: expected active, suspended, or closed" unless ACCESS_STATUSES.include?(status)
 
           return ParseFailure.new(issues) unless issues.empty?
 
@@ -116,14 +118,25 @@ module ZeroClick
               buyer_id: buyer_id, buyer_email: buyer_email,
               idempotency_key: body["idempotencyKey"], state_version: state_version,
               plan: plan, period: period, status: status,
-              credit_granted_usd: credit_granted, credit_reversed_usd: credit_reversed,
+              lifetime_credit_granted_usd: credit_granted, lifetime_credit_reversed_usd: credit_reversed,
               base_price_usd_micros: base_price_micros,
-              credit_granted_usd_micros: Money.parse_money_usd(credit_granted),
-              credit_reversed_usd_micros: Money.parse_money_usd(credit_reversed)
+              lifetime_credit_granted_usd_micros: Money.parse_money_usd(credit_granted),
+              lifetime_credit_reversed_usd_micros: Money.parse_money_usd(credit_reversed)
             )
           )
         end
 
+        # The one request-time gate: serve only while the account is active AND
+        # its paid period (when it has one) is still current. Checking status
+        # alone misses period-based revocation; checking the period alone
+        # misses suspension and closure.
+        def serviceable?(state, now = Time.now)
+          return false unless state.status == "active"
+
+          finish = state.period&.end
+          finish.nil? || Time.iso8601(finish) > now
+        end
+
         # Never-regress: an entitlement is applied only when it is strictly
         # newer than what was last applied. Equal versions are replays, which
         # is what makes delivery retries safe.
@@ -166,30 +179,30 @@ module ZeroClick
         def derive_credit_delta(stored, entitlement)
           return CreditReplay.new if !stored.nil? && !should_apply?(stored.state_version, entitlement.state_version)
 
-          incoming = entitlement.credit_granted_usd_micros
+          incoming = entitlement.lifetime_credit_granted_usd_micros
           if incoming.nil?
             return NoCreditDimension.new(
               StoredCreditGrant.new(
                 state_version: entitlement.state_version,
-                credit_granted_usd_micros: stored&.credit_granted_usd_micros,
-                credit_reversed_usd_micros: stored&.credit_reversed_usd_micros
+                lifetime_credit_granted_usd_micros: stored&.lifetime_credit_granted_usd_micros,
+                lifetime_credit_reversed_usd_micros: stored&.lifetime_credit_reversed_usd_micros
               )
             )
           end
 
-          prior = stored_micros(stored&.credit_granted_usd_micros, "credit")
-          prior_reversed = stored_micros(stored&.credit_reversed_usd_micros, "reversal")
+          prior = stored_micros(stored&.lifetime_credit_granted_usd_micros, "credit")
+          prior_reversed = stored_micros(stored&.lifetime_credit_reversed_usd_micros, "reversal")
 
           # max(), not assignment: a stale delivery carrying a smaller total
           # must not walk the purse backwards.
           next_credit = [prior, incoming].max
-          next_reversed = [prior_reversed, entitlement.credit_reversed_usd_micros || 0].max
+          next_reversed = [prior_reversed, entitlement.lifetime_credit_reversed_usd_micros || 0].max
           delta = (next_credit - prior) - (next_reversed - prior_reversed)
 
           next_state = StoredCreditGrant.new(
             state_version: entitlement.state_version,
-            credit_granted_usd_micros: next_credit,
-            credit_reversed_usd_micros: next_reversed
+            lifetime_credit_granted_usd_micros: next_credit,
+            lifetime_credit_reversed_usd_micros: next_reversed
           )
 
           if delta.negative?

data/lib/zeroclick/sellers/version.rb

@@ -4,6 +4,6 @@ module ZeroClick
   module Sellers
     # Bump this to publish. The workflow reads it, asks RubyGems whether this
     # version already exists, and publishes only when it does not.
-    VERSION = "0.3.0"
+    VERSION = "0.4.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zeroclick-sellers
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - ZeroClick