@tolinku/web-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,298 @@
+/** Configuration options for the Tolinku SDK */
+interface TolinkuConfig {
+    /** Your Tolinku publishable API key (starts with tolk_pub_) */
+    apiKey: string;
+    /** Base URL of your Tolinku domain. Defaults to https://api.tolinku.com */
+    baseUrl?: string;
+}
+/** Properties for custom event tracking */
+interface TrackProperties {
+    campaign?: string;
+    source?: string;
+    medium?: string;
+    platform?: string;
+    [key: string]: string | undefined;
+}
+/** Options for creating a referral */
+interface CreateReferralOptions {
+    userId: string;
+    metadata?: Record<string, string>;
+    userName?: string;
+}
+/** Response from creating a referral */
+interface CreateReferralResult {
+    referral_code: string;
+    referral_url: string | null;
+    referral_id: string;
+}
+/** Options for completing a referral */
+interface CompleteReferralOptions {
+    code: string;
+    referredUserId: string;
+    milestone?: string;
+    referredUserName?: string;
+}
+/** Response from completing a referral */
+interface CompleteReferralResult {
+    referral: {
+        id: string;
+        referrer_id: string;
+        referred_user_id: string;
+        status: string;
+        milestone: string;
+        completed_at: string;
+        reward_type: string | null;
+        reward_value: string | null;
+    };
+}
+/** Options for updating a referral milestone */
+interface MilestoneOptions {
+    code: string;
+    milestone: string;
+}
+/** Response from updating a milestone */
+interface MilestoneResult {
+    referral: {
+        id: string;
+        referral_code: string;
+        milestone: string;
+        status: string;
+        reward_type: string | null;
+        reward_value: string | null;
+    };
+}
+/** Referral info returned by GET /api/referral/:code */
+interface ReferralInfo {
+    referrer_id: string;
+    status: string;
+    milestone: string;
+    milestone_history: Array<{
+        milestone: string;
+        timestamp: string;
+    }>;
+    reward_type: string | null;
+    reward_value: string | null;
+    reward_claimed: boolean;
+    created_at: string;
+}
+/** Leaderboard entry */
+interface LeaderboardEntry {
+    referrer_id: string;
+    referrer_name: string | null;
+    total: number;
+    completed: number;
+    pending: number;
+    total_reward_value: string | null;
+}
+/** Deferred deep link result */
+interface DeferredLink {
+    deep_link_path: string;
+    appspace_id: string;
+    referrer_id?: string;
+    referral_code?: string;
+}
+/** Options for claiming deferred link by signals */
+interface ClaimBySignalsOptions {
+    appspaceId: string;
+    timezone?: string;
+    language?: string;
+    screenWidth?: number;
+    screenHeight?: number;
+}
+/** Banner config returned by the API */
+interface BannerConfig {
+    enabled: boolean;
+    app_name?: string;
+    app_icon?: string;
+    install_url?: string;
+    banners: BannerItem[];
+}
+/** Individual banner item */
+interface BannerItem {
+    id: string;
+    label: string;
+    title: string;
+    body: string | null;
+    action_url: string | null;
+    background_color: string;
+    text_color: string;
+    cta_text: string | null;
+    position: string | null;
+    dismiss_days: number | null;
+    priority: number;
+}
+/** Options for showing a banner */
+interface ShowBannerOptions {
+    position?: 'top' | 'bottom';
+    label?: string;
+}
+/** In-app message from the API */
+interface Message {
+    id: string;
+    name: string;
+    title: string;
+    body: string | null;
+    trigger: string;
+    trigger_value: string | null;
+    content: MessageContent | null;
+    background_color: string;
+    priority: number;
+    dismiss_days: number | null;
+    max_impressions: number | null;
+    min_interval_hours: number | null;
+}
+/** Puck component content tree */
+interface MessageContent {
+    root: {
+        props: Record<string, unknown>;
+    };
+    content: MessageComponent[];
+}
+/** A single Puck component */
+interface MessageComponent {
+    type: string;
+    props: Record<string, unknown>;
+}
+/** Options for showing an in-app message */
+interface ShowMessageOptions {
+    trigger?: string;
+    triggerValue?: string;
+    onDismiss?: (messageId: string) => void;
+    onButtonPress?: (action: string, messageId: string) => void;
+}
+
+declare class HttpClient {
+    private _baseUrl;
+    private apiKey;
+    private abortController;
+    constructor(config: Required<TolinkuConfig>);
+    /** Abort all in-flight requests (called by Tolinku.destroy()) */
+    abort(): void;
+    /** Get a signal for the current request batch, creating a controller if needed */
+    private get signal();
+    /** Public accessor for the base URL */
+    get baseUrl(): string;
+    /** Public accessor for the API key (used by sendBeacon which cannot set custom headers) */
+    get key(): string;
+    get<T>(path: string, params?: Record<string, string>): Promise<T>;
+    post<T>(path: string, body?: Record<string, unknown>): Promise<T>;
+    /** GET without API key auth (for public endpoints like banner config) */
+    getPublic<T>(path: string, params?: Record<string, string>): Promise<T>;
+    /** POST without API key auth (for public endpoints like deferred claim) */
+    postPublic<T>(path: string, body?: Record<string, unknown>): Promise<T>;
+    /**
+     * Fetch with retry logic. Retries on network errors, HTTP 429, and 5xx responses.
+     * Uses exponential backoff: BASE_DELAY_MS * 2^attempt + random jitter.
+     * Respects Retry-After header on 429 responses.
+     * Does NOT retry on 4xx errors (except 429) or successful responses.
+     */
+    private fetchWithRetry;
+    /** Compute backoff delay: BASE_DELAY_MS * 2^attempt + random jitter (0 to MAX_JITTER_MS) */
+    private computeDelay;
+    /** Sleep for a given duration, but throw if the signal is aborted */
+    private sleep;
+    /** Safely parse JSON from a response, handling non-JSON 200s */
+    private parseJson;
+    private headers;
+}
+declare class TolinkuError extends Error {
+    status: number;
+    code: string | undefined;
+    constructor(message: string, status: number, code?: string);
+}
+
+declare class Analytics {
+    private client;
+    private queue;
+    private flushTimer;
+    private unloadHandler;
+    constructor(client: HttpClient);
+    /**
+     * Track a custom event. Event type must start with "custom." and match
+     * the pattern custom.[a-z0-9_]+
+     *
+     * Events are queued and sent in batches for efficiency.
+     */
+    track(eventType: string, properties?: TrackProperties): Promise<void>;
+    /** Send all queued events to the server */
+    flush(): Promise<void>;
+    /**
+     * Flush remaining events using navigator.sendBeacon (best-effort).
+     * Called on page unload when a normal fetch may not complete.
+     */
+    private flushBeacon;
+    /** Clean up timers and event listeners. Called by Tolinku.destroy(). */
+    destroy(): void;
+}
+
+declare class Referrals {
+    private client;
+    constructor(client: HttpClient);
+    /** Create a new referral for a user */
+    create(options: CreateReferralOptions): Promise<CreateReferralResult>;
+    /** Get referral info by code */
+    get(code: string): Promise<ReferralInfo>;
+    /** Complete a referral (mark as converted) */
+    complete(options: CompleteReferralOptions): Promise<CompleteReferralResult>;
+    /** Update a referral milestone */
+    milestone(options: MilestoneOptions): Promise<MilestoneResult>;
+    /** Claim a referral reward */
+    claimReward(code: string): Promise<{
+        success: boolean;
+        referral_code: string;
+        reward_claimed: boolean;
+    }>;
+    /** Get the referral leaderboard */
+    leaderboard(limit?: number): Promise<{
+        leaderboard: LeaderboardEntry[];
+    }>;
+}
+
+declare class Deferred {
+    private client;
+    constructor(client: HttpClient);
+    /** Claim a deferred deep link by referrer token (from Play Store referrer or clipboard) */
+    claimByToken(token: string): Promise<DeferredLink | null>;
+    /** Claim a deferred deep link by device signal matching */
+    claimBySignals(options: ClaimBySignalsOptions): Promise<DeferredLink | null>;
+}
+
+declare class Tolinku {
+    private client;
+    /** Analytics: track custom events */
+    readonly analytics: Analytics;
+    /** Referrals: create, complete, milestone, leaderboard */
+    readonly referrals: Referrals;
+    /** Deferred deep links: claim by token or signals */
+    readonly deferred: Deferred;
+    private banners;
+    private messages;
+    /** The current user ID, used for segment targeting and analytics. */
+    private _userId;
+    constructor(config: TolinkuConfig);
+    /**
+     * Set the user ID for segment targeting and analytics attribution.
+     * Pass null to clear the user ID.
+     */
+    setUserId(userId: string | null): void;
+    /**
+     * Track a custom event (shorthand for analytics.track).
+     * Event type is auto-prefixed with "custom." if not already.
+     * If a userId has been set, it is automatically injected into event properties.
+     */
+    track(eventType: string, properties?: TrackProperties): Promise<void>;
+    /** Show a smart banner at the top or bottom of the page */
+    showBanner(options?: ShowBannerOptions): Promise<void>;
+    /** Dismiss the currently visible smart banner */
+    dismissBanner(): void;
+    /** Show an in-app message as a modal overlay */
+    showMessage(options?: ShowMessageOptions): Promise<void>;
+    /** Dismiss the currently visible in-app message */
+    dismissMessage(): void;
+    /** Flush any queued analytics events immediately */
+    flush(): Promise<void>;
+    /** Clean up all DOM elements, flush events, and cancel in-flight requests (e.g. before unmounting in SPAs) */
+    destroy(): void;
+}
+
+export { type BannerConfig, type BannerItem, type ClaimBySignalsOptions, type CompleteReferralOptions, type CompleteReferralResult, type CreateReferralOptions, type CreateReferralResult, type DeferredLink, type LeaderboardEntry, type Message, type MessageComponent, type MessageContent, type MilestoneOptions, type MilestoneResult, type ReferralInfo, type ShowBannerOptions, type ShowMessageOptions, Tolinku, type TolinkuConfig, TolinkuError, type TrackProperties };