@tolinku/web-sdk 0.1.0 → 0.2.0

package/README.md

@@ -84,6 +84,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: `viewItem`, `addToCart`, `removeFromCart`, `addToWishlist`, `viewCart`, `addPaymentInfo`, `beginCheckout`, `purchase`, `refund`, `search`, `share`, `rate`, and `spendCredits`. Cart IDs are managed automatically via `sessionStorage` and cleared after purchase.
+
 ### 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.
@@ -175,6 +201,25 @@ tolinku.setUserId('user_123');
 | `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

@@ -160,6 +160,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;
@@ -225,6 +297,38 @@ declare class Analytics {
     destroy(): void;
 }
 
+declare class Ecommerce {
+    private client;
+    private queue;
+    private flushTimer;
+    private unloadHandler;
+    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(): void;
+    private enqueue;
+    private flushBeacon;
+    private getOrCreateCartId;
+    private getCartId;
+    private setCartId;
+    private clearCartId;
+    private generateId;
+}
+
 declare class Referrals {
     private client;
     constructor(client: HttpClient);
@@ -261,6 +365,8 @@ declare class Tolinku {
     private client;
     /** Analytics: track custom events */
     readonly analytics: Analytics;
+    /** Ecommerce: track purchases, carts, products, revenue */
+    readonly ecommerce: Ecommerce;
     /** Referrals: create, complete, milestone, leaderboard */
     readonly referrals: Referrals;
     /** Deferred deep links: claim by token or signals */
@@ -289,10 +395,10 @@ declare class Tolinku {
     showMessage(options?: ShowMessageOptions): Promise<void>;
     /** Dismiss the currently visible in-app message */
     dismissMessage(): void;
-    /** Flush any queued analytics events immediately */
+    /** Flush any queued analytics and ecommerce 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 };
+export { type AddPaymentInfoParams, type AddToCartParams, type AddToWishlistParams, type BannerConfig, type BannerItem, 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 SearchParams, type ShareParams, type ShowBannerOptions, type ShowMessageOptions, type SpendCreditsParams, Tolinku, type TolinkuConfig, TolinkuError, type TrackProperties, type ViewItemParams };

package/dist/index.d.ts

@@ -160,6 +160,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;
@@ -225,6 +297,38 @@ declare class Analytics {
     destroy(): void;
 }
 
+declare class Ecommerce {
+    private client;
+    private queue;
+    private flushTimer;
+    private unloadHandler;
+    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(): void;
+    private enqueue;
+    private flushBeacon;
+    private getOrCreateCartId;
+    private getCartId;
+    private setCartId;
+    private clearCartId;
+    private generateId;
+}
+
 declare class Referrals {
     private client;
     constructor(client: HttpClient);
@@ -261,6 +365,8 @@ declare class Tolinku {
     private client;
     /** Analytics: track custom events */
     readonly analytics: Analytics;
+    /** Ecommerce: track purchases, carts, products, revenue */
+    readonly ecommerce: Ecommerce;
     /** Referrals: create, complete, milestone, leaderboard */
     readonly referrals: Referrals;
     /** Deferred deep links: claim by token or signals */
@@ -289,10 +395,10 @@ declare class Tolinku {
     showMessage(options?: ShowMessageOptions): Promise<void>;
     /** Dismiss the currently visible in-app message */
     dismissMessage(): void;
-    /** Flush any queued analytics events immediately */
+    /** Flush any queued analytics and ecommerce 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 };
+export { type AddPaymentInfoParams, type AddToCartParams, type AddToWishlistParams, type BannerConfig, type BannerItem, 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 SearchParams, type ShareParams, type ShowBannerOptions, type ShowMessageOptions, type SpendCreditsParams, Tolinku, type TolinkuConfig, TolinkuError, type TrackProperties, type ViewItemParams };

package/dist/index.js

@@ -277,6 +277,208 @@ var Analytics = class {
   }
 };
 
+// src/ecommerce.ts
+var BATCH_SIZE2 = 10;
+var FLUSH_INTERVAL_MS2 = 5e3;
+var MAX_QUEUE_SIZE2 = 500;
+var CART_ID_KEY = "tolk_cart_id";
+var Ecommerce = class {
+  // fallback when sessionStorage unavailable
+  constructor(client, getUserId) {
+    this.client = client;
+    this.queue = [];
+    this.flushTimer = null;
+    this.unloadHandler = null;
+    this.memoryCartId = null;
+    this.getUserId = getUserId;
+    if (typeof window !== "undefined") {
+      this.unloadHandler = () => this.flushBeacon();
+      window.addEventListener("beforeunload", this.unloadHandler);
+    }
+  }
+  // ─── 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 || this.getOrCreateCartId();
+    await this.enqueue({ event_type: "add_to_cart", items: params.items, cart_id: cartId });
+  }
+  async removeFromCart(params) {
+    await this.enqueue({ event_type: "remove_from_cart", items: params.items, cart_id: params.cart_id || this.getCartId() });
+  }
+  async addToWishlist(params) {
+    await this.enqueue({ event_type: "add_to_wishlist", items: params.items });
+  }
+  async viewCart() {
+    await this.enqueue({ event_type: "view_cart", cart_id: this.getCartId() });
+  }
+  async addPaymentInfo(params) {
+    await this.enqueue({ event_type: "add_payment_info", cart_id: params?.cart_id || this.getCartId() });
+  }
+  async beginCheckout(params) {
+    await this.enqueue({
+      event_type: "begin_checkout",
+      revenue: params.revenue,
+      currency: params.currency,
+      cart_id: params.cart_id || this.getCartId(),
+      items: params.items
+    });
+  }
+  async purchase(params) {
+    const cartId = params.cart_id || 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
+    });
+    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.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+    if (this.queue.length === 0) return;
+    const events = this.queue.splice(0);
+    try {
+      const result = await this.client.post(
+        "/v1/api/analytics/ecommerce/batch",
+        { events }
+      );
+      if (result.errors && result.errors.length > 0) {
+        console.warn("[TolinkuSDK] Ecommerce batch partial failure:", result.errors);
+      }
+    } catch {
+      this.queue.unshift(...events);
+      if (this.queue.length > MAX_QUEUE_SIZE2) {
+        this.queue.splice(0, this.queue.length - MAX_QUEUE_SIZE2);
+      }
+    }
+  }
+  destroy() {
+    this.flushBeacon();
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+    if (typeof window !== "undefined" && this.unloadHandler) {
+      window.removeEventListener("beforeunload", this.unloadHandler);
+      this.unloadHandler = null;
+    }
+  }
+  // ─── Private ───────────────────────────────────────────
+  async enqueue(event) {
+    const userId = this.getUserId();
+    if (userId) event.user_id = userId;
+    this.queue.push(event);
+    if (this.queue.length === 1 && !this.flushTimer) {
+      this.flushTimer = setTimeout(() => {
+        this.flushTimer = null;
+        this.flush();
+      }, FLUSH_INTERVAL_MS2);
+    }
+    if (this.queue.length >= BATCH_SIZE2) {
+      await this.flush();
+    }
+  }
+  flushBeacon() {
+    if (this.queue.length === 0) return;
+    const events = this.queue.splice(0);
+    const url = this.client.baseUrl + "/v1/api/analytics/ecommerce/batch";
+    const body = JSON.stringify({ events, apiKey: this.client.key });
+    if (typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function") {
+      navigator.sendBeacon(url, new Blob([body], { type: "application/json" }));
+    }
+  }
+  // ─── Cart ID lifecycle ─────────────────────────────────
+  getOrCreateCartId() {
+    const existing = this.getCartId();
+    if (existing) return existing;
+    const cartId = this.generateId();
+    this.setCartId(cartId);
+    return cartId;
+  }
+  getCartId() {
+    try {
+      if (typeof sessionStorage !== "undefined") {
+        const stored = sessionStorage.getItem(CART_ID_KEY);
+        if (stored) return stored;
+      }
+    } catch {
+    }
+    return this.memoryCartId || void 0;
+  }
+  setCartId(cartId) {
+    this.memoryCartId = cartId;
+    try {
+      if (typeof sessionStorage !== "undefined") {
+        sessionStorage.setItem(CART_ID_KEY, cartId);
+      }
+    } catch {
+    }
+  }
+  clearCartId() {
+    this.memoryCartId = null;
+    try {
+      if (typeof sessionStorage !== "undefined") {
+        sessionStorage.removeItem(CART_ID_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 {
   constructor(client) {
@@ -857,6 +1059,7 @@ var Tolinku = class {
     }
     this.client = new HttpClient(resolvedConfig);
     this.analytics = new Analytics(this.client);
+    this.ecommerce = new Ecommerce(this.client, () => this._userId);
     this.referrals = new Referrals(this.client);
     this.deferred = new Deferred(this.client);
     this.banners = new Banners(this.client);
@@ -894,13 +1097,14 @@ var Tolinku = class {
   dismissMessage() {
     this.messages.dismiss();
   }
-  /** Flush any queued analytics events immediately */
+  /** Flush any queued analytics and ecommerce events immediately */
   async flush() {
-    return this.analytics.flush();
+    await Promise.all([this.analytics.flush(), this.ecommerce.flush()]);
   }
   /** Clean up all DOM elements, flush events, and cancel in-flight requests (e.g. before unmounting in SPAs) */
   destroy() {
     this.analytics.destroy();
+    this.ecommerce.destroy();
     this.client.abort();
     this.banners.dismiss();
     this.messages.dismiss();