@orangecheck/me-client 0.28.0 → 0.30.0

package/README.md

@@ -4,9 +4,9 @@
 > Hand-written prose below is the high-level overview; the docs site is the source of truth for every export, type, and signature.
 
 
-Client for [me.ochk.io](https://me.ochk.io). Popup sign-in for any site, framework-agnostic server-side verification, session lifecycle hooks, payment authorization, webhook signature verification, the canonical billable-event taxonomy as TypeScript types. `OcSignInButton` rides the family cookie, so it works only on orangecheck's own sites; anywhere else, sign people in with `signInWithOc()` from `/popup`.
+Client for [me.ochk.io](https://me.ochk.io). Popup sign-in for any site, framework-agnostic server-side verification, session lifecycle hooks, payment authorization, webhook signature verification, the canonical billable-event taxonomy as TypeScript types. Sign people in with `signInWithOc()` from `/popup`; the deprecated `OcSignInButton` rides the family cookie and works only on orangecheck's own sites.
 
-> You pay for sessions and actions, not for clicks.
+> Sign-in is free. Paying your users is optional: always, in promos you schedule, or never.
 
 ## Three entry points, three audiences
 
@@ -73,6 +73,24 @@ export default withOcAuth(handler, {
 
 Or set it in code with `requireBond: { minSats: 100_000, minDays: 30, maxAgeSecs: 3600 }`. ochk.io re-checks the coin when its last check is over ten minutes old; `maxAgeSecs` refuses a claim checked longer ago than you accept. From 0.28.0, an account below the floor gets `403 { ok: false, reason: 'bond_required', need: { min_sats, min_days }, have: { sats_floor, days_floor } | null, back_url }`: link the person to `back_url` to back their account. If the project's setting can't be read and never has been, the request gets `503 { reason: 'bond_policy_unavailable' }` rather than being let through unchecked. `readBondClaim(session)` and `bondMeets(session, { minSats, minDays, maxAgeSecs })` are exported for your own checks.
 
+## Pay your users, when you choose to
+
+Paying the people who use your app is optional. In your project's dashboard you turn it on, schedule promos ("Launch week", Oct 20 to 27), or leave it off. While a pay period runs, each event you send earns the person their share and takes its fee from your balance. Outside every period an event earns and costs nothing, and me.ochk.io records nothing, so you can fire events from code that runs all the time:
+
+```ts
+const res = await oc.event.fire({
+    project_key: 'pk_live_yourcompany',
+    subtype: 'account_creation',
+    signingSecret: process.env.OC_SIGNING_SECRET,
+    accountId: didOc,
+});
+if (!res.earned) {
+    // res.reason === 'not_paying'; res.next_pay_period says when paying starts, if scheduled
+}
+```
+
+`fireBatch` answers `not_paying` per event. `GET /api/integrator/config` publishes the project's `pay_periods`, past ones included, and `payingAt(periods, date)` tells you whether a project pays at a moment. Pass them to `oc.event.verify(envelope, config, amount, { payPeriods })` to flag a receipt billed outside every period.
+
 ## Session lifecycle
 
 Sessions are the billable atom for me.ochk.io: your server fires one `session_creation` event per real session with `oc.event.fire`. `oc.session.create` opens a session and records no charge, and a signin within a still-valid session is **free**. Site declares the policy at integration time; the OC verifier enforces it both client-side and server-side.

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { v as verifyActivityAttestation, r as refreshEnvelopeJwks } from './identity-1VYMOhzV.mjs';
 export { A as ActivityAttestation, a as ActivityAttestationBundle, b as ActivityVerifyCheck, c as ActivityVerifyResult, V as VerifyActivityOptions, i as identity } from './identity-1VYMOhzV.mjs';
-import { E as EventKey, B as BillableEvent, I as IntegratorPriceConfig, S as SessionPolicy, a as Session, T as TelemetryEvent, b as SignInOptions, P as PaymentAuthorizeOptions, c as PaymentResult, V as ValidationResult, f as fromTemplate, g as getArchetypeTemplate, A as ArchetypeTemplate, F as Federation } from './integrator-BVzzkZ6l.mjs';
+import { B as BillableEvent, E as EventKey, I as IntegratorPriceConfig, S as SessionPolicy, a as Session, T as TelemetryEvent, b as SignInOptions, P as PaymentAuthorizeOptions, c as PaymentResult, V as ValidationResult, f as fromTemplate, g as getArchetypeTemplate, A as ArchetypeTemplate, F as Federation } from './integrator-BVzzkZ6l.mjs';
 export { d as ALL_EVENT_SUBTYPES, e as ARCHETYPE_TEMPLATES, h as AgentClassOverride, i as AttestTier, C as ClassASubtype, j as ClassBSubtype, k as ClassCSubtype, l as ComputedFees, D as DropCadence, m as DropClosedWebhookPayload, n as DropResponseBlock, o as DropScheduleSummary, p as EVENT_SUBTYPES, q as EventClass, r as EventSubtype, s as EventSubtypeMetadata, t as FederationStatus, u as IntegratorArchetype, v as IntegratorEventConfig, M as MAX_DROP_WINDOW_DAYS, w as MIN_INTEGRATOR_PRICE_SATS, x as PLATFORM_FEE_POLICY, y as SigningMethod, z as SiteFeeShape, G as SystemWebhookPayload, W as WebhookHeaders, H as WebhookPayload, J as computeFees, K as subtypesForClass, L as validateIntegratorConfig } from './integrator-BVzzkZ6l.mjs';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
@@ -79,6 +79,21 @@ declare const webhook: {
     fetchJwks: typeof fetchJwksForce;
 };
 
+interface PayPeriod {
+    id: string;
+    name: string;
+    starts_at: string;
+    ends_at: string | null;
+}
+type PayingState = {
+    paying: true;
+    period: PayPeriod;
+} | {
+    paying: false;
+    next: PayPeriod | null;
+};
+declare function payingAt(periods: readonly PayPeriod[], at?: Date): PayingState;
+
 interface FireEventOptions {
     project_key: string;
     subtype: EventKey;
@@ -87,11 +102,27 @@ interface FireEventOptions {
     metadata?: Record<string, unknown>;
     is_agent?: boolean;
     signingSecret?: string;
+    accountId?: string;
     userAddress?: string;
     bearerToken?: string;
     idempotencyKey?: string;
 }
-declare function fire(options: FireEventOptions): Promise<BillableEvent>;
+type FireEventResult = {
+    ok: true;
+    earned: true;
+    event: BillableEvent;
+    webhooks_fired: number;
+    escrow_mode: 'simulation' | 'live';
+    idempotent_replay?: boolean;
+    simulation_mode_note?: string;
+} | {
+    ok: true;
+    earned: false;
+    reason: 'not_paying';
+    detail: string;
+    next_pay_period: PayPeriod | null;
+};
+declare function fire(options: FireEventOptions): Promise<FireEventResult>;
 interface BatchEventInput {
     subtype: EventKey;
     payment_amount_sats?: number;
@@ -112,6 +143,9 @@ type BatchEventResult = {
     index: number;
     status: 'rejected';
     reason: string;
+} | {
+    index: number;
+    status: 'not_paying';
 };
 interface FireBatchOptions {
     project_key: string;
@@ -122,6 +156,7 @@ interface FireBatchOptions {
 interface FireBatchResponse {
     ok: boolean;
     results: BatchEventResult[];
+    next_pay_period?: PayPeriod | null;
     escrow_mode: 'simulation' | 'live';
     simulation_mode_note?: string;
 }
@@ -129,7 +164,7 @@ declare function fireBatch(options: FireBatchOptions): Promise<FireBatchResponse
 interface VerifyEventResult {
     ok: boolean;
     issues: Array<{
-        field: 'gross_fee_sats' | 'platform_fee_sats' | 'user_earned_sats' | 'site_rebate_sats' | 'subtype_disabled' | 'subtype_unconfigured' | 'percent_amount_missing';
+        field: 'gross_fee_sats' | 'platform_fee_sats' | 'user_earned_sats' | 'site_rebate_sats' | 'subtype_disabled' | 'subtype_unconfigured' | 'percent_amount_missing' | 'outside_pay_period';
         expected: number | null;
         actual: number | null;
         message: string;
@@ -141,7 +176,9 @@ interface VerifyEventResult {
         site_rebate_sats: number;
     } | null;
 }
-declare function verify(envelope: BillableEvent, config: IntegratorPriceConfig, payment_amount_sats?: number): VerifyEventResult;
+declare function verify(envelope: BillableEvent, config: IntegratorPriceConfig, payment_amount_sats?: number, opts?: {
+    payPeriods?: readonly PayPeriod[];
+}): VerifyEventResult;
 declare const event: {
     fire: typeof fire;
     fireBatch: typeof fireBatch;
@@ -224,9 +261,11 @@ declare const oc: {
         authorize: (opts: PaymentAuthorizeOptions) => Promise<PaymentResult>;
     };
     event: {
-        fire: (options: FireEventOptions) => Promise<BillableEvent>;
+        fire: (options: FireEventOptions) => Promise<FireEventResult>;
         fireBatch: (options: FireBatchOptions) => Promise<FireBatchResponse>;
-        verify: (envelope: BillableEvent, config: IntegratorPriceConfig, payment_amount_sats?: number) => VerifyEventResult;
+        verify: (envelope: BillableEvent, config: IntegratorPriceConfig, payment_amount_sats?: number, opts?: {
+            payPeriods?: readonly PayPeriod[];
+        }) => VerifyEventResult;
     };
     config: {
         validate: (cfg: IntegratorPriceConfig) => ValidationResult;
@@ -258,4 +297,4 @@ declare const oc: {
     };
 };
 
-export { ArchetypeTemplate, BillableEvent, EventKey, type FamilyScopesOptions, type FamilyScopesResult, type FamilyVerb, Federation, type FireEventOptions, type GrantedOptions, type GrantedResult, IntegratorPriceConfig, MeClientError, type OcPublicJwk, OcSignInButton, type OcSignInButtonProps, PaymentAuthorizeOptions, PaymentResult, type RequestOptions, type Scope, Session, SessionPolicy, SignInOptions, TelemetryEvent, type TrustAttestationCount, ValidationResult, type VerifyEventResult, type VerifyOptions, type VerifyResult, type WithRateLimitRetryOptions, clearBearerToken, config, fromTemplate as configFromTemplate, event, family, federations, getArchetypeTemplate, getBearerToken, getOrigin, oc, onTelemetry, parseTrustAttestationCount, payment, refreshEnvelopeJwks, scope, session, setBearerToken, setOrigin, verifyActivityAttestation, webhook, withRateLimitRetry };
+export { ArchetypeTemplate, type BatchEventResult, BillableEvent, EventKey, type FamilyScopesOptions, type FamilyScopesResult, type FamilyVerb, Federation, type FireBatchResponse, type FireEventOptions, type FireEventResult, type GrantedOptions, type GrantedResult, IntegratorPriceConfig, MeClientError, type OcPublicJwk, OcSignInButton, type OcSignInButtonProps, type PayPeriod, type PayingState, PaymentAuthorizeOptions, PaymentResult, type RequestOptions, type Scope, Session, SessionPolicy, SignInOptions, TelemetryEvent, type TrustAttestationCount, ValidationResult, type VerifyEventResult, type VerifyOptions, type VerifyResult, type WithRateLimitRetryOptions, clearBearerToken, config, fromTemplate as configFromTemplate, event, family, federations, getArchetypeTemplate, getBearerToken, getOrigin, oc, onTelemetry, parseTrustAttestationCount, payingAt, payment, refreshEnvelopeJwks, scope, session, setBearerToken, setOrigin, verifyActivityAttestation, webhook, withRateLimitRetry };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { v as verifyActivityAttestation, r as refreshEnvelopeJwks } from './identity-1VYMOhzV.js';
 export { A as ActivityAttestation, a as ActivityAttestationBundle, b as ActivityVerifyCheck, c as ActivityVerifyResult, V as VerifyActivityOptions, i as identity } from './identity-1VYMOhzV.js';
-import { E as EventKey, B as BillableEvent, I as IntegratorPriceConfig, S as SessionPolicy, a as Session, T as TelemetryEvent, b as SignInOptions, P as PaymentAuthorizeOptions, c as PaymentResult, V as ValidationResult, f as fromTemplate, g as getArchetypeTemplate, A as ArchetypeTemplate, F as Federation } from './integrator-BVzzkZ6l.js';
+import { B as BillableEvent, E as EventKey, I as IntegratorPriceConfig, S as SessionPolicy, a as Session, T as TelemetryEvent, b as SignInOptions, P as PaymentAuthorizeOptions, c as PaymentResult, V as ValidationResult, f as fromTemplate, g as getArchetypeTemplate, A as ArchetypeTemplate, F as Federation } from './integrator-BVzzkZ6l.js';
 export { d as ALL_EVENT_SUBTYPES, e as ARCHETYPE_TEMPLATES, h as AgentClassOverride, i as AttestTier, C as ClassASubtype, j as ClassBSubtype, k as ClassCSubtype, l as ComputedFees, D as DropCadence, m as DropClosedWebhookPayload, n as DropResponseBlock, o as DropScheduleSummary, p as EVENT_SUBTYPES, q as EventClass, r as EventSubtype, s as EventSubtypeMetadata, t as FederationStatus, u as IntegratorArchetype, v as IntegratorEventConfig, M as MAX_DROP_WINDOW_DAYS, w as MIN_INTEGRATOR_PRICE_SATS, x as PLATFORM_FEE_POLICY, y as SigningMethod, z as SiteFeeShape, G as SystemWebhookPayload, W as WebhookHeaders, H as WebhookPayload, J as computeFees, K as subtypesForClass, L as validateIntegratorConfig } from './integrator-BVzzkZ6l.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
@@ -79,6 +79,21 @@ declare const webhook: {
     fetchJwks: typeof fetchJwksForce;
 };
 
+interface PayPeriod {
+    id: string;
+    name: string;
+    starts_at: string;
+    ends_at: string | null;
+}
+type PayingState = {
+    paying: true;
+    period: PayPeriod;
+} | {
+    paying: false;
+    next: PayPeriod | null;
+};
+declare function payingAt(periods: readonly PayPeriod[], at?: Date): PayingState;
+
 interface FireEventOptions {
     project_key: string;
     subtype: EventKey;
@@ -87,11 +102,27 @@ interface FireEventOptions {
     metadata?: Record<string, unknown>;
     is_agent?: boolean;
     signingSecret?: string;
+    accountId?: string;
     userAddress?: string;
     bearerToken?: string;
     idempotencyKey?: string;
 }
-declare function fire(options: FireEventOptions): Promise<BillableEvent>;
+type FireEventResult = {
+    ok: true;
+    earned: true;
+    event: BillableEvent;
+    webhooks_fired: number;
+    escrow_mode: 'simulation' | 'live';
+    idempotent_replay?: boolean;
+    simulation_mode_note?: string;
+} | {
+    ok: true;
+    earned: false;
+    reason: 'not_paying';
+    detail: string;
+    next_pay_period: PayPeriod | null;
+};
+declare function fire(options: FireEventOptions): Promise<FireEventResult>;
 interface BatchEventInput {
     subtype: EventKey;
     payment_amount_sats?: number;
@@ -112,6 +143,9 @@ type BatchEventResult = {
     index: number;
     status: 'rejected';
     reason: string;
+} | {
+    index: number;
+    status: 'not_paying';
 };
 interface FireBatchOptions {
     project_key: string;
@@ -122,6 +156,7 @@ interface FireBatchOptions {
 interface FireBatchResponse {
     ok: boolean;
     results: BatchEventResult[];
+    next_pay_period?: PayPeriod | null;
     escrow_mode: 'simulation' | 'live';
     simulation_mode_note?: string;
 }
@@ -129,7 +164,7 @@ declare function fireBatch(options: FireBatchOptions): Promise<FireBatchResponse
 interface VerifyEventResult {
     ok: boolean;
     issues: Array<{
-        field: 'gross_fee_sats' | 'platform_fee_sats' | 'user_earned_sats' | 'site_rebate_sats' | 'subtype_disabled' | 'subtype_unconfigured' | 'percent_amount_missing';
+        field: 'gross_fee_sats' | 'platform_fee_sats' | 'user_earned_sats' | 'site_rebate_sats' | 'subtype_disabled' | 'subtype_unconfigured' | 'percent_amount_missing' | 'outside_pay_period';
         expected: number | null;
         actual: number | null;
         message: string;
@@ -141,7 +176,9 @@ interface VerifyEventResult {
         site_rebate_sats: number;
     } | null;
 }
-declare function verify(envelope: BillableEvent, config: IntegratorPriceConfig, payment_amount_sats?: number): VerifyEventResult;
+declare function verify(envelope: BillableEvent, config: IntegratorPriceConfig, payment_amount_sats?: number, opts?: {
+    payPeriods?: readonly PayPeriod[];
+}): VerifyEventResult;
 declare const event: {
     fire: typeof fire;
     fireBatch: typeof fireBatch;
@@ -224,9 +261,11 @@ declare const oc: {
         authorize: (opts: PaymentAuthorizeOptions) => Promise<PaymentResult>;
     };
     event: {
-        fire: (options: FireEventOptions) => Promise<BillableEvent>;
+        fire: (options: FireEventOptions) => Promise<FireEventResult>;
         fireBatch: (options: FireBatchOptions) => Promise<FireBatchResponse>;
-        verify: (envelope: BillableEvent, config: IntegratorPriceConfig, payment_amount_sats?: number) => VerifyEventResult;
+        verify: (envelope: BillableEvent, config: IntegratorPriceConfig, payment_amount_sats?: number, opts?: {
+            payPeriods?: readonly PayPeriod[];
+        }) => VerifyEventResult;
     };
     config: {
         validate: (cfg: IntegratorPriceConfig) => ValidationResult;
@@ -258,4 +297,4 @@ declare const oc: {
     };
 };
 
-export { ArchetypeTemplate, BillableEvent, EventKey, type FamilyScopesOptions, type FamilyScopesResult, type FamilyVerb, Federation, type FireEventOptions, type GrantedOptions, type GrantedResult, IntegratorPriceConfig, MeClientError, type OcPublicJwk, OcSignInButton, type OcSignInButtonProps, PaymentAuthorizeOptions, PaymentResult, type RequestOptions, type Scope, Session, SessionPolicy, SignInOptions, TelemetryEvent, type TrustAttestationCount, ValidationResult, type VerifyEventResult, type VerifyOptions, type VerifyResult, type WithRateLimitRetryOptions, clearBearerToken, config, fromTemplate as configFromTemplate, event, family, federations, getArchetypeTemplate, getBearerToken, getOrigin, oc, onTelemetry, parseTrustAttestationCount, payment, refreshEnvelopeJwks, scope, session, setBearerToken, setOrigin, verifyActivityAttestation, webhook, withRateLimitRetry };
+export { ArchetypeTemplate, type BatchEventResult, BillableEvent, EventKey, type FamilyScopesOptions, type FamilyScopesResult, type FamilyVerb, Federation, type FireBatchResponse, type FireEventOptions, type FireEventResult, type GrantedOptions, type GrantedResult, IntegratorPriceConfig, MeClientError, type OcPublicJwk, OcSignInButton, type OcSignInButtonProps, type PayPeriod, type PayingState, PaymentAuthorizeOptions, PaymentResult, type RequestOptions, type Scope, Session, SessionPolicy, SignInOptions, TelemetryEvent, type TrustAttestationCount, ValidationResult, type VerifyEventResult, type VerifyOptions, type VerifyResult, type WithRateLimitRetryOptions, clearBearerToken, config, fromTemplate as configFromTemplate, event, family, federations, getArchetypeTemplate, getBearerToken, getOrigin, oc, onTelemetry, parseTrustAttestationCount, payingAt, payment, refreshEnvelopeJwks, scope, session, setBearerToken, setOrigin, verifyActivityAttestation, webhook, withRateLimitRetry };

package/dist/index.js

@@ -339,6 +339,18 @@ function validateIntegratorConfig(cfg) {
   return { ok: errors.length === 0, errors };
 }
 
+// src/pay-periods.ts
+var ms = (iso) => Date.parse(iso);
+function payingAt(periods, at = /* @__PURE__ */ new Date()) {
+  const t = at.getTime();
+  const current = periods.find(
+    (p) => ms(p.starts_at) <= t && (p.ends_at === null || t < ms(p.ends_at))
+  );
+  if (current) return { paying: true, period: current };
+  const next = periods.filter((p) => ms(p.starts_at) > t).sort((a, b) => ms(a.starts_at) - ms(b.starts_at))[0];
+  return { paying: false, next: next ?? null };
+}
+
 // src/event.ts
 async function hmacSha256Hex(secret, message) {
   const enc = new TextEncoder();
@@ -364,9 +376,13 @@ async function fire(options) {
   if (!options.subtype) {
     throw new Error("event.fire requires subtype");
   }
-  if (options.userAddress && !options.signingSecret) {
+  if (options.accountId !== void 0 && options.userAddress !== void 0 && options.accountId !== options.userAddress) {
+    throw new Error("event.fire: accountId and userAddress name different earners");
+  }
+  const earner = options.accountId ?? options.userAddress;
+  if (earner && !options.signingSecret) {
     throw new Error(
-      "event.fire: userAddress names who earns, so it requires signingSecret \u2014 the signature over the request body is what authorises that earner. Without the secret, pass bearerToken (or rely on the oc_session cookie) and the caller earns instead."
+      "event.fire: accountId names who earns, so it requires signingSecret \u2014 the signature over the request body is what authorises that earner. Without the secret, pass bearerToken (or rely on the oc_session cookie) and the caller earns instead."
     );
   }
   const requestBody = {
@@ -378,7 +394,7 @@ async function fire(options) {
   if (options.action_label !== void 0) requestBody.action_label = options.action_label;
   if (options.metadata !== void 0) requestBody.metadata = options.metadata;
   if (options.is_agent !== void 0) requestBody.is_agent = options.is_agent;
-  if (options.userAddress !== void 0) requestBody.user_address = options.userAddress;
+  if (earner !== void 0) requestBody.user_address = earner;
   const headers = {};
   if (options.idempotencyKey) headers["idempotency-key"] = options.idempotencyKey;
   if (options.signingSecret) {
@@ -421,14 +437,23 @@ async function fireBatch(options) {
     bearerToken: options.bearerToken
   });
 }
-function verify(envelope, config2, payment_amount_sats) {
+function verify(envelope, config2, payment_amount_sats, opts = {}) {
   const issues = [];
+  if (opts.payPeriods && !payingAt(opts.payPeriods, new Date(envelope.occurred_at)).paying) {
+    issues.push({
+      field: "outside_pay_period",
+      expected: null,
+      actual: null,
+      message: `billed at ${envelope.occurred_at}, when ${config2.project_key} wasn't paying its users`
+    });
+  }
   const eventCfg = config2.events[envelope.subtype];
   if (!eventCfg) {
     return {
       ok: false,
       expected: null,
       issues: [
+        ...issues,
         {
           field: "subtype_unconfigured",
           expected: null,
@@ -443,6 +468,7 @@ function verify(envelope, config2, payment_amount_sats) {
       ok: false,
       expected: null,
       issues: [
+        ...issues,
         {
           field: "subtype_disabled",
           expected: null,
@@ -457,6 +483,7 @@ function verify(envelope, config2, payment_amount_sats) {
       ok: false,
       expected: null,
       issues: [
+        ...issues,
         {
           field: "percent_amount_missing",
           expected: null,
@@ -1574,6 +1601,7 @@ exports.identity = identity;
 exports.oc = oc;
 exports.onTelemetry = onTelemetry;
 exports.parseTrustAttestationCount = parseTrustAttestationCount;
+exports.payingAt = payingAt;
 exports.payment = payment;
 exports.refreshEnvelopeJwks = refreshEnvelopeJwks;
 exports.scope = scope;