@tolinku/react-native-sdk 0.1.0 → 0.2.0

package/README.md

@@ -105,6 +105,32 @@ await Tolinku.referrals.claimReward(referral_code);
 const { leaderboard } = await Tolinku.referrals.leaderboard(10);
 ```
 
+### Ecommerce
+
+Track purchases, cart activity, and product events with built-in revenue analytics. Available on paid plans.
+
+```typescript
+Tolinku.setUserId('user_123');
+
+// Track a product view
+await Tolinku.ecommerce.viewItem({
+  items: [{ item_id: 'sku_1', item_name: 'T-Shirt', price: 24.99 }]
+});
+
+// Track a purchase
+await Tolinku.ecommerce.purchase({
+  transaction_id: 'order_456',
+  revenue: 49.99,
+  currency: 'USD',
+  items: [{ item_id: 'sku_1', item_name: 'T-Shirt', price: 24.99, quantity: 2 }]
+});
+
+// Flush ecommerce events
+await Tolinku.ecommerce.flush();
+```
+
+The SDK supports 13 event types covering the full shopping journey. Cart IDs are managed automatically via `AsyncStorage` and cleared after purchase. Events auto-flush when the app enters the background.
+
 ### 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.
@@ -201,6 +227,25 @@ await Tolinku.destroy();
 | `claimReward(code)` | Claim a referral reward |
 | `leaderboard(limit?)` | Fetch the referral leaderboard |
 
+### `Tolinku.ecommerce`
+
+| Method | Description |
+|--------|-------------|
+| `viewItem(params)` | Track a product view |
+| `addToCart(params)` | Track item added to cart |
+| `removeFromCart(params)` | Track item removed from cart |
+| `addToWishlist(params)` | Track item added to wishlist |
+| `viewCart()` | Track cart view |
+| `addPaymentInfo()` | Track payment info entered |
+| `beginCheckout(params?)` | Track checkout started |
+| `purchase(params)` | Track a purchase |
+| `refund(params)` | Track a refund |
+| `search(params)` | Track a product search |
+| `share(params)` | Track a product share |
+| `rate(params)` | Track a product rating |
+| `spendCredits(params)` | Track loyalty credits spent |
+| `flush()` | Send all queued ecommerce events |
+
 ### `Tolinku.deferred`
 
 | Method | Description |

package/dist/index.d.mts

@@ -146,6 +146,78 @@ interface ShowMessageOptions {
     onDismiss?: (messageId: string) => void;
     onButtonPress?: (action: string, messageId: string) => void;
 }
+interface EcommerceItem {
+    item_id: string;
+    item_name?: string;
+    item_category?: string;
+    item_brand?: string;
+    item_variant?: string;
+    item_list_name?: string;
+    item_list_id?: string;
+    item_image_url?: string;
+    price?: number;
+    quantity?: number;
+    currency?: string;
+    coupon_code?: string;
+    discount?: number;
+}
+interface PurchaseParams {
+    transaction_id: string;
+    revenue: number;
+    currency: string;
+    items?: EcommerceItem[];
+    cart_id?: string;
+    coupon_code?: string;
+    discount?: number;
+    shipping?: number;
+    tax?: number;
+}
+interface AddToCartParams {
+    items: EcommerceItem[];
+    cart_id?: string;
+}
+interface RemoveFromCartParams {
+    items: EcommerceItem[];
+    cart_id?: string;
+}
+interface AddToWishlistParams {
+    items: EcommerceItem[];
+}
+interface BeginCheckoutParams {
+    revenue?: number;
+    currency?: string;
+    cart_id?: string;
+    items?: EcommerceItem[];
+}
+interface RefundParams {
+    transaction_id: string;
+    revenue: number;
+    currency?: string;
+    items?: EcommerceItem[];
+}
+interface ViewItemParams {
+    items: EcommerceItem[];
+}
+interface SearchParams {
+    search_term: string;
+}
+interface AddPaymentInfoParams {
+    cart_id?: string;
+}
+interface ShareParams {
+    item_id?: string;
+    url?: string;
+    method?: string;
+}
+interface RateParams {
+    item_id: string;
+    rating: number;
+    max_rating?: number;
+}
+interface SpendCreditsParams {
+    revenue: number;
+    currency: string;
+}
 
 declare class HttpClient {
     private baseUrl;
@@ -185,6 +257,41 @@ declare class TolinkuError extends Error {
     constructor(message: string, status: number, code?: string);
 }
 
+declare class Ecommerce {
+    private client;
+    private queue;
+    private flushTimer;
+    private appStateSubscription;
+    private isFlushing;
+    private getUserId;
+    private memoryCartId;
+    constructor(client: HttpClient, getUserId: () => string | null);
+    viewItem(params: ViewItemParams): Promise<void>;
+    addToCart(params: AddToCartParams): Promise<void>;
+    removeFromCart(params: RemoveFromCartParams): Promise<void>;
+    addToWishlist(params: AddToWishlistParams): Promise<void>;
+    viewCart(): Promise<void>;
+    addPaymentInfo(params?: AddPaymentInfoParams): Promise<void>;
+    beginCheckout(params: BeginCheckoutParams): Promise<void>;
+    purchase(params: PurchaseParams): Promise<void>;
+    refund(params: RefundParams): Promise<void>;
+    search(params: SearchParams): Promise<void>;
+    share(params: ShareParams): Promise<void>;
+    rate(params: RateParams): Promise<void>;
+    spendCredits(params: SpendCreditsParams): Promise<void>;
+    flush(): Promise<void>;
+    destroy(): Promise<void>;
+    private enqueue;
+    private handleAppStateChange;
+    private startFlushTimer;
+    private cancelFlushTimer;
+    private getOrCreateCartId;
+    private getCartId;
+    private setCartId;
+    private clearCartId;
+    private generateId;
+}
+
 declare class Referrals {
     private client;
     constructor(client: HttpClient);
@@ -230,6 +337,7 @@ declare class Tolinku {
     static readonly VERSION = "0.1.0";
     private static client;
     private static analyticsInstance;
+    private static ecommerceInstance;
     private static referralsInstance;
     private static deferredInstance;
     private static _initialized;
@@ -259,9 +367,11 @@ declare class Tolinku {
      */
     static track(eventType: string, properties?: TrackProperties): Promise<void>;
     /**
-     * Immediately flush all queued analytics events to the server.
+     * Immediately flush all queued analytics and ecommerce events to the server.
      */
     static flush(): Promise<void>;
+    /** Ecommerce: track purchases, carts, products, revenue */
+    static get ecommerce(): Ecommerce;
     /** Referrals: create, complete, milestone, leaderboard, claimReward */
     static get referrals(): Referrals;
     /** Deferred deep links: claimByToken, claimBySignals */
@@ -303,4 +413,4 @@ declare function TolinkuMessages({ trigger, triggerValue, onDismiss, onButtonPre
  */
 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 };
+export { type AddPaymentInfoParams, type AddToCartParams, type AddToWishlistParams, type BeginCheckoutParams, type ClaimBySignalsOptions, type CompleteReferralOptions, type CompleteReferralResult, type CreateReferralOptions, type CreateReferralResult, type DeferredLink, type EcommerceItem, type LeaderboardEntry, type Message, type MessageComponent, type MessageContent, type MilestoneOptions, type MilestoneResult, type PurchaseParams, type RateParams, type ReferralInfo, type RefundParams, type RemoveFromCartParams, type ResolvedTolinkuConfig, type SearchParams, type ShareParams, type ShowMessageOptions, type SpendCreditsParams, Tolinku, type TolinkuConfig, TolinkuError, TolinkuMessages, type TrackProperties, type ViewItemParams, isSafeUrl };

package/dist/index.d.ts

@@ -146,6 +146,78 @@ interface ShowMessageOptions {
     onDismiss?: (messageId: string) => void;
     onButtonPress?: (action: string, messageId: string) => void;
 }
+interface EcommerceItem {
+    item_id: string;
+    item_name?: string;
+    item_category?: string;
+    item_brand?: string;
+    item_variant?: string;
+    item_list_name?: string;
+    item_list_id?: string;
+    item_image_url?: string;
+    price?: number;
+    quantity?: number;
+    currency?: string;
+    coupon_code?: string;
+    discount?: number;
+}
+interface PurchaseParams {
+    transaction_id: string;
+    revenue: number;
+    currency: string;
+    items?: EcommerceItem[];
+    cart_id?: string;
+    coupon_code?: string;
+    discount?: number;
+    shipping?: number;
+    tax?: number;
+}
+interface AddToCartParams {
+    items: EcommerceItem[];
+    cart_id?: string;
+}
+interface RemoveFromCartParams {
+    items: EcommerceItem[];
+    cart_id?: string;
+}
+interface AddToWishlistParams {
+    items: EcommerceItem[];
+}
+interface BeginCheckoutParams {
+    revenue?: number;
+    currency?: string;
+    cart_id?: string;
+    items?: EcommerceItem[];
+}
+interface RefundParams {
+    transaction_id: string;
+    revenue: number;
+    currency?: string;
+    items?: EcommerceItem[];
+}
+interface ViewItemParams {
+    items: EcommerceItem[];
+}
+interface SearchParams {
+    search_term: string;
+}
+interface AddPaymentInfoParams {
+    cart_id?: string;
+}
+interface ShareParams {
+    item_id?: string;
+    url?: string;
+    method?: string;
+}
+interface RateParams {
+    item_id: string;
+    rating: number;
+    max_rating?: number;
+}
+interface SpendCreditsParams {
+    revenue: number;
+    currency: string;
+}
 
 declare class HttpClient {
     private baseUrl;
@@ -185,6 +257,41 @@ declare class TolinkuError extends Error {
     constructor(message: string, status: number, code?: string);
 }
 
+declare class Ecommerce {
+    private client;
+    private queue;
+    private flushTimer;
+    private appStateSubscription;
+    private isFlushing;
+    private getUserId;
+    private memoryCartId;
+    constructor(client: HttpClient, getUserId: () => string | null);
+    viewItem(params: ViewItemParams): Promise<void>;
+    addToCart(params: AddToCartParams): Promise<void>;
+    removeFromCart(params: RemoveFromCartParams): Promise<void>;
+    addToWishlist(params: AddToWishlistParams): Promise<void>;
+    viewCart(): Promise<void>;
+    addPaymentInfo(params?: AddPaymentInfoParams): Promise<void>;
+    beginCheckout(params: BeginCheckoutParams): Promise<void>;
+    purchase(params: PurchaseParams): Promise<void>;
+    refund(params: RefundParams): Promise<void>;
+    search(params: SearchParams): Promise<void>;
+    share(params: ShareParams): Promise<void>;
+    rate(params: RateParams): Promise<void>;
+    spendCredits(params: SpendCreditsParams): Promise<void>;
+    flush(): Promise<void>;
+    destroy(): Promise<void>;
+    private enqueue;
+    private handleAppStateChange;
+    private startFlushTimer;
+    private cancelFlushTimer;
+    private getOrCreateCartId;
+    private getCartId;
+    private setCartId;
+    private clearCartId;
+    private generateId;
+}
+
 declare class Referrals {
     private client;
     constructor(client: HttpClient);
@@ -230,6 +337,7 @@ declare class Tolinku {
     static readonly VERSION = "0.1.0";
     private static client;
     private static analyticsInstance;
+    private static ecommerceInstance;
     private static referralsInstance;
     private static deferredInstance;
     private static _initialized;
@@ -259,9 +367,11 @@ declare class Tolinku {
      */
     static track(eventType: string, properties?: TrackProperties): Promise<void>;
     /**
-     * Immediately flush all queued analytics events to the server.
+     * Immediately flush all queued analytics and ecommerce events to the server.
      */
     static flush(): Promise<void>;
+    /** Ecommerce: track purchases, carts, products, revenue */
+    static get ecommerce(): Ecommerce;
     /** Referrals: create, complete, milestone, leaderboard, claimReward */
     static get referrals(): Referrals;
     /** Deferred deep links: claimByToken, claimBySignals */
@@ -303,4 +413,4 @@ declare function TolinkuMessages({ trigger, triggerValue, onDismiss, onButtonPre
  */
 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 };
+export { type AddPaymentInfoParams, type AddToCartParams, type AddToWishlistParams, type BeginCheckoutParams, type ClaimBySignalsOptions, type CompleteReferralOptions, type CompleteReferralResult, type CreateReferralOptions, type CreateReferralResult, type DeferredLink, type EcommerceItem, type LeaderboardEntry, type Message, type MessageComponent, type MessageContent, type MilestoneOptions, type MilestoneResult, type PurchaseParams, type RateParams, type ReferralInfo, type RefundParams, type RemoveFromCartParams, type ResolvedTolinkuConfig, type SearchParams, type ShareParams, type ShowMessageOptions, type SpendCreditsParams, Tolinku, type TolinkuConfig, TolinkuError, TolinkuMessages, type TrackProperties, type ViewItemParams, isSafeUrl };

package/dist/index.js

@@ -353,6 +353,215 @@ var Analytics = class {
     }
   }
 };
+var BATCH_SIZE2 = 10;
+var FLUSH_INTERVAL_MS2 = 5e3;
+var MAX_QUEUE_SIZE2 = 500;
+var CART_ID_STORAGE_KEY = "tolinku_ecom_cart_id";
+var Ecommerce = class {
+  constructor(client, getUserId) {
+    this.queue = [];
+    this.flushTimer = null;
+    this.appStateSubscription = null;
+    this.isFlushing = false;
+    this.memoryCartId = null;
+    this.handleAppStateChange = (state) => {
+      if (state === "background" || state === "inactive") {
+        this.flush().catch(() => {
+        });
+      }
+    };
+    this.client = client;
+    this.getUserId = getUserId;
+    this.appStateSubscription = reactNative.AppState.addEventListener(
+      "change",
+      this.handleAppStateChange
+    );
+  }
+  // ─── Public methods (13 event types) ────────────────────
+  async viewItem(params) {
+    await this.enqueue({ event_type: "view_item", items: params.items });
+  }
+  async addToCart(params) {
+    const cartId = params.cart_id || await this.getOrCreateCartId();
+    await this.enqueue({ event_type: "add_to_cart", items: params.items, cart_id: cartId });
+  }
+  async removeFromCart(params) {
+    const cartId = params.cart_id || await this.getCartId();
+    await this.enqueue({ event_type: "remove_from_cart", items: params.items, cart_id: cartId });
+  }
+  async addToWishlist(params) {
+    await this.enqueue({ event_type: "add_to_wishlist", items: params.items });
+  }
+  async viewCart() {
+    const cartId = await this.getCartId();
+    await this.enqueue({ event_type: "view_cart", cart_id: cartId });
+  }
+  async addPaymentInfo(params) {
+    const cartId = params?.cart_id || await this.getCartId();
+    await this.enqueue({ event_type: "add_payment_info", cart_id: cartId });
+  }
+  async beginCheckout(params) {
+    const cartId = params.cart_id || await this.getCartId();
+    await this.enqueue({
+      event_type: "begin_checkout",
+      revenue: params.revenue,
+      currency: params.currency,
+      cart_id: cartId,
+      items: params.items
+    });
+  }
+  async purchase(params) {
+    const cartId = params.cart_id || await this.getCartId();
+    await this.enqueue({
+      event_type: "purchase",
+      transaction_id: params.transaction_id,
+      revenue: params.revenue,
+      currency: params.currency,
+      cart_id: cartId,
+      coupon_code: params.coupon_code,
+      discount: params.discount,
+      shipping: params.shipping,
+      tax: params.tax,
+      items: params.items
+    });
+    await this.clearCartId();
+  }
+  async refund(params) {
+    await this.enqueue({
+      event_type: "refund",
+      transaction_id: params.transaction_id,
+      revenue: params.revenue,
+      currency: params.currency,
+      items: params.items
+    });
+  }
+  async search(params) {
+    await this.enqueue({ event_type: "search", properties: { search_term: params.search_term } });
+  }
+  async share(params) {
+    const props = {};
+    if (params.item_id) props.item_id = params.item_id;
+    if (params.url) props.url = params.url;
+    if (params.method) props.method = params.method;
+    await this.enqueue({ event_type: "share", properties: props });
+  }
+  async rate(params) {
+    await this.enqueue({
+      event_type: "rate",
+      properties: {
+        item_id: params.item_id,
+        rating: String(params.rating),
+        ...params.max_rating != null ? { max_rating: String(params.max_rating) } : {}
+      }
+    });
+  }
+  async spendCredits(params) {
+    await this.enqueue({ event_type: "spend_credits", revenue: params.revenue, currency: params.currency });
+  }
+  // ─── Flush ─────────────────────────────────────────────
+  async flush() {
+    if (this.queue.length === 0 || this.isFlushing) return;
+    this.isFlushing = true;
+    const events = this.queue.splice(0);
+    this.cancelFlushTimer();
+    try {
+      debugLog(`Flushing ${events.length} ecommerce event(s)`);
+      const result = await this.client.post(
+        "/v1/api/analytics/ecommerce/batch",
+        { events }
+      );
+      if (result.errors && result.errors.length > 0) {
+        debugWarn(`Ecommerce batch partial failure: ${result.errors.join(", ")}`);
+      }
+    } catch (err) {
+      debugWarn(`Failed to flush ecommerce events: ${err.message}`);
+      const spaceLeft = MAX_QUEUE_SIZE2 - this.queue.length;
+      if (spaceLeft > 0) {
+        this.queue.unshift(...events.slice(0, spaceLeft));
+      }
+    } finally {
+      this.isFlushing = false;
+    }
+  }
+  async destroy() {
+    this.cancelFlushTimer();
+    this.appStateSubscription?.remove();
+    this.appStateSubscription = null;
+    try {
+      await this.flush();
+    } catch {
+    }
+  }
+  // ─── Private ───────────────────────────────────────────
+  async enqueue(event) {
+    const userId = this.getUserId();
+    if (userId) event.user_id = userId;
+    if (this.queue.length >= MAX_QUEUE_SIZE2) {
+      debugWarn(`Ecommerce queue full (${MAX_QUEUE_SIZE2}). Dropping oldest event.`);
+      this.queue.shift();
+    }
+    this.queue.push(event);
+    if (this.queue.length >= BATCH_SIZE2) {
+      await this.flush();
+    } else if (this.queue.length === 1) {
+      this.startFlushTimer();
+    }
+  }
+  startFlushTimer() {
+    this.cancelFlushTimer();
+    this.flushTimer = setTimeout(() => {
+      this.flush().catch((err) => {
+        debugWarn(`Ecommerce timer flush failed: ${err.message}`);
+      });
+    }, FLUSH_INTERVAL_MS2);
+  }
+  cancelFlushTimer() {
+    if (this.flushTimer !== null) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+  }
+  // ─── Cart ID lifecycle (AsyncStorage + memory fallback) ─
+  async getOrCreateCartId() {
+    const existing = await this.getCartId();
+    if (existing) return existing;
+    const cartId = this.generateId();
+    await this.setCartId(cartId);
+    return cartId;
+  }
+  async getCartId() {
+    try {
+      const stored = await AsyncStorage__default.default.getItem(CART_ID_STORAGE_KEY);
+      if (stored) return stored;
+    } catch {
+    }
+    return this.memoryCartId || void 0;
+  }
+  async setCartId(cartId) {
+    this.memoryCartId = cartId;
+    try {
+      await AsyncStorage__default.default.setItem(CART_ID_STORAGE_KEY, cartId);
+    } catch {
+    }
+  }
+  async clearCartId() {
+    this.memoryCartId = null;
+    try {
+      await AsyncStorage__default.default.removeItem(CART_ID_STORAGE_KEY);
+    } catch {
+    }
+  }
+  generateId() {
+    if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+      return crypto.randomUUID();
+    }
+    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+      const r = Math.random() * 16 | 0;
+      const v = c === "x" ? r : r & 3 | 8;
+      return v.toString(16);
+    });
+  }
+};
 
 // src/referrals.ts
 var Referrals = class {
@@ -568,6 +777,7 @@ var _Tolinku = class _Tolinku {
     setStorageNamespace(config.apiKey);
     _Tolinku.client = new HttpClient(resolvedConfig);
     _Tolinku.analyticsInstance = new Analytics(_Tolinku.client);
+    _Tolinku.ecommerceInstance = new Ecommerce(_Tolinku.client, () => _Tolinku._userId);
     _Tolinku.referralsInstance = new Referrals(_Tolinku.client);
     _Tolinku.deferredInstance = new Deferred(_Tolinku.client);
     _Tolinku._initialized = true;
@@ -608,13 +818,23 @@ var _Tolinku = class _Tolinku {
     return _Tolinku.analyticsInstance.track(eventType, mergedProps);
   }
   /**
-   * Immediately flush all queued analytics events to the server.
+   * Immediately flush all queued analytics and ecommerce events to the server.
    */
   static async flush() {
     if (!_Tolinku.analyticsInstance) {
       throw new Error("Tolinku: SDK not initialized. Call Tolinku.init() first.");
     }
-    return _Tolinku.analyticsInstance.flush();
+    await Promise.all([
+      _Tolinku.analyticsInstance.flush(),
+      _Tolinku.ecommerceInstance?.flush()
+    ]);
+  }
+  /** Ecommerce: track purchases, carts, products, revenue */
+  static get ecommerce() {
+    if (!_Tolinku.ecommerceInstance) {
+      throw new Error("Tolinku: SDK not initialized. Call Tolinku.init() first.");
+    }
+    return _Tolinku.ecommerceInstance;
   }
   /** Referrals: create, complete, milestone, leaderboard, claimReward */
   static get referrals() {
@@ -641,12 +861,16 @@ var _Tolinku = class _Tolinku {
     if (_Tolinku.analyticsInstance) {
       await _Tolinku.analyticsInstance.destroy();
     }
+    if (_Tolinku.ecommerceInstance) {
+      await _Tolinku.ecommerceInstance.destroy();
+    }
     if (_Tolinku.client) {
       _Tolinku.client.abort();
     }
     resetStorageNamespace();
     _Tolinku.client = null;
     _Tolinku.analyticsInstance = null;
+    _Tolinku.ecommerceInstance = null;
     _Tolinku.referralsInstance = null;
     _Tolinku.deferredInstance = null;
     _Tolinku._initialized = false;
@@ -657,6 +881,7 @@ var _Tolinku = class _Tolinku {
 _Tolinku.VERSION = SDK_VERSION;
 _Tolinku.client = null;
 _Tolinku.analyticsInstance = null;
+_Tolinku.ecommerceInstance = null;
 _Tolinku.referralsInstance = null;
 _Tolinku.deferredInstance = null;
 _Tolinku._initialized = false;