@tolinku/web-sdk 0.1.0 → 0.3.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.
@@ -95,12 +121,17 @@ if (link) {
   console.log(link.deep_link_path); // e.g. "/merchant/xyz"
 }
 
-// Claim by device signal matching
+// Claim by device signal matching. Timezone, language, screen size and pixel ratio
+// are detected for you.
 const link = await tolinku.deferred.claimBySignals({
-  appspaceId: 'your_appspace_id',
+  appspaceId: '64f0a1b2c3d4e5f60718',
 });
 ```
 
+`appspaceId` is your Appspace ID, not your subdomain or slug. Copy it from the dashboard
+under **Integrate** or **Settings**. It looks like `64f0a1b2c3d4e5f60718`.
+
+
 ### In-App Messages
 
 Display visually rich, server-configured messages as modal overlays. Create and manage messages from the Tolinku dashboard without shipping app updates.
@@ -175,6 +206,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

@@ -98,6 +98,8 @@ interface ClaimBySignalsOptions {
     language?: string;
     screenWidth?: number;
     screenHeight?: number;
+    /** Defaults to `window.devicePixelRatio`. Override only if you report a custom screen size. */
+    devicePixelRatio?: number;
 }
 /** Banner config returned by the API */
 interface BannerConfig {
@@ -118,13 +120,47 @@ interface BannerItem {
     text_color: string;
     cta_text: string | null;
     position: string | null;
+    style: string | null;
+    shadow: string | null;
+    radius: number | null;
+    margin: number | null;
     dismiss_days: number | null;
     priority: number;
 }
-/** Options for showing a banner */
+/** Options for showing a banner. All fields are optional.
+ *  Resolution chain per value: option → server config → theme → built-in default. */
 interface ShowBannerOptions {
     position?: 'top' | 'bottom';
+    style?: 'pinned' | 'floating' | 'stacked';
+    animation?: 'slide' | 'fade' | 'pop' | 'none';
+    theme?: 'light' | 'dark';
     label?: string;
+    delay?: number;
+    /** Stacked-mode only: CSS selector for the element to inject before (top) or after (bottom).
+     *  Falls back to auto-detect when omitted. */
+    anchor?: string;
+    bg?: string;
+    border?: string;
+    radius?: number;
+    margin?: number;
+    shadow?: 'none' | 'sm' | 'md' | 'lg';
+    titleColor?: string;
+    titleSize?: number;
+    titleWeight?: 400 | 500 | 600 | 700;
+    bodyColor?: string;
+    bodySize?: number;
+    bodyWeight?: 400 | 500 | 600 | 700;
+    ctaBg?: string;
+    ctaColor?: string;
+    ctaSize?: number;
+    ctaWeight?: 400 | 500 | 600 | 700;
+    ctaRadius?: number;
+    iconSize?: number;
+    iconRadius?: number;
+    hideIcon?: boolean;
+    hideClose?: boolean;
+    hideBody?: boolean;
+    customClass?: string;
 }
 /** In-app message from the API */
 interface Message {
@@ -160,6 +196,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 +333,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 +401,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 +431,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

@@ -98,6 +98,8 @@ interface ClaimBySignalsOptions {
     language?: string;
     screenWidth?: number;
     screenHeight?: number;
+    /** Defaults to `window.devicePixelRatio`. Override only if you report a custom screen size. */
+    devicePixelRatio?: number;
 }
 /** Banner config returned by the API */
 interface BannerConfig {
@@ -118,13 +120,47 @@ interface BannerItem {
     text_color: string;
     cta_text: string | null;
     position: string | null;
+    style: string | null;
+    shadow: string | null;
+    radius: number | null;
+    margin: number | null;
     dismiss_days: number | null;
     priority: number;
 }
-/** Options for showing a banner */
+/** Options for showing a banner. All fields are optional.
+ *  Resolution chain per value: option → server config → theme → built-in default. */
 interface ShowBannerOptions {
     position?: 'top' | 'bottom';
+    style?: 'pinned' | 'floating' | 'stacked';
+    animation?: 'slide' | 'fade' | 'pop' | 'none';
+    theme?: 'light' | 'dark';
     label?: string;
+    delay?: number;
+    /** Stacked-mode only: CSS selector for the element to inject before (top) or after (bottom).
+     *  Falls back to auto-detect when omitted. */
+    anchor?: string;
+    bg?: string;
+    border?: string;
+    radius?: number;
+    margin?: number;
+    shadow?: 'none' | 'sm' | 'md' | 'lg';
+    titleColor?: string;
+    titleSize?: number;
+    titleWeight?: 400 | 500 | 600 | 700;
+    bodyColor?: string;
+    bodySize?: number;
+    bodyWeight?: 400 | 500 | 600 | 700;
+    ctaBg?: string;
+    ctaColor?: string;
+    ctaSize?: number;
+    ctaWeight?: 400 | 500 | 600 | 700;
+    ctaRadius?: number;
+    iconSize?: number;
+    iconRadius?: number;
+    hideIcon?: boolean;
+    hideClose?: boolean;
+    hideBody?: boolean;
+    customClass?: string;
 }
 /** In-app message from the API */
 interface Message {
@@ -160,6 +196,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 +333,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 +401,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 +431,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 };