shopgpt 0.2.0 → 0.3.0

package/README.md

@@ -1,94 +1,95 @@
-# shopgpt — Shoppable CTV Ad SDK
-
-TV ad plays → viewer presses the CTA → cart converts → TV updates live.
-
-Works on any HTML5 CTV (Samsung Tizen, LG webOS, FireTV, AndroidTV, Roku webview). No native code.
-
-## Quickstart
-
-```ts
-import { ShopGPTCTV } from "shopgpt";
-
-const ctv = new ShopGPTCTV({ placementId: "AD-01" }); // ← /embed ad spot id
-
-// listen for conversions
-ctv.onEvent((e) => {
-  if (e.type === "added_to_cart") showBadge(e.session);
-});
-
-// when the ad spot starts — any /embed ad
-const { session } = await ctv.createSession(product);
-
-// CTA press → raises the added_to_cart flag
-await ctv.addToCart(session.id);
-```
-
-## CTA (fully customisable)
-
-Two built-in presets, or any custom text:
-
-```tsx
-import { ShopGPTAddToCartButton } from "shopgpt/react";
-
-// preset 1 (default)
-<ShopGPTAddToCartButton session={session} cta="add_to_cart" />
-
-// preset 2
-<ShopGPTAddToCartButton session={session} cta="send_to_phone" />
-
-// fully custom — change it as you want
-<ShopGPTAddToCartButton
-  session={session}
-  label="Buy Now"
-  className="my-cta-class"
-  onCta={(s) => analytics.track("ctv_cta", { sessionId: s.id })}
-/>
-```
-
-## React
-
-```tsx
-import { ShopGPTCTVPlayer, useShopGPTShoppableAd } from "shopgpt/react";
-
-<ShopGPTCTVPlayer
-  videoSrc="https://…/ad.mp4"
-  product={product}
-  placementId="hero"
-  cta="send_to_phone"   // or ctaLabel="Buy Now"
-  onConverted={(s) => console.log("sold!", s.cartCount)}
-/>
-```
-
-Hooks: `useShopGPTShoppableAd(product, opts)` (create + poll automatically),
-`useShopGPTSession(sessionId)` (follow a live session).
-
-## Backend (included in this repo)
-
-| Method | Route | Purpose |
-|---|---|---|
-| POST | `/api/ctv/session` | create session `{ product, placementId, campaignId }` |
-| GET | `/api/ctv/session/:id` | poll session (no-store) |
-| PATCH | `/api/ctv/session/:id` | `{ status: "scanned" \| "viewing" \| "completed" }` |
-| POST | `/api/ctv/cart` | `{ sessionId, qty }` → marks `added_to_cart` |
-| GET | `/api/ctv/cart?sessionId=` | list cart items |
-| GET | `/api/ctv/products` | catalog products shaped for TV |
-
-Demo: `/ctv-demo/tv` (TV) → press the CTA → spot flips to converted live.
-
-## ShopGPT handoff (CTV → shopgpt.rankup.diy)
-
-Sessions carry a ShopGPT deep link (`session.mobileUrl`):
-
-```
-https://shopgpt.rankup.diy/?product_id=<acp_item_id>&ctv=<sessionId>
-```
-
-`?product_id=` opens the ShopGPT product dialog (chat + add to cart);
-`&ctv=` lets ShopGPT beacon `scanned` / `added_to_cart` back to
-`/api/ctv/session/:id` and `/api/ctv/cart` (CORS open) so the TV updates live.
-
-## Production notes
-
-- Current store is in-memory (`lib/ctv/store.ts`). Move to Supabase `ctv_sessions` + `ctv_cart_items` or Upstash Redis for multi-instance.
-- Wire `product` from Shopify / Woo / ACP feed (`lib/acp`, `app/shop/[slug]/[itemId]`).
-- Analytics: `ctv.track("impression", { sessionId })` → POST `/api/ctv/session/track` (stub, add table).
+# shopgpt — Shoppable CTV Ad SDK
+
+TV ad plays → viewer presses the CTA → cart converts → TV updates live.
+
+Works on any HTML5 CTV (Samsung Tizen, LG webOS, FireTV, AndroidTV, Roku webview). No native code.
+
+## Quickstart
+
+```ts
+import { ShopGPTCTV } from "shopgpt";
+
+const ctv = new ShopGPTCTV({ apiBase: "https://app.rankup.diy" });
+
+// listen for conversions
+ctv.onEvent((e) => {
+  if (e.type === "added_to_cart") showBadge(e.session);
+});
+
+// when the ad starts — pass the 3 VAST params as-is.
+// The product (title, image, price) is looked up server-side from rankupid.
+const { session } = await ctv.createSession({ shoppable, rankupid, cta });
+if (!session) return; // shoppable: false → plain ad
+
+// CTA press → raises the added_to_cart flag
+await ctv.addToCart(session.id);
+```
+
+## CTA (fully customisable)
+
+Two built-in presets, or any custom text:
+
+```tsx
+import { ShopGPTAddToCartButton } from "shopgpt/react";
+
+// preset 1 (default)
+<ShopGPTAddToCartButton session={session} cta="add_to_cart" />
+
+// preset 2
+<ShopGPTAddToCartButton session={session} cta="send_to_phone" />
+
+// fully custom — change it as you want
+<ShopGPTAddToCartButton
+  session={session}
+  label="Buy Now"
+  className="my-cta-class"
+  onCta={(s) => analytics.track("ctv_cta", { sessionId: s.id })}
+/>
+```
+
+## React
+
+```tsx
+import { ShopGPTCTVPlayer, useShopGPTShoppableAd } from "shopgpt/react";
+
+<ShopGPTCTVPlayer
+  videoSrc="https://…/ad.mp4"
+  ad={{ shoppable: true, rankupid: 10403886137619, cta: "Scan to buy" }}
+  cta="send_to_phone"   // or ctaLabel="Buy Now"
+  onConverted={(s) => console.log("sold!", s.cartCount)}
+/>
+```
+
+Hooks: `useShopGPTShoppableAd(ad, opts)` (create + poll automatically),
+`useShopGPTSession(sessionId)` (follow a live session).
+
+## Backend (included in this repo)
+
+| Method | Route | Purpose |
+|---|---|---|
+| POST | `/api/ctv/session` | create session `{ shoppable, rankupid, cta }` → product resolved server-side (404 if unknown) |
+| GET | `/api/ctv/session/:id` | poll session (no-store) |
+| PATCH | `/api/ctv/session/:id` | `{ status: "scanned" \| "viewing" \| "completed" }` |
+| POST | `/api/ctv/cart` | `{ sessionId, qty }` → marks `added_to_cart` |
+| GET | `/api/ctv/cart?sessionId=` | list cart items |
+| GET | `/api/ctv/products` | catalog products shaped for TV |
+
+Demo: `/ctv-demo/tv` (TV) → press the CTA → spot flips to converted live.
+
+## ShopGPT handoff (CTV → shopgpt.rankup.diy)
+
+Sessions carry a ShopGPT deep link (`session.mobileUrl`):
+
+```
+https://shopgpt.rankup.diy/?product_id=<acp_item_id>&ctv=<sessionId>
+```
+
+`?product_id=` opens the ShopGPT product dialog (chat + add to cart);
+`&ctv=` lets ShopGPT beacon `scanned` / `added_to_cart` back to
+`/api/ctv/session/:id` and `/api/ctv/cart` (CORS open) so the TV updates live.
+
+## Production notes
+
+- Current store is in-memory (`lib/ctv/store.ts`). Move to Supabase `ctv_sessions` + `ctv_cart_items` or Upstash Redis for multi-instance.
+- Wire `product` from Shopify / Woo / ACP feed (`lib/acp`, `app/shop/[slug]/[itemId]`).
+- Analytics: `ctv.track("impression", { sessionId })` → POST `/api/ctv/session/track` (stub, add table).

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { ShopGPTConfig, ShopGPTEvent, ShopGPTProduct, ShopGPTSession } from "./types";
+import type { ShopGPTAdParams, ShopGPTConfig, ShopGPTEvent, ShopGPTProduct, ShopGPTSession } from "./types";
 export * from "./types";
 type Listener = (e: ShopGPTEvent) => void;
 /**
@@ -8,8 +8,8 @@ type Listener = (e: ShopGPTEvent) => void;
  * Phone side: getSession() → markViewed() → addToCart()
  *
  * @example
- * const ctv = new ShopGPTCTV({ placementId: "living-room-hero" });
- * const { session } = await ctv.createSession(product);
+ * const ctv = new ShopGPTCTV({ apiBase: "https://app.rankup.diy" });
+ * const { session } = await ctv.createSession({ shoppable: true, rankupid: 10403886137619, cta: "Scan to buy" });
  * ctv.onEvent((e) => { if (e.type === "added_to_cart") showBadge(e.session); });
  */
 export declare class ShopGPTCTV {
@@ -21,13 +21,9 @@ export declare class ShopGPTCTV {
     onEvent(fn: Listener): () => void;
     private emit;
     private f;
-    createSession(product: ShopGPTProduct, opts?: {
-        campaignId?: string;
-        placementId?: string;
-        ttlSec?: number;
-    }): Promise<{
-        session: ShopGPTSession;
-        mobileUrl: string;
+    createSession(ad: ShopGPTAdParams): Promise<{
+        session: ShopGPTSession | null;
+        mobileUrl: string | null;
     }>;
     getSession(sessionId: string): Promise<ShopGPTSession>;
     pollSession(sessionId: string, onUpdate?: (s: ShopGPTSession) => void): () => void;
@@ -42,5 +38,5 @@ export declare class ShopGPTCTV {
     }>;
     track(event: string, props?: Record<string, unknown>): void;
 }
-/** Vanilla script-tag helper: <div data-shopgpt-ctv data-product-id="..."> */
+/** Vanilla script-tag helper: marks [data-shopgpt-ctv] elements ready. */
 export declare function autoInit(selector?: string): ShopGPTCTV;

package/dist/index.js

@@ -13,8 +13,8 @@ function resolveBase(cfg) {
  * Phone side: getSession() → markViewed() → addToCart()
  *
  * @example
- * const ctv = new ShopGPTCTV({ placementId: "living-room-hero" });
- * const { session } = await ctv.createSession(product);
+ * const ctv = new ShopGPTCTV({ apiBase: "https://app.rankup.diy" });
+ * const { session } = await ctv.createSession({ shoppable: true, rankupid: 10403886137619, cta: "Scan to buy" });
  * ctv.onEvent((e) => { if (e.type === "added_to_cart") showBadge(e.session); });
  */
 export class ShopGPTCTV {
@@ -43,24 +43,28 @@ export class ShopGPTCTV {
     f() {
         return this.cfg.fetchImpl ?? fetch.bind(globalThis);
     }
-    // ── TV: create a shoppable session ──────────────────────────────
-    async createSession(product, opts) {
+    // ── TV: create a shoppable session from the VAST ad params ─────
+    // Only { shoppable, rankupid, cta } are needed — the server looks up the
+    // product. `session` is null when the ad isn't shoppable.
+    async createSession(ad) {
+        if (ad.shoppable === false)
+            return { session: null, mobileUrl: null };
         const res = await this.f()(`${this.apiBase}/api/ctv/session`, {
             method: "POST",
             headers: { "content-type": "application/json" },
             body: JSON.stringify({
-                product,
-                placementId: opts?.placementId ?? this.cfg.placementId,
-                campaignId: opts?.campaignId ?? this.cfg.campaignId,
-                ttlSec: opts?.ttlSec ?? 600,
+                shoppable: ad.shoppable ?? true,
+                rankupid: ad.rankupid,
+                cta: ad.cta,
             }),
         });
         if (!res.ok)
             throw new Error(`createSession failed: ${res.status}`);
         const session = (await res.json()).session;
-        const mobileUrl = session.mobileUrl;
+        if (!session)
+            return { session: null, mobileUrl: null };
         this.emit({ type: "session_created", session });
-        return { session, mobileUrl };
+        return { session, mobileUrl: session.mobileUrl };
     }
     // ── Shared: fetch one session ───────────────────────────────────
     async getSession(sessionId) {
@@ -142,7 +146,7 @@ export class ShopGPTCTV {
         }
     }
 }
-/** Vanilla script-tag helper: <div data-shopgpt-ctv data-product-id="..."> */
+/** Vanilla script-tag helper: marks [data-shopgpt-ctv] elements ready. */
 export function autoInit(selector = "[data-shopgpt-ctv]") {
     const client = new ShopGPTCTV();
     if (typeof document !== "undefined") {

package/dist/react.d.ts

@@ -1,12 +1,10 @@
 import { ShopGPTCTV } from "./index";
-import type { ShopGPTProduct, ShopGPTSession } from "./types";
+import type { ShopGPTAdParams, ShopGPTSession } from "./types";
 export declare function useShopGPTSession(sessionId: string | null, apiBase?: string): {
     session: ShopGPTSession | null;
     error: string | null;
 };
-export declare function useShopGPTShoppableAd(product: ShopGPTProduct | null, opts?: {
-    placementId?: string;
-    campaignId?: string;
+export declare function useShopGPTShoppableAd(ad: ShopGPTAdParams | null, opts?: {
     apiBase?: string;
     autoCreate?: boolean;
 }): {
@@ -30,15 +28,14 @@ export declare function ShopGPTAddToCartButton({ session, client, apiBase, qty,
     onAdded?: (s: ShopGPTSession) => void;
     className?: string;
 }): import("react/jsx-runtime").JSX.Element | null;
-export declare function ShopGPTCTVPlayer({ videoSrc, product, placementId, campaignId, apiBase, cta, ctaLabel, onConverted, }: {
+export declare function ShopGPTCTVPlayer({ videoSrc, ad, apiBase, cta, ctaLabel, onConverted, }: {
     videoSrc: string;
-    product: ShopGPTProduct;
-    placementId?: string;
-    campaignId?: string;
+    /** VAST ad params: { shoppable, rankupid, cta } */
+    ad: ShopGPTAdParams;
     apiBase?: string;
     /** CTA preset passed to the button: "add_to_cart" | "send_to_phone" */
     cta?: ShopGPTCta;
-    /** Fully custom CTA text (overrides the preset) */
+    /** Fully custom CTA text (overrides the preset and the ad's `cta`) */
     ctaLabel?: string;
     onConverted?: (s: ShopGPTSession) => void;
 }): import("react/jsx-runtime").JSX.Element;

package/dist/react.js

@@ -22,35 +22,33 @@ export function useShopGPTSession(sessionId, apiBase) {
     }, [sessionId, apiBase]);
     return { session, error };
 }
-// ── Hook: create session for a product (TV ad start) ──────────────
-export function useShopGPTShoppableAd(product, opts) {
+// ── Hook: create session from the VAST ad params (TV ad start) ────
+export function useShopGPTShoppableAd(ad, opts) {
     const [session, setSession] = useState(null);
     const [loading, setLoading] = useState(false);
     const clientRef = useRef(null);
     if (!clientRef.current)
         clientRef.current = new ShopGPTCTV(opts?.apiBase ? { apiBase: opts.apiBase } : {});
     const create = useCallback(async () => {
-        if (!product)
+        if (!ad)
             return null;
         setLoading(true);
         try {
-            const r = await clientRef.current.createSession(product, {
-                placementId: opts?.placementId,
-                campaignId: opts?.campaignId,
-            });
+            const r = await clientRef.current.createSession(ad);
             setSession(r.session);
-            clientRef.current.pollSession(r.session.id, setSession);
+            if (r.session)
+                clientRef.current.pollSession(r.session.id, setSession);
             return r.session;
         }
         finally {
             setLoading(false);
         }
-    }, [product, opts?.placementId, opts?.campaignId]);
+    }, [ad]);
     useEffect(() => {
-        if (opts?.autoCreate !== false && product && !session)
+        if (opts?.autoCreate !== false && ad && !session)
             void create();
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [product?.id]);
+    }, [ad?.rankupid, ad?.shoppable]);
     useEffect(() => () => clientRef.current?.stopPolling(), []);
     return { session, loading, create };
 }
@@ -86,16 +84,12 @@ export function ShopGPTAddToCartButton({ session, client, apiBase, qty = 1, cta
 // ── Component: minimal CTV player wrapper ─────────────────────────
 // Remote CTA button (raises `added_to_cart` flag). Overlay shows the
 // product name only — no other chrome.
-export function ShopGPTCTVPlayer({ videoSrc, product, placementId, campaignId, apiBase, cta = "add_to_cart", ctaLabel, onConverted, }) {
-    const { session } = useShopGPTShoppableAd(product, {
-        placementId,
-        campaignId,
-        apiBase,
-    });
+export function ShopGPTCTVPlayer({ videoSrc, ad, apiBase, cta = "add_to_cart", ctaLabel, onConverted, }) {
+    const { session } = useShopGPTShoppableAd(ad, { apiBase });
     useEffect(() => {
         if (session &&
             (session.status === "added_to_cart" || session.status === "completed"))
             onConverted?.(session);
     }, [session, onConverted]);
-    return (_jsxs("div", { className: "relative aspect-video w-full overflow-hidden rounded-2xl bg-black", children: [_jsx("video", { src: videoSrc, controls: true, autoPlay: true, muted: true, loop: true, playsInline: true, className: "h-full w-full object-cover" }), session && (_jsx("div", { className: "absolute bottom-6 right-6 z-20 rounded-2xl bg-black/70 p-4 text-white shadow-2xl backdrop-blur", children: _jsxs("div", { className: "pr-2", children: [_jsx("p", { className: "max-w-[240px] truncate text-sm font-semibold", children: session.product.title }), _jsx("div", { className: "mt-2", children: _jsx(ShopGPTAddToCartButton, { session: session, apiBase: apiBase, cta: cta, label: ctaLabel }) })] }) }))] }));
+    return (_jsxs("div", { className: "relative aspect-video w-full overflow-hidden rounded-2xl bg-black", children: [_jsx("video", { src: videoSrc, controls: true, autoPlay: true, muted: true, loop: true, playsInline: true, className: "h-full w-full object-cover" }), session && (_jsx("div", { className: "absolute bottom-6 right-6 z-20 rounded-2xl bg-black/70 p-4 text-white shadow-2xl backdrop-blur", children: _jsxs("div", { className: "pr-2", children: [_jsx("p", { className: "max-w-[240px] truncate text-sm font-semibold", children: session.product.title }), _jsx("div", { className: "mt-2", children: _jsx(ShopGPTAddToCartButton, { session: session, apiBase: apiBase, cta: cta, label: ctaLabel ?? session.cta }) })] }) }))] }));
 }

package/dist/types.d.ts

@@ -8,13 +8,22 @@ export interface ShopGPTProduct {
     url?: string;
     description?: string;
 }
+/** The three params a VAST ad carries. The product is resolved server-side from `rankupid`. */
+export interface ShopGPTAdParams {
+    /** false → plain ad, no session is created */
+    shoppable?: boolean;
+    /** Our product id (unique identifier) */
+    rankupid: number | string;
+    /** CTA label shown on the TV, e.g. "Scan to buy" */
+    cta?: string;
+}
 export type ShopGPTSessionStatus = "created" | "scanned" | "viewing" | "added_to_cart" | "completed" | "expired";
 export interface ShopGPTSession {
     id: string;
     product: ShopGPTProduct;
     status: ShopGPTSessionStatus;
-    placementId?: string;
-    campaignId?: string;
+    rankupid?: string;
+    cta?: string;
     mobileUrl: string;
     cartCount: number;
     scanCount: number;
@@ -24,8 +33,6 @@ export interface ShopGPTSession {
 export interface ShopGPTConfig {
     /** e.g. "https://shop.example.com" — base the SDK falls back to for links. Defaults to window.location.origin */
     apiBase?: string;
-    placementId?: string;
-    campaignId?: string;
     pollIntervalMs?: number;
     fetchImpl?: typeof fetch;
 }

package/package.json

@@ -1,23 +1,28 @@
-{
-  "name": "shopgpt",
-  "version": "0.2.0",
-  "description": "ShopGPT Shoppable CTV Ad SDK — remote CTA to cart with live TV conversion events. Works on any HTML5 CTV player (Tizen, webOS, FireTV, AndroidTV).",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "files": ["dist", "README.md"],
-  "type": "module",
-  "exports": {
-    ".": "./dist/index.js",
-    "./react": "./dist/react.js"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json"
-  },
-  "peerDependencies": {
-    "react": ">=18"
-  },
-  "peerDependenciesMeta": {
-    "react": { "optional": true }
-  },
-  "license": "MIT"
-}
+{
+  "name": "shopgpt",
+  "version": "0.3.0",
+  "description": "ShopGPT Shoppable CTV Ad SDK — remote CTA to cart with live TV conversion events. Works on any HTML5 CTV player (Tizen, webOS, FireTV, AndroidTV).",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./react": "./dist/react.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "license": "MIT"
+}