shopgpt 0.1.0

package/README.md

@@ -0,0 +1,78 @@
+# @enem/ctv-sdk — CTV Shoppable Ad SDK
+
+TV ad plays → QR overlay → phone scans → PDP opens → Add to Cart → TV updates live.
+
+Works on any HTML5 CTV (Samsung Tizen, LG webOS, FireTV, AndroidTV, Roku webview). No native code.
+
+## Quickstart
+
+```ts
+import { EnemCTV } from "@enem/ctv-sdk";
+
+const ctv = new EnemCTV({ placementId: "hero-ctv" });
+
+// TV side — when ad starts
+const { session, qrImageUrl } = await ctv.createSession({
+  id: "sku-123",
+  title: "Enem Runner",
+  price: "3499 INR",
+  imageUrl: "https://…/shoe.png",
+});
+// render qrImageUrl in 10-foot overlay, mobileUrl = session.mobileUrl
+
+// TV side — live updates (scanned → added_to_cart)
+ctv.pollSession(session.id, (s) => {
+  if (s.status === "scanned") showToast("Phone connected");
+  if (s.status === "added_to_cart") showToast(`Added ×${s.cartCount}`);
+});
+```
+
+```ts
+// Phone side — /c/:sessionId page
+await ctv.markScanned(sessionId); // TV shows "connected"
+await ctv.addToCart(sessionId, { qty: 1 }); // TV shows "Added to cart"
+```
+
+## React
+
+```tsx
+import { EnemCTVPlayer, EnemQROverlay, useEnemShoppableAd } from "@enem/ctv-sdk/react";
+
+<EnemCTVPlayer videoSrc="https://…/ad.mp4" product={product} placementId="hero" />
+```
+
+## 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 |
+
+Demo: `/ctv-demo/tv` (TV) → scan QR → ShopGPT product dialog directly.
+
+## ShopGPT handoff (CTV → shopgpt.rankup.diy)
+
+QR encodes the ShopGPT deep link directly (no interstitial page):
+
+```
+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.
+`POST /api/ctv/session` returns this as `session.mobileUrl`, and per-product
+URLs are included in `GET /api/ctv/products` as `shopgptUrl`
+(append `&ctv=<sessionId>` at session time) — see `lib/ctv/shopgpt.ts`.
+
+## 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.
+- QR uses `api.qrserver.com` image CDN (zero dep). Swap to server-side `qrcode` lib if offline needed.
+- 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

@@ -0,0 +1,48 @@
+import type { EnemCTVConfig, EnemEvent, EnemProduct, EnemSession } from "./types";
+export * from "./types";
+export * from "./qr";
+type Listener = (e: EnemEvent) => void;
+/**
+ * EnemCTV — framework-agnostic core.
+ *
+ * TV side: createSession() → render QR → pollSession()
+ * Phone side: getSession() → markViewed() → addToCart()
+ *
+ * @example
+ * const ctv = new EnemCTV({ placementId: "living-room-hero" });
+ * const { session, qrImageUrl } = await ctv.createSession(product);
+ * ctv.pollSession(session.id, (e) => console.log(e.type));
+ */
+export declare class EnemCTV {
+    private cfg;
+    private listeners;
+    private pollTimer;
+    constructor(config?: EnemCTVConfig);
+    get apiBase(): string;
+    onEvent(fn: Listener): () => void;
+    private emit;
+    private f;
+    createSession(product: EnemProduct, opts?: {
+        campaignId?: string;
+        placementId?: string;
+        ttlSec?: number;
+    }): Promise<{
+        session: EnemSession;
+        mobileUrl: string;
+        qrImageUrl: string;
+    }>;
+    getSession(sessionId: string): Promise<EnemSession>;
+    pollSession(sessionId: string, onUpdate?: (s: EnemSession) => void): () => void;
+    stopPolling(): void;
+    markScanned(sessionId: string): Promise<EnemSession>;
+    addToCart(sessionId: string, opts?: {
+        qty?: number;
+        product?: EnemProduct;
+    }): Promise<{
+        ok: boolean;
+        session: EnemSession;
+    }>;
+    track(event: string, props?: Record<string, unknown>): void;
+}
+/** Vanilla script-tag helper: <div data-enem-ctv data-product-id="..."> */
+export declare function autoInit(selector?: string): EnemCTV;

package/dist/index.js

@@ -0,0 +1,157 @@
+import { buildMobileUrl, buildQRImageUrl } from "./qr";
+export * from "./types";
+export * from "./qr";
+function resolveBase(cfg) {
+    if (cfg?.apiBase)
+        return cfg.apiBase.replace(/\/$/, "");
+    if (typeof window !== "undefined" && window.location?.origin)
+        return window.location.origin;
+    return "";
+}
+/**
+ * EnemCTV — framework-agnostic core.
+ *
+ * TV side: createSession() → render QR → pollSession()
+ * Phone side: getSession() → markViewed() → addToCart()
+ *
+ * @example
+ * const ctv = new EnemCTV({ placementId: "living-room-hero" });
+ * const { session, qrImageUrl } = await ctv.createSession(product);
+ * ctv.pollSession(session.id, (e) => console.log(e.type));
+ */
+export class EnemCTV {
+    constructor(config = {}) {
+        this.listeners = new Set();
+        this.pollTimer = null;
+        this.cfg = { pollIntervalMs: 2500, ...config };
+    }
+    get apiBase() {
+        return resolveBase(this.cfg);
+    }
+    onEvent(fn) {
+        this.listeners.add(fn);
+        return () => this.listeners.delete(fn);
+    }
+    emit(e) {
+        this.listeners.forEach((fn) => {
+            try {
+                fn(e);
+            }
+            catch {
+                /* noop */
+            }
+        });
+    }
+    f() {
+        return this.cfg.fetchImpl ?? fetch.bind(globalThis);
+    }
+    // ── TV: create a shoppable session ──────────────────────────────
+    async createSession(product, opts) {
+        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,
+            }),
+        });
+        if (!res.ok)
+            throw new Error(`createSession failed: ${res.status}`);
+        const session = (await res.json()).session;
+        const mobileUrl = session.mobileUrl || buildMobileUrl(this.apiBase, session.id);
+        const qrImageUrl = buildQRImageUrl(mobileUrl);
+        this.emit({ type: "session_created", session });
+        return { session, mobileUrl, qrImageUrl };
+    }
+    // ── Shared: fetch one session ───────────────────────────────────
+    async getSession(sessionId) {
+        const res = await this.f()(`${this.apiBase}/api/ctv/session/${sessionId}`, {
+            cache: "no-store",
+        });
+        if (!res.ok)
+            throw new Error(`getSession failed: ${res.status}`);
+        return (await res.json()).session;
+    }
+    // ── TV: poll until scanned / added_to_cart ──────────────────────
+    pollSession(sessionId, onUpdate) {
+        this.stopPolling();
+        let lastStatus = "";
+        const tick = async () => {
+            try {
+                const s = await this.getSession(sessionId);
+                if (s.status !== lastStatus) {
+                    lastStatus = s.status;
+                    onUpdate?.(s);
+                    this.emit({ type: "session_updated", session: s });
+                    if (s.status === "scanned" || s.status === "viewing")
+                        this.emit({ type: "scanned", session: s });
+                    if (s.status === "added_to_cart" || s.status === "completed")
+                        this.emit({ type: "added_to_cart", session: s });
+                }
+                if (s.status === "completed" || s.status === "expired")
+                    this.stopPolling();
+            }
+            catch {
+                /* transient — keep polling */
+            }
+        };
+        void tick();
+        this.pollTimer = setInterval(tick, this.cfg.pollIntervalMs ?? 2500);
+        return () => this.stopPolling();
+    }
+    stopPolling() {
+        if (this.pollTimer)
+            clearInterval(this.pollTimer);
+        this.pollTimer = null;
+    }
+    // ── Phone: mark scanned/viewing ─────────────────────────────────
+    async markScanned(sessionId) {
+        const res = await this.f()(`${this.apiBase}/api/ctv/session/${sessionId}`, {
+            method: "PATCH",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ status: "scanned" }),
+        });
+        if (!res.ok)
+            throw new Error(`markScanned failed: ${res.status}`);
+        return (await res.json()).session;
+    }
+    // ── Phone: add to cart (marks session converted) ────────────────
+    async addToCart(sessionId, opts) {
+        const res = await this.f()(`${this.apiBase}/api/ctv/cart`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ sessionId, qty: opts?.qty ?? 1, product: opts?.product }),
+        });
+        if (!res.ok)
+            throw new Error(`addToCart failed: ${res.status}`);
+        const data = await res.json();
+        if (data.session)
+            this.emit({ type: "added_to_cart", session: data.session });
+        return data;
+    }
+    // ── Analytics (fire-and-forget) ─────────────────────────────────
+    track(event, props) {
+        try {
+            void this.f()(`${this.apiBase}/api/ctv/session/track`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ event, ...props }),
+            });
+        }
+        catch {
+            /* noop */
+        }
+    }
+}
+/** Vanilla script-tag helper: <div data-enem-ctv data-product-id="..."> */
+export function autoInit(selector = "[data-enem-ctv]") {
+    const client = new EnemCTV();
+    if (typeof document !== "undefined") {
+        document.querySelectorAll(selector).forEach((el) => {
+            el.setAttribute("data-enem-ctv-ready", "true");
+        });
+    }
+    return client;
+}

package/dist/qr.d.ts

@@ -0,0 +1,13 @@
+/** QR helpers — zero dependency. Uses api.qrserver.com image CDN by default. */
+/**
+ * Legacy fallback deep-link builder.
+ * Prefer `session.mobileUrl` from the server — it already points directly at
+ * the ShopGPT product dialog (?product_id=…&ctv=…).
+ */
+export declare function buildMobileUrl(apiBase: string, sessionId: string): string;
+export declare function buildQRImageUrl(mobileUrl: string, size?: number, opts?: {
+    color?: string;
+    bgcolor?: string;
+}): string;
+/** Short human code shown under QR for manual entry (last 6 of session id). */
+export declare function shortCode(sessionId: string): string;

package/dist/qr.js

@@ -0,0 +1,25 @@
+/** QR helpers — zero dependency. Uses api.qrserver.com image CDN by default. */
+/**
+ * Legacy fallback deep-link builder.
+ * Prefer `session.mobileUrl` from the server — it already points directly at
+ * the ShopGPT product dialog (?product_id=…&ctv=…).
+ */
+export function buildMobileUrl(apiBase, sessionId) {
+    const base = apiBase.replace(/\/$/, "");
+    return `${base}/c/${sessionId}`;
+}
+export function buildQRImageUrl(mobileUrl, size = 220, opts) {
+    const params = new URLSearchParams({
+        size: `${size}x${size}`,
+        data: mobileUrl,
+        color: (opts?.color ?? "111827").replace("#", ""),
+        bgcolor: (opts?.bgcolor ?? "ffffff").replace("#", ""),
+        qzone: "1",
+        format: "png",
+    });
+    return `https://api.qrserver.com/v1/create-qr-code/?${params.toString()}`;
+}
+/** Short human code shown under QR for manual entry (last 6 of session id). */
+export function shortCode(sessionId) {
+    return sessionId.replace(/[^a-zA-Z0-9]/g, "").slice(-6).toUpperCase() || "ENEM01";
+}

package/dist/react.d.ts

@@ -0,0 +1,41 @@
+import { EnemCTV } from "./index";
+import type { EnemProduct, EnemSession } from "./types";
+export declare function useEnemSession(sessionId: string | null, apiBase?: string): {
+    session: EnemSession | null;
+    error: string | null;
+};
+export declare function useEnemShoppableAd(product: EnemProduct | null, opts?: {
+    placementId?: string;
+    campaignId?: string;
+    apiBase?: string;
+    autoCreate?: boolean;
+}): {
+    session: EnemSession | null;
+    qrImageUrl: string | null;
+    loading: boolean;
+    create: () => Promise<EnemSession | null>;
+};
+export declare function EnemAddToCartButton({ session, client, apiBase, qty, label, onAdded, className, }: {
+    session: EnemSession | null;
+    client?: EnemCTV;
+    apiBase?: string;
+    qty?: number;
+    label?: string;
+    onAdded?: (s: EnemSession) => void;
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element | null;
+export declare function EnemQROverlay({ session, qrImageUrl, position, theme, }: {
+    session: EnemSession | null;
+    qrImageUrl: string | null;
+    position?: "bottom-right" | "bottom-left" | "right";
+    theme?: "dark" | "light";
+}): import("react/jsx-runtime").JSX.Element | null;
+export declare function EnemCTVPlayer({ videoSrc, product, placementId, campaignId, apiBase, showQR, onConverted, }: {
+    videoSrc: string;
+    product: EnemProduct;
+    placementId?: string;
+    campaignId?: string;
+    apiBase?: string;
+    showQR?: boolean;
+    onConverted?: (s: EnemSession) => void;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/react.js

@@ -0,0 +1,118 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { EnemCTV } from "./index";
+import { buildQRImageUrl, shortCode } from "./qr";
+// ── Hook: live session (TV side polling) ──────────────────────────
+export function useEnemSession(sessionId, apiBase) {
+    const [session, setSession] = useState(null);
+    const [error, setError] = useState(null);
+    useEffect(() => {
+        if (!sessionId)
+            return;
+        const client = new EnemCTV(apiBase ? { apiBase } : {});
+        let stop = () => { };
+        client
+            .getSession(sessionId)
+            .then((s) => {
+            setSession(s);
+            stop = client.pollSession(sessionId, setSession);
+        })
+            .catch((e) => setError(String(e?.message ?? e)));
+        return () => stop();
+    }, [sessionId, apiBase]);
+    return { session, error };
+}
+// ── Hook: create session for a product (TV ad start) ──────────────
+export function useEnemShoppableAd(product, opts) {
+    const [session, setSession] = useState(null);
+    const [qrImageUrl, setQrImageUrl] = useState(null);
+    const [loading, setLoading] = useState(false);
+    const clientRef = useRef(null);
+    if (!clientRef.current)
+        clientRef.current = new EnemCTV(opts?.apiBase ? { apiBase: opts.apiBase } : {});
+    const create = useCallback(async () => {
+        if (!product)
+            return null;
+        setLoading(true);
+        try {
+            const r = await clientRef.current.createSession(product, {
+                placementId: opts?.placementId,
+                campaignId: opts?.campaignId,
+            });
+            setSession(r.session);
+            setQrImageUrl(r.qrImageUrl);
+            clientRef.current.pollSession(r.session.id, setSession);
+            return r.session;
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [product, opts?.placementId, opts?.campaignId]);
+    useEffect(() => {
+        if (opts?.autoCreate !== false && product && !session)
+            void create();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [product?.id]);
+    useEffect(() => () => clientRef.current?.stopPolling(), []);
+    return { session, qrImageUrl, loading, create };
+}
+// ── Component: Add-to-Cart button for CTV (10-foot UI, no QR needed) ──
+// Calls ctv.addToCart(sessionId) so the SDK emits the `added_to_cart` flag;
+// the TV poll then flips the spot to the converted state.
+export function EnemAddToCartButton({ session, client, apiBase, qty = 1, label = "Add to Cart", onAdded, className, }) {
+    const [adding, setAdding] = useState(false);
+    const converted = session?.status === "added_to_cart" || session?.status === "completed";
+    if (!session)
+        return null;
+    if (converted) {
+        return (_jsx("p", { className: "inline-block rounded-full bg-emerald-500 px-3 py-1 text-xs font-bold text-white", children: "\u2713 Added to cart" }));
+    }
+    return (_jsx("button", { type: "button", disabled: adding, onClick: async () => {
+            const c = client ?? new EnemCTV(apiBase ? { apiBase } : {});
+            setAdding(true);
+            try {
+                const res = await c.addToCart(session.id, { qty });
+                if (res.session)
+                    onAdded?.(res.session);
+            }
+            finally {
+                setAdding(false);
+            }
+        }, className: className ??
+            "rounded-full bg-white px-6 py-2.5 text-sm font-bold text-black transition hover:bg-emerald-300 disabled:opacity-50", children: adding ? "Adding…" : label }));
+}
+// ── Component: QR overlay for CTV (10-foot UI) ─────────────────────
+// Legacy phone-scan path. Prefer EnemAddToCartButton for remote-driven
+// spots — it raises the same `added_to_cart` SDK flag with no QR.
+export function EnemQROverlay({ session, qrImageUrl, position = "bottom-right", theme = "dark", }) {
+    if (!session || !qrImageUrl)
+        return null;
+    const pos = position === "bottom-left"
+        ? "left-6 bottom-6"
+        : position === "right"
+            ? "right-6 top-1/2 -translate-y-1/2"
+            : "right-6 bottom-6";
+    const converted = session.status === "added_to_cart" || session.status === "completed";
+    const scanned = session.status === "scanned" || session.status === "viewing" || converted;
+    return (_jsxs("div", { className: `absolute ${pos} z-20 flex items-center gap-4 rounded-2xl p-4 shadow-2xl backdrop-blur ${theme === "dark" ? "bg-black/70 text-white" : "bg-white/95 text-gray-900"}`, children: [_jsx("img", { src: qrImageUrl, alt: "Scan to shop", width: 132, height: 132, className: "rounded-xl bg-white p-1" }), _jsxs("div", { className: "pr-2", children: [_jsx("p", { className: "text-[11px] font-bold uppercase tracking-[0.2em] opacity-70", children: "Shop this ad" }), _jsx("p", { className: "mt-1 max-w-[180px] truncate text-sm font-semibold", children: session.product.title }), _jsx("p", { className: "text-sm opacity-80", children: session.product.salePrice ?? session.product.price }), converted ? (_jsx("p", { className: "mt-2 inline-block rounded-full bg-emerald-500 px-3 py-1 text-xs font-bold text-white", children: "\u2713 Added to cart" })) : scanned ? (_jsx("p", { className: "mt-2 inline-block rounded-full bg-sky-500 px-3 py-1 text-xs font-bold text-white", children: "\u25CF Phone connected" })) : (_jsxs("p", { className: "mt-2 text-xs opacity-80", children: ["Scan with camera", _jsx("span", { className: "ml-2 rounded bg-white/20 px-1.5 py-0.5 font-mono", children: shortCode(session.id) })] }))] })] }));
+}
+// ── Component: minimal CTV player wrapper ─────────────────────────
+// Remote-first: shows Add to Cart (raises `added_to_cart` flag). Opt into
+// the legacy QR overlay with showQR.
+export function EnemCTVPlayer({ videoSrc, product, placementId, campaignId, apiBase, showQR = false, onConverted, }) {
+    const { session, qrImageUrl } = useEnemShoppableAd(product, {
+        placementId,
+        campaignId,
+        apiBase,
+    });
+    const mobileUrl = session
+        ? buildQRImageUrl(session.mobileUrl) && session.mobileUrl
+        : null;
+    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" }), showQR ? (_jsx(EnemQROverlay, { session: session, qrImageUrl: qrImageUrl })) : (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: _jsx(EnemAddToCartButton, { session: session, apiBase: apiBase }) }))), mobileUrl && showQR ? (_jsx("div", { className: "absolute left-6 top-6 rounded-full bg-black/60 px-3 py-1 font-mono text-[11px] text-white/80", children: mobileUrl })) : null] }));
+}

package/dist/types.d.ts

@@ -0,0 +1,44 @@
+export interface EnemProduct {
+    id: string;
+    title: string;
+    brand?: string;
+    price: string;
+    salePrice?: string;
+    imageUrl: string;
+    url?: string;
+    description?: string;
+}
+export type EnemSessionStatus = "created" | "scanned" | "viewing" | "added_to_cart" | "completed" | "expired";
+export interface EnemSession {
+    id: string;
+    product: EnemProduct;
+    status: EnemSessionStatus;
+    placementId?: string;
+    campaignId?: string;
+    mobileUrl: string;
+    cartCount: number;
+    scanCount: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface EnemCTVConfig {
+    /** 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;
+}
+export type EnemEvent = {
+    type: "session_created";
+    session: EnemSession;
+} | {
+    type: "session_updated";
+    session: EnemSession;
+} | {
+    type: "scanned";
+    session: EnemSession;
+} | {
+    type: "added_to_cart";
+    session: EnemSession;
+};

package/dist/types.js

@@ -0,0 +1,2 @@
+// Enem CTV SDK — shared types (framework agnostic)
+export {};

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "shopgpt",
+  "version": "0.1.0",
+  "description": "Enem CTV Shoppable Ad SDK — QR to mobile PDP to cart. Works on any HTML5 CTV player (Tizen, webOS, FireTV, AndroidTV).",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "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"
+}

package/src/index.ts

@@ -0,0 +1,171 @@
+import type { EnemCTVConfig, EnemEvent, EnemProduct, EnemSession } from "./types";
+import { buildMobileUrl, buildQRImageUrl } from "./qr";
+
+export * from "./types";
+export * from "./qr";
+
+type Listener = (e: EnemEvent) => void;
+
+function resolveBase(cfg?: EnemCTVConfig): string {
+  if (cfg?.apiBase) return cfg.apiBase.replace(/\/$/, "");
+  if (typeof window !== "undefined" && window.location?.origin) return window.location.origin;
+  return "";
+}
+
+/**
+ * EnemCTV — framework-agnostic core.
+ *
+ * TV side: createSession() → render QR → pollSession()
+ * Phone side: getSession() → markViewed() → addToCart()
+ *
+ * @example
+ * const ctv = new EnemCTV({ placementId: "living-room-hero" });
+ * const { session, qrImageUrl } = await ctv.createSession(product);
+ * ctv.pollSession(session.id, (e) => console.log(e.type));
+ */
+export class EnemCTV {
+  private cfg: EnemCTVConfig;
+  private listeners = new Set<Listener>();
+  private pollTimer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(config: EnemCTVConfig = {}) {
+    this.cfg = { pollIntervalMs: 2500, ...config };
+  }
+
+  get apiBase(): string {
+    return resolveBase(this.cfg);
+  }
+
+  onEvent(fn: Listener): () => void {
+    this.listeners.add(fn);
+    return () => this.listeners.delete(fn);
+  }
+
+  private emit(e: EnemEvent) {
+    this.listeners.forEach((fn) => {
+      try {
+        fn(e);
+      } catch {
+        /* noop */
+      }
+    });
+  }
+
+  private f(): typeof fetch {
+    return this.cfg.fetchImpl ?? fetch.bind(globalThis);
+  }
+
+  // ── TV: create a shoppable session ──────────────────────────────
+  async createSession(
+    product: EnemProduct,
+    opts?: { campaignId?: string; placementId?: string; ttlSec?: number }
+  ): Promise<{ session: EnemSession; mobileUrl: string; qrImageUrl: string }> {
+    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,
+      }),
+    });
+    if (!res.ok) throw new Error(`createSession failed: ${res.status}`);
+    const session = (await res.json()).session as EnemSession;
+    const mobileUrl = session.mobileUrl || buildMobileUrl(this.apiBase, session.id);
+    const qrImageUrl = buildQRImageUrl(mobileUrl);
+    this.emit({ type: "session_created", session });
+    return { session, mobileUrl, qrImageUrl };
+  }
+
+  // ── Shared: fetch one session ───────────────────────────────────
+  async getSession(sessionId: string): Promise<EnemSession> {
+    const res = await this.f()(`${this.apiBase}/api/ctv/session/${sessionId}`, {
+      cache: "no-store",
+    });
+    if (!res.ok) throw new Error(`getSession failed: ${res.status}`);
+    return (await res.json()).session as EnemSession;
+  }
+
+  // ── TV: poll until scanned / added_to_cart ──────────────────────
+  pollSession(sessionId: string, onUpdate?: (s: EnemSession) => void): () => void {
+    this.stopPolling();
+    let lastStatus = "";
+    const tick = async () => {
+      try {
+        const s = await this.getSession(sessionId);
+        if (s.status !== lastStatus) {
+          lastStatus = s.status;
+          onUpdate?.(s);
+          this.emit({ type: "session_updated", session: s });
+          if (s.status === "scanned" || s.status === "viewing")
+            this.emit({ type: "scanned", session: s });
+          if (s.status === "added_to_cart" || s.status === "completed")
+            this.emit({ type: "added_to_cart", session: s });
+        }
+        if (s.status === "completed" || s.status === "expired") this.stopPolling();
+      } catch {
+        /* transient — keep polling */
+      }
+    };
+    void tick();
+    this.pollTimer = setInterval(tick, this.cfg.pollIntervalMs ?? 2500);
+    return () => this.stopPolling();
+  }
+
+  stopPolling() {
+    if (this.pollTimer) clearInterval(this.pollTimer);
+    this.pollTimer = null;
+  }
+
+  // ── Phone: mark scanned/viewing ─────────────────────────────────
+  async markScanned(sessionId: string): Promise<EnemSession> {
+    const res = await this.f()(`${this.apiBase}/api/ctv/session/${sessionId}`, {
+      method: "PATCH",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ status: "scanned" }),
+    });
+    if (!res.ok) throw new Error(`markScanned failed: ${res.status}`);
+    return (await res.json()).session as EnemSession;
+  }
+
+  // ── Phone: add to cart (marks session converted) ────────────────
+  async addToCart(
+    sessionId: string,
+    opts?: { qty?: number; product?: EnemProduct }
+  ): Promise<{ ok: boolean; session: EnemSession }> {
+    const res = await this.f()(`${this.apiBase}/api/ctv/cart`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ sessionId, qty: opts?.qty ?? 1, product: opts?.product }),
+    });
+    if (!res.ok) throw new Error(`addToCart failed: ${res.status}`);
+    const data = await res.json();
+    if (data.session) this.emit({ type: "added_to_cart", session: data.session });
+    return data;
+  }
+
+  // ── Analytics (fire-and-forget) ─────────────────────────────────
+  track(event: string, props?: Record<string, unknown>): void {
+    try {
+      void this.f()(`${this.apiBase}/api/ctv/session/track`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ event, ...props }),
+      });
+    } catch {
+      /* noop */
+    }
+  }
+}
+
+/** Vanilla script-tag helper: <div data-enem-ctv data-product-id="..."> */
+export function autoInit(selector = "[data-enem-ctv]"): EnemCTV {
+  const client = new EnemCTV();
+  if (typeof document !== "undefined") {
+    document.querySelectorAll(selector).forEach((el) => {
+      el.setAttribute("data-enem-ctv-ready", "true");
+    });
+  }
+  return client;
+}

package/src/qr.ts

@@ -0,0 +1,32 @@
+/** QR helpers — zero dependency. Uses api.qrserver.com image CDN by default. */
+
+/**
+ * Legacy fallback deep-link builder.
+ * Prefer `session.mobileUrl` from the server — it already points directly at
+ * the ShopGPT product dialog (?product_id=…&ctv=…).
+ */
+export function buildMobileUrl(apiBase: string, sessionId: string): string {
+  const base = apiBase.replace(/\/$/, "");
+  return `${base}/c/${sessionId}`;
+}
+
+export function buildQRImageUrl(
+  mobileUrl: string,
+  size = 220,
+  opts?: { color?: string; bgcolor?: string }
+): string {
+  const params = new URLSearchParams({
+    size: `${size}x${size}`,
+    data: mobileUrl,
+    color: (opts?.color ?? "111827").replace("#", ""),
+    bgcolor: (opts?.bgcolor ?? "ffffff").replace("#", ""),
+    qzone: "1",
+    format: "png",
+  });
+  return `https://api.qrserver.com/v1/create-qr-code/?${params.toString()}`;
+}
+
+/** Short human code shown under QR for manual entry (last 6 of session id). */
+export function shortCode(sessionId: string): string {
+  return sessionId.replace(/[^a-zA-Z0-9]/g, "").slice(-6).toUpperCase() || "ENEM01";
+}

package/src/react.tsx

@@ -0,0 +1,232 @@
+"use client";
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import { EnemCTV } from "./index";
+import { buildQRImageUrl, shortCode } from "./qr";
+import type { EnemProduct, EnemSession } from "./types";
+
+// ── Hook: live session (TV side polling) ──────────────────────────
+export function useEnemSession(sessionId: string | null, apiBase?: string) {
+  const [session, setSession] = useState<EnemSession | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!sessionId) return;
+    const client = new EnemCTV(apiBase ? { apiBase } : {});
+    let stop = () => {};
+    client
+      .getSession(sessionId)
+      .then((s) => {
+        setSession(s);
+        stop = client.pollSession(sessionId, setSession);
+      })
+      .catch((e) => setError(String(e?.message ?? e)));
+    return () => stop();
+  }, [sessionId, apiBase]);
+
+  return { session, error };
+}
+
+// ── Hook: create session for a product (TV ad start) ──────────────
+export function useEnemShoppableAd(
+  product: EnemProduct | null,
+  opts?: { placementId?: string; campaignId?: string; apiBase?: string; autoCreate?: boolean }
+) {
+  const [session, setSession] = useState<EnemSession | null>(null);
+  const [qrImageUrl, setQrImageUrl] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
+  const clientRef = useRef<EnemCTV | null>(null);
+  if (!clientRef.current) clientRef.current = new EnemCTV(opts?.apiBase ? { apiBase: opts.apiBase } : {});
+
+  const create = useCallback(async () => {
+    if (!product) return null;
+    setLoading(true);
+    try {
+      const r = await clientRef.current!.createSession(product, {
+        placementId: opts?.placementId,
+        campaignId: opts?.campaignId,
+      });
+      setSession(r.session);
+      setQrImageUrl(r.qrImageUrl);
+      clientRef.current!.pollSession(r.session.id, setSession);
+      return r.session;
+    } finally {
+      setLoading(false);
+    }
+  }, [product, opts?.placementId, opts?.campaignId]);
+
+  useEffect(() => {
+    if (opts?.autoCreate !== false && product && !session) void create();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [product?.id]);
+
+  useEffect(() => () => clientRef.current?.stopPolling(), []);
+
+  return { session, qrImageUrl, loading, create };
+}
+
+// ── Component: Add-to-Cart button for CTV (10-foot UI, no QR needed) ──
+// Calls ctv.addToCart(sessionId) so the SDK emits the `added_to_cart` flag;
+// the TV poll then flips the spot to the converted state.
+export function EnemAddToCartButton({
+  session,
+  client,
+  apiBase,
+  qty = 1,
+  label = "Add to Cart",
+  onAdded,
+  className,
+}: {
+  session: EnemSession | null;
+  client?: EnemCTV;
+  apiBase?: string;
+  qty?: number;
+  label?: string;
+  onAdded?: (s: EnemSession) => void;
+  className?: string;
+}) {
+  const [adding, setAdding] = useState(false);
+  const converted =
+    session?.status === "added_to_cart" || session?.status === "completed";
+  if (!session) return null;
+  if (converted) {
+    return (
+      <p className="inline-block rounded-full bg-emerald-500 px-3 py-1 text-xs font-bold text-white">
+        ✓ Added to cart
+      </p>
+    );
+  }
+  return (
+    <button
+      type="button"
+      disabled={adding}
+      onClick={async () => {
+        const c = client ?? new EnemCTV(apiBase ? { apiBase } : {});
+        setAdding(true);
+        try {
+          const res = await c.addToCart(session.id, { qty });
+          if (res.session) onAdded?.(res.session);
+        } finally {
+          setAdding(false);
+        }
+      }}
+      className={
+        className ??
+        "rounded-full bg-white px-6 py-2.5 text-sm font-bold text-black transition hover:bg-emerald-300 disabled:opacity-50"
+      }
+    >
+      {adding ? "Adding…" : label}
+    </button>
+  );
+}
+
+// ── Component: QR overlay for CTV (10-foot UI) ─────────────────────
+// Legacy phone-scan path. Prefer EnemAddToCartButton for remote-driven
+// spots — it raises the same `added_to_cart` SDK flag with no QR.
+export function EnemQROverlay({
+  session,
+  qrImageUrl,
+  position = "bottom-right",
+  theme = "dark",
+}: {
+  session: EnemSession | null;
+  qrImageUrl: string | null;
+  position?: "bottom-right" | "bottom-left" | "right";
+  theme?: "dark" | "light";
+}) {
+  if (!session || !qrImageUrl) return null;
+  const pos =
+    position === "bottom-left"
+      ? "left-6 bottom-6"
+      : position === "right"
+        ? "right-6 top-1/2 -translate-y-1/2"
+        : "right-6 bottom-6";
+  const converted = session.status === "added_to_cart" || session.status === "completed";
+  const scanned = session.status === "scanned" || session.status === "viewing" || converted;
+  return (
+    <div
+      className={`absolute ${pos} z-20 flex items-center gap-4 rounded-2xl p-4 shadow-2xl backdrop-blur ${
+        theme === "dark" ? "bg-black/70 text-white" : "bg-white/95 text-gray-900"
+      }`}
+    >
+      {/* eslint-disable-next-line @next/next/no-img-element */}
+      <img src={qrImageUrl} alt="Scan to shop" width={132} height={132} className="rounded-xl bg-white p-1" />
+      <div className="pr-2">
+        <p className="text-[11px] font-bold uppercase tracking-[0.2em] opacity-70">Shop this ad</p>
+        <p className="mt-1 max-w-[180px] truncate text-sm font-semibold">{session.product.title}</p>
+        <p className="text-sm opacity-80">{session.product.salePrice ?? session.product.price}</p>
+        {converted ? (
+          <p className="mt-2 inline-block rounded-full bg-emerald-500 px-3 py-1 text-xs font-bold text-white">
+            ✓ Added to cart
+          </p>
+        ) : scanned ? (
+          <p className="mt-2 inline-block rounded-full bg-sky-500 px-3 py-1 text-xs font-bold text-white">
+            ● Phone connected
+          </p>
+        ) : (
+          <p className="mt-2 text-xs opacity-80">
+            Scan with camera
+            <span className="ml-2 rounded bg-white/20 px-1.5 py-0.5 font-mono">{shortCode(session.id)}</span>
+          </p>
+        )}
+      </div>
+    </div>
+  );
+}
+
+// ── Component: minimal CTV player wrapper ─────────────────────────
+// Remote-first: shows Add to Cart (raises `added_to_cart` flag). Opt into
+// the legacy QR overlay with showQR.
+export function EnemCTVPlayer({
+  videoSrc,
+  product,
+  placementId,
+  campaignId,
+  apiBase,
+  showQR = false,
+  onConverted,
+}: {
+  videoSrc: string;
+  product: EnemProduct;
+  placementId?: string;
+  campaignId?: string;
+  apiBase?: string;
+  showQR?: boolean;
+  onConverted?: (s: EnemSession) => void;
+}) {
+  const { session, qrImageUrl } = useEnemShoppableAd(product, {
+    placementId,
+    campaignId,
+    apiBase,
+  });
+  const mobileUrl = session
+    ? buildQRImageUrl(session.mobileUrl) && session.mobileUrl
+    : null;
+
+  useEffect(() => {
+    if (
+      session &&
+      (session.status === "added_to_cart" || session.status === "completed")
+    )
+      onConverted?.(session);
+  }, [session, onConverted]);
+
+  return (
+    <div className="relative aspect-video w-full overflow-hidden rounded-2xl bg-black">
+      <video src={videoSrc} controls autoPlay muted loop playsInline className="h-full w-full object-cover" />
+      {showQR ? (
+        <EnemQROverlay session={session} qrImageUrl={qrImageUrl} />
+      ) : (
+        session && (
+          <div className="absolute bottom-6 right-6 z-20 rounded-2xl bg-black/70 p-4 text-white shadow-2xl backdrop-blur">
+            <EnemAddToCartButton session={session} apiBase={apiBase} />
+          </div>
+        )
+      )}
+      {mobileUrl && showQR ? (
+        <div className="absolute left-6 top-6 rounded-full bg-black/60 px-3 py-1 font-mono text-[11px] text-white/80">
+          {mobileUrl}
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/types.ts

@@ -0,0 +1,48 @@
+// Enem CTV SDK — shared types (framework agnostic)
+
+export interface EnemProduct {
+  id: string;
+  title: string;
+  brand?: string;
+  price: string; // e.g. "999 INR"
+  salePrice?: string;
+  imageUrl: string;
+  url?: string;
+  description?: string;
+}
+
+export type EnemSessionStatus =
+  | "created"
+  | "scanned"
+  | "viewing"
+  | "added_to_cart"
+  | "completed"
+  | "expired";
+
+export interface EnemSession {
+  id: string;
+  product: EnemProduct;
+  status: EnemSessionStatus;
+  placementId?: string;
+  campaignId?: string;
+  mobileUrl: string; // deep link phone opens after scan
+  cartCount: number;
+  scanCount: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface EnemCTVConfig {
+  /** 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;
+}
+
+export type EnemEvent =
+  | { type: "session_created"; session: EnemSession }
+  | { type: "session_updated"; session: EnemSession }
+  | { type: "scanned"; session: EnemSession }
+  | { type: "added_to_cart"; session: EnemSession };

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "skipLibCheck": true,
+    "jsx": "react-jsx",
+    "lib": ["ES2020", "DOM"],
+    "types": ["react"]
+  },
+  "include": ["src"]
+}