@tolinku/react-native-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Sitepact LLC (Tolinku)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,233 @@
+# @tolinku/react-native-sdk
+
+[![npm version](https://img.shields.io/npm/v/@tolinku/react-native-sdk.svg)](https://www.npmjs.com/package/@tolinku/react-native-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+The official [Tolinku](https://tolinku.com) SDK for **React Native**. Add deep linking, analytics, referral tracking, deferred deep links, and in-app messages to your React Native app. Works with both React Native CLI and Expo projects.
+
+## What is Tolinku?
+
+[Tolinku](https://tolinku.com) is a deep linking platform for mobile and web apps. It handles Universal Links (iOS), App Links (Android), deferred deep linking, referral programs, analytics, and smart banners. Tolinku provides a complete toolkit for user acquisition, attribution, and engagement across platforms.
+
+Get your API key at [tolinku.com](https://tolinku.com) and check out the [documentation](https://tolinku.com/docs) to get started.
+
+## Installation
+
+```bash
+npm install @tolinku/react-native-sdk @react-native-async-storage/async-storage
+```
+
+Or with yarn:
+
+```bash
+yarn add @tolinku/react-native-sdk @react-native-async-storage/async-storage
+```
+
+`@react-native-async-storage/async-storage` is a required peer dependency used for message impression tracking and dismissal state.
+
+### Expo
+
+This SDK is compatible with [Expo](https://expo.dev). No custom native modules are required.
+
+```bash
+npx expo install @tolinku/react-native-sdk @react-native-async-storage/async-storage
+```
+
+Most features (analytics, referrals, in-app messages) work in Expo Go. However, deep linking (Universal Links and App Links) requires a [development build](https://docs.expo.dev/develop/development-builds/introduction/) or production build, since Expo Go cannot register custom domain associations. Use `npx expo run:ios` or `eas build --profile development` to create a dev build for testing deep links.
+
+### React Native CLI
+
+For bare React Native projects, install the packages above and run pod install for iOS:
+
+```bash
+cd ios && pod install
+```
+
+## Quick Start
+
+```typescript
+import { Tolinku } from '@tolinku/react-native-sdk';
+
+// Initialize the SDK (typically at app startup)
+Tolinku.init({ apiKey: 'tolk_pub_your_api_key' });
+
+// Identify a user
+Tolinku.setUserId('user_123');
+
+// Track a custom event
+await Tolinku.track('purchase', { plan: 'growth' });
+```
+
+## Features
+
+### Analytics
+
+Track custom events with automatic batching. Events are queued and sent in batches of 10, or every 5 seconds.
+
+```typescript
+await Tolinku.track('signup_completed', { source: 'landing_page' });
+
+// Flush queued events immediately
+await Tolinku.flush();
+```
+
+### Referrals
+
+Create and manage referral programs with leaderboards and reward tracking.
+
+```typescript
+// Create a referral
+const { referral_code, referral_url } = await Tolinku.referrals.create({
+  userId: 'user_123',
+  userName: 'Alice',
+});
+
+// Look up a referral
+const info = await Tolinku.referrals.get(referral_code);
+
+// Complete a referral
+await Tolinku.referrals.complete({
+  code: referral_code,
+  referredUserId: 'user_456',
+  referredUserName: 'Bob',
+});
+
+// Update milestone
+await Tolinku.referrals.milestone({
+  code: referral_code,
+  milestone: 'first_purchase',
+});
+
+// Claim reward
+await Tolinku.referrals.claimReward(referral_code);
+
+// Fetch leaderboard
+const { leaderboard } = await Tolinku.referrals.leaderboard(10);
+```
+
+### Deferred Deep Links
+
+Recover deep link context for users who installed your app after clicking a link. Deferred deep linking lets you route users to specific content even when the app was not installed at the time of the click.
+
+```typescript
+// Claim by referrer token (from Play Store referrer or clipboard)
+const link = await Tolinku.deferred.claimByToken('abc123');
+if (link) {
+  console.log(link.deep_link_path); // e.g. "/merchant/xyz"
+}
+
+// Claim by device signal matching (auto-detects timezone, language, screen size)
+const link = await Tolinku.deferred.claimBySignals({
+  appspaceId: 'your_appspace_id',
+});
+```
+
+### In-App Messages (React Native Component)
+
+Display server-configured in-app messages using the `<TolinkuMessages>` component. Drop it anywhere in your React Native component tree to automatically fetch and render messages as a modal overlay. Messages are created and managed from the Tolinku dashboard without shipping app updates.
+
+```tsx
+import { TolinkuMessages } from '@tolinku/react-native-sdk';
+
+function App() {
+  return (
+    <>
+      <MainContent />
+      <TolinkuMessages
+        trigger="milestone"
+        triggerValue="first_purchase"
+        onButtonPress={(action, messageId) => {
+          console.log(`Action: ${action}, Message: ${messageId}`);
+        }}
+        onDismiss={(messageId) => {
+          console.log(`Dismissed: ${messageId}`);
+        }}
+      />
+    </>
+  );
+}
+```
+
+The component automatically filters dismissed and suppressed messages, and shows the highest-priority match. It respects `dismiss_days`, `max_impressions`, and `min_interval_hours` settings from the server.
+
+**Props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `trigger` | `string?` | Filter messages by trigger type |
+| `triggerValue` | `string?` | Match a specific trigger value |
+| `onButtonPress` | `(action, messageId) => void` | Called when a message button is pressed |
+| `onDismiss` | `(messageId) => void` | Called when a message is dismissed |
+
+## Configuration Options
+
+```typescript
+Tolinku.init({
+  apiKey: 'tolk_pub_your_api_key',      // Required. Your Tolinku publishable API key.
+  baseUrl: 'https://api.tolinku.com',  // Optional. API base URL.
+  debug: false,                         // Optional. Enable debug logging.
+  timeout: 30000,                       // Optional. Request timeout in ms.
+});
+
+// Set user identity at any time
+Tolinku.setUserId('user_123');
+
+// Shut down the SDK
+await Tolinku.destroy();
+```
+
+## API Reference
+
+### `Tolinku`
+
+| Method | Description |
+|--------|-------------|
+| `init(config)` | Initialize the SDK (static) |
+| `isConfigured()` | Check if the SDK is initialized (static) |
+| `setUserId(userId)` | Set or clear the current user ID (static) |
+| `getUserId()` | Get the current user ID (static) |
+| `track(eventType, properties?)` | Track a custom event (static) |
+| `flush()` | Flush queued analytics events (static) |
+| `destroy()` | Shut down the SDK and release resources (static) |
+
+### `Tolinku.referrals`
+
+| Method | Description |
+|--------|-------------|
+| `create(options)` | Create a new referral |
+| `get(code)` | Get referral details by code |
+| `complete(options)` | Mark a referral as converted |
+| `milestone(options)` | Update a referral milestone |
+| `claimReward(code)` | Claim a referral reward |
+| `leaderboard(limit?)` | Fetch the referral leaderboard |
+
+### `Tolinku.deferred`
+
+| Method | Description |
+|--------|-------------|
+| `claimByToken(token)` | Claim a deferred link by token |
+| `claimBySignals(options)` | Claim a deferred link by device signals |
+
+### `<TolinkuMessages>`
+
+| Prop | Description |
+|------|-------------|
+| `trigger` | Filter messages by trigger type |
+| `triggerValue` | Match a specific trigger value |
+| `onButtonPress` | Callback for button presses |
+| `onDismiss` | Callback for message dismissal |
+
+## Documentation
+
+Full documentation is available at [tolinku.com/docs](https://tolinku.com/docs).
+
+## Community
+
+- [GitHub](https://github.com/tolinku)
+- [X (Twitter)](https://x.com/trytolinku)
+- [Facebook](https://facebook.com/trytolinku)
+- [Instagram](https://www.instagram.com/trytolinku/)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -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 };