@fruga/sdk 1.0.4 → 1.3.0

package/dist/index.d.ts

@@ -163,6 +163,129 @@ interface OfferQuery {
     categories?: string[];
 }
 
+/**
+ * Version of the loader <-> widget postMessage protocol.
+ * Contract of record: docs/PRD.md section 5.6.
+ */
+declare const PROTOCOL_VERSION: "1.0";
+/** Fields carried by every message on the wire. */
+interface FrugaMessageEnvelope {
+    /** Protocol version of the sender, e.g. '1.0'. */
+    version: string;
+}
+/** Why the widget is asking the host for a token. */
+type NeedTokenReason = 'ttl' | 'unauthorized';
+/** Widget -> loader: the widget has no usable token and asks the host for one. */
+interface NeedTokenMessage extends FrugaMessageEnvelope {
+    type: 'NEED_TOKEN';
+    /**
+     * `ttl` when the current token is about to expire, `unauthorized` when the
+     * API rejected it. The native shell mirrors this into `tokenRequired.reason`.
+     */
+    reason: NeedTokenReason;
+}
+/** Loader -> widget: a fresh authentication token. */
+interface FrugaTokenUpdateMessage extends FrugaMessageEnvelope {
+    type: 'FRUGA_TOKEN_UPDATE';
+    token: string;
+}
+/** Loader -> widget: request the current balances. */
+interface FrugaGetBalanceMessage extends FrugaMessageEnvelope {
+    type: 'FRUGA_GET_BALANCE';
+    /** Correlation id; always set by the loader and echoed back by the widget. */
+    requestId: string;
+}
+/** Widget -> loader: answer to {@link FrugaGetBalanceMessage}. */
+interface FrugaBalanceResponseMessage extends FrugaMessageEnvelope {
+    type: 'FRUGA_BALANCE_RESPONSE';
+    /** Echo of the {@link FrugaGetBalanceMessage} `requestId`. */
+    requestId: string;
+    available: number;
+    pending: number;
+}
+/** Widget -> loader: the iframe should be resized to these dimensions. */
+interface FrugaResizeMessage extends FrugaMessageEnvelope {
+    type: 'FRUGA_RESIZE';
+    width: number;
+    height: number;
+    isFullscreen: boolean;
+}
+/** Loader -> widget: the host page viewport changed. */
+interface FrugaHostResizeMessage extends FrugaMessageEnvelope {
+    type: 'FRUGA_HOST_RESIZE';
+    isHostMobile: boolean;
+    hostHeight: number;
+    hostWidth: number;
+}
+/** Widget -> loader: the widget is mounted and able to receive messages. */
+interface FrugaReadyMessage extends FrugaMessageEnvelope {
+    type: 'FRUGA_READY';
+    protocolVersion: string;
+    widgetVersion: string;
+}
+/** Host page description handed to the widget in {@link FrugaInitMessage}. */
+interface FrugaInitHost {
+    origin: string;
+    width: number;
+    height: number;
+    isMobile: boolean;
+}
+/**
+ * Host-supplied overrides carried in {@link FrugaInitMessage}. Each field, when
+ * present, takes precedence over the matching value in `bootstrap.config.ui`.
+ * Sourced from the loader's public `LoaderOptions`.
+ */
+interface FrugaInitOverrides {
+    /** Overrides `bootstrap.config.ui.defaultTheme`. */
+    theme?: 'light' | 'dark';
+    /** Overrides `bootstrap.config.ui.accent`. */
+    primaryColor?: string;
+    /** Host-app identifier for the current end user. */
+    userId?: string;
+    /** Render the widget with its panel already open (native shell mounts this way). */
+    panelOpen?: boolean;
+}
+/** Loader -> widget: single initialisation payload sent after FRUGA_READY. */
+interface FrugaInitMessage extends FrugaMessageEnvelope {
+    type: 'FRUGA_INIT';
+    protocolVersion: string;
+    token?: string;
+    bootstrap: WidgetBootstrap;
+    apiBaseUrl?: string;
+    host: FrugaInitHost;
+    /** Host-supplied overrides of `bootstrap.config.ui`; absent when the host set none. */
+    overrides?: FrugaInitOverrides;
+}
+/** Every message that may cross the loader <-> widget boundary. */
+type FrugaMessage = NeedTokenMessage | FrugaTokenUpdateMessage | FrugaGetBalanceMessage | FrugaBalanceResponseMessage | FrugaResizeMessage | FrugaHostResizeMessage | FrugaReadyMessage | FrugaInitMessage;
+type FrugaMessageType = FrugaMessage['type'];
+/** Narrow the union to the single member with the given `type`. */
+type FrugaMessageOf<T extends FrugaMessageType> = Extract<FrugaMessage, {
+    type: T;
+}>;
+declare const isFrugaMessageType: (value: unknown) => value is FrugaMessageType;
+/**
+ * Structural guard for anything arriving from an untrusted `MessageEvent`.
+ * `version` is not required: pre-1.0 senders omit it and transports stamp
+ * {@link PROTOCOL_VERSION} on arrival.
+ */
+declare const isFrugaMessage: (data: unknown) => data is FrugaMessage;
+/**
+ * Major component of a protocol version string. Returns `NaN` for
+ * unparseable input so callers can treat it as incompatible.
+ */
+declare const protocolMajor: (v: string) => number;
+
+/**
+ * Host viewport width, in px, below which the host page counts as mobile and
+ * the widget switches to its fullscreen layout. Matches the PRD's `<768px`
+ * host mobile rule.
+ *
+ * Single source of truth for the loader, the widgets and any future native
+ * wrapper: none of them may redefine the number locally.
+ */
+declare const HOST_MOBILE_BREAKPOINT = 768;
+
 type PartnerType = 'RELAY' | 'CONNECT' | 'EXTERNAL_TENANT';
 interface PartnerConfig {
     partnerId: string;
@@ -192,11 +315,26 @@ interface BootstrapAuth {
     issuer: string;
     tokenTtlSeconds: number;
 }
+/**
+ * Who receives the cashback. The wire type is deliberately wider than the two
+ * modes the UI knows about: the API may introduce further values, so every
+ * consumer narrows through {@link resolvePayoutMode} instead of comparing
+ * against a literal.
+ */
+type PayoutMode = 'PARTNER' | 'USER';
+/** `partnerPayout` as it arrives on the wire, including values this build does not know. */
+type PartnerPayout = PayoutMode | 'UNKNOWN';
+/**
+ * Narrows an unvalidated `partnerPayout` to a mode the UI can act on.
+ * Returns `null` for missing, malformed or unrecognised values so an
+ * unexpected API response never renders as a known payout mode.
+ */
+declare const resolvePayoutMode: (value: unknown) => PayoutMode | null;
 interface WidgetBootstrap {
     partnerEnvId: string;
     partnerId: string;
     partnerType: PartnerType;
-    partnerPayout: 'PARTNER' | 'USER';
+    partnerPayout: PartnerPayout;
     auth: BootstrapAuth;
     config: {
         ui: WidgetUiConfig;
@@ -205,6 +343,20 @@ interface WidgetBootstrap {
             launcherIcon: string[];
         };
     };
+    /**
+     * Absolute URL of the widget document to load. When present the loader uses
+     * it instead of its default, which gives ops a kill switch and native
+     * wrappers the URL from the same call.
+     */
+    widgetUrl?: string;
+}
+/**
+ * localStorage envelope around a cached {@link WidgetBootstrap}.
+ * `fetchedAt` is epoch milliseconds and lets a reader apply a TTL.
+ */
+interface CachedBootstrap {
+    fetchedAt: number;
+    bootstrap: WidgetBootstrap;
 }
 interface RelayConfig {
     containerId: string;
@@ -230,6 +382,14 @@ declare global {
     }
 }
 
+declare class HttpError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+declare class UnauthorizedError extends HttpError {
+    constructor(message?: string);
+}
+
 interface IWalletService {
     getWallet(): Promise<Wallet>;
 }
@@ -249,12 +409,26 @@ interface IPayoutService {
     deleteMethod(id: string | number): Promise<void>;
 }
 
+/**
+ * Platform-neutral seam for loader <-> widget messaging.
+ * Web implementation: `PostMessageTransport`. Native wrappers provide their own.
+ * `M` defaults to `FrugaMessage`; a bridge with its own message union
+ * instantiates it with that union instead.
+ */
+interface IMessageTransport<M = FrugaMessage> {
+    /** Send a message to the peer. Implementations stamp `version` when absent. */
+    send(message: M): void;
+    /** Register a handler for validated inbound messages. Returns an unsubscribe function. */
+    subscribe(handler: (message: M) => void): () => void;
+    /** Release the underlying listener. Subscribing afterwards throws. */
+    dispose(): void;
+}
+
 declare class HttpWalletService implements IWalletService {
     private readonly baseUrl;
     private readonly token;
     constructor(baseUrl: string, token: string);
     getWallet(): Promise<Wallet>;
-    private getEmptyWallet;
 }
 
 type QueryParamValue = string | number | boolean | string[] | undefined | null;
@@ -268,14 +442,12 @@ declare abstract class BaseHttpService {
 declare class HttpActivityService extends BaseHttpService implements IActivityService {
     constructor(baseUrl: string, token: string);
     getActivity(pageNumber?: number, pageSize?: number): Promise<PaginatedActivity>;
-    private getEmptyActivity;
 }
 
 declare class HttpOffersService extends BaseHttpService implements IOffersService {
     constructor(baseUrl: string, token: string);
     getCategories(): Promise<OfferCategoryResponse>;
     getOffers(query: OfferQuery): Promise<PaginatedResponse<Offer>>;
-    private getEmptyPaginatedResponse;
 }
 
 declare class HttpPayoutService implements IPayoutService {
@@ -287,13 +459,82 @@ declare class HttpPayoutService implements IPayoutService {
     deleteMethod(id: string | number): Promise<void>;
 }
 
-interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
-    variant?: 'primary' | 'secondary';
+interface PostMessageTransportOptions {
+    /** Window messages are sent to (the iframe's `window.parent`, or the iframe's `contentWindow`). */
+    target: Window;
+    /** `targetOrigin` passed to `postMessage`. Use '*' only until the peer origin is known. */
+    targetOrigin: string;
+    /** When set, inbound events from any other `event.source` are dropped. */
+    acceptSource?: Window;
+    /** When set, inbound events from any other `event.origin` are dropped. */
+    acceptOrigin?: string;
+    /** Window the 'message' listener is attached to. Defaults to the global `window`. */
+    listenOn?: Window;
+    /**
+     * Message type that establishes the peer origin (widget side passes
+     * `'FRUGA_INIT'`). While unpinned, only messages of this type are delivered,
+     * from any origin that also satisfies `acceptSource`; the first one accepted
+     * pins the transport to `event.origin` via {@link PostMessageTransport.pinOrigin},
+     * or to the wildcard `'*'` when that origin is opaque.
+     */
+    pinOriginFrom?: FrugaMessageType;
+}
+type MessageHandler = (message: FrugaMessage) => void;
+/**
+ * `IMessageTransport` over `Window.postMessage`.
+ * Owns all `MessageEvent` validation: subscribers only ever see typed,
+ * origin- and source-checked `FrugaMessage` values.
+ */
+declare class PostMessageTransport implements IMessageTransport {
+    private readonly target;
+    private readonly acceptSource?;
+    private readonly listenOn;
+    private readonly handlers;
+    private readonly pinOriginFrom?;
+    private targetOrigin;
+    private acceptOrigin?;
+    private pinned;
+    private disposed;
+    constructor(options: PostMessageTransportOptions);
+    /**
+     * Origin the transport has locked onto, `'*'` when it pinned to the wildcard
+     * after an opaque-origin handshake, or `null` while still unpinned.
+     */
+    get pinnedOrigin(): string | null;
+    /** Lock both the outbound and inbound origin once the peer origin is known. */
+    pinOrigin(origin: string): void;
+    send(message: FrugaMessage): void;
+    subscribe(handler: MessageHandler): () => void;
+    dispose(): void;
+    private readonly onMessage;
+    /**
+     * Gate applied only while `pinOriginFrom` is set and the transport is still
+     * unpinned: nothing but the pinning message type gets through, and the first
+     * one that does completes the handshake for everything after it.
+     */
+    private admitWhileUnpinned;
 }
-declare const WidgetButton: React.FC<ButtonProps>;
-declare const WidgetHeader: React.FC<{
-    title: string;
-}>;
+
+interface CreateHostTransportOptions {
+    /** Window the widget document runs in. Defaults to the global `window`. */
+    listenOn?: Window;
+}
+/**
+ * Builds the single `PostMessageTransport` a widget document uses to talk to
+ * its host. Centralised here so every widget entry point (relay, connect, and
+ * future wrappers) shares one framing check instead of duplicating it inline.
+ *
+ * `window.parent !== window` is true only when this document is loaded
+ * inside an iframe (the normal embed path); an unframed page (e.g. the
+ * widget opened directly, or under a test harness that renders it at the
+ * top level) has no host to accept messages from, so `acceptSource` is
+ * omitted rather than pinned to `window` itself.
+ *
+ * Note for tests: happy-dom sets `MessageEvent.source` to `null` for
+ * same-window `dispatchEvent` calls, so a same-window `acceptSource` check
+ * would always fail there too - another reason not to fall back to `window`.
+ */
+declare const createHostTransport: (options?: CreateHostTransportOptions) => PostMessageTransport;
 
 interface WidgetContainerProps {
     children: ReactNode;
@@ -317,13 +558,34 @@ declare const WidgetProvider: React.FC<{
 }>;
 declare const useWidget: () => WidgetContextType;
 
+declare const MessageTransportContext: React.Context<IMessageTransport<FrugaMessage> | null>;
+interface MessageTransportProviderProps {
+    transport: IMessageTransport;
+    children: ReactNode;
+}
+/**
+ * Provides the single `IMessageTransport` instance used by the widget tree.
+ * The owner of the transport (widget entry point) is responsible for `dispose()`.
+ */
+declare const MessageTransportProvider: React.FC<MessageTransportProviderProps>;
+
+/** Whether the widget currently holds a usable token. */
+type WidgetAuthStatus = 'pending' | 'authenticated';
 interface WidgetState {
     isOpen: boolean;
     isFocused: boolean;
     isIdle: boolean;
     mode: 'light' | 'dark';
     token: string | null;
-    partnerPayout: 'PARTNER' | 'USER' | null;
+    /**
+     * Bumped every time the token *value* changes. Data layers key their caches
+     * on it so a token refresh invalidates anything fetched with the old token.
+     */
+    tokenEpoch: number;
+    /** Derived from `token` on every `setToken`; never set directly. */
+    authStatus: WidgetAuthStatus;
+    /** Narrowed payout mode; `null` while unknown or when the API sent a value this build does not recognise. */
+    partnerPayout: PayoutMode | null;
     toggle: () => void;
     setOpen: (open: boolean) => void;
     setFocused: (focused: boolean) => void;
@@ -333,7 +595,8 @@ interface WidgetState {
     setBalances: (available: number, pending: number) => void;
     setMode: (mode: 'light' | 'dark') => void;
     setToken: (token: string | null) => void;
-    setPartnerPayout: (payout: 'PARTNER' | 'USER') => void;
+    /** Accepts the raw wire value; anything but `'PARTNER'` or `'USER'` resets the mode to `null`. */
+    setPartnerPayout: (payout: unknown) => void;
     isAddingPayoutFromAlert: boolean;
     setIsAddingPayoutFromAlert: (val: boolean) => void;
     showPayoutSuccess: boolean;
@@ -349,23 +612,63 @@ declare const useWidgetStore: zustand.UseBoundStore<zustand.StoreApi<WidgetState
  */
 declare const useDebounce: <T>(value: T, delay: number) => T;
 
-declare const STORAGE_KEYS: {
-    readonly BOOTSTRAP_DATA: "fruga_bootstrap";
-    readonly BOOTSTRAP_CONFIG: "fruga_active_config";
-};
+declare const useMessageTransport: () => IMessageTransport;
+/**
+ * Subscribe to a single message type. The latest `handler` is kept in a ref so
+ * the subscription is created once per transport and type.
+ */
+declare const useFrugaMessage: <T extends FrugaMessageType>(type: T, handler: (message: FrugaMessageOf<T>) => void) => void;
+
+/** Names of the entries the SDK is allowed to persist. */
+type StorageEntryName = 'bootstrap';
+/**
+ * Legacy, partner-unscoped bootstrap key written by SDK <= 1.0.4. Kept only so
+ * callers can delete stale data during migration; never write it again.
+ *
+ * @deprecated Use {@link storageKey} instead.
+ */
+declare const LEGACY_BOOTSTRAP_STORAGE_KEY = "fruga_bootstrap";
+/**
+ * Builds a partner-scoped localStorage key, e.g. `fruga:pk_live_123:bootstrap`.
+ * Scoping keeps two partners embedded on the same origin from reading each
+ * other's cached data.
+ */
+declare const storageKey: (partnerKey: string, name: StorageEntryName) => string;
+/**
+ * Namespaced localStorage access. Every method is a no-op outside a browser
+ * (SSR) and swallows quota / privacy-mode failures — persistence is a cache,
+ * never a correctness requirement.
+ */
 declare class StorageService {
     static set<T>(key: string, value: T): void;
     static get<T>(key: string): T | null;
     static remove(key: string): void;
-    static clear(): void;
 }
 
 /**
- * Default API Base URL for the Fruga SDK.
- * This can be overridden at build-time using the VITE_FRUGA_API_URL environment variable.
+ * Production API base URL. Used whenever the build did not inject
+ * `__FRUGA_API_URL__` (see `src/globals.d.ts`).
+ *
+ * Resolution is build-time only: `process.env` is never read, because
+ * `process` does not exist in a browser (which used to pin every bundle to the
+ * dev API) and under SSR a host application's identically named variable would
+ * leak into the widget.
  */
-declare const DEFAULT_API_URL: string;
+declare const DEFAULT_API_URL = "https://api.fruga.co.uk";
+/** Resolves the API base URL: explicit override, then build-time flag, then production. */
 declare const getBaseUrl: (override?: string) => string;
+/**
+ * Whether this bundle runs in test mode (mock repositories, mock bootstrap).
+ * Decided solely by the build-time `__FRUGA_MODE__` define — never by the
+ * presence or absence of a token.
+ */
+declare const isTestMode: () => boolean;
+/**
+ * Version of this SDK build, injected from the root `package.json` by the
+ * bundler's `define`. Falls back to `0.0.0-dev` in vitest and in an
+ * unconfigured build.
+ */
+declare const SDK_VERSION: string;
 
 /**
  * Formats a date string to "DD-MM-YYYY"
@@ -395,4 +698,4 @@ declare const getDaysRemaining: (dateStr?: string) => number | null;
  */
 declare const truncateText: (str: string | undefined | null, maxLength?: number) => string;
 
-export { type Activity, type AddBankPayload, type BankInfo, type BootstrapAuth, type Category, DEFAULT_API_URL, DEFAULT_THEME, DEFAULT_THEME as DefaultTheme, HttpActivityService, HttpOffersService, HttpPayoutService, HttpWalletService, type IActivityService, type IOffersService, type IPayoutService, type IWalletService, type Offer, type OfferCategory, type OfferCategoryResponse, type OfferQuery, type PaginatedActivity, type PaginatedResponse, type PartnerConfig, type PartnerType, type PayoutMethod, type PayoutMethodListResponse, type PayoutMethodStatus, type PayoutMethodType, type RelayConfig, type RelayState, type RequiredAction, type RequiredActionType, type ResolvedTheme, STORAGE_KEYS, StorageService, type Theme, type Transaction, type Wallet, type WidgetBootstrap, WidgetButton, WidgetContainer, type WidgetContainerProps, type WidgetContextType, WidgetHeader, WidgetProvider, type WidgetState, type WidgetUiConfig, formatDate, getBaseUrl, getDaysRemaining, getResolvedTheme, isWithinDays, truncateText, useDebounce, useWidget, useWidgetStore };
+export { type Activity, type AddBankPayload, type BankInfo, type BootstrapAuth, type CachedBootstrap, type Category, type CreateHostTransportOptions, DEFAULT_API_URL, DEFAULT_THEME, DEFAULT_THEME as DefaultTheme, type FrugaBalanceResponseMessage, type FrugaGetBalanceMessage, type FrugaHostResizeMessage, type FrugaInitHost, type FrugaInitMessage, type FrugaInitOverrides, type FrugaMessage, type FrugaMessageEnvelope, type FrugaMessageOf, type FrugaMessageType, type FrugaReadyMessage, type FrugaResizeMessage, type FrugaTokenUpdateMessage, HOST_MOBILE_BREAKPOINT, HttpActivityService, HttpError, HttpOffersService, HttpPayoutService, HttpWalletService, type IActivityService, type IMessageTransport, type IOffersService, type IPayoutService, type IWalletService, LEGACY_BOOTSTRAP_STORAGE_KEY, MessageTransportContext, MessageTransportProvider, type MessageTransportProviderProps, type NeedTokenMessage, type NeedTokenReason, type Offer, type OfferCategory, type OfferCategoryResponse, type OfferQuery, PROTOCOL_VERSION, type PaginatedActivity, type PaginatedResponse, type PartnerConfig, type PartnerPayout, type PartnerType, type PayoutMethod, type PayoutMethodListResponse, type PayoutMethodStatus, type PayoutMethodType, type PayoutMode, PostMessageTransport, type PostMessageTransportOptions, type RelayConfig, type RelayState, type RequiredAction, type RequiredActionType, type ResolvedTheme, SDK_VERSION, type StorageEntryName, StorageService, type Theme, type Transaction, UnauthorizedError, type Wallet, type WidgetAuthStatus, type WidgetBootstrap, WidgetContainer, type WidgetContainerProps, type WidgetContextType, WidgetProvider, type WidgetState, type WidgetUiConfig, createHostTransport, formatDate, getBaseUrl, getDaysRemaining, getResolvedTheme, isFrugaMessage, isFrugaMessageType, isTestMode, isWithinDays, protocolMajor, resolvePayoutMode, storageKey, truncateText, useDebounce, useFrugaMessage, useMessageTransport, useWidget, useWidgetStore };