@likyly/react 0.0.0-stage → 0.2.1

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+# @likyly/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Show LIKYLY recommendations in a React app, with the impressions and clicks LIKYLY learns from
+tracked for you.
+
+The fastest way to set it up is the wizard, which installs this package, writes your public key
+and connects your AI coding assistant:
+
+```sh
+npx @likyly/wizard
+```
+
+## Install
+
+```sh
+npm install @likyly/react
+```
+
+React 18 or 19. Works with Next.js (App Router included), Vite, Remix and others.
+
+## Quick start
+
+```tsx
+import { LikylyProvider, LikylyRecommendations, useLikyly } from "@likyly/react";
+
+export function App() {
+  return (
+    <LikylyProvider apiKey={process.env.NEXT_PUBLIC_LIKYLY_KEY!}>
+      <ProductPage />
+    </LikylyProvider>
+  );
+}
+
+function ProductPage({ product, user }) {
+  const { session } = useLikyly();
+  return (
+    <LikylyRecommendations placement="pdp-related" itemId={product.id} limit={4}
+      userId={user?.id} sessionId={session.getAnonymousId()} />
+  );
+}
+```
+
+- `apiKey` is your **public key** (`pk_…`). A secret or developer key is refused in the browser.
+- `pdp-related` is a placement you create once in LIKYLY (console or AI assistant), not in code.
+- `sessionId` is the visitor's anonymous id, kept in the browser (first-party, no cookie). Pass it
+  so visitors who are not signed in count too.
+
+## Your own markup
+
+Keep your own cards; impressions and clicks are still tracked:
+
+```tsx
+<LikylyRecommendations
+  placement="pdp-related"
+  itemId={product.id}
+  renderItem={(item, { onClick }) => <ProductCard product={item} onClick={onClick} />}
+/>
+```
+
+Or take full control with the hook, and report what was seen and clicked:
+
+```tsx
+import { useLikyly, useRecommendations } from "@likyly/react";
+
+function Related({ product }) {
+  const { session } = useLikyly();
+  const { items, isLoading, trackImpression, trackClick } = useRecommendations({
+    placement: "pdp-related",
+    context: { itemId: product.id, sessionId: session.getAnonymousId() },
+    limit: 4,
+  });
+  if (isLoading) return null;
+  return items.map((item) => (
+    <ProductCard key={item.itemId} product={item}
+      onVisible={() => trackImpression(item.itemId)} onClick={() => trackClick(item.itemId)} />
+  ));
+}
+```
+
+## Other events
+
+Product views, add-to-cart and purchases happen in your own code, so send them from there:
+
+```ts
+const { client } = useLikyly();
+await client.events.productView({ itemId: product.id, userId: user?.id });
+await client.events.addToCart({ itemId: product.id, userId: user?.id, quantity: 1 });
+await client.events.purchase({ eventId: `purchase_${order.id}_${item.id}`, itemId: item.id, userId: user?.id,
+  quantity: item.quantity, properties: { price: item.price, currency: "EUR" } });
+```
+
+Set `eventId` on purchases: a retried purchase is then never counted twice.
+
+## Sign-in
+
+At sign-in, attach what the visitor did anonymously to their account:
+
+```tsx
+const { client, session } = useLikyly();
+await session.identify(client, user.id);
+```
+
+## Links
+
+- [`@likyly/sdk`](https://www.npmjs.com/package/@likyly/sdk): the JavaScript client this package is built on
+- [likyly.com](https://likyly.com)

package/dist/controller.d.ts

@@ -0,0 +1,46 @@
+import type { Likyly, PlacementContext, RecommendedItem } from "@likyly/sdk";
+/**
+ * Framework-agnostic state machine behind `useRecommendations` - kept separate from any React
+ * API on purpose: it's what makes the hook's fetch/race-condition/tracking logic testable with
+ * plain Node tests, no DOM or React renderer needed (see test/controller.test.ts). The hook
+ * itself (`use-recommendations.ts`) is a thin `useSyncExternalStore` wrapper around one instance
+ * of this per component.
+ */
+export interface RecommendationsControllerOptions {
+    placement: string;
+    context?: PlacementContext;
+    limit?: number;
+    /** Skip fetching - e.g. while a signal the placement needs (itemId, userId) isn't known yet. */
+    enabled?: boolean;
+}
+export interface RecommendationsState {
+    items: RecommendedItem[];
+    strategyUsed?: string;
+    recommendationId?: string;
+    isLoading: boolean;
+    error?: Error;
+}
+type TrackableLikyly = Pick<Likyly, "recommend" | "events">;
+export declare class RecommendationsController {
+    private readonly likyly;
+    private state;
+    private readonly listeners;
+    private lastPlacement;
+    private lastContext;
+    private generation;
+    private lastRequestKey;
+    constructor(likyly: TrackableLikyly);
+    getState(): RecommendationsState;
+    subscribe(listener: () => void): () => void;
+    private setState;
+    run(opts: RecommendationsControllerOptions): Promise<void>;
+    /** `recommendationImpression` for one rendered item, attributed to the last `recommend()`
+     * call - manual in headless mode (there's no DOM for LIKYLY to observe); `<LikylyRecommendations>`
+     * calls this automatically via IntersectionObserver. A no-op before the first result arrives,
+     * or if neither a user nor a session was in the context (nothing to attribute the event to). */
+    trackImpression(itemId: string): void;
+    /** `recommendationClick` for one item - same attribution/no-op rules as {@link trackImpression}. */
+    trackClick(itemId: string): void;
+    private trackRecommendationEvent;
+}
+export {};

package/dist/controller.js

@@ -0,0 +1,79 @@
+const INITIAL_STATE = { items: [], isLoading: false };
+export class RecommendationsController {
+    likyly;
+    state = INITIAL_STATE;
+    listeners = new Set();
+    lastPlacement;
+    lastContext;
+    // Bumped on every run() - a response for a superseded call (placement/context changed while
+    // it was in flight) is dropped instead of clobbering a newer, already-resolved state.
+    generation = 0;
+    // What the current items answer. A different request (another product, user, placement...)
+    // must not keep showing the previous answer while it loads - that flashed the last product's
+    // recommendations on the next product page. A refetch of the same request keeps them.
+    lastRequestKey;
+    constructor(likyly) {
+        this.likyly = likyly;
+    }
+    getState() {
+        return this.state;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    setState(patch) {
+        this.state = { ...this.state, ...patch };
+        for (const listener of this.listeners)
+            listener();
+    }
+    async run(opts) {
+        this.lastPlacement = opts.placement;
+        this.lastContext = opts.context;
+        if (opts.enabled === false) {
+            this.generation += 1; // invalidate any call still in flight from before enabled became false
+            this.lastRequestKey = undefined;
+            this.setState(INITIAL_STATE);
+            return;
+        }
+        const generation = ++this.generation;
+        const requestKey = JSON.stringify([opts.placement, opts.context ?? {}, opts.limit ?? null]);
+        const sameRequest = requestKey === this.lastRequestKey;
+        this.lastRequestKey = requestKey;
+        this.setState(sameRequest
+            ? { isLoading: true, error: undefined }
+            : { items: [], strategyUsed: undefined, recommendationId: undefined, isLoading: true, error: undefined });
+        try {
+            const result = await this.likyly.recommend({ placement: opts.placement, context: opts.context, limit: opts.limit });
+            if (generation !== this.generation)
+                return; // a newer call already started - drop this result
+            this.setState({ items: result.items, strategyUsed: result.strategyUsed, recommendationId: result.recommendationId, isLoading: false });
+        }
+        catch (error) {
+            if (generation !== this.generation)
+                return;
+            this.setState({ isLoading: false, error: error instanceof Error ? error : new Error(String(error)) });
+        }
+    }
+    /** `recommendationImpression` for one rendered item, attributed to the last `recommend()`
+     * call - manual in headless mode (there's no DOM for LIKYLY to observe); `<LikylyRecommendations>`
+     * calls this automatically via IntersectionObserver. A no-op before the first result arrives,
+     * or if neither a user nor a session was in the context (nothing to attribute the event to). */
+    trackImpression(itemId) {
+        this.trackRecommendationEvent("recommendationImpression", itemId);
+    }
+    /** `recommendationClick` for one item - same attribution/no-op rules as {@link trackImpression}. */
+    trackClick(itemId) {
+        this.trackRecommendationEvent("recommendationClick", itemId);
+    }
+    trackRecommendationEvent(method, itemId) {
+        const { recommendationId } = this.state;
+        if (!recommendationId || !this.lastPlacement)
+            return;
+        const userId = this.lastContext?.userId;
+        const sessionId = this.lastContext?.sessionId ?? this.lastContext?.anonymousId;
+        if (!userId && !sessionId)
+            return; // an event needs a user or a session - see @likyly/sdk's EventInput
+        void this.likyly.events[method]({ itemId, recommendationId, placement: this.lastPlacement, userId, sessionId });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { LikylyProvider, useLikyly } from "./provider.js";
+export type { LikylyContextValue, LikylyProviderProps } from "./provider.js";
+export { useRecommendations } from "./use-recommendations.js";
+export type { UseRecommendationsOptions, UseRecommendationsResult } from "./use-recommendations.js";
+export { LikylyRecommendations } from "./likyly-recommendations.js";
+export type { LikylyRecommendationsProps } from "./likyly-recommendations.js";
+export { RecommendationsController } from "./controller.js";
+export type { RecommendationsControllerOptions, RecommendationsState } from "./controller.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { LikylyProvider, useLikyly } from "./provider.js";
+export { useRecommendations } from "./use-recommendations.js";
+export { LikylyRecommendations } from "./likyly-recommendations.js";
+export { RecommendationsController } from "./controller.js";

package/dist/likyly-recommendations.d.ts

@@ -0,0 +1,45 @@
+import { type ReactNode } from "react";
+import type { RecommendedItem } from "@likyly/sdk";
+export interface LikylyRecommendationsProps {
+    /** The placement's slug, e.g. "pdp-related". */
+    placement: string;
+    itemId?: string;
+    userId?: string;
+    sessionId?: string;
+    anonymousId?: string;
+    categoryId?: string;
+    collectionId?: string;
+    cartItemIds?: string[];
+    limit?: number;
+    /** Skip fetching - e.g. while `itemId`/`userId` aren't known yet. Default true. */
+    enabled?: boolean;
+    /** Applied to the wrapping `<ul>` - the only styling hook when using the default markup. */
+    className?: string;
+    /**
+     * Full control over each card's markup - this component still fetches the data and
+     * auto-tracks impression/click, you own every pixel of the card itself. `onClick` fires
+     * `recommendationClick`; wire it to whatever element the visitor actually interacts with.
+     */
+    renderItem?: (item: RecommendedItem, helpers: {
+        onClick: () => void;
+    }) => ReactNode;
+    /** Rendered while the first request is in flight. */
+    loadingFallback?: ReactNode;
+    /** Rendered on a request error, or once loaded with zero items. Nothing, by default - a
+     * recommendations block that has nothing to show should usually just not be there. */
+    emptyFallback?: ReactNode;
+}
+/**
+ * Ready-to-use: fetches a placement's recommendations and renders them, auto-tracking
+ * `recommendationImpression` (via `IntersectionObserver` - fired when a card is actually seen,
+ * not merely fetched) and `recommendationClick`. Needs a `<LikylyProvider>` above it in the tree.
+ *
+ * ```tsx
+ * <LikylyRecommendations placement="pdp-related" itemId={product.id} userId={user?.id} limit={4} />
+ * ```
+ *
+ * `product_view`/`add_to_cart`/`purchase` are never tracked here - see docs/placements.md for
+ * why (this component can't reliably know when your own checkout completes) and the SDK
+ * helpers (`likyly.events.productView`/`addToCart`/`purchase`) for instrumenting them yourself.
+ */
+export declare function LikylyRecommendations({ placement, itemId, userId, sessionId, anonymousId, categoryId, collectionId, cartItemIds, limit, enabled, className, renderItem, loadingFallback, emptyFallback, }: LikylyRecommendationsProps): import("react").JSX.Element;

package/dist/likyly-recommendations.js

@@ -0,0 +1,62 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef } from "react";
+import { useRecommendations } from "./use-recommendations.js";
+/**
+ * Ready-to-use: fetches a placement's recommendations and renders them, auto-tracking
+ * `recommendationImpression` (via `IntersectionObserver` - fired when a card is actually seen,
+ * not merely fetched) and `recommendationClick`. Needs a `<LikylyProvider>` above it in the tree.
+ *
+ * ```tsx
+ * <LikylyRecommendations placement="pdp-related" itemId={product.id} userId={user?.id} limit={4} />
+ * ```
+ *
+ * `product_view`/`add_to_cart`/`purchase` are never tracked here - see docs/placements.md for
+ * why (this component can't reliably know when your own checkout completes) and the SDK
+ * helpers (`likyly.events.productView`/`addToCart`/`purchase`) for instrumenting them yourself.
+ */
+export function LikylyRecommendations({ placement, itemId, userId, sessionId, anonymousId, categoryId, collectionId, cartItemIds, limit, enabled, className, renderItem, loadingFallback = null, emptyFallback = null, }) {
+    const { items, isLoading, error, trackImpression, trackClick } = useRecommendations({
+        placement,
+        context: { itemId, userId, sessionId, anonymousId, categoryId, collectionId, cartItemIds },
+        limit,
+        enabled,
+    });
+    if (isLoading && items.length === 0)
+        return _jsx(_Fragment, { children: loadingFallback });
+    if (error || items.length === 0)
+        return _jsx(_Fragment, { children: emptyFallback });
+    return (_jsx("ul", { className: className, "data-likyly-placement": placement, children: items.map((item) => (_jsx(RecommendationCard, { item: item, renderItem: renderItem, onImpression: () => trackImpression(item.itemId), onClick: () => trackClick(item.itemId) }, item.itemId))) }));
+}
+function RecommendationCard({ item, renderItem, onImpression, onClick, }) {
+    const ref = useRef(null);
+    const trackedImpression = useRef(false);
+    useEffect(() => {
+        const el = ref.current;
+        if (!el || trackedImpression.current)
+            return;
+        // No IntersectionObserver (very old browsers, some SSR-adjacent test environments): fire
+        // once eagerly rather than never tracking the impression at all.
+        if (typeof IntersectionObserver === "undefined") {
+            trackedImpression.current = true;
+            onImpression();
+            return;
+        }
+        const observer = new IntersectionObserver((entries) => {
+            for (const entry of entries) {
+                if (entry.isIntersecting && !trackedImpression.current) {
+                    trackedImpression.current = true;
+                    onImpression();
+                    observer.disconnect();
+                }
+            }
+        }, { threshold: 0.5 });
+        observer.observe(el);
+        return () => observer.disconnect();
+        // onImpression is re-created each render (it closes over `item`) but always calls the same
+        // underlying tracked item - re-subscribing on every render would still only ever fire once
+        // thanks to trackedImpression, so omitting it from deps is deliberate, not a bug.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    return (_jsx("li", { ref: ref, "data-likyly-item-id": item.itemId, onClick: onClick, children: renderItem ? (renderItem(item, { onClick })) : (_jsxs("a", { href: typeof item.properties.url === "string" ? item.properties.url : undefined, children: [typeof item.properties.image === "string" ? _jsx("img", { src: item.properties.image, alt: item.title ?? "" }) : null, _jsx("div", { children: item.title }), item.properties.price !== undefined ? _jsx("div", { children: String(item.properties.price) }) : null] })) }));
+}

package/dist/provider.d.ts

@@ -0,0 +1,28 @@
+import { type ReactNode } from "react";
+import { Likyly, LikylySession, type LikylyOptions } from "@likyly/sdk";
+export interface LikylyProviderProps extends Pick<LikylyOptions, "apiKey" | "baseUrl" | "catalog"> {
+    children: ReactNode;
+    /** Namespaces the anonymous-session localStorage key - see @likyly/sdk's LikylySession. */
+    sessionStorageKey?: string;
+}
+export interface LikylyContextValue {
+    client: Likyly;
+    session: LikylySession;
+}
+/**
+ * Wrap your app (or the part of it that shows recommendations) once. `apiKey` must be your
+ * **restricted public key** - this runs in the browser, and `Likyly`'s own constructor refuses
+ * a secret/developer-shaped key there (see @likyly/sdk's README, "Which key?"). Never read it
+ * from a server-only env var by mistake.
+ *
+ * ```tsx
+ * <LikylyProvider apiKey={process.env.NEXT_PUBLIC_LIKYLY_KEY!}>
+ *   <ProductPage />
+ * </LikylyProvider>
+ * ```
+ */
+export declare function LikylyProvider({ apiKey, baseUrl, catalog, sessionStorageKey, children }: LikylyProviderProps): import("react").JSX.Element;
+/** The `Likyly` client and `LikylySession` this component tree's `<LikylyProvider>` holds -
+ * what `useRecommendations`/`<LikylyRecommendations>` use internally; call it yourself for
+ * anything else the SDK offers (`client.events.identify`, `session.getAnonymousId()`, ...). */
+export declare function useLikyly(): LikylyContextValue;

package/dist/provider.js

@@ -0,0 +1,37 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from "react";
+import { Likyly, LikylySession } from "@likyly/sdk";
+const LikylyContext = createContext(undefined);
+/**
+ * Wrap your app (or the part of it that shows recommendations) once. `apiKey` must be your
+ * **restricted public key** - this runs in the browser, and `Likyly`'s own constructor refuses
+ * a secret/developer-shaped key there (see @likyly/sdk's README, "Which key?"). Never read it
+ * from a server-only env var by mistake.
+ *
+ * ```tsx
+ * <LikylyProvider apiKey={process.env.NEXT_PUBLIC_LIKYLY_KEY!}>
+ *   <ProductPage />
+ * </LikylyProvider>
+ * ```
+ */
+export function LikylyProvider({ apiKey, baseUrl, catalog, sessionStorageKey, children }) {
+    const value = useMemo(() => ({
+        client: new Likyly({ apiKey, baseUrl, catalog, userAgent: "react" }),
+        session: new LikylySession({ storageKey: sessionStorageKey }),
+    }), 
+    // apiKey/baseUrl/catalog/sessionStorageKey are configuration, not per-render values - a real
+    // change (e.g. switching accounts at runtime) intentionally creates a fresh client/session.
+    [apiKey, baseUrl, catalog, sessionStorageKey]);
+    return _jsx(LikylyContext.Provider, { value: value, children: children });
+}
+/** The `Likyly` client and `LikylySession` this component tree's `<LikylyProvider>` holds -
+ * what `useRecommendations`/`<LikylyRecommendations>` use internally; call it yourself for
+ * anything else the SDK offers (`client.events.identify`, `session.getAnonymousId()`, ...). */
+export function useLikyly() {
+    const value = useContext(LikylyContext);
+    if (!value) {
+        throw new Error("useLikyly (and useRecommendations / <LikylyRecommendations>) must be used inside <LikylyProvider>");
+    }
+    return value;
+}

package/dist/test/src/controller.js

@@ -0,0 +1,79 @@
+const INITIAL_STATE = { items: [], isLoading: false };
+export class RecommendationsController {
+    likyly;
+    state = INITIAL_STATE;
+    listeners = new Set();
+    lastPlacement;
+    lastContext;
+    // Bumped on every run() - a response for a superseded call (placement/context changed while
+    // it was in flight) is dropped instead of clobbering a newer, already-resolved state.
+    generation = 0;
+    // What the current items answer. A different request (another product, user, placement...)
+    // must not keep showing the previous answer while it loads - that flashed the last product's
+    // recommendations on the next product page. A refetch of the same request keeps them.
+    lastRequestKey;
+    constructor(likyly) {
+        this.likyly = likyly;
+    }
+    getState() {
+        return this.state;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    setState(patch) {
+        this.state = { ...this.state, ...patch };
+        for (const listener of this.listeners)
+            listener();
+    }
+    async run(opts) {
+        this.lastPlacement = opts.placement;
+        this.lastContext = opts.context;
+        if (opts.enabled === false) {
+            this.generation += 1; // invalidate any call still in flight from before enabled became false
+            this.lastRequestKey = undefined;
+            this.setState(INITIAL_STATE);
+            return;
+        }
+        const generation = ++this.generation;
+        const requestKey = JSON.stringify([opts.placement, opts.context ?? {}, opts.limit ?? null]);
+        const sameRequest = requestKey === this.lastRequestKey;
+        this.lastRequestKey = requestKey;
+        this.setState(sameRequest
+            ? { isLoading: true, error: undefined }
+            : { items: [], strategyUsed: undefined, recommendationId: undefined, isLoading: true, error: undefined });
+        try {
+            const result = await this.likyly.recommend({ placement: opts.placement, context: opts.context, limit: opts.limit });
+            if (generation !== this.generation)
+                return; // a newer call already started - drop this result
+            this.setState({ items: result.items, strategyUsed: result.strategyUsed, recommendationId: result.recommendationId, isLoading: false });
+        }
+        catch (error) {
+            if (generation !== this.generation)
+                return;
+            this.setState({ isLoading: false, error: error instanceof Error ? error : new Error(String(error)) });
+        }
+    }
+    /** `recommendationImpression` for one rendered item, attributed to the last `recommend()`
+     * call - manual in headless mode (there's no DOM for LIKYLY to observe); `<LikylyRecommendations>`
+     * calls this automatically via IntersectionObserver. A no-op before the first result arrives,
+     * or if neither a user nor a session was in the context (nothing to attribute the event to). */
+    trackImpression(itemId) {
+        this.trackRecommendationEvent("recommendationImpression", itemId);
+    }
+    /** `recommendationClick` for one item - same attribution/no-op rules as {@link trackImpression}. */
+    trackClick(itemId) {
+        this.trackRecommendationEvent("recommendationClick", itemId);
+    }
+    trackRecommendationEvent(method, itemId) {
+        const { recommendationId } = this.state;
+        if (!recommendationId || !this.lastPlacement)
+            return;
+        const userId = this.lastContext?.userId;
+        const sessionId = this.lastContext?.sessionId ?? this.lastContext?.anonymousId;
+        if (!userId && !sessionId)
+            return; // an event needs a user or a session - see @likyly/sdk's EventInput
+        void this.likyly.events[method]({ itemId, recommendationId, placement: this.lastPlacement, userId, sessionId });
+    }
+}

package/dist/test/src/index.js

@@ -0,0 +1,4 @@
+export { LikylyProvider, useLikyly } from "./provider.js";
+export { useRecommendations } from "./use-recommendations.js";
+export { LikylyRecommendations } from "./likyly-recommendations.js";
+export { RecommendationsController } from "./controller.js";

package/dist/test/src/likyly-recommendations.js

@@ -0,0 +1,62 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef } from "react";
+import { useRecommendations } from "./use-recommendations.js";
+/**
+ * Ready-to-use: fetches a placement's recommendations and renders them, auto-tracking
+ * `recommendationImpression` (via `IntersectionObserver` - fired when a card is actually seen,
+ * not merely fetched) and `recommendationClick`. Needs a `<LikylyProvider>` above it in the tree.
+ *
+ * ```tsx
+ * <LikylyRecommendations placement="pdp-related" itemId={product.id} userId={user?.id} limit={4} />
+ * ```
+ *
+ * `product_view`/`add_to_cart`/`purchase` are never tracked here - see docs/placements.md for
+ * why (this component can't reliably know when your own checkout completes) and the SDK
+ * helpers (`likyly.events.productView`/`addToCart`/`purchase`) for instrumenting them yourself.
+ */
+export function LikylyRecommendations({ placement, itemId, userId, sessionId, anonymousId, categoryId, collectionId, cartItemIds, limit, enabled, className, renderItem, loadingFallback = null, emptyFallback = null, }) {
+    const { items, isLoading, error, trackImpression, trackClick } = useRecommendations({
+        placement,
+        context: { itemId, userId, sessionId, anonymousId, categoryId, collectionId, cartItemIds },
+        limit,
+        enabled,
+    });
+    if (isLoading && items.length === 0)
+        return _jsx(_Fragment, { children: loadingFallback });
+    if (error || items.length === 0)
+        return _jsx(_Fragment, { children: emptyFallback });
+    return (_jsx("ul", { className: className, "data-likyly-placement": placement, children: items.map((item) => (_jsx(RecommendationCard, { item: item, renderItem: renderItem, onImpression: () => trackImpression(item.itemId), onClick: () => trackClick(item.itemId) }, item.itemId))) }));
+}
+function RecommendationCard({ item, renderItem, onImpression, onClick, }) {
+    const ref = useRef(null);
+    const trackedImpression = useRef(false);
+    useEffect(() => {
+        const el = ref.current;
+        if (!el || trackedImpression.current)
+            return;
+        // No IntersectionObserver (very old browsers, some SSR-adjacent test environments): fire
+        // once eagerly rather than never tracking the impression at all.
+        if (typeof IntersectionObserver === "undefined") {
+            trackedImpression.current = true;
+            onImpression();
+            return;
+        }
+        const observer = new IntersectionObserver((entries) => {
+            for (const entry of entries) {
+                if (entry.isIntersecting && !trackedImpression.current) {
+                    trackedImpression.current = true;
+                    onImpression();
+                    observer.disconnect();
+                }
+            }
+        }, { threshold: 0.5 });
+        observer.observe(el);
+        return () => observer.disconnect();
+        // onImpression is re-created each render (it closes over `item`) but always calls the same
+        // underlying tracked item - re-subscribing on every render would still only ever fire once
+        // thanks to trackedImpression, so omitting it from deps is deliberate, not a bug.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    return (_jsx("li", { ref: ref, "data-likyly-item-id": item.itemId, onClick: onClick, children: renderItem ? (renderItem(item, { onClick })) : (_jsxs("a", { href: typeof item.properties.url === "string" ? item.properties.url : undefined, children: [typeof item.properties.image === "string" ? _jsx("img", { src: item.properties.image, alt: item.title ?? "" }) : null, _jsx("div", { children: item.title }), item.properties.price !== undefined ? _jsx("div", { children: String(item.properties.price) }) : null] })) }));
+}

package/dist/test/src/provider.js

@@ -0,0 +1,37 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from "react";
+import { Likyly, LikylySession } from "@likyly/sdk";
+const LikylyContext = createContext(undefined);
+/**
+ * Wrap your app (or the part of it that shows recommendations) once. `apiKey` must be your
+ * **restricted public key** - this runs in the browser, and `Likyly`'s own constructor refuses
+ * a secret/developer-shaped key there (see @likyly/sdk's README, "Which key?"). Never read it
+ * from a server-only env var by mistake.
+ *
+ * ```tsx
+ * <LikylyProvider apiKey={process.env.NEXT_PUBLIC_LIKYLY_KEY!}>
+ *   <ProductPage />
+ * </LikylyProvider>
+ * ```
+ */
+export function LikylyProvider({ apiKey, baseUrl, catalog, sessionStorageKey, children }) {
+    const value = useMemo(() => ({
+        client: new Likyly({ apiKey, baseUrl, catalog, userAgent: "react" }),
+        session: new LikylySession({ storageKey: sessionStorageKey }),
+    }), 
+    // apiKey/baseUrl/catalog/sessionStorageKey are configuration, not per-render values - a real
+    // change (e.g. switching accounts at runtime) intentionally creates a fresh client/session.
+    [apiKey, baseUrl, catalog, sessionStorageKey]);
+    return _jsx(LikylyContext.Provider, { value: value, children: children });
+}
+/** The `Likyly` client and `LikylySession` this component tree's `<LikylyProvider>` holds -
+ * what `useRecommendations`/`<LikylyRecommendations>` use internally; call it yourself for
+ * anything else the SDK offers (`client.events.identify`, `session.getAnonymousId()`, ...). */
+export function useLikyly() {
+    const value = useContext(LikylyContext);
+    if (!value) {
+        throw new Error("useLikyly (and useRecommendations / <LikylyRecommendations>) must be used inside <LikylyProvider>");
+    }
+    return value;
+}

package/dist/test/src/use-recommendations.js

@@ -0,0 +1,46 @@
+"use client";
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import { RecommendationsController } from "./controller.js";
+import { useLikyly } from "./provider.js";
+/**
+ * Headless: fetches recommendations for one placement and returns the data plus tracking
+ * helpers - you render 100% of the markup. See `<LikylyRecommendations>` for a ready-to-use
+ * component that also auto-tracks impressions/clicks.
+ *
+ * ```tsx
+ * const { items, isLoading, trackClick } = useRecommendations({
+ *   placement: "pdp-related",
+ *   context: { itemId: product.id, userId: user?.id, sessionId },
+ * });
+ * ```
+ */
+export function useRecommendations(opts) {
+    const { client } = useLikyly();
+    const controllerRef = useRef(null);
+    if (!controllerRef.current)
+        controllerRef.current = new RecommendationsController(client);
+    const controller = controllerRef.current;
+    // Third argument (getServerSnapshot) is required for SSR/SSG (Next.js prerendering, ...) -
+    // without it React throws ("Missing getServerSnapshot") the moment this hook is reached
+    // during a server render. Safe to reuse the same getSnapshot here: run() only ever executes
+    // from the effect below, which never runs during a server render, so the controller's state
+    // is still the untouched initial one (a stable reference) at that point.
+    const state = useSyncExternalStore((onStoreChange) => controller.subscribe(onStoreChange), () => controller.getState(), () => controller.getState());
+    // Compared by value, not identity: `context` is a fresh object literal on most callers' every
+    // render, and re-fetching on every render (rather than on an actual change) would defeat the
+    // point of the hook.
+    const contextKey = JSON.stringify(opts.context ?? {});
+    const runCurrent = () => void controller.run(opts);
+    useEffect(() => {
+        runCurrent();
+        // contextKey stands in for opts.context; opts.placement/limit/enabled are the other real
+        // inputs - this intentionally does not depend on the `opts` object identity itself.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [controller, opts.placement, contextKey, opts.limit, opts.enabled]);
+    return {
+        ...state,
+        refetch: runCurrent,
+        trackImpression: (itemId) => controller.trackImpression(itemId),
+        trackClick: (itemId) => controller.trackClick(itemId),
+    };
+}

package/dist/test/test/controller.test.js

@@ -0,0 +1,123 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { RecommendationsController } from "../src/controller.js";
+function fakeLikyly(recommendImpl) {
+    const eventCalls = [];
+    const client = {
+        recommend: (call) => recommendImpl(call),
+        events: {
+            recommendationImpression: async (input) => {
+                eventCalls.push({ method: "recommendationImpression", input });
+                return { message: "ok", duplicate: false };
+            },
+            recommendationClick: async (input) => {
+                eventCalls.push({ method: "recommendationClick", input });
+                return { message: "ok", duplicate: false };
+            },
+        },
+    };
+    return { client, eventCalls };
+}
+const RESULT = { recommendationId: "rec_1", placement: "pdp-related", strategyUsed: "content", items: [{ itemId: "SKU-1", properties: {} }] };
+describe("RecommendationsController", () => {
+    it("a new product never shows the previous product's items while loading; a refetch keeps them", async () => {
+        const { client } = fakeLikyly(async () => RESULT);
+        const controller = new RecommendationsController(client);
+        await controller.run({ placement: "pdp-related", context: { itemId: "SKU-1" } });
+        assert.equal(controller.getState().items.length, 1);
+        const next = controller.run({ placement: "pdp-related", context: { itemId: "SKU-2" } });
+        assert.deepEqual(controller.getState().items, [], "cleared as soon as the product changes");
+        assert.equal(controller.getState().recommendationId, undefined);
+        await next;
+        const again = controller.run({ placement: "pdp-related", context: { itemId: "SKU-2" } });
+        assert.equal(controller.getState().items.length, 1, "same request: kept while it refreshes");
+        await again;
+    });
+    it("starts idle, then loading, then resolved", async () => {
+        const { client } = fakeLikyly(async () => RESULT);
+        const controller = new RecommendationsController(client);
+        assert.deepEqual(controller.getState(), { items: [], isLoading: false });
+        const pending = controller.run({ placement: "pdp-related", context: { itemId: "SKU-1" } });
+        assert.equal(controller.getState().isLoading, true);
+        await pending;
+        assert.equal(controller.getState().isLoading, false);
+        assert.equal(controller.getState().strategyUsed, "content");
+        assert.equal(controller.getState().recommendationId, "rec_1");
+        assert.equal(controller.getState().items.length, 1);
+    });
+    it("notifies subscribers on every state change", async () => {
+        const { client } = fakeLikyly(async () => RESULT);
+        const controller = new RecommendationsController(client);
+        let notifications = 0;
+        const unsubscribe = controller.subscribe(() => (notifications += 1));
+        await controller.run({ placement: "pdp-related" });
+        assert.ok(notifications >= 2); // at least: loading=true, then resolved
+        unsubscribe();
+        const before = notifications;
+        await controller.run({ placement: "pdp-related" });
+        assert.equal(notifications, before); // unsubscribed - no more notifications
+    });
+    it("enabled: false resets to idle and never calls recommend", async () => {
+        let calls = 0;
+        const { client } = fakeLikyly(async () => {
+            calls += 1;
+            return RESULT;
+        });
+        const controller = new RecommendationsController(client);
+        await controller.run({ placement: "pdp-related", enabled: false });
+        assert.equal(calls, 0);
+        assert.deepEqual(controller.getState(), { items: [], isLoading: false });
+    });
+    it("a superseded call's response is dropped, not applied", async () => {
+        const resolvers = [];
+        const { client } = fakeLikyly(() => new Promise((resolve) => resolvers.push(resolve)));
+        const controller = new RecommendationsController(client);
+        const first = controller.run({ placement: "pdp-related", context: { itemId: "SKU-1" } });
+        const second = controller.run({ placement: "pdp-related", context: { itemId: "SKU-2" } });
+        resolvers[1]({ ...RESULT, recommendationId: "rec_second" });
+        await second;
+        resolvers[0]({ ...RESULT, recommendationId: "rec_first" });
+        await first;
+        assert.equal(controller.getState().recommendationId, "rec_second"); // the first (stale) response never overwrote it
+    });
+    it("a rejected recommend() call surfaces as state.error, not a thrown exception", async () => {
+        const { client } = fakeLikyly(async () => {
+            throw new Error("network down");
+        });
+        const controller = new RecommendationsController(client);
+        await controller.run({ placement: "pdp-related" });
+        assert.equal(controller.getState().error?.message, "network down");
+        assert.equal(controller.getState().isLoading, false);
+    });
+    it("trackImpression/trackClick send the right event, attributed to the last recommend() call", async () => {
+        const { client, eventCalls } = fakeLikyly(async () => RESULT);
+        const controller = new RecommendationsController(client);
+        await controller.run({ placement: "pdp-related", context: { itemId: "SKU-1", sessionId: "sess_1" } });
+        controller.trackImpression("SKU-1");
+        controller.trackClick("SKU-1");
+        assert.deepEqual(eventCalls, [
+            { method: "recommendationImpression", input: { itemId: "SKU-1", recommendationId: "rec_1", placement: "pdp-related", userId: undefined, sessionId: "sess_1" } },
+            { method: "recommendationClick", input: { itemId: "SKU-1", recommendationId: "rec_1", placement: "pdp-related", userId: undefined, sessionId: "sess_1" } },
+        ]);
+    });
+    it("tracking is a no-op before any result has arrived (nothing to attribute to yet)", async () => {
+        const { client, eventCalls } = fakeLikyly(async () => RESULT);
+        const controller = new RecommendationsController(client);
+        controller.trackImpression("SKU-1");
+        assert.equal(eventCalls.length, 0);
+    });
+    it("tracking is a no-op with neither a userId nor a sessionId in the context", async () => {
+        const { client, eventCalls } = fakeLikyly(async () => RESULT);
+        const controller = new RecommendationsController(client);
+        await controller.run({ placement: "pdp-related", context: { itemId: "SKU-1" } }); // no user/session
+        controller.trackClick("SKU-1");
+        assert.equal(eventCalls.length, 0);
+    });
+    it("anonymousId in the context is used as the session for attribution when sessionId is absent", async () => {
+        const { client, eventCalls } = fakeLikyly(async () => RESULT);
+        const controller = new RecommendationsController(client);
+        await controller.run({ placement: "pdp-related", context: { itemId: "SKU-1", anonymousId: "anon_1" } });
+        controller.trackClick("SKU-1");
+        assert.equal(eventCalls[0].input.sessionId, "anon_1");
+    });
+});

package/dist/test/test/ssr.test.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import assert from "node:assert/strict";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, it } from "node:test";
+import { LikylyProvider, LikylyRecommendations, useRecommendations } from "../src/index.js";
+// Regression test for a real bug found while integrating @likyly/react into a Next.js app
+// (examples/demo-storefront): `useSyncExternalStore` without a third (getServerSnapshot)
+// argument throws "Missing getServerSnapshot" the moment a page using this hook is
+// server-rendered/statically generated - `next dev` alone never catches this, since it only
+// ever renders these components client-side; `next build`'s static generation does.
+describe("server-side rendering", () => {
+    it("useRecommendations does not throw during a server render", () => {
+        function Probe() {
+            const { isLoading, items } = useRecommendations({ placement: "pdp-related", context: { itemId: "SKU-1" } });
+            return _jsx("div", { children: `${isLoading} ${items.length}` });
+        }
+        const html = renderToStaticMarkup(_jsx(LikylyProvider, { apiKey: "pk_test_ssr", children: _jsx(Probe, {}) }));
+        assert.match(html, /<div>/);
+    });
+    it("<LikylyRecommendations> does not throw during a server render", () => {
+        const html = renderToStaticMarkup(_jsx(LikylyProvider, { apiKey: "pk_test_ssr", children: _jsx(LikylyRecommendations, { placement: "pdp-related", itemId: "SKU-1" }) }));
+        assert.equal(typeof html, "string"); // isLoading, 0 items on first render -> renders its loadingFallback (null)
+    });
+});

package/dist/use-recommendations.d.ts

@@ -0,0 +1,34 @@
+import type { PlacementContext } from "@likyly/sdk";
+import { type RecommendationsState } from "./controller.js";
+export interface UseRecommendationsOptions {
+    /** The placement's slug, e.g. "pdp-related" - configure it once via the LIKYLY MCP admin
+     * tools or dashboard, not from this hook. */
+    placement: string;
+    context?: PlacementContext;
+    /** Overrides the placement's own configured limit for this call. */
+    limit?: number;
+    /** Skip fetching - e.g. while a signal the placement needs (itemId, userId) isn't known yet. Default true. */
+    enabled?: boolean;
+}
+export interface UseRecommendationsResult extends RecommendationsState {
+    /** Re-runs the same request (e.g. a manual "refresh" action). */
+    refetch: () => void;
+    /** Fire `recommendationImpression` for one of the returned items - manual here, since a
+     * headless hook has no DOM for LIKYLY to observe; `<LikylyRecommendations>` does this for you. */
+    trackImpression: (itemId: string) => void;
+    /** Fire `recommendationClick` for one of the returned items. */
+    trackClick: (itemId: string) => void;
+}
+/**
+ * Headless: fetches recommendations for one placement and returns the data plus tracking
+ * helpers - you render 100% of the markup. See `<LikylyRecommendations>` for a ready-to-use
+ * component that also auto-tracks impressions/clicks.
+ *
+ * ```tsx
+ * const { items, isLoading, trackClick } = useRecommendations({
+ *   placement: "pdp-related",
+ *   context: { itemId: product.id, userId: user?.id, sessionId },
+ * });
+ * ```
+ */
+export declare function useRecommendations(opts: UseRecommendationsOptions): UseRecommendationsResult;

package/dist/use-recommendations.js

@@ -0,0 +1,46 @@
+"use client";
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import { RecommendationsController } from "./controller.js";
+import { useLikyly } from "./provider.js";
+/**
+ * Headless: fetches recommendations for one placement and returns the data plus tracking
+ * helpers - you render 100% of the markup. See `<LikylyRecommendations>` for a ready-to-use
+ * component that also auto-tracks impressions/clicks.
+ *
+ * ```tsx
+ * const { items, isLoading, trackClick } = useRecommendations({
+ *   placement: "pdp-related",
+ *   context: { itemId: product.id, userId: user?.id, sessionId },
+ * });
+ * ```
+ */
+export function useRecommendations(opts) {
+    const { client } = useLikyly();
+    const controllerRef = useRef(null);
+    if (!controllerRef.current)
+        controllerRef.current = new RecommendationsController(client);
+    const controller = controllerRef.current;
+    // Third argument (getServerSnapshot) is required for SSR/SSG (Next.js prerendering, ...) -
+    // without it React throws ("Missing getServerSnapshot") the moment this hook is reached
+    // during a server render. Safe to reuse the same getSnapshot here: run() only ever executes
+    // from the effect below, which never runs during a server render, so the controller's state
+    // is still the untouched initial one (a stable reference) at that point.
+    const state = useSyncExternalStore((onStoreChange) => controller.subscribe(onStoreChange), () => controller.getState(), () => controller.getState());
+    // Compared by value, not identity: `context` is a fresh object literal on most callers' every
+    // render, and re-fetching on every render (rather than on an actual change) would defeat the
+    // point of the hook.
+    const contextKey = JSON.stringify(opts.context ?? {});
+    const runCurrent = () => void controller.run(opts);
+    useEffect(() => {
+        runCurrent();
+        // contextKey stands in for opts.context; opts.placement/limit/enabled are the other real
+        // inputs - this intentionally does not depend on the `opts` object identity itself.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [controller, opts.placement, contextKey, opts.limit, opts.enabled]);
+    return {
+        ...state,
+        refetch: runCurrent,
+        trackImpression: (itemId) => controller.trackImpression(itemId),
+        trackClick: (itemId) => controller.trackClick(itemId),
+    };
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@likyly/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "React bindings for @likyly/sdk: useRecommendations (headless) and <LikylyRecommendations> (ready-to-use) for LIKYLY placements.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.test.json --noEmit",
+    "test": "rm -rf dist/test && tsc -p tsconfig.test.json && node --test \"dist/test/test/*.test.js\""
+  },
+  "dependencies": {
+    "@likyly/sdk": "^1.1.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "typescript": "^5.5.4"
+  }
+}