@likyly/sdk 0.0.0-stage → 1.1.1

package/dist/cjs/http.d.ts

@@ -0,0 +1,49 @@
+import type { RequestOptions } from "./types.js";
+export interface HttpConfig {
+    apiKey: string;
+    baseUrl: string;
+    catalog?: string;
+    timeout: number;
+    maxRetries: number;
+    userAgent: string;
+    fetch: typeof fetch;
+    /** Test hooks - not part of the public API. */
+    sleep: (ms: number) => Promise<void>;
+    random: () => number;
+}
+export interface HttpRequest {
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    /** Path already percent-encoded, starting with "/". */
+    path: string;
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    /**
+     * Safe to send again if the outcome is unknown (a timeout, a 5xx, a dropped connection)? True for
+     * reads, PUT/DELETE and the upserts; false for events without an `eventId`, where a blind retry
+     * could record the event twice.
+     */
+    idempotent: boolean;
+    options?: RequestOptions;
+}
+export interface HttpResponse<T> {
+    data: T;
+    status: number;
+    headers: Headers;
+    requestId?: string;
+}
+/**
+ * The only place that talks HTTP. Every resource goes through `request()`: auth header, catalog
+ * parameter, timeout, retries with exponential backoff + jitter, and the error mapping.
+ */
+export declare class HttpClient {
+    private readonly config;
+    constructor(config: HttpConfig);
+    request<T>(req: HttpRequest): Promise<HttpResponse<T>>;
+    /** Milliseconds to wait before the next attempt, or undefined if this failure must not be retried. */
+    private retryDelay;
+    private buildUrl;
+    private attempt;
+}
+/** Retry-After is either a number of seconds or an HTTP date. */
+export declare function parseRetryAfter(value: string | null): number | undefined;
+export declare function assertNonEmptyObject(value: unknown, name: string): asserts value is Record<string, unknown>;

package/dist/cjs/http.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpClient = void 0;
+exports.parseRetryAfter = parseRetryAfter;
+exports.assertNonEmptyObject = assertNonEmptyObject;
+const errors_js_1 = require("./errors.js");
+const RETRY_BASE_MS = 500;
+const RETRY_CAP_MS = 8_000;
+/** A Retry-After longer than this is not waited for: the RateLimitError is thrown instead. */
+const MAX_RETRY_AFTER_MS = 60_000;
+/**
+ * The only place that talks HTTP. Every resource goes through `request()`: auth header, catalog
+ * parameter, timeout, retries with exponential backoff + jitter, and the error mapping.
+ */
+class HttpClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async request(req) {
+        const maxRetries = req.options?.maxRetries ?? this.config.maxRetries;
+        const url = this.buildUrl(req);
+        let attempt = 0;
+        for (;;) {
+            let failure;
+            try {
+                return await this.attempt(req, url);
+            }
+            catch (error) {
+                if (!(error instanceof errors_js_1.LikylyError))
+                    throw error; // e.g. the caller's own AbortError
+                failure = error;
+            }
+            const delay = this.retryDelay(failure, attempt, req.idempotent);
+            if (delay === undefined || attempt >= maxRetries)
+                throw failure;
+            attempt += 1;
+            await this.config.sleep(delay);
+        }
+    }
+    /** Milliseconds to wait before the next attempt, or undefined if this failure must not be retried. */
+    retryDelay(error, attempt, idempotent) {
+        const backoff = () => this.config.random() * Math.min(RETRY_CAP_MS, RETRY_BASE_MS * 2 ** attempt); // full jitter
+        if (error.statusCode === 429) {
+            // Rejected by the rate limiter before reaching the application: nothing was processed, so
+            // retrying is safe for every request.
+            if (error.retryAfter !== undefined) {
+                const wait = error.retryAfter * 1000;
+                return wait <= MAX_RETRY_AFTER_MS ? wait : undefined;
+            }
+            return backoff();
+        }
+        if (!idempotent)
+            return undefined; // the outcome is unknown - never risk a duplicate
+        if (error.statusCode === 502 || error.statusCode === 503 || error.statusCode === 504) {
+            if (error.retryAfter !== undefined) {
+                const wait = error.retryAfter * 1000;
+                return wait <= MAX_RETRY_AFTER_MS ? wait : undefined;
+            }
+            return backoff();
+        }
+        if (error instanceof errors_js_1.NetworkError || error instanceof errors_js_1.TimeoutError)
+            return backoff();
+        return undefined;
+    }
+    buildUrl(req) {
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(req.query ?? {})) {
+            if (value !== undefined)
+                params.set(key, String(value));
+        }
+        if (this.config.catalog)
+            params.set("data_product_type", this.config.catalog);
+        const qs = params.toString();
+        return this.config.baseUrl + req.path + (qs ? `?${qs}` : "");
+    }
+    async attempt(req, url) {
+        const timeoutMs = req.options?.timeout ?? this.config.timeout;
+        const controller = new AbortController();
+        const userSignal = req.options?.signal;
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, timeoutMs);
+        const onUserAbort = () => controller.abort();
+        if (userSignal) {
+            if (userSignal.aborted)
+                controller.abort();
+            else
+                userSignal.addEventListener("abort", onUserAbort, { once: true });
+        }
+        const headers = {
+            "X-API-Key": this.config.apiKey,
+            Accept: "application/json",
+            "User-Agent": this.config.userAgent,
+        };
+        if (req.body !== undefined)
+            headers["Content-Type"] = "application/json";
+        let response;
+        try {
+            response = await this.config.fetch(url, {
+                method: req.method,
+                headers,
+                body: req.body !== undefined ? JSON.stringify(req.body) : undefined,
+                signal: controller.signal,
+            });
+        }
+        catch (cause) {
+            if (timedOut)
+                throw new errors_js_1.TimeoutError(`LIKYLY request timed out after ${timeoutMs} ms`, { cause });
+            if (userSignal?.aborted)
+                throw cause; // the caller cancelled: surface their AbortError untouched
+            throw new errors_js_1.NetworkError(`Could not reach the LIKYLY API: ${cause?.message ?? cause}`, { cause });
+        }
+        finally {
+            clearTimeout(timer);
+            userSignal?.removeEventListener("abort", onUserAbort);
+        }
+        const text = await response.text().catch(() => "");
+        let data = undefined;
+        if (text) {
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                data = text; // e.g. an HTML 502 page from a proxy
+            }
+        }
+        const requestId = response.headers.get("x-request-id") ??
+            (data && typeof data === "object" && "request_id" in data ? String(data.request_id) : undefined);
+        if (!response.ok) {
+            throw (0, errors_js_1.errorFromResponse)(response.status, data, requestId ?? undefined, parseRetryAfter(response.headers.get("retry-after")));
+        }
+        return { data: data, status: response.status, headers: response.headers, requestId: requestId ?? undefined };
+    }
+}
+exports.HttpClient = HttpClient;
+/** Retry-After is either a number of seconds or an HTTP date. */
+function parseRetryAfter(value) {
+    if (!value)
+        return undefined;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return seconds;
+    const date = Date.parse(value);
+    if (!Number.isNaN(date))
+        return Math.max(0, Math.ceil((date - Date.now()) / 1000));
+    return undefined;
+}
+function assertNonEmptyObject(value, name) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new errors_js_1.ValidationError(`${name} must be an object`);
+    }
+}

package/dist/cjs/index.d.ts

@@ -0,0 +1,8 @@
+export { Likyly } from "./client.js";
+export type { LikylyOptions } from "./client.js";
+export { LikylySession } from "./session.js";
+export type { LikylySessionOptions } from "./session.js";
+export { LikylyError, ApiError, AuthenticationError, PermissionDeniedError, NotFoundError, RateLimitError, ValidationError, NetworkError, TimeoutError, PausedError, } from "./errors.js";
+export type { RecommendCacheOptions } from "./recommend-cache.js";
+export { SDK_VERSION } from "./version.js";
+export type * from "./types.js";

package/dist/cjs/index.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_VERSION = exports.PausedError = exports.TimeoutError = exports.NetworkError = exports.ValidationError = exports.RateLimitError = exports.NotFoundError = exports.PermissionDeniedError = exports.AuthenticationError = exports.ApiError = exports.LikylyError = exports.LikylySession = exports.Likyly = void 0;
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "Likyly", { enumerable: true, get: function () { return client_js_1.Likyly; } });
+var session_js_1 = require("./session.js");
+Object.defineProperty(exports, "LikylySession", { enumerable: true, get: function () { return session_js_1.LikylySession; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "LikylyError", { enumerable: true, get: function () { return errors_js_1.LikylyError; } });
+Object.defineProperty(exports, "ApiError", { enumerable: true, get: function () { return errors_js_1.ApiError; } });
+Object.defineProperty(exports, "AuthenticationError", { enumerable: true, get: function () { return errors_js_1.AuthenticationError; } });
+Object.defineProperty(exports, "PermissionDeniedError", { enumerable: true, get: function () { return errors_js_1.PermissionDeniedError; } });
+Object.defineProperty(exports, "NotFoundError", { enumerable: true, get: function () { return errors_js_1.NotFoundError; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return errors_js_1.RateLimitError; } });
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return errors_js_1.ValidationError; } });
+Object.defineProperty(exports, "NetworkError", { enumerable: true, get: function () { return errors_js_1.NetworkError; } });
+Object.defineProperty(exports, "TimeoutError", { enumerable: true, get: function () { return errors_js_1.TimeoutError; } });
+Object.defineProperty(exports, "PausedError", { enumerable: true, get: function () { return errors_js_1.PausedError; } });
+var version_js_1 = require("./version.js");
+Object.defineProperty(exports, "SDK_VERSION", { enumerable: true, get: function () { return version_js_1.SDK_VERSION; } });

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/recommend-cache.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Client-side protection for `placements.recommend`, so a page does not call LIKYLY on every
+ * view and does not keep hammering it when it is down:
+ *
+ * - a cache: an answer is reused for `ttlSeconds` (default one hour) for the same placement,
+ *   item and visitor. In a browser it lives in `sessionStorage` (one visitor's tab session:
+ *   back/forward and revisits cost nothing); elsewhere (SSR, Node) in memory. A reused answer
+ *   keeps its `recommendationId`, so impressions and clicks stay attributed.
+ * - a circuit breaker: after a network error, a timeout or a 5xx, calls fail at once for
+ *   `pauseSeconds` (default 30) instead of waiting on LIKYLY, so the page shows its own
+ *   fallback straight away. The next call after the pause tries again.
+ */
+import type { PlacementRecommendResponse } from "./types.js";
+export interface RecommendCacheOptions {
+    /** How long an answer is reused, in seconds. Default 3600. */
+    ttlSeconds?: number;
+    /** After LIKYLY fails, how long to skip calls, in seconds. Default 30. Set 0 to always call. */
+    pauseSeconds?: number;
+    /** Where answers are kept. Default: "session" in a browser (sessionStorage), "memory" elsewhere. */
+    storage?: "session" | "memory";
+}
+export declare class RecommendCache {
+    private readonly now;
+    private readonly ttlMs;
+    private readonly pauseMs;
+    private readonly storage;
+    private readonly memory;
+    private pausedUntil;
+    constructor(options?: RecommendCacheOptions, now?: () => number);
+    get(key: string): PlacementRecommendResponse | null;
+    set(key: string, value: PlacementRecommendResponse): void;
+    /** Drop every cached answer of this client (e.g. after a purge in the LIKYLY console). */
+    clear(): void;
+    /** True while calls are paused after a failure. */
+    isPaused(): boolean;
+    /** Seconds left in the pause (0 when not paused). */
+    pauseRemaining(): number;
+    recordFailure(): void;
+    recordSuccess(): void;
+    private read;
+    private remove;
+}

package/dist/cjs/recommend-cache.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecommendCache = void 0;
+const PREFIX = "likyly:rec:";
+const MAX_MEMORY_ENTRIES = 500;
+function browserStorage() {
+    try {
+        const storage = globalThis.sessionStorage;
+        if (!storage)
+            return null;
+        storage.getItem(PREFIX); // throws where storage is blocked (privacy settings, sandboxed frames)
+        return storage;
+    }
+    catch {
+        return null;
+    }
+}
+class RecommendCache {
+    now;
+    ttlMs;
+    pauseMs;
+    storage;
+    memory = new Map();
+    pausedUntil = 0;
+    constructor(options = {}, now = Date.now) {
+        this.now = now;
+        this.ttlMs = Math.max(0, options.ttlSeconds ?? 3600) * 1000;
+        this.pauseMs = Math.max(0, options.pauseSeconds ?? 30) * 1000;
+        this.storage = options.storage === "memory" ? null : browserStorage();
+    }
+    get(key) {
+        if (this.ttlMs === 0)
+            return null;
+        const entry = this.read(key);
+        if (!entry)
+            return null;
+        if (entry.expires <= this.now()) {
+            this.remove(key);
+            return null;
+        }
+        return entry.value;
+    }
+    set(key, value) {
+        if (this.ttlMs === 0)
+            return;
+        const entry = { expires: this.now() + this.ttlMs, value };
+        if (this.storage) {
+            try {
+                this.storage.setItem(PREFIX + key, JSON.stringify(entry));
+                return;
+            }
+            catch {
+                // Storage full or blocked: fall back to memory for this one.
+            }
+        }
+        this.memory.set(key, entry);
+        if (this.memory.size > MAX_MEMORY_ENTRIES)
+            this.memory.delete(this.memory.keys().next().value);
+    }
+    /** Drop every cached answer of this client (e.g. after a purge in the LIKYLY console). */
+    clear() {
+        this.memory.clear();
+        if (!this.storage)
+            return;
+        try {
+            for (let i = this.storage.length - 1; i >= 0; i--) {
+                const k = this.storage.key(i);
+                if (k?.startsWith(PREFIX))
+                    this.storage.removeItem(k);
+            }
+        }
+        catch {
+            // Blocked storage: nothing was written there either.
+        }
+    }
+    /** True while calls are paused after a failure. */
+    isPaused() {
+        return this.now() < this.pausedUntil;
+    }
+    /** Seconds left in the pause (0 when not paused). */
+    pauseRemaining() {
+        return Math.max(0, Math.ceil((this.pausedUntil - this.now()) / 1000));
+    }
+    recordFailure() {
+        if (this.pauseMs > 0)
+            this.pausedUntil = this.now() + this.pauseMs;
+    }
+    recordSuccess() {
+        this.pausedUntil = 0;
+    }
+    read(key) {
+        if (this.storage) {
+            try {
+                const raw = this.storage.getItem(PREFIX + key);
+                if (raw)
+                    return JSON.parse(raw);
+            }
+            catch {
+                // Unreadable entry or storage: treat as a miss.
+            }
+        }
+        return this.memory.get(key) ?? null;
+    }
+    remove(key) {
+        this.memory.delete(key);
+        try {
+            this.storage?.removeItem(PREFIX + key);
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+exports.RecommendCache = RecommendCache;

package/dist/cjs/resources/events.d.ts

@@ -0,0 +1,45 @@
+import type { HttpClient } from "../http.js";
+import type { EventBatchResult, EventInput, EventResult, IdentifyInput, IdentifyResult, RequestOptions, TypedEventInput } from "../types.js";
+/**
+ * `likyly.events` - what your visitors do. Works with the **public** key from a browser, or the
+ * secret key from your backend. `track()` is the one mechanism; `view()`, `click()`, ... are
+ * shortcuts that call it with the matching event type.
+ */
+export declare class EventsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Records one event of any type: `view`, `click`, ... or your own (`favorite`, `share`, ...).
+     * Event types are open strings - the six helpers below are conveniences, not a closed list.
+     *
+     * Retries: a failed call is only retried automatically when it carries an `eventId` (then a
+     * replay is harmless); without one, an ambiguous failure is thrown rather than risking a duplicate.
+     */
+    track(type: string, event: EventInput, options?: RequestOptions): Promise<EventResult>;
+    /** Up to 1000 events in one call, each with its own `type`. All-or-nothing validation. */
+    trackMany(events: TypedEventInput[], options?: RequestOptions): Promise<EventBatchResult>;
+    /** The item was shown to the visitor (send the `recommendationId` it came with). */
+    impression(event: EventInput, options?: RequestOptions): Promise<EventResult>;
+    /** The visitor looked at the item (a product page, an article). */
+    view(event: EventInput, options?: RequestOptions): Promise<EventResult>;
+    /** The visitor clicked the item. */
+    click(event: EventInput, options?: RequestOptions): Promise<EventResult>;
+    addToCart(event: EventInput, options?: RequestOptions): Promise<EventResult>;
+    removeFromCart(event: EventInput, options?: RequestOptions): Promise<EventResult>;
+    /** Set `eventId` (e.g. `purchase_<orderId>_<itemId>`) so a retry can never count the purchase twice. */
+    purchase(event: EventInput, options?: RequestOptions): Promise<EventResult>;
+    /** Alias of {@link impression} - the item was shown to the visitor in a recommendation slot. */
+    recommendationImpression(event: EventInput, options?: RequestOptions): Promise<EventResult>;
+    /** Alias of {@link click} - the visitor clicked a recommended item. */
+    recommendationClick(event: EventInput, options?: RequestOptions): Promise<EventResult>;
+    /** Alias of {@link view} - the visitor looked at a product/article page. */
+    productView(event: EventInput, options?: RequestOptions): Promise<EventResult>;
+    /**
+     * Call right after login/signup, once you know `userId`, for the `sessionId` the visitor
+     * was anonymous under: every past interaction of that session not already attributed to a
+     * user is reassigned to `userId`, so it counts as that user's history from then on. Safe to
+     * call more than once. See `LikylySession.identify` for the client-side counterpart that
+     * also remembers the link locally.
+     */
+    identify(input: IdentifyInput, options?: RequestOptions): Promise<IdentifyResult>;
+}

package/dist/cjs/resources/events.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventsResource = void 0;
+const encoding_js_1 = require("../encoding.js");
+const errors_js_1 = require("../errors.js");
+/**
+ * `likyly.events` - what your visitors do. Works with the **public** key from a browser, or the
+ * secret key from your backend. `track()` is the one mechanism; `view()`, `click()`, ... are
+ * shortcuts that call it with the matching event type.
+ */
+class EventsResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Records one event of any type: `view`, `click`, ... or your own (`favorite`, `share`, ...).
+     * Event types are open strings - the six helpers below are conveniences, not a closed list.
+     *
+     * Retries: a failed call is only retried automatically when it carries an `eventId` (then a
+     * replay is harmless); without one, an ambiguous failure is thrown rather than risking a duplicate.
+     */
+    async track(type, event, options) {
+        const res = await this.http.request({
+            method: "POST",
+            path: `/events/${(0, encoding_js_1.encodeSegment)(requireEventType(type))}`,
+            body: eventBody(event),
+            idempotent: event.eventId !== undefined,
+            options,
+        });
+        return { message: res.data.message, eventId: res.data.event_id ?? undefined, duplicate: res.data.duplicate === true };
+    }
+    /** Up to 1000 events in one call, each with its own `type`. All-or-nothing validation. */
+    async trackMany(events, options) {
+        if (!Array.isArray(events) || events.length === 0)
+            throw new errors_js_1.ValidationError("events must be a non-empty array");
+        const res = await this.http.request({
+            method: "POST",
+            path: "/events/batch",
+            body: { events: events.map((e) => ({ event_type: requireEventType(e.type), ...eventBody(e) })) },
+            idempotent: events.every((e) => e.eventId !== undefined),
+            options,
+        });
+        return { received: res.data.received, accepted: res.data.accepted, duplicates: res.data.duplicates };
+    }
+    /** The item was shown to the visitor (send the `recommendationId` it came with). */
+    impression(event, options) {
+        return this.track("impression", event, options);
+    }
+    /** The visitor looked at the item (a product page, an article). */
+    view(event, options) {
+        return this.track("view", event, options);
+    }
+    /** The visitor clicked the item. */
+    click(event, options) {
+        return this.track("click", event, options);
+    }
+    addToCart(event, options) {
+        return this.track("add_to_cart", event, options);
+    }
+    removeFromCart(event, options) {
+        return this.track("remove_from_cart", event, options);
+    }
+    /** Set `eventId` (e.g. `purchase_<orderId>_<itemId>`) so a retry can never count the purchase twice. */
+    purchase(event, options) {
+        return this.track("purchase", event, options);
+    }
+    // ---- Clearer aliases for the recommendation-tracking events ---------------------------
+    // Same wire call as impression/view/click above (mapped server-side onto the same
+    // already-weighted event type - see db.EVENT_TYPE_ALIASES) - purely a naming preference,
+    // e.g. for code a coding agent generates from the LIKYLY MCP tools' own vocabulary.
+    /** Alias of {@link impression} - the item was shown to the visitor in a recommendation slot. */
+    recommendationImpression(event, options) {
+        return this.track("recommendation_impression", event, options);
+    }
+    /** Alias of {@link click} - the visitor clicked a recommended item. */
+    recommendationClick(event, options) {
+        return this.track("recommendation_click", event, options);
+    }
+    /** Alias of {@link view} - the visitor looked at a product/article page. */
+    productView(event, options) {
+        return this.track("product_view", event, options);
+    }
+    /**
+     * Call right after login/signup, once you know `userId`, for the `sessionId` the visitor
+     * was anonymous under: every past interaction of that session not already attributed to a
+     * user is reassigned to `userId`, so it counts as that user's history from then on. Safe to
+     * call more than once. See `LikylySession.identify` for the client-side counterpart that
+     * also remembers the link locally.
+     */
+    async identify(input, options) {
+        const userId = (0, encoding_js_1.requireId)(input.userId, "userId");
+        const sessionId = (0, encoding_js_1.requireId)(input.sessionId, "sessionId");
+        const res = await this.http.request({
+            method: "POST",
+            path: "/events/identify",
+            body: { user_id: userId, session_id: sessionId },
+            idempotent: true, // only ever reassigns not-yet-attributed rows - replaying is harmless
+            options,
+        });
+        return { linkedInteractions: res.data.linked_interactions };
+    }
+}
+exports.EventsResource = EventsResource;
+function requireEventType(type) {
+    if (typeof type !== "string" || !/^[A-Za-z0-9_-]{1,64}$/.test(type)) {
+        throw new errors_js_1.ValidationError('event type must be 1-64 characters of letters, digits, "_" or "-" (e.g. "view", "add_to_cart", "favorite")');
+    }
+    return type;
+}
+/** `properties` is passed through untouched: its keys are yours. */
+function eventBody(event) {
+    if (event === null || typeof event !== "object")
+        throw new errors_js_1.ValidationError("event must be an object");
+    const itemId = (0, encoding_js_1.requireId)(event.itemId, "itemId");
+    if (event.userId === undefined && event.sessionId === undefined) {
+        throw new errors_js_1.ValidationError("an event needs a userId or a sessionId (or both)");
+    }
+    if (event.userId !== undefined)
+        (0, encoding_js_1.requireId)(event.userId, "userId");
+    if (event.sessionId !== undefined)
+        (0, encoding_js_1.requireId)(event.sessionId, "sessionId");
+    return (0, encoding_js_1.compact)({
+        event_id: event.eventId,
+        user_id: event.userId,
+        session_id: event.sessionId,
+        item_id: itemId,
+        recommendation_id: event.recommendationId,
+        placement: event.placement,
+        quantity: event.quantity,
+        occurred_at: event.occurredAt instanceof Date ? event.occurredAt.toISOString() : event.occurredAt,
+        properties: event.properties,
+    });
+}

package/dist/cjs/resources/items.d.ts

@@ -0,0 +1,43 @@
+import type { HttpClient } from "../http.js";
+import type { BatchResult, Item, ItemImport, ItemInput, ItemList, ListOptions, RequestOptions } from "../types.js";
+/** `likyly.items` - your catalog. Needs the **secret** API key. */
+export declare class ItemsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** One item by your own id. */
+    get(itemId: string, options?: RequestOptions): Promise<Item>;
+    /** One page of the catalog. Pagination is `limit` + `offset` (the API's default is 100 per page); `total` is the whole catalog's size. */
+    list(listOptions?: ListOptions, options?: RequestOptions): Promise<ItemList>;
+    /**
+     * Creates the item, or replaces it if it exists - idempotent, safe to call as often as you like.
+     * The body is the whole item: fields you leave out are cleared.
+     */
+    upsert(itemId: string, item: ItemInput, options?: RequestOptions): Promise<Item>;
+    /** Removes the item from the catalog. Events already recorded for it are kept. */
+    delete(itemId: string, options?: RequestOptions): Promise<void>;
+    /** Batch upsert (1-1000 items) - each entry behaves like `upsert`. A failing entry is reported in `errors`. */
+    upsertMany(items: ItemImport[], options?: RequestOptions): Promise<BatchResult>;
+    /** Alias of {@link upsertMany}: the API's `POST /items/import` is a JSON batch upsert. (A CSV import exists only in the LIKYLY dashboard.) */
+    import(items: ItemImport[], options?: RequestOptions): Promise<BatchResult>;
+    /** Batch delete (1-1000 ids). Ids that don't exist are reported in `errors`. */
+    deleteMany(itemIds: string[], options?: RequestOptions): Promise<BatchResult>;
+}
+interface WireItem {
+    item_id: string;
+    title: string;
+    description?: string | null;
+    properties?: Record<string, unknown>;
+}
+export interface WireBatch {
+    received: number;
+    succeeded: number;
+    failed: number;
+    errors?: {
+        index: number;
+        id?: string | null;
+        message: string;
+    }[];
+}
+export declare function toItem(w: WireItem): Item;
+export declare function toBatch(w: WireBatch): BatchResult;
+export {};