@orangecheck/me-client 0.9.0 → 0.12.0

package/dist/index.d.mts

@@ -1,6 +1,28 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
 
+type Scope = 'bitcoin_address' | 'email' | 'attest_tier' | 'display_name';
+interface GrantedOptions {
+    project_key: string;
+    signal?: AbortSignal;
+}
+interface GrantedResult {
+    sub: string;
+    scopes_granted: Scope[];
+    scopes: Partial<Record<Scope, string>>;
+}
+declare function granted(options: GrantedOptions): Promise<GrantedResult>;
+interface RequestOptions {
+    project_key: string;
+    return_to: string;
+    origin?: string;
+}
+declare function request(scopes: Scope[], options: RequestOptions): never;
+declare const scope: {
+    granted: typeof granted;
+    request: typeof request;
+};
+
 interface VerifyResult {
     ok: boolean;
     reason?: string;
@@ -152,6 +174,37 @@ interface FireEventOptions {
     metadata?: Record<string, unknown>;
 }
 declare function fire(options: FireEventOptions): Promise<BillableEvent>;
+interface BatchEventInput {
+    subtype: EventSubtype;
+    payment_amount_sats?: number;
+    action_label?: string;
+    note?: string;
+    idempotency_key?: string;
+}
+type BatchEventResult = {
+    index: number;
+    status: 'recorded';
+    event: BillableEvent;
+} | {
+    index: number;
+    status: 'duplicate';
+    event: BillableEvent;
+} | {
+    index: number;
+    status: 'rejected';
+    reason: string;
+};
+interface FireBatchOptions {
+    project_key: string;
+    events: BatchEventInput[];
+}
+interface FireBatchResponse {
+    ok: boolean;
+    results: BatchEventResult[];
+    escrow_mode: 'simulation' | 'live';
+    simulation_mode_note?: string;
+}
+declare function fireBatch(options: FireBatchOptions): Promise<FireBatchResponse>;
 interface VerifyEventResult {
     ok: boolean;
     issues: Array<{
@@ -170,6 +223,7 @@ interface VerifyEventResult {
 declare function verify(envelope: BillableEvent, config: IntegratorPriceConfig, payment_amount_sats?: number): VerifyEventResult;
 declare const event: {
     fire: typeof fire;
+    fireBatch: typeof fireBatch;
     verify: typeof verify;
 };
 
@@ -221,8 +275,20 @@ declare function getBearerToken(): string | null;
 declare function clearBearerToken(): void;
 declare class MeClientError extends Error {
     readonly status: number;
-    constructor(message: string, status: number);
+    readonly errorCode: string | undefined;
+    readonly retryAfterSeconds: number | undefined;
+    constructor(message: string, status: number, opts?: {
+        errorCode?: string;
+        retryAfterSeconds?: number;
+    });
+    get isRateLimited(): boolean;
 }
+interface WithRateLimitRetryOptions {
+    maxRetries?: number;
+    maxRetryAfterSeconds?: number;
+    baseBackoffMs?: number;
+}
+declare function withRateLimitRetry<T>(fn: () => Promise<T>, opts?: WithRateLimitRetryOptions): Promise<T>;
 
 declare const oc: {
     session: {
@@ -235,6 +301,7 @@ declare const oc: {
     };
     event: {
         fire: (options: FireEventOptions) => Promise<BillableEvent>;
+        fireBatch: (options: FireBatchOptions) => Promise<FireBatchResponse>;
         verify: (envelope: BillableEvent, config: IntegratorPriceConfig, payment_amount_sats?: number) => VerifyEventResult;
     };
     config: {
@@ -250,6 +317,10 @@ declare const oc: {
         get: (slug: string) => Promise<Federation | null>;
         defaultLive: () => Promise<Federation | null>;
     };
+    scope: {
+        granted: (options: GrantedOptions) => Promise<GrantedResult>;
+        request: typeof request;
+    };
 };
 
-export { type AttestTier, type BillableEvent, type ClassASubtype, type ClassBSubtype, type ClassCSubtype, type ComputedFees, type EventClass, type EventSubtype, type Federation, type FederationStatus, type FireEventOptions, type IntegratorEventConfig, type IntegratorPriceConfig, MIN_INTEGRATOR_PRICE_SATS, MeClientError, type OcPublicJwk, OcSignInButton, type OcSignInButtonProps, PLATFORM_FEE_POLICY, type PaymentAuthorizeOptions, type PaymentResult, type Session, type SessionPolicy, type SignInOptions, type SigningMethod, type SiteFeeShape, type TelemetryEvent, type ValidationResult, type VerifyEventResult, type VerifyOptions, type VerifyResult, clearBearerToken, computeFees, config, event, federations, getBearerToken, getOrigin, oc, onTelemetry, payment, session, setBearerToken, setOrigin, validateIntegratorConfig, webhook };
+export { type AttestTier, type BillableEvent, type ClassASubtype, type ClassBSubtype, type ClassCSubtype, type ComputedFees, type EventClass, type EventSubtype, type Federation, type FederationStatus, type FireEventOptions, type GrantedOptions, type GrantedResult, type IntegratorEventConfig, type IntegratorPriceConfig, MIN_INTEGRATOR_PRICE_SATS, MeClientError, type OcPublicJwk, OcSignInButton, type OcSignInButtonProps, PLATFORM_FEE_POLICY, type PaymentAuthorizeOptions, type PaymentResult, type RequestOptions, type Scope, type Session, type SessionPolicy, type SignInOptions, type SigningMethod, type SiteFeeShape, type TelemetryEvent, type ValidationResult, type VerifyEventResult, type VerifyOptions, type VerifyResult, type WithRateLimitRetryOptions, clearBearerToken, computeFees, config, event, federations, getBearerToken, getOrigin, oc, onTelemetry, payment, scope, session, setBearerToken, setOrigin, validateIntegratorConfig, webhook, withRateLimitRetry };

package/dist/index.d.ts

@@ -1,6 +1,28 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
 
+type Scope = 'bitcoin_address' | 'email' | 'attest_tier' | 'display_name';
+interface GrantedOptions {
+    project_key: string;
+    signal?: AbortSignal;
+}
+interface GrantedResult {
+    sub: string;
+    scopes_granted: Scope[];
+    scopes: Partial<Record<Scope, string>>;
+}
+declare function granted(options: GrantedOptions): Promise<GrantedResult>;
+interface RequestOptions {
+    project_key: string;
+    return_to: string;
+    origin?: string;
+}
+declare function request(scopes: Scope[], options: RequestOptions): never;
+declare const scope: {
+    granted: typeof granted;
+    request: typeof request;
+};
+
 interface VerifyResult {
     ok: boolean;
     reason?: string;
@@ -152,6 +174,37 @@ interface FireEventOptions {
     metadata?: Record<string, unknown>;
 }
 declare function fire(options: FireEventOptions): Promise<BillableEvent>;
+interface BatchEventInput {
+    subtype: EventSubtype;
+    payment_amount_sats?: number;
+    action_label?: string;
+    note?: string;
+    idempotency_key?: string;
+}
+type BatchEventResult = {
+    index: number;
+    status: 'recorded';
+    event: BillableEvent;
+} | {
+    index: number;
+    status: 'duplicate';
+    event: BillableEvent;
+} | {
+    index: number;
+    status: 'rejected';
+    reason: string;
+};
+interface FireBatchOptions {
+    project_key: string;
+    events: BatchEventInput[];
+}
+interface FireBatchResponse {
+    ok: boolean;
+    results: BatchEventResult[];
+    escrow_mode: 'simulation' | 'live';
+    simulation_mode_note?: string;
+}
+declare function fireBatch(options: FireBatchOptions): Promise<FireBatchResponse>;
 interface VerifyEventResult {
     ok: boolean;
     issues: Array<{
@@ -170,6 +223,7 @@ interface VerifyEventResult {
 declare function verify(envelope: BillableEvent, config: IntegratorPriceConfig, payment_amount_sats?: number): VerifyEventResult;
 declare const event: {
     fire: typeof fire;
+    fireBatch: typeof fireBatch;
     verify: typeof verify;
 };
 
@@ -221,8 +275,20 @@ declare function getBearerToken(): string | null;
 declare function clearBearerToken(): void;
 declare class MeClientError extends Error {
     readonly status: number;
-    constructor(message: string, status: number);
+    readonly errorCode: string | undefined;
+    readonly retryAfterSeconds: number | undefined;
+    constructor(message: string, status: number, opts?: {
+        errorCode?: string;
+        retryAfterSeconds?: number;
+    });
+    get isRateLimited(): boolean;
 }
+interface WithRateLimitRetryOptions {
+    maxRetries?: number;
+    maxRetryAfterSeconds?: number;
+    baseBackoffMs?: number;
+}
+declare function withRateLimitRetry<T>(fn: () => Promise<T>, opts?: WithRateLimitRetryOptions): Promise<T>;
 
 declare const oc: {
     session: {
@@ -235,6 +301,7 @@ declare const oc: {
     };
     event: {
         fire: (options: FireEventOptions) => Promise<BillableEvent>;
+        fireBatch: (options: FireBatchOptions) => Promise<FireBatchResponse>;
         verify: (envelope: BillableEvent, config: IntegratorPriceConfig, payment_amount_sats?: number) => VerifyEventResult;
     };
     config: {
@@ -250,6 +317,10 @@ declare const oc: {
         get: (slug: string) => Promise<Federation | null>;
         defaultLive: () => Promise<Federation | null>;
     };
+    scope: {
+        granted: (options: GrantedOptions) => Promise<GrantedResult>;
+        request: typeof request;
+    };
 };
 
-export { type AttestTier, type BillableEvent, type ClassASubtype, type ClassBSubtype, type ClassCSubtype, type ComputedFees, type EventClass, type EventSubtype, type Federation, type FederationStatus, type FireEventOptions, type IntegratorEventConfig, type IntegratorPriceConfig, MIN_INTEGRATOR_PRICE_SATS, MeClientError, type OcPublicJwk, OcSignInButton, type OcSignInButtonProps, PLATFORM_FEE_POLICY, type PaymentAuthorizeOptions, type PaymentResult, type Session, type SessionPolicy, type SignInOptions, type SigningMethod, type SiteFeeShape, type TelemetryEvent, type ValidationResult, type VerifyEventResult, type VerifyOptions, type VerifyResult, clearBearerToken, computeFees, config, event, federations, getBearerToken, getOrigin, oc, onTelemetry, payment, session, setBearerToken, setOrigin, validateIntegratorConfig, webhook };
+export { type AttestTier, type BillableEvent, type ClassASubtype, type ClassBSubtype, type ClassCSubtype, type ComputedFees, type EventClass, type EventSubtype, type Federation, type FederationStatus, type FireEventOptions, type GrantedOptions, type GrantedResult, type IntegratorEventConfig, type IntegratorPriceConfig, MIN_INTEGRATOR_PRICE_SATS, MeClientError, type OcPublicJwk, OcSignInButton, type OcSignInButtonProps, PLATFORM_FEE_POLICY, type PaymentAuthorizeOptions, type PaymentResult, type RequestOptions, type Scope, type Session, type SessionPolicy, type SignInOptions, type SigningMethod, type SiteFeeShape, type TelemetryEvent, type ValidationResult, type VerifyEventResult, type VerifyOptions, type VerifyResult, type WithRateLimitRetryOptions, clearBearerToken, computeFees, config, event, federations, getBearerToken, getOrigin, oc, onTelemetry, payment, scope, session, setBearerToken, setOrigin, validateIntegratorConfig, webhook, withRateLimitRetry };

package/dist/index.js

@@ -60,22 +60,69 @@ async function api(path, opts = {}) {
   });
   if (!res.ok) {
     let message = `me.ochk.io ${res.status}`;
+    let errorCode;
+    let body;
     try {
       const data = await res.json();
-      if (data?.error) message = data.error;
+      body = data;
+      if (data?.error) {
+        errorCode = data.error;
+        message = data.reason ?? data.error;
+      }
     } catch {
     }
-    throw new MeClientError(message, res.status);
+    let retryAfterSeconds;
+    if (res.status === 429) {
+      const headerValue = res.headers.get("retry-after");
+      if (headerValue) {
+        const parsed = Number.parseInt(headerValue, 10);
+        if (Number.isFinite(parsed) && parsed >= 0) retryAfterSeconds = parsed;
+      }
+      if (retryAfterSeconds == null && typeof body?.retry_after_seconds === "number") {
+        retryAfterSeconds = body.retry_after_seconds;
+      }
+    }
+    throw new MeClientError(message, res.status, { errorCode, retryAfterSeconds });
   }
   return await res.json();
 }
 var MeClientError = class extends Error {
-  constructor(message, status) {
+  constructor(message, status, opts) {
     super(message);
     this.name = "MeClientError";
     this.status = status;
+    this.errorCode = opts?.errorCode;
+    this.retryAfterSeconds = opts?.retryAfterSeconds;
+  }
+  /** True for the 429 surface · convenience boolean so callers don't
+   *  have to compare status === 429 every time. */
+  get isRateLimited() {
+    return this.status === 429;
   }
 };
+async function withRateLimitRetry(fn, opts = {}) {
+  const maxRetries = opts.maxRetries ?? 2;
+  const maxRetryAfter = opts.maxRetryAfterSeconds ?? 30;
+  const baseBackoff = opts.baseBackoffMs ?? 250;
+  let attempt = 0;
+  while (true) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (!(err instanceof MeClientError) || !err.isRateLimited) throw err;
+      if (attempt >= maxRetries) throw err;
+      let waitMs;
+      if (err.retryAfterSeconds != null) {
+        if (err.retryAfterSeconds > maxRetryAfter) throw err;
+        waitMs = err.retryAfterSeconds * 1e3;
+      } else {
+        waitMs = baseBackoff * 2 ** attempt;
+      }
+      await new Promise((resolve) => setTimeout(resolve, waitMs));
+      attempt++;
+    }
+  }
+}
 
 // src/session.ts
 var DEFAULT_POLICY = {
@@ -131,7 +178,7 @@ async function invalidate(sessionId) {
 }
 var session = { create, refresh, invalidate };
 function OcSignInButton({
-  scope,
+  scope: scope2,
   sessionPolicy,
   returnTo,
   onSignin,
@@ -152,7 +199,7 @@ function OcSignInButton({
         if (event2.defaultPrevented) return;
         setPending(true);
         try {
-          const result = await session.create({ scope, sessionPolicy, returnTo });
+          const result = await session.create({ scope: scope2, sessionPolicy, returnTo });
           onSignin?.(result);
         } catch (err) {
           onSignInError?.(err instanceof Error ? err : new Error(String(err)));
@@ -294,6 +341,23 @@ async function fire(options) {
     body: options
   });
 }
+async function fireBatch(options) {
+  if (!options.project_key) {
+    throw new Error("event.fireBatch requires project_key");
+  }
+  if (!Array.isArray(options.events) || options.events.length === 0) {
+    throw new Error("event.fireBatch requires at least one event");
+  }
+  if (options.events.length > 100) {
+    throw new Error(
+      `event.fireBatch \xB7 max 100 events per call (got ${options.events.length}). Split client-side.`
+    );
+  }
+  return api("/api/integrator/event/batch", {
+    method: "POST",
+    body: options
+  });
+}
 function verify(envelope, config2, payment_amount_sats) {
   const issues = [];
   const eventCfg = config2.events[envelope.subtype];
@@ -378,7 +442,7 @@ function verify(envelope, config2, payment_amount_sats) {
     issues
   };
 }
-var event = { fire, verify };
+var event = { fire, fireBatch, verify };
 
 // src/config.ts
 function validate(cfg) {
@@ -744,8 +808,59 @@ async function defaultLive() {
 }
 var federations = { list, live, get, defaultLive };
 
+// src/scope.ts
+var VALID_SCOPES = [
+  "bitcoin_address",
+  "email",
+  "attest_tier",
+  "display_name"
+];
+async function granted(options) {
+  if (!options.project_key) {
+    throw new Error("oc.scope.granted: project_key is required");
+  }
+  const r = await api(
+    `/api/integrator/scopes/${encodeURIComponent(options.project_key)}`,
+    { method: "GET", signal: options.signal }
+  );
+  return {
+    sub: r.sub,
+    scopes_granted: r.scopes_granted,
+    scopes: r.scopes
+  };
+}
+function request(scopes, options) {
+  if (!options.project_key) {
+    throw new Error("oc.scope.request: project_key is required");
+  }
+  if (!options.return_to) {
+    throw new Error("oc.scope.request: return_to is required");
+  }
+  if (!Array.isArray(scopes) || scopes.length === 0) {
+    throw new Error("oc.scope.request: scopes must be a non-empty array");
+  }
+  for (const s of scopes) {
+    if (!VALID_SCOPES.includes(s)) {
+      throw new Error(
+        `oc.scope.request: unknown scope "${s}" \xB7 valid: ${VALID_SCOPES.join(", ")}`
+      );
+    }
+  }
+  if (typeof window === "undefined") {
+    throw new Error("oc.scope.request: must be called in a browser environment");
+  }
+  const origin2 = options.origin ?? getOrigin();
+  const url = new URL("/me/scope-grant", origin2);
+  url.searchParams.set("project_key", options.project_key);
+  url.searchParams.set("scopes", scopes.join(","));
+  url.searchParams.set("return_to", options.return_to);
+  window.location.assign(url.toString());
+  throw new Error("oc.scope.request: redirected to consent prompt");
+}
+var scope = { granted, request };
+
 // src/index.ts
-var oc = { session, payment, event, config, webhook, federations };
+var oc = { session, payment, event, config, webhook, federations, scope };
 
 exports.MIN_INTEGRATOR_PRICE_SATS = MIN_INTEGRATOR_PRICE_SATS;
 exports.MeClientError = MeClientError;
@@ -761,10 +876,12 @@ exports.getOrigin = getOrigin;
 exports.oc = oc;
 exports.onTelemetry = onTelemetry;
 exports.payment = payment;
+exports.scope = scope;
 exports.session = session;
 exports.setBearerToken = setBearerToken;
 exports.setOrigin = setOrigin;
 exports.validateIntegratorConfig = validateIntegratorConfig;
 exports.webhook = webhook;
+exports.withRateLimitRetry = withRateLimitRetry;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map