@tolinku/react-native-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,306 @@
+import React from 'react';
+
+/** 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;
+    /** Enable debug logging to the console. Defaults to false. */
+    debug?: boolean;
+    /** Request timeout in milliseconds. Defaults to 30000 (30 seconds). */
+    timeout?: number;
+}
+/** Resolved configuration with all defaults applied */
+interface ResolvedTolinkuConfig {
+    apiKey: string;
+    baseUrl: string;
+    debug: boolean;
+    timeout: number;
+}
+/** 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;
+}
+/** 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 timeout;
+    /** Set of AbortControllers for in-flight requests. Used by destroy() to cancel all. */
+    private pendingControllers;
+    private destroyed;
+    constructor(config: ResolvedTolinkuConfig);
+    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 deferred claim) */
+    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>;
+    /**
+     * Abort all in-flight requests and mark the client as destroyed.
+     * After calling this, all future requests will throw immediately.
+     */
+    abort(): void;
+    private authenticatedHeaders;
+    private publicHeaders;
+    /**
+     * Execute a fetch request with retry logic. Retries on:
+     * - Network errors (fetch throws)
+     * - HTTP 429 (Too Many Requests), respecting the Retry-After header
+     * - HTTP 5xx (server errors)
+     *
+     * Does NOT retry on 4xx errors (except 429).
+     * Uses exponential backoff: BASE_DELAY_MS * 2^attempt + random jitter (0..MAX_JITTER_MS).
+     */
+    private executeWithRetry;
+}
+declare class TolinkuError extends Error {
+    status: number;
+    code: string | undefined;
+    constructor(message: string, status: number, code?: string);
+}
+
+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>;
+}
+
+/**
+ * Main Tolinku SDK singleton.
+ *
+ * Initialize once with Tolinku.init(), then use static methods for all operations.
+ *
+ * Example:
+ *   Tolinku.init({ apiKey: 'tolk_pub_...' });
+ *   await Tolinku.track('signup', { source: 'onboarding' });
+ */
+declare class Tolinku {
+    static readonly VERSION = "0.1.0";
+    private static client;
+    private static analyticsInstance;
+    private static referralsInstance;
+    private static deferredInstance;
+    private static _initialized;
+    private static _userId;
+    /**
+     * Initialize the SDK. Must be called before any other method.
+     *
+     * If init() is called a second time without calling destroy() first,
+     * a warning is logged and the existing instance is returned.
+     */
+    static init(config: TolinkuConfig): void;
+    /** Check whether the SDK has been initialized. */
+    static isConfigured(): boolean;
+    /**
+     * Set the user ID for segment targeting and analytics attribution.
+     * Pass null to clear the user ID.
+     */
+    static setUserId(userId: string | null): void;
+    /** Get the current user ID, or null if not set. */
+    static getUserId(): string | null;
+    /** Get the underlying HTTP client (used internally by MessageProvider) */
+    static getClient(): HttpClient;
+    /**
+     * Track a custom event (shorthand for analytics.track).
+     * Event type is auto-prefixed with "custom." if not already.
+     * Events are batched and flushed automatically.
+     */
+    static track(eventType: string, properties?: TrackProperties): Promise<void>;
+    /**
+     * Immediately flush all queued analytics events to the server.
+     */
+    static flush(): Promise<void>;
+    /** Referrals: create, complete, milestone, leaderboard, claimReward */
+    static get referrals(): Referrals;
+    /** Deferred deep links: claimByToken, claimBySignals */
+    static get deferred(): Deferred;
+    /**
+     * Shut down the SDK and release resources.
+     * Flushes remaining analytics events, cancels timers, removes listeners,
+     * and aborts in-flight requests. After calling this, you must call init()
+     * again before using the SDK.
+     */
+    static destroy(): Promise<void>;
+}
+
+interface TolinkuMessagesProps {
+    /** The trigger type to filter messages by (e.g. "milestone", "event") */
+    trigger?: string;
+    /** The trigger value to match (e.g. "installed", "first_purchase") */
+    triggerValue?: string;
+    /** Called when a message is dismissed */
+    onDismiss?: (messageId: string) => void;
+    /** Called when a button in the message is pressed */
+    onButtonPress?: (action: string, messageId: string) => void;
+}
+/**
+ * React component that fetches and displays in-app messages as a modal overlay.
+ *
+ * Place this component anywhere in your component tree. It will automatically
+ * fetch messages matching the given trigger and display the highest-priority
+ * non-dismissed message.
+ *
+ * Example:
+ *   <TolinkuMessages trigger="milestone" triggerValue="installed" />
+ */
+declare function TolinkuMessages({ trigger, triggerValue, onDismiss, onButtonPress, }: TolinkuMessagesProps): React.ReactElement;
+
+/**
+ * Check if a URL is safe to open or render. Only allows http: and https: protocols.
+ * Blocks javascript:, data:, file:, and other potentially dangerous protocols.
+ */
+declare function isSafeUrl(url: string): boolean;
+
+export { 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 ResolvedTolinkuConfig, type ShowMessageOptions, Tolinku, type TolinkuConfig, TolinkuError, TolinkuMessages, type TrackProperties, isSafeUrl };