@tolinku/web-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+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,198 @@
+# @tolinku/web-sdk
+
+[![npm version](https://img.shields.io/npm/v/@tolinku/web-sdk.svg)](https://www.npmjs.com/package/@tolinku/web-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+The official [Tolinku](https://tolinku.com) SDK for the web. Add deep linking, analytics, referral tracking, deferred deep links, smart banners, and in-app messages to any website or web app.
+
+## 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/web-sdk
+```
+
+Or with yarn:
+
+```bash
+yarn add @tolinku/web-sdk
+```
+
+## Quick Start
+
+```typescript
+import { Tolinku } from '@tolinku/web-sdk';
+
+const tolinku = new Tolinku({ 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). On page unload, remaining events are delivered via `navigator.sendBeacon` for reliable delivery.
+
+```typescript
+await tolinku.track('signup_completed', { source: 'landing_page' });
+
+// Flush queued events immediately
+await tolinku.flush();
+```
+
+### Referrals
+
+Create and manage referral programs with built-in 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 (when a referred user converts)
+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
+const link = await tolinku.deferred.claimBySignals({
+  appspaceId: 'your_appspace_id',
+});
+```
+
+### In-App Messages
+
+Display visually rich, server-configured messages as modal overlays. Create and manage messages from the Tolinku dashboard without shipping app updates.
+
+```typescript
+// Show the highest-priority message matching a trigger
+await tolinku.showMessage({ trigger: 'milestone' });
+
+// Dismiss the current message
+tolinku.dismissMessage();
+```
+
+Messages support components including headings, text blocks, images, buttons, sections, spacers, and dividers. Impression tracking and suppression rules (max impressions, minimum interval, dismiss duration) are handled automatically.
+
+### Smart Banners
+
+Display app install banners that link users to the App Store, Google Play, or a custom URL. Smart banners help convert web visitors into app users with a non-intrusive prompt.
+
+```typescript
+// Show a smart banner
+await tolinku.showBanner({ position: 'top' });
+
+// Dismiss the banner
+tolinku.dismissBanner();
+```
+
+Banners include an app icon, title, body text, and a call-to-action button. Dismissal state is tracked so banners do not reappear until the configured duration has passed.
+
+## Configuration Options
+
+```typescript
+const tolinku = new Tolinku({
+  apiKey: 'tolk_pub_your_api_key',     // Required. Your Tolinku publishable API key.
+  baseUrl: 'https://api.tolinku.com', // Optional. API base URL.
+});
+
+// Set user identity at any time
+tolinku.setUserId('user_123');
+```
+
+## API Reference
+
+### `Tolinku`
+
+| Method | Description |
+|--------|-------------|
+| `new Tolinku(config)` | Create a new SDK instance |
+| `setUserId(userId)` | Set or clear the current user ID |
+| `track(eventType, properties?)` | Track a custom event |
+| `flush()` | Flush queued analytics events |
+| `showBanner(options?)` | Display a smart banner |
+| `dismissBanner()` | Dismiss the smart banner |
+| `showMessage(options?)` | Show an in-app message |
+| `dismissMessage()` | Dismiss the in-app message |
+| `destroy()` | Clean up all resources |
+
+### `tolinku.analytics`
+
+| Method | Description |
+|--------|-------------|
+| `track(eventType, properties?)` | Queue a custom event |
+| `flush()` | Send all queued events |
+
+### `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 |
+
+## 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,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 };