@rovenue/web-sdk 0.0.0-stage → 0.16.0

package/dist/index.d.cts

@@ -0,0 +1,222 @@
+interface SdkStorage {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+}
+/**
+ * In-memory storage. The default, and the fallback whenever a real store is
+ * unavailable.
+ *
+ * Nothing here throws: a viewer whose browser refuses storage must still get
+ * a working SDK, just one that forgets between page loads.
+ */
+declare function createMemoryStorage(): SdkStorage;
+/**
+ * Storage backed by `localStorage` where it works, memory where it does not.
+ *
+ * `localStorage` fails in three different ways and only the first is caught
+ * by asking whether it is defined:
+ *
+ *   1. **Absent** — server-side rendering. This is why the probe runs on
+ *      first use and never at module scope: an access during import throws
+ *      before any consumer could guard it.
+ *   2. **Present but throwing** — Safari private mode, and browsers with
+ *      site data blocked. `typeof localStorage` is `"object"` and the first
+ *      write raises.
+ *   3. **Present and full** — a quota error on a write, long after the probe
+ *      said everything was fine. So every operation is guarded, not just the
+ *      probe: a store that passed once can still fail later.
+ *
+ * A failed write drops the value and returns. Losing a cached entitlement is
+ * a lost convenience; taking the host application down over it is not a
+ * trade the SDK gets to make on the developer's behalf.
+ */
+declare function createStorage(): SdkStorage;
+
+interface Identity {
+    /** The permanent wire identity for this browser. */
+    rovenueId(): string;
+    /** The host application's own name for this person, if it set one. */
+    appUserScope(): string | null;
+    identify(appUserId: string): void;
+    /** Forgets both, and mints a fresh rovenueId. */
+    logOut(): void;
+}
+
+declare class RovenueApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+interface HttpClient {
+    get<T>(path: string): Promise<T>;
+    post<T>(path: string, body: unknown, init?: {
+        idempotencyKey?: string;
+        keepalive?: boolean;
+    }): Promise<T>;
+    /** Absolute base, e.g. `https://api.example/v1/web/pk_live_x`. */
+    readonly baseUrl: string;
+}
+
+interface CachedEntitlements {
+    entitlements: Record<string, unknown>;
+    /** Epoch millis of the response this came from. */
+    fetchedAt: number;
+}
+
+/** Wire format version the server expects (EVENT_WIRE_VERSION). */
+declare const EVENT_WIRE_VERSION = 1;
+interface TrackInput {
+    eventType: string;
+    occurredAt?: string;
+    subscriberId?: string;
+    productId?: string;
+    amount?: string;
+    currency?: string;
+    eventSourceUrl?: string;
+}
+interface QueuedEvent extends TrackInput {
+    version: typeof EVENT_WIRE_VERSION;
+    eventId: string;
+    occurredAt: string;
+}
+
+interface RovenueOptions {
+    /** The project's PUBLIC api key. Visible in the browser by design. */
+    apiKey: string;
+    /** Base URL of the Rovenue API, without a trailing path. */
+    apiUrl: string;
+    /** Injected for tests and for hosts that wrap fetch. */
+    fetchImpl?: typeof fetch;
+    /**
+     * Where the rovenueId, the entitlement cache and the event queue persist.
+     *
+     * Defaults to {@link createStorage}, which uses `localStorage` where it
+     * works and falls back to memory where it does not — including during
+     * server rendering. Defaulting to memory instead would silently mint a new
+     * subscriber on every page load, orphaning the cache and the queue with it,
+     * and would only be correct for developers who read the docs.
+     */
+    storage?: SdkStorage;
+}
+interface EntitlementsResponse {
+    entitlements: Record<string, unknown>;
+}
+interface CheckoutResult {
+    sessionId: string;
+    url: string;
+}
+/** One package slot of an offering, as GET /v1/offerings serves it. */
+interface WebPackage {
+    /** The package slot id — what {@link Rovenue.checkout} takes as `packageIdentifier`. */
+    packageIdentifier: string;
+    /** The product's own identifier. Not accepted by checkout(). */
+    identifier: string;
+    /** The product type, e.g. `SUBSCRIPTION`. Web checkout sells subscriptions only. */
+    type: string;
+    /** The product's display name as configured in the dashboard. */
+    displayName: string;
+    /** The package's position within its offering, ascending. */
+    order: number;
+    /** Whether the dashboard marked this package as the one to highlight. */
+    isPromoted: boolean;
+    /** Identifiers of the accesses (entitlements) a purchase grants. */
+    accessIds: string[];
+    /** The product's store identifiers, keyed by store (e.g. `stripe`). */
+    storeIds: Record<string, string>;
+    /** Free-form metadata set on this package slot in the offering. */
+    metadata: unknown;
+}
+/** An offering — `identifier` is what {@link Rovenue.checkout} takes as `offeringIdentifier`. */
+interface WebOffering {
+    /** The offering's identifier — pass it to checkout() as `offeringIdentifier`. */
+    identifier: string;
+    /** Whether this is the project's default (current) offering. */
+    isDefault: boolean;
+    /** The offering's package slots, in display order. */
+    packages: WebPackage[];
+    /** Free-form offering metadata from the dashboard. */
+    metadata: unknown;
+}
+/** The body of GET /v1/offerings. */
+interface WebOfferingsResponse {
+    /** The project's offerings, as served to this subscriber. */
+    offerings: WebOffering[];
+}
+interface Rovenue {
+    /** The wire identity for this browser. */
+    rovenueId(): string;
+    /** Client-local. Merging subscribers is a server-side, secret-key operation. */
+    identify(appUserId: string): void;
+    /** Flushes queued events under the current identity, then rotates it. */
+    logOut(): Promise<void>;
+    getEntitlements(): Promise<Record<string, unknown>>;
+    /**
+     * Last-known entitlements, or null if nothing has been fetched yet.
+     *
+     * Synchronous and network-free, so a first paint can render the truth the
+     * server gave last time instead of a flash of the paywall a subscriber has
+     * already paid to remove. It is a cache, never an authorization decision:
+     * the storage behind it is viewer-editable.
+     */
+    getCachedEntitlements(): Record<string, unknown> | null;
+    /** The cache entry with its timestamp, for callers that need staleness. */
+    getCachedEntitlementsEntry(): CachedEntitlements | null;
+    /**
+     * Queues an event for at-least-once delivery.
+     *
+     * Returns immediately: the event is persisted and sent by the queue, which
+     * retries across page loads and flushes when the tab is hidden or closing.
+     */
+    track(input: TrackInput): void;
+    /** Attempts every queued event once. Called automatically on unload. */
+    flushEvents(): Promise<void>;
+    /**
+     * Registers the unload listeners that flush queued events.
+     *
+     * Not called by configure(): configure() also runs during server
+     * rendering, where there is nothing to listen to. The React provider calls
+     * this in an effect; a non-React host calls it once after construction.
+     */
+    startEventQueue(): void;
+    stopEventQueue(): void;
+    /**
+     * Records that a subscriber was shown an experiment variant.
+     *
+     * Assignment alone is invisible to the analytics: a visitor bucketed into
+     * an arm but missing from `exposure_events` still contributes revenue while
+     * being absent from the denominator, which biases conversion rates and
+     * breaks the sample-ratio check. The native path fires this immediately
+     * after the draw; so does the web one.
+     */
+    recordExposure(input: {
+        experimentId: string;
+        variantId: string;
+        placementId?: string;
+    }): Promise<void>;
+    getOfferings(): Promise<WebOfferingsResponse>;
+    getPlacement(identifier: string): Promise<unknown>;
+    /**
+     * Starts a Stripe Checkout and returns the URL to send the browser to.
+     *
+     * The caller names a package, never a price: the amount is resolved
+     * server-side from the offering, so a page that lies about what something
+     * costs changes nothing about what is charged.
+     *
+     * Redirect URLs must be on one of the key's allowed origins (exact scheme,
+     * host and port) or a verified custom domain over https.
+     */
+    checkout(input: {
+        offeringIdentifier: string;
+        packageIdentifier: string;
+        successUrl: string;
+        cancelUrl: string;
+        idempotencyKey?: string;
+    }): Promise<CheckoutResult>;
+    /** Escape hatch for endpoints without a typed wrapper yet. */
+    readonly http: HttpClient;
+    readonly identity: Identity;
+}
+declare function configure(options: RovenueOptions): Rovenue;
+
+export { type CachedEntitlements, type CheckoutResult, type EntitlementsResponse, type QueuedEvent, type Rovenue, RovenueApiError, type RovenueOptions, type SdkStorage, type TrackInput, type WebOffering, type WebOfferingsResponse, type WebPackage, configure, createMemoryStorage, createStorage };

package/dist/index.d.ts

@@ -0,0 +1,222 @@
+interface SdkStorage {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+}
+/**
+ * In-memory storage. The default, and the fallback whenever a real store is
+ * unavailable.
+ *
+ * Nothing here throws: a viewer whose browser refuses storage must still get
+ * a working SDK, just one that forgets between page loads.
+ */
+declare function createMemoryStorage(): SdkStorage;
+/**
+ * Storage backed by `localStorage` where it works, memory where it does not.
+ *
+ * `localStorage` fails in three different ways and only the first is caught
+ * by asking whether it is defined:
+ *
+ *   1. **Absent** — server-side rendering. This is why the probe runs on
+ *      first use and never at module scope: an access during import throws
+ *      before any consumer could guard it.
+ *   2. **Present but throwing** — Safari private mode, and browsers with
+ *      site data blocked. `typeof localStorage` is `"object"` and the first
+ *      write raises.
+ *   3. **Present and full** — a quota error on a write, long after the probe
+ *      said everything was fine. So every operation is guarded, not just the
+ *      probe: a store that passed once can still fail later.
+ *
+ * A failed write drops the value and returns. Losing a cached entitlement is
+ * a lost convenience; taking the host application down over it is not a
+ * trade the SDK gets to make on the developer's behalf.
+ */
+declare function createStorage(): SdkStorage;
+
+interface Identity {
+    /** The permanent wire identity for this browser. */
+    rovenueId(): string;
+    /** The host application's own name for this person, if it set one. */
+    appUserScope(): string | null;
+    identify(appUserId: string): void;
+    /** Forgets both, and mints a fresh rovenueId. */
+    logOut(): void;
+}
+
+declare class RovenueApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+interface HttpClient {
+    get<T>(path: string): Promise<T>;
+    post<T>(path: string, body: unknown, init?: {
+        idempotencyKey?: string;
+        keepalive?: boolean;
+    }): Promise<T>;
+    /** Absolute base, e.g. `https://api.example/v1/web/pk_live_x`. */
+    readonly baseUrl: string;
+}
+
+interface CachedEntitlements {
+    entitlements: Record<string, unknown>;
+    /** Epoch millis of the response this came from. */
+    fetchedAt: number;
+}
+
+/** Wire format version the server expects (EVENT_WIRE_VERSION). */
+declare const EVENT_WIRE_VERSION = 1;
+interface TrackInput {
+    eventType: string;
+    occurredAt?: string;
+    subscriberId?: string;
+    productId?: string;
+    amount?: string;
+    currency?: string;
+    eventSourceUrl?: string;
+}
+interface QueuedEvent extends TrackInput {
+    version: typeof EVENT_WIRE_VERSION;
+    eventId: string;
+    occurredAt: string;
+}
+
+interface RovenueOptions {
+    /** The project's PUBLIC api key. Visible in the browser by design. */
+    apiKey: string;
+    /** Base URL of the Rovenue API, without a trailing path. */
+    apiUrl: string;
+    /** Injected for tests and for hosts that wrap fetch. */
+    fetchImpl?: typeof fetch;
+    /**
+     * Where the rovenueId, the entitlement cache and the event queue persist.
+     *
+     * Defaults to {@link createStorage}, which uses `localStorage` where it
+     * works and falls back to memory where it does not — including during
+     * server rendering. Defaulting to memory instead would silently mint a new
+     * subscriber on every page load, orphaning the cache and the queue with it,
+     * and would only be correct for developers who read the docs.
+     */
+    storage?: SdkStorage;
+}
+interface EntitlementsResponse {
+    entitlements: Record<string, unknown>;
+}
+interface CheckoutResult {
+    sessionId: string;
+    url: string;
+}
+/** One package slot of an offering, as GET /v1/offerings serves it. */
+interface WebPackage {
+    /** The package slot id — what {@link Rovenue.checkout} takes as `packageIdentifier`. */
+    packageIdentifier: string;
+    /** The product's own identifier. Not accepted by checkout(). */
+    identifier: string;
+    /** The product type, e.g. `SUBSCRIPTION`. Web checkout sells subscriptions only. */
+    type: string;
+    /** The product's display name as configured in the dashboard. */
+    displayName: string;
+    /** The package's position within its offering, ascending. */
+    order: number;
+    /** Whether the dashboard marked this package as the one to highlight. */
+    isPromoted: boolean;
+    /** Identifiers of the accesses (entitlements) a purchase grants. */
+    accessIds: string[];
+    /** The product's store identifiers, keyed by store (e.g. `stripe`). */
+    storeIds: Record<string, string>;
+    /** Free-form metadata set on this package slot in the offering. */
+    metadata: unknown;
+}
+/** An offering — `identifier` is what {@link Rovenue.checkout} takes as `offeringIdentifier`. */
+interface WebOffering {
+    /** The offering's identifier — pass it to checkout() as `offeringIdentifier`. */
+    identifier: string;
+    /** Whether this is the project's default (current) offering. */
+    isDefault: boolean;
+    /** The offering's package slots, in display order. */
+    packages: WebPackage[];
+    /** Free-form offering metadata from the dashboard. */
+    metadata: unknown;
+}
+/** The body of GET /v1/offerings. */
+interface WebOfferingsResponse {
+    /** The project's offerings, as served to this subscriber. */
+    offerings: WebOffering[];
+}
+interface Rovenue {
+    /** The wire identity for this browser. */
+    rovenueId(): string;
+    /** Client-local. Merging subscribers is a server-side, secret-key operation. */
+    identify(appUserId: string): void;
+    /** Flushes queued events under the current identity, then rotates it. */
+    logOut(): Promise<void>;
+    getEntitlements(): Promise<Record<string, unknown>>;
+    /**
+     * Last-known entitlements, or null if nothing has been fetched yet.
+     *
+     * Synchronous and network-free, so a first paint can render the truth the
+     * server gave last time instead of a flash of the paywall a subscriber has
+     * already paid to remove. It is a cache, never an authorization decision:
+     * the storage behind it is viewer-editable.
+     */
+    getCachedEntitlements(): Record<string, unknown> | null;
+    /** The cache entry with its timestamp, for callers that need staleness. */
+    getCachedEntitlementsEntry(): CachedEntitlements | null;
+    /**
+     * Queues an event for at-least-once delivery.
+     *
+     * Returns immediately: the event is persisted and sent by the queue, which
+     * retries across page loads and flushes when the tab is hidden or closing.
+     */
+    track(input: TrackInput): void;
+    /** Attempts every queued event once. Called automatically on unload. */
+    flushEvents(): Promise<void>;
+    /**
+     * Registers the unload listeners that flush queued events.
+     *
+     * Not called by configure(): configure() also runs during server
+     * rendering, where there is nothing to listen to. The React provider calls
+     * this in an effect; a non-React host calls it once after construction.
+     */
+    startEventQueue(): void;
+    stopEventQueue(): void;
+    /**
+     * Records that a subscriber was shown an experiment variant.
+     *
+     * Assignment alone is invisible to the analytics: a visitor bucketed into
+     * an arm but missing from `exposure_events` still contributes revenue while
+     * being absent from the denominator, which biases conversion rates and
+     * breaks the sample-ratio check. The native path fires this immediately
+     * after the draw; so does the web one.
+     */
+    recordExposure(input: {
+        experimentId: string;
+        variantId: string;
+        placementId?: string;
+    }): Promise<void>;
+    getOfferings(): Promise<WebOfferingsResponse>;
+    getPlacement(identifier: string): Promise<unknown>;
+    /**
+     * Starts a Stripe Checkout and returns the URL to send the browser to.
+     *
+     * The caller names a package, never a price: the amount is resolved
+     * server-side from the offering, so a page that lies about what something
+     * costs changes nothing about what is charged.
+     *
+     * Redirect URLs must be on one of the key's allowed origins (exact scheme,
+     * host and port) or a verified custom domain over https.
+     */
+    checkout(input: {
+        offeringIdentifier: string;
+        packageIdentifier: string;
+        successUrl: string;
+        cancelUrl: string;
+        idempotencyKey?: string;
+    }): Promise<CheckoutResult>;
+    /** Escape hatch for endpoints without a typed wrapper yet. */
+    readonly http: HttpClient;
+    readonly identity: Identity;
+}
+declare function configure(options: RovenueOptions): Rovenue;
+
+export { type CachedEntitlements, type CheckoutResult, type EntitlementsResponse, type QueuedEvent, type Rovenue, RovenueApiError, type RovenueOptions, type SdkStorage, type TrackInput, type WebOffering, type WebOfferingsResponse, type WebPackage, configure, createMemoryStorage, createStorage };