@likyly/sdk 0.0.0-stage → 1.1.0

package/dist/esm/http.js

@@ -0,0 +1,149 @@
+import { LikylyError, NetworkError, TimeoutError, ValidationError, errorFromResponse, } from "./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.
+ */
+export 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 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 NetworkError || error instanceof 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 TimeoutError(`LIKYLY request timed out after ${timeoutMs} ms`, { cause });
+            if (userSignal?.aborted)
+                throw cause; // the caller cancelled: surface their AbortError untouched
+            throw new 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 errorFromResponse(response.status, data, requestId ?? undefined, parseRetryAfter(response.headers.get("retry-after")));
+        }
+        return { data: data, status: response.status, headers: response.headers, requestId: requestId ?? undefined };
+    }
+}
+/** Retry-After is either a number of seconds or an HTTP date. */
+export 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;
+}
+export function assertNonEmptyObject(value, name) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new ValidationError(`${name} must be an object`);
+    }
+}

package/dist/esm/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/esm/index.js

@@ -0,0 +1,4 @@
+export { Likyly } from "./client.js";
+export { LikylySession } from "./session.js";
+export { LikylyError, ApiError, AuthenticationError, PermissionDeniedError, NotFoundError, RateLimitError, ValidationError, NetworkError, TimeoutError, PausedError, } from "./errors.js";
+export { SDK_VERSION } from "./version.js";

package/dist/esm/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/esm/recommend-cache.js

@@ -0,0 +1,110 @@
+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;
+    }
+}
+export 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
+        }
+    }
+}

package/dist/esm/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/esm/resources/events.js

@@ -0,0 +1,130 @@
+import { compact, encodeSegment, requireId } from "../encoding.js";
+import { ValidationError } from "../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.
+ */
+export 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/${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 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 = requireId(input.userId, "userId");
+        const sessionId = 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 };
+    }
+}
+function requireEventType(type) {
+    if (typeof type !== "string" || !/^[A-Za-z0-9_-]{1,64}$/.test(type)) {
+        throw new 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 ValidationError("event must be an object");
+    const itemId = requireId(event.itemId, "itemId");
+    if (event.userId === undefined && event.sessionId === undefined) {
+        throw new ValidationError("an event needs a userId or a sessionId (or both)");
+    }
+    if (event.userId !== undefined)
+        requireId(event.userId, "userId");
+    if (event.sessionId !== undefined)
+        requireId(event.sessionId, "sessionId");
+    return 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/esm/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 {};

package/dist/esm/resources/items.js

@@ -0,0 +1,91 @@
+import { compact, encodeSegment, requireId } from "../encoding.js";
+import { ValidationError } from "../errors.js";
+/** `likyly.items` - your catalog. Needs the **secret** API key. */
+export class ItemsResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** One item by your own id. */
+    async get(itemId, options) {
+        const res = await this.http.request({ method: "GET", path: `/items/${encodeSegment(requireId(itemId, "itemId"))}`, idempotent: true, options });
+        return toItem(res.data);
+    }
+    /** One page of the catalog. Pagination is `limit` + `offset` (the API's default is 100 per page); `total` is the whole catalog's size. */
+    async list(listOptions = {}, options) {
+        const res = await this.http.request({
+            method: "GET",
+            path: "/items",
+            query: { limit: listOptions.limit, offset: listOptions.offset },
+            idempotent: true,
+            options,
+        });
+        const total = res.headers.get("x-total-count");
+        return { items: res.data.map(toItem), total: total === null ? undefined : Number(total), limit: listOptions.limit, offset: listOptions.offset ?? 0 };
+    }
+    /**
+     * 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.
+     */
+    async upsert(itemId, item, options) {
+        const res = await this.http.request({
+            method: "PUT",
+            path: `/items/${encodeSegment(requireId(itemId, "itemId"))}`,
+            body: itemBody(item),
+            idempotent: true,
+            options,
+        });
+        return toItem(res.data);
+    }
+    /** Removes the item from the catalog. Events already recorded for it are kept. */
+    async delete(itemId, options) {
+        await this.http.request({ method: "DELETE", path: `/items/${encodeSegment(requireId(itemId, "itemId"))}`, idempotent: true, options });
+    }
+    /** Batch upsert (1-1000 items) - each entry behaves like `upsert`. A failing entry is reported in `errors`. */
+    async upsertMany(items, options) {
+        if (!Array.isArray(items) || items.length === 0)
+            throw new ValidationError("items must be a non-empty array");
+        const res = await this.http.request({
+            method: "POST",
+            path: "/items/import",
+            body: { items: items.map((i) => ({ item_id: requireId(i.itemId, "itemId"), ...itemBody(i) })) },
+            idempotent: true, // an upsert: replaying it changes nothing
+            options,
+        });
+        return toBatch(res.data);
+    }
+    /** 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, options) {
+        return this.upsertMany(items, options);
+    }
+    /** Batch delete (1-1000 ids). Ids that don't exist are reported in `errors`. */
+    async deleteMany(itemIds, options) {
+        if (!Array.isArray(itemIds) || itemIds.length === 0)
+            throw new ValidationError("itemIds must be a non-empty array");
+        const res = await this.http.request({
+            method: "POST",
+            path: "/items/delete",
+            body: { item_ids: itemIds.map((id) => requireId(id, "itemId")) },
+            idempotent: true,
+            options,
+        });
+        return toBatch(res.data);
+    }
+}
+function itemBody(item) {
+    if (item === null || typeof item !== "object" || typeof item.title !== "string" || item.title === "") {
+        throw new ValidationError("an item needs a non-empty title");
+    }
+    return compact({ title: item.title, description: item.description, properties: item.properties });
+}
+export function toItem(w) {
+    return { itemId: w.item_id, title: w.title, description: w.description ?? undefined, properties: w.properties ?? {} };
+}
+export function toBatch(w) {
+    return {
+        received: w.received,
+        succeeded: w.succeeded,
+        failed: w.failed,
+        errors: (w.errors ?? []).map((e) => ({ index: e.index, id: e.id ?? undefined, message: e.message })),
+    };
+}

package/dist/esm/resources/placements.d.ts

@@ -0,0 +1,24 @@
+import type { HttpClient } from "../http.js";
+import type { PlacementRecommendOptions, PlacementRecommendResponse, RequestOptions } from "../types.js";
+import type { RecommendCache } from "../recommend-cache.js";
+/**
+ * `likyly.placements` - the recommended way to ask for recommendations. A Placement ("what to
+ * recommend, where, with what fallback and filters") is configured once - via the LIKYLY MCP
+ * admin tools or dashboard, never from this runtime SDK - and called by `slug` from here on.
+ * `likyly.recommendations` (the strategy-specific / signal-based API) remains available for
+ * advanced, per-call use with no persistent configuration.
+ */
+export declare class PlacementsResource {
+    private readonly http;
+    /** null when the client was built with `cache: false`. */
+    readonly cache: RecommendCache | null;
+    constructor(http: HttpClient, 
+    /** null when the client was built with `cache: false`. */
+    cache?: RecommendCache | null);
+    /**
+     * Recommendations for one placement: send whatever context you have (`itemId`, `userId`,
+     * `sessionId`, ...) - the placement's own configuration decides the strategy, fallback and
+     * filters, not you. Send `recommendationId` back on the events that follow to attribute them.
+     */
+    recommend(opts: PlacementRecommendOptions, options?: RequestOptions): Promise<PlacementRecommendResponse>;
+}