@likyly/sdk 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,279 @@
-# Temporary Holding Version
+# LIKYLY SDK for TypeScript / JavaScript
 
-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.
+The official TypeScript / JavaScript client for the [LIKYLY](https://likyly.com) recommendations API. Send your catalog and what your visitors do, get personalised recommendations back.
+
+```
+catalog (items)  →  events  →  recommendations  →  impression → click → purchase
+```
+
+## Install
+
+```sh
+npm install @likyly/sdk
+```
+
+Node.js 18 or later, or any runtime that has `fetch` (Bun, Deno, Cloudflare Workers, browsers). ESM and CommonJS builds, TypeScript types included, no runtime dependency.
+
+## Quick start
+
+### Initialize
+
+Create one client and reuse it. Use your **secret** key on your server (see [Which key?](#which-key)).
+
+```js
+import { Likyly, NotFoundError, RateLimitError } from "@likyly/sdk";
+
+// Backend only: the secret key gives access to your catalog and your users.
+const likyly = new Likyly({
+  apiKey: process.env.LIKYLY_SECRET_KEY,
+});
+```
+
+### Send your catalog
+
+```js
+// Send your catalog once (and whenever it changes). Ids are YOUR ids: SKUs, UUIDs, Shopify gids...
+await likyly.items.upsertMany([
+  { itemId: "SKU-1", title: "Nike Air Max", description: "Running shoe with air cushioning", properties: { category: "shoes", brand: "Nike", price: 129.9 } },
+  { itemId: "SKU-2", title: "Adidas Ultraboost", description: "Responsive running shoe", properties: { category: "shoes", brand: "Adidas", price: 149 } },
+  { itemId: "SKU-3", title: "Nike Pegasus", description: "Everyday running shoe", properties: { category: "shoes", brand: "Nike", price: 119 } },
+]);
+
+// Users are optional: describe them if you want the profile to travel with their events.
+await likyly.users.upsert("user_123", { properties: { country: "FR", segment: "premium" } });
+```
+
+Ids are your own: any string (`SKU-123`, a UUID, `gid://shopify/Product/123`). `properties` is free-form; `category` and `description` improve similarity, everything else is stored as is.
+
+### Track events
+
+```js
+// Tell LIKYLY what your visitors do.
+await likyly.events.view({ userId: "user_123", itemId: "SKU-1" });
+
+// Purchases carry an eventId: replaying the call can never count the sale twice.
+await likyly.events.purchase({
+  eventId: "purchase_order_9281_SKU-1",
+  userId: "user_123",
+  itemId: "SKU-1",
+  quantity: 1,
+  properties: { price: 129.9, currency: "EUR", orderId: "order_9281" },
+});
+```
+
+### Get recommendations
+
+```js
+// Ask what to show. You never pick an algorithm: LIKYLY chooses the best strategy for what it knows.
+const recs = await likyly.recommendations.get({ userId: "user_123", placement: "homepage", limit: 3 });
+
+console.log(`strategy: ${recs.strategy}`);
+for (const item of recs.items) console.log(item.itemId, item.title);
+```
+
+You never choose an algorithm: LIKYLY picks the best strategy for what it knows about the visitor and tells you which one it used (`strategy`: `hybrid`, `content`, `collaborative`, `session` or `popular`). With no user, no session and no item you still get a useful answer: what is popular.
+
+### Placements: the recommended way
+
+```js
+// The recommended way: a placement ("pdp-related"...) is configured once in LIKYLY - strategy,
+// fallback, filters - and your page only says where it is and what it knows.
+const related = await likyly.placements.recommend({
+  placement: "pdp-related",
+  context: { itemId: "SKU-123", sessionId: "sess_abc" },
+  limit: 4,
+});
+console.log(`strategy used: ${related.strategyUsed}`);
+
+// When an anonymous visitor signs in, attach their session's history to their account.
+const { linkedInteractions } = await likyly.events.identify({ userId: "user_123", sessionId: "sess_abc" });
+console.log(`linked: ${linkedInteractions}`);
+```
+
+A placement (`pdp-related`, `home-for-you`, `cart-cross-sell`...) is configured once in LIKYLY, by your coding assistant through the MCP server or in the console: strategy, fallback, filters, how many items. Your code only names it and passes what it knows (`itemId`, `userId`, `sessionId`, ...); change the configuration later without redeploying. `identify` attaches an anonymous visitor's history to their account the moment they sign in, so their recommendations stay personal.
+
+### Close the loop
+
+```js
+// Send the recommendationId back: LIKYLY measures which recommendations get seen, clicked and bought.
+await likyly.events.impression({ userId: "user_123", itemId: recs.items[0].itemId, recommendationId: recs.recommendationId, placement: "homepage" });
+await likyly.events.click({ userId: "user_123", itemId: recs.items[0].itemId, recommendationId: recs.recommendationId, placement: "homepage" });
+```
+
+Send the recommendation id back on the events that follow (`impression` when it is displayed, `click`, `add_to_cart`, `purchase`) and LIKYLY can measure which recommendations actually convert.
+
+## Which key?
+
+| | Secret key | Public key |
+|---|---|---|
+| Where | your server only | anywhere, including a web page |
+| Recommendations | yes | yes |
+| Record events | yes | yes |
+| Items and users (create, read, delete) | yes | no (`PermissionDeniedError`) |
+| `debug` explanations | yes | no |
+
+The public key can only read recommendations and write events, so it is safe to expose. **Never put the secret key in code that ships to a browser or a mobile app.**
+
+```js
+// In a web page, use the PUBLIC key: it can only read recommendations and record events.
+const browser = new Likyly({
+  apiKey: process.env.LIKYLY_PUBLIC_KEY,
+});
+
+// A visitor who is not logged in: use an anonymous session id (any string you generate and keep in a cookie).
+await browser.events.view({ sessionId: "sess_abc", itemId: "SKU-2" });
+const forVisitor = await browser.recommendations.get({ sessionId: "sess_abc", viewedItemIds: ["SKU-2"], placement: "product_page", limit: 3 });
+```
+
+## Events
+
+`track` is the one mechanism; `impression`, `view`, `click`, `add_to_cart`, `remove_from_cart` and `purchase` are shortcuts that call it with the matching type. Event types are **open strings**: use your own (`favorite`, `share`, `video_played`, ...) as freely as the official ones.
+
+```js
+// Any string is a valid event type: track what matters to your business.
+await likyly.events.track("favorite", { userId: "user_123", itemId: "SKU-2", properties: { list: "wishlist" } });
+
+// Up to 1000 events per call, each with its own type.
+await likyly.events.trackMany([
+  { type: "view", userId: "user_123", itemId: "SKU-3" },
+  { type: "add_to_cart", userId: "user_123", itemId: "SKU-3", quantity: 1 },
+]);
+```
+
+- An event needs an item and a user, a session, or both (both ties the anonymous session to the user once they log in).
+- Anonymous visitors: generate a session id (any string) and keep it in a cookie; no login needed.
+- `properties` is a free-form object (price, currency, order id, ...). Its keys are stored exactly as you send them and are never renamed by the SDK.
+- `event_id` (idempotency key): replaying an event with the same id records nothing and returns `duplicate: true`. Set it on purchases, for example `purchase_<orderId>_<itemId>`.
+- `placement` is a free-form label of where something happened or will be displayed (`homepage`, `product_page`, `cart`, ...).
+
+## Advanced recommendations
+
+`recommendations.get` is the normal way. When you want to pick the strategy yourself:
+
+```js
+// Advanced Recommendations: one strategy at a time, when you want to choose.
+const similar = await likyly.recommendations.similar({ itemId: "SKU-1", limit: 3 });
+const hybrid = await likyly.recommendations.hybrid({ userId: "user_123", itemId: "SKU-1", alpha: 0.7, limit: 3 });
+const session = await likyly.recommendations.session({ viewedItemIds: ["SKU-1", "SKU-2"], limit: 3 });
+```
+
+| Strategy | What it does |
+|---|---|
+| `popular` | The most popular items: the fallback for a visitor with no history |
+| `similar` | Items similar to one item (content similarity), no user needed |
+| `collaborative` | What users with similar histories liked. Needs a trained model, otherwise a not-found error |
+| `hybrid` | Similar items personalised for a user; `alpha` (0 to 1) weighs collaborative against content |
+| `session` | Recency-weighted, from `viewed item ids` or from a user's own view history (exactly one) |
+
+These endpoints carry ids in the URL path, so ids containing `/` (such as `gid://shopify/Product/1`) or, for the session list, `,` are refused with a validation error: use `recommendations.get`, which takes ids in the request body.
+
+## Errors
+
+Errors are typed (every one is a `LikylyError`). Catch the specific ones you care about:
+
+| Error | When |
+|---|---|
+| `ValidationError` | The request is invalid: caught by the SDK before anything is sent, or a 422 from the API (the message names the offending fields) |
+| `AuthenticationError` | 401: missing, invalid or revoked API key |
+| `PermissionDeniedError` | 403: for example a public key used for a secret-key operation, or a plan limit |
+| `NotFoundError` | 404 |
+| `RateLimitError` | 429: see the retry-after value |
+| `ApiError` | Any other error status from the API (the four rows above are its subtypes) |
+| `NetworkError` | No HTTP response: DNS, connection reset, TLS |
+| `TimeoutError` | The request timed out |
+
+Errors that come from the API carry `statusCode`, `requestId`, `retryAfter` (seconds), `body`. Quote the request id when you contact support.
+
+```js
+try {
+  await likyly.items.get("does-not-exist");
+} catch (error) {
+  if (error instanceof NotFoundError) console.log("no such item, request", error.requestId);
+  else if (error instanceof RateLimitError) console.log("slow down, retry in", error.retryAfter, "s");
+  else throw error;
+}
+```
+
+## Retries and timeouts
+
+The SDK retries transient failures for you (2 retries by default, exponential backoff from 0.5 s capped at 8 s, with full jitter):
+
+- **429**: always retried, honouring `Retry-After`. A `Retry-After` longer than 60 s is not waited for: the rate-limit error is returned instead.
+- **502, 503, 504, dropped connections and timeouts**: retried only when replaying the call is harmless: reads, upserts, deletes, events that carry an `event_id`, and batches where every event has one.
+- An event **without** an `event_id` is never retried after an ambiguous failure, so a flaky network can never record a purchase twice. Set `event_id` on events you care about and they become safe to retry.
+- Other 4xx errors are never retried.
+
+## Configuration
+
+| Setting | Option | Default |
+|---|---|---|
+| API key | `apiKey` | required |
+| Base URL | `baseUrl` | `https://api.likyly.com` |
+| Catalog | `catalog` | your only catalog |
+| Timeout | `timeout` (milliseconds) | 10 000 |
+| Retries | `maxRetries` | 2 |
+| User-Agent suffix | `userAgent` | none |
+| Custom HTTP | `fetch` | global `fetch` |
+| Recommendation cache | `cache`: `{ ttlSeconds, pauseSeconds, storage }` or `false` | 1 hour; 30 s pause after a failure |
+
+```js
+const tuned = new Likyly({
+  apiKey: process.env.LIKYLY_SECRET_KEY,
+  timeout: 5_000, // milliseconds per attempt (default 10 000)
+  maxRetries: 3, // automatic retries on 429 / 502 / 503 / 504 / network errors (default 2, 0 disables)
+  userAgent: "my-shop/1.4", // appended to the SDK's User-Agent
+});
+```
+
+Every method takes a last `options` argument: `{ signal, timeout, maxRetries }` (an `AbortSignal` cancels the call).
+
+## API reference
+
+`key` says which API key may call it: **S** = secret key only, **P** = public or secret key.
+
+| Method | What it does | Key |
+|---|---|---|
+| `likyly.items.get` | One item by your own id | S |
+| `likyly.items.list` | One page of the catalog (`limit` / `offset`), with the catalog's total | S |
+| `likyly.items.upsert` | Create or replace an item (idempotent) | S |
+| `likyly.items.delete` | Remove an item (events already recorded for it are kept) | S |
+| `likyly.items.upsertMany` | Batch upsert, 1 to 1000 items | S |
+| `likyly.items.import` | Alias of the batch upsert above (JSON batch) | S |
+| `likyly.items.deleteMany` | Batch delete, 1 to 1000 ids; unknown ids are reported, not raised | S |
+| `likyly.users.get` | One user profile | S |
+| `likyly.users.list` | One page of users (`limit` / `offset`) | S |
+| `likyly.users.upsert` | Create or replace a profile (free-form `properties`) | S |
+| `likyly.users.delete` | Erase the profile **and every event recorded for that user** | S |
+| `likyly.users.import` | Batch upsert of users, 1 to 1000 | S |
+| `likyly.events.track` | Record an event of any type (open string) | P |
+| `likyly.events.trackMany` | Up to 1000 events in one call, each with its own type | P |
+| `likyly.events.impression` | The item was displayed to the visitor | P |
+| `likyly.events.view` | The visitor looked at the item | P |
+| `likyly.events.click` | The visitor clicked the item | P |
+| `likyly.events.addToCart` | The visitor added the item to their cart | P |
+| `likyly.events.removeFromCart` | The visitor removed the item from their cart | P |
+| `likyly.events.purchase` | The visitor bought the item (set an event id) | P |
+| `likyly.events.identify` | An anonymous visitor signed in: attach their session's history to their user id | P |
+| `likyly.placements.recommend` | Recommendations for a named placement configured in LIKYLY (the recommended way) | P |
+| `likyly.recommendations.get` | Recommendations with the automatic strategy: user, session, item or viewed items | P |
+| `likyly.recommendations.popular` | Advanced: the most popular items | P |
+| `likyly.recommendations.similar` | Advanced: items similar to one item | P |
+| `likyly.recommendations.collaborative` | Advanced: what similar users liked (needs a trained model) | P |
+| `likyly.recommendations.hybrid` | Advanced: similar items personalised for a user (`alpha`) | P |
+| `likyly.recommendations.session` | Advanced: from viewed items or a user's view history | P |
+
+Lists are paginated with `limit` and `offset` (the API's default page is 100 items); the total is reported next to the page. Users have a batch `import` but no batch delete: the API has no such endpoint. `import` on items is an alias of the batch upsert (the CSV import is a dashboard feature).
+
+## Notes for TypeScript
+
+- Identifiers are plain strings and are never coerced: `itemId: 42` is a type error, and a JavaScript caller passing a number gets a `ValidationError`.
+- Request and response fields are `camelCase` (`itemId`, `recommendationId`); the keys inside `properties` are yours and are never renamed.
+- Placement recommendations are cached (one hour, per visitor in a browser, `sessionStorage`) and, after a network error, a timeout, a 429 or a 5xx, calls pause for 30 seconds and throw `PausedError` at once, so your page shows its fallback instead of waiting. `likyly.clearRecommendationCache()` forgets the cached answers; the LIKYLY console's "Vider le cache" empties the server side.
+
+## Documentation and support
+
+- Documentation: <https://likyly.com/docs/sdk/typescript>
+- REST API reference (OpenAPI): <https://api.likyly.com/docs>
+- Package: @likyly/sdk on npm
+
+MIT licensed.

package/dist/cjs/client.d.ts

@@ -0,0 +1,70 @@
+import { EventsResource } from "./resources/events.js";
+import { ItemsResource } from "./resources/items.js";
+import { PlacementsResource } from "./resources/placements.js";
+import { type RecommendCacheOptions } from "./recommend-cache.js";
+import { RecommendationsResource } from "./resources/recommendations.js";
+import { UsersResource } from "./resources/users.js";
+import type { PlacementRecommendOptions, PlacementRecommendResponse, RequestOptions } from "./types.js";
+export interface LikylyOptions {
+    /**
+     * Your API key. Two kinds: the **secret** key (backend only: items, users, everything) and the
+     * **public** key (safe in a web page: recommendations and event tracking only). Never put the
+     * secret key in code that ships to a browser.
+     */
+    apiKey: string;
+    /** Defaults to `https://api.likyly.com`. */
+    baseUrl?: string;
+    /**
+     * Which of your catalogs to use, if your account has several. Omit it if you have one: LIKYLY
+     * uses your only catalog.
+     */
+    catalog?: string;
+    /** Per-request timeout in milliseconds. Default 10000. */
+    timeout?: number;
+    /** Automatic retries on transient failures (429, 502, 503, 504, dropped connections). Default 2. Set 0 to disable. */
+    maxRetries?: number;
+    /** Appended to the SDK's User-Agent, e.g. `my-shop/1.4`. */
+    userAgent?: string;
+    /**
+     * Placement recommendations are cached (one hour, per visitor in a browser) and LIKYLY is not
+     * called again for 30 seconds after it fails, so pages fall back to their own content at once.
+     * Tune it (`{ ttlSeconds, pauseSeconds, storage }`) or turn it off with `false`.
+     */
+    cache?: RecommendCacheOptions | false;
+    /** Custom `fetch` (proxies, tests). Defaults to the global one (Node 18+, browsers, edge runtimes). */
+    fetch?: typeof fetch;
+    /** @internal test hooks */
+    _internal?: {
+        sleep?: (ms: number) => Promise<void>;
+        random?: () => number;
+    };
+}
+/**
+ * The LIKYLY client. Five things to know:
+ *
+ *   likyly.items            your catalog
+ *   likyly.users            your users (optional)
+ *   likyly.events           what visitors do
+ *   likyly.recommendations  what to show them (advanced, per-call)
+ *   likyly.placements       what to show them (recommended - a named, persistent config)
+ */
+export declare class Likyly {
+    readonly items: ItemsResource;
+    readonly users: UsersResource;
+    readonly events: EventsResource;
+    readonly recommendations: RecommendationsResource;
+    readonly placements: PlacementsResource;
+    constructor(options: LikylyOptions);
+    /**
+     * Shorthand for `likyly.placements.recommend(...)` - recommendations for one placement.
+     * Configure the placement once (LIKYLY's MCP admin tools or dashboard), then:
+     *
+     *     const result = await likyly.recommend({
+     *       placement: "pdp-related",
+     *       context: { itemId: product.id, userId: user?.id, sessionId },
+     *     });
+     */
+    recommend(opts: PlacementRecommendOptions, options?: RequestOptions): Promise<PlacementRecommendResponse>;
+    /** Forget the cached placement recommendations (this browser tab or process only). */
+    clearRecommendationCache(): void;
+}

package/dist/cjs/client.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Likyly = void 0;
+const errors_js_1 = require("./errors.js");
+const http_js_1 = require("./http.js");
+const events_js_1 = require("./resources/events.js");
+const items_js_1 = require("./resources/items.js");
+const placements_js_1 = require("./resources/placements.js");
+const recommend_cache_js_1 = require("./recommend-cache.js");
+const recommendations_js_1 = require("./resources/recommendations.js");
+const users_js_1 = require("./resources/users.js");
+const version_js_1 = require("./version.js");
+/** Key prefixes issued from now on (older, unprefixed keys keep working) - "sk_" secret,
+ * "pk_" public, "lk_" developer. Lets this SDK refuse a browser-unsafe key at construction
+ * time instead of only documenting "don't do this" - see the constructor below. */
+const UNSAFE_FOR_BROWSER_PREFIXES = ["sk_", "lk_"];
+/**
+ * The LIKYLY client. Five things to know:
+ *
+ *   likyly.items            your catalog
+ *   likyly.users            your users (optional)
+ *   likyly.events           what visitors do
+ *   likyly.recommendations  what to show them (advanced, per-call)
+ *   likyly.placements       what to show them (recommended - a named, persistent config)
+ */
+class Likyly {
+    items;
+    users;
+    events;
+    recommendations;
+    placements;
+    constructor(options) {
+        if (!options || typeof options.apiKey !== "string" || options.apiKey.trim() === "") {
+            throw new errors_js_1.ValidationError("apiKey is required (create one in your LIKYLY account)");
+        }
+        // A secret or developer key running where a browser could read this process's memory/
+        // bundle (window+document present - true in a real browser, false in Node/most edge
+        // runtimes) is exactly the mistake this guard exists to catch immediately, rather than
+        // silently shipping it. Neither key kind has any reason to run there: recommendations and
+        // event tracking (the only things safe in a browser) only ever need the public key.
+        const isBrowserLike = typeof globalThis.window !== "undefined" && typeof globalThis.document !== "undefined";
+        if (isBrowserLike && UNSAFE_FOR_BROWSER_PREFIXES.some((prefix) => options.apiKey.startsWith(prefix))) {
+            throw new errors_js_1.ValidationError("This looks like a secret or developer key, and this code is running in a browser. " +
+                "Never put a secret/developer key where browser-facing code could read it - use the " +
+                "restricted public key here instead (account page's \"Clé publique\"), and keep the " +
+                "secret/developer key server-side only.");
+        }
+        const fetchImpl = options.fetch ?? globalThis.fetch?.bind(globalThis);
+        if (!fetchImpl)
+            throw new errors_js_1.ValidationError("no fetch implementation found: use Node 18+ or pass options.fetch");
+        const http = new http_js_1.HttpClient({
+            apiKey: options.apiKey,
+            baseUrl: (options.baseUrl ?? version_js_1.DEFAULT_BASE_URL).replace(/\/+$/, ""),
+            catalog: options.catalog,
+            timeout: options.timeout ?? 10_000,
+            maxRetries: options.maxRetries ?? 2,
+            userAgent: options.userAgent ? `${version_js_1.USER_AGENT} ${options.userAgent}` : version_js_1.USER_AGENT,
+            fetch: fetchImpl,
+            sleep: options._internal?.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+            random: options._internal?.random ?? Math.random,
+        });
+        this.items = new items_js_1.ItemsResource(http);
+        this.users = new users_js_1.UsersResource(http);
+        this.events = new events_js_1.EventsResource(http);
+        this.recommendations = new recommendations_js_1.RecommendationsResource(http);
+        this.placements = new placements_js_1.PlacementsResource(http, options.cache === false ? null : new recommend_cache_js_1.RecommendCache(options.cache ?? {}));
+    }
+    /**
+     * Shorthand for `likyly.placements.recommend(...)` - recommendations for one placement.
+     * Configure the placement once (LIKYLY's MCP admin tools or dashboard), then:
+     *
+     *     const result = await likyly.recommend({
+     *       placement: "pdp-related",
+     *       context: { itemId: product.id, userId: user?.id, sessionId },
+     *     });
+     */
+    recommend(opts, options) {
+        return this.placements.recommend(opts, options);
+    }
+    /** Forget the cached placement recommendations (this browser tab or process only). */
+    clearRecommendationCache() {
+        this.placements.cache?.clear();
+    }
+}
+exports.Likyly = Likyly;

package/dist/cjs/encoding.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Percent-encodes a path segment: everything outside RFC 3986 "unreserved" (A-Z a-z 0-9 - . _ ~)
+ * becomes %XX (UTF-8), '/' included - so an id like "gid://shopify/Product/1" is one segment.
+ */
+export declare function encodeSegment(value: string): string;
+/** Ids are opaque, non-empty strings - never coerced to numbers. */
+export declare function requireId(value: unknown, name: string): string;
+/** Advanced recommendation endpoints carry ids in the URL path, where '/' cannot be used. */
+export declare function requirePathSafeId(value: unknown, name: string): string;
+/** Removes undefined values so optional fields are simply not sent. */
+export declare function compact<T extends Record<string, unknown>>(obj: T): Record<string, unknown>;

package/dist/cjs/encoding.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeSegment = encodeSegment;
+exports.requireId = requireId;
+exports.requirePathSafeId = requirePathSafeId;
+exports.compact = compact;
+const errors_js_1 = require("./errors.js");
+/**
+ * Percent-encodes a path segment: everything outside RFC 3986 "unreserved" (A-Z a-z 0-9 - . _ ~)
+ * becomes %XX (UTF-8), '/' included - so an id like "gid://shopify/Product/1" is one segment.
+ */
+function encodeSegment(value) {
+    return encodeURIComponent(value).replace(/[!'()*]/g, (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase());
+}
+/** Ids are opaque, non-empty strings - never coerced to numbers. */
+function requireId(value, name) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new errors_js_1.ValidationError(`${name} must be a non-empty string (your own identifier, e.g. "SKU-123")`);
+    }
+    return value;
+}
+/** Advanced recommendation endpoints carry ids in the URL path, where '/' cannot be used. */
+function requirePathSafeId(value, name) {
+    const id = requireId(value, name);
+    if (id.includes("/")) {
+        throw new errors_js_1.ValidationError(`${name} "${id}" contains "/", which this endpoint cannot carry in its URL path - use recommendations.get(), which takes ids in the request body`);
+    }
+    return id;
+}
+/** Removes undefined values so optional fields are simply not sent. */
+function compact(obj) {
+    const out = {};
+    for (const [key, value] of Object.entries(obj))
+        if (value !== undefined)
+            out[key] = value;
+    return out;
+}

package/dist/cjs/errors.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Every error the SDK throws extends LikylyError, so `catch (e) { if (e instanceof LikylyError) ... }`
+ * is enough to separate LIKYLY failures from your own bugs.
+ *
+ *   LikylyError
+ *   ├─ NetworkError            no HTTP response (DNS, connection reset, ...)
+ *   ├─ TimeoutError            the request timed out
+ *   ├─ ValidationError         invalid request - caught by the SDK before sending, or 422 from the API
+ *   └─ ApiError                the API answered with an error status
+ *      ├─ AuthenticationError  401 - missing / invalid / revoked API key
+ *      ├─ PermissionDeniedError 403 - e.g. a public key used for a secret-key operation, or a plan limit
+ *      ├─ NotFoundError        404
+ *      └─ RateLimitError       429 - see `retryAfter`
+ */
+export interface ErrorDetails {
+    statusCode?: number;
+    requestId?: string;
+    retryAfter?: number;
+    body?: unknown;
+    cause?: unknown;
+}
+export declare class LikylyError extends Error {
+    /** HTTP status code, when there was an HTTP response. */
+    readonly statusCode?: number;
+    /** The `request_id` of the failed call (also the `X-Request-ID` response header) - quote it when reporting a problem. */
+    readonly requestId?: string;
+    /** Seconds to wait before retrying, from the `Retry-After` header (429/503). */
+    readonly retryAfter?: number;
+    /** The parsed response body, when there was one. */
+    readonly body?: unknown;
+    constructor(message: string, details?: ErrorDetails);
+}
+export declare class NetworkError extends LikylyError {
+}
+export declare class TimeoutError extends LikylyError {
+}
+export declare class ValidationError extends LikylyError {
+}
+/** LIKYLY failed moments ago: the SDK skips calls for a short pause (see `cache.pauseSeconds`). */
+export declare class PausedError extends LikylyError {
+}
+export declare class ApiError extends LikylyError {
+}
+export declare class AuthenticationError extends ApiError {
+}
+export declare class PermissionDeniedError extends ApiError {
+}
+export declare class NotFoundError extends ApiError {
+}
+export declare class RateLimitError extends ApiError {
+}
+export declare function errorFromResponse(status: number, body: unknown, requestId: string | undefined, retryAfter: number | undefined): ApiError | ValidationError;

package/dist/cjs/errors.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimitError = exports.NotFoundError = exports.PermissionDeniedError = exports.AuthenticationError = exports.ApiError = exports.PausedError = exports.ValidationError = exports.TimeoutError = exports.NetworkError = exports.LikylyError = void 0;
+exports.errorFromResponse = errorFromResponse;
+class LikylyError extends Error {
+    /** HTTP status code, when there was an HTTP response. */
+    statusCode;
+    /** The `request_id` of the failed call (also the `X-Request-ID` response header) - quote it when reporting a problem. */
+    requestId;
+    /** Seconds to wait before retrying, from the `Retry-After` header (429/503). */
+    retryAfter;
+    /** The parsed response body, when there was one. */
+    body;
+    constructor(message, details = {}) {
+        super(message, details.cause !== undefined ? { cause: details.cause } : undefined);
+        this.name = new.target.name;
+        this.statusCode = details.statusCode;
+        this.requestId = details.requestId;
+        this.retryAfter = details.retryAfter;
+        this.body = details.body;
+    }
+}
+exports.LikylyError = LikylyError;
+class NetworkError extends LikylyError {
+}
+exports.NetworkError = NetworkError;
+class TimeoutError extends LikylyError {
+}
+exports.TimeoutError = TimeoutError;
+class ValidationError extends LikylyError {
+}
+exports.ValidationError = ValidationError;
+/** LIKYLY failed moments ago: the SDK skips calls for a short pause (see `cache.pauseSeconds`). */
+class PausedError extends LikylyError {
+}
+exports.PausedError = PausedError;
+class ApiError extends LikylyError {
+}
+exports.ApiError = ApiError;
+class AuthenticationError extends ApiError {
+}
+exports.AuthenticationError = AuthenticationError;
+class PermissionDeniedError extends ApiError {
+}
+exports.PermissionDeniedError = PermissionDeniedError;
+class NotFoundError extends ApiError {
+}
+exports.NotFoundError = NotFoundError;
+class RateLimitError extends ApiError {
+}
+exports.RateLimitError = RateLimitError;
+function errorFromResponse(status, body, requestId, retryAfter) {
+    const message = extractMessage(body) ?? `LIKYLY API error (HTTP ${status})`;
+    const details = { statusCode: status, requestId, retryAfter, body };
+    switch (status) {
+        case 401:
+            return new AuthenticationError(message, details);
+        case 403:
+            return new PermissionDeniedError(message, details);
+        case 404:
+            return new NotFoundError(message, details);
+        case 422:
+            return new ValidationError(message, details);
+        case 429:
+            return new RateLimitError(message, details);
+        default:
+            return new ApiError(message, details);
+    }
+}
+function extractMessage(body) {
+    if (body && typeof body === "object" && "detail" in body) {
+        const detail = body.detail;
+        if (typeof detail === "string")
+            return detail;
+        if (Array.isArray(detail)) {
+            return detail
+                .map((d) => (d && typeof d === "object" && "msg" in d ? String(d.msg) : JSON.stringify(d)))
+                .join("; ");
+        }
+        return JSON.stringify(detail);
+    }
+    return undefined;
+}