@likyly/sdk 0.0.0-stage → 1.1.1

package/dist/cjs/types.d.ts

@@ -0,0 +1,226 @@
+/** Free-form JSON object: price, currency, orderId, category, any field of your own. Keys are stored exactly as you send them. */
+export type Properties = Record<string, unknown>;
+export interface Item {
+    /** Your own identifier - any string (`SKU-123`, a UUID, `gid://shopify/Product/123`). */
+    itemId: string;
+    title: string;
+    description?: string;
+    properties: Properties;
+}
+/** What you send to create or replace an item. Only `title` is required. */
+export interface ItemInput {
+    title: string;
+    description?: string;
+    /** `category` and `description` feed content similarity; everything else is stored as is. */
+    properties?: Properties;
+}
+export interface ItemImport extends ItemInput {
+    itemId: string;
+}
+export interface ListOptions {
+    /** Page size (1-1000, default 100). */
+    limit?: number;
+    /** Rows to skip. */
+    offset?: number;
+}
+export interface ItemList {
+    items: Item[];
+    /** Total number of items in the catalog (`X-Total-Count`), when the API reported it. */
+    total?: number;
+    /** The page size you asked for (undefined = the API's default). */
+    limit?: number;
+    offset: number;
+}
+export interface User {
+    userId: string;
+    properties: Properties;
+}
+export interface UserInput {
+    /** country, segment, language, ... - whatever describes your users. */
+    properties?: Properties;
+}
+export interface UserImport extends UserInput {
+    userId: string;
+}
+export interface UserList {
+    users: User[];
+    total?: number;
+    limit?: number;
+    offset: number;
+}
+/** Result of a batch call. A failing entry is reported in `errors`, it does not throw. */
+export interface BatchResult {
+    received: number;
+    succeeded: number;
+    failed: number;
+    errors: {
+        index: number;
+        id?: string;
+        message: string;
+    }[];
+}
+/**
+ * An interaction. `itemId` and at least one of `userId` / `sessionId` are required; sending both
+ * ties an anonymous session to the user.
+ */
+export interface EventInput {
+    itemId: string;
+    userId?: string;
+    /** Anonymous visitor / browsing session - no login needed. */
+    sessionId?: string;
+    /** The `recommendationId` of the recommendation that surfaced this item - enables attribution. */
+    recommendationId?: string;
+    /** Free-form label of where this happened: `homepage`, `product_page`, `cart`, ... */
+    placement?: string;
+    quantity?: number;
+    /** ISO 8601 string or Date. Defaults to the server's time. */
+    occurredAt?: string | Date;
+    properties?: Properties;
+    /**
+     * Idempotency key, unique per account: replaying an event with the same `eventId` records nothing
+     * and returns `duplicate: true`. Set it on purchases - it makes retries safe.
+     */
+    eventId?: string;
+}
+/** An event of any type, for `events.trackMany`. `type` is an open string (`view`, `favorite`, ...). */
+export interface TypedEventInput extends EventInput {
+    type: string;
+}
+export interface EventResult {
+    message: string;
+    eventId?: string;
+    /** True if this `eventId` was already recorded - nothing was written. */
+    duplicate: boolean;
+}
+export interface EventBatchResult {
+    received: number;
+    accepted: number;
+    /** Events skipped because their `eventId` was already recorded. */
+    duplicates: number;
+}
+/** Call right after login/signup, once you know `userId`, for the `sessionId` the visitor was
+ * anonymous under - see `events.identify`. */
+export interface IdentifyInput {
+    userId: string;
+    sessionId: string;
+}
+export interface IdentifyResult {
+    /** How many of this session's past interactions now belong to `userId`. */
+    linkedInteractions: number;
+}
+/** Send whatever you know: LIKYLY chooses the best strategy. All fields are optional. */
+export interface RecommendationRequest {
+    userId?: string;
+    sessionId?: string;
+    /** The item being looked at (e.g. the product page). */
+    itemId?: string;
+    /** Recently viewed items, oldest first. */
+    viewedItemIds?: string[];
+    /** Free-form label of where the recommendations will be shown. */
+    placement?: string;
+    /** How many items to return (1-100, default 10). */
+    limit?: number;
+    /** Diagnostic detail in `explanation`. Secret key only. */
+    debug?: boolean;
+}
+export interface SimilarUser {
+    userId: string;
+    sharedItemIds: string[];
+}
+export interface Explanation {
+    reason: string;
+    contentSimilarity?: number;
+    semanticSimilarity?: number;
+    popularityScore?: number;
+    interactionCount?: number;
+    interactionLabel?: string;
+    collaborativeScore?: number;
+    sourceItemIds?: string[];
+    /** Only with `debug` and a secret key. */
+    similarUsers?: SimilarUser[];
+}
+export interface RecommendedItem {
+    itemId: string;
+    score?: number;
+    title?: string;
+    description?: string;
+    properties: Properties;
+    explanation?: Explanation;
+}
+export interface RecommendationResponse {
+    /** Send it back on the impression / click / add_to_cart / purchase events for these items. */
+    recommendationId: string;
+    /** What LIKYLY used: `hybrid`, `content`, `collaborative`, `session` or `popular`. */
+    strategy: string;
+    placement?: string;
+    items: RecommendedItem[];
+}
+interface AdvancedBase {
+    placement?: string;
+    /** Attach the recommendation to an anonymous session, for attribution. */
+    sessionId?: string;
+    /** How many items to return (default 10). */
+    limit?: number;
+}
+export interface PopularOptions extends AdvancedBase {
+}
+export interface SimilarOptions extends AdvancedBase {
+    itemId: string;
+}
+export interface CollaborativeOptions extends AdvancedBase {
+    userId: string;
+}
+export interface HybridOptions extends AdvancedBase {
+    userId: string;
+    itemId: string;
+    /** Weight of the collaborative signal against content similarity: 0 = pure content, 1 = pure collaborative (default 0.5). */
+    alpha?: number;
+}
+/** Give `viewedItemIds` (an explicit list, oldest first) OR `userId` (LIKYLY's own history of that user's views). */
+export interface SessionOptions extends AdvancedBase {
+    viewedItemIds?: string[];
+    userId?: string;
+}
+/**
+ * What you know about the moment - every field optional unless the placement's own
+ * `signals.required` names it (see `likyly.placements` and GET .../requirements).
+ */
+export interface PlacementContext {
+    /** The product/article/listing currently being viewed. */
+    itemId?: string;
+    categoryId?: string;
+    collectionId?: string;
+    /** Identified visitor. */
+    userId?: string;
+    /** Stable anonymous visitor id - used like `sessionId` when `sessionId` is omitted. See `LikylySession`. */
+    anonymousId?: string;
+    /** Anonymous browsing session. */
+    sessionId?: string;
+    cartItemIds?: string[];
+    locale?: string;
+    customContext?: Record<string, unknown>;
+}
+export interface PlacementRecommendOptions {
+    /** The placement's slug, e.g. "pdp-related". */
+    placement: string;
+    context?: PlacementContext;
+    /** Overrides the placement's own configured limit for this call. */
+    limit?: number;
+}
+export interface PlacementRecommendResponse {
+    /** Send it back on the impression / click / add_to_cart / purchase events for these items. */
+    recommendationId: string;
+    placement: string;
+    /** What the placement actually used: `hybrid`, `content`, `collaborative`, `session` or `popular`. */
+    strategyUsed: string;
+    items: RecommendedItem[];
+}
+export interface RequestOptions {
+    /** Cancel the call. */
+    signal?: AbortSignal;
+    /** Overrides the client's timeout (milliseconds) for this call. */
+    timeout?: number;
+    /** Overrides the client's retry count for this call. */
+    maxRetries?: number;
+}
+export {};

package/dist/cjs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/version.d.ts

@@ -0,0 +1,3 @@
+export declare const SDK_VERSION = "1.1.1";
+export declare const DEFAULT_BASE_URL = "https://api.likyly.com";
+export declare const USER_AGENT = "likyly-typescript/1.1.1";

package/dist/cjs/version.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.USER_AGENT = exports.DEFAULT_BASE_URL = exports.SDK_VERSION = void 0;
+exports.SDK_VERSION = "1.1.1";
+exports.DEFAULT_BASE_URL = "https://api.likyly.com";
+exports.USER_AGENT = `likyly-typescript/${exports.SDK_VERSION}`;

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

@@ -0,0 +1,81 @@
+import { ValidationError } from "./errors.js";
+import { HttpClient } from "./http.js";
+import { EventsResource } from "./resources/events.js";
+import { ItemsResource } from "./resources/items.js";
+import { PlacementsResource } from "./resources/placements.js";
+import { RecommendCache } from "./recommend-cache.js";
+import { RecommendationsResource } from "./resources/recommendations.js";
+import { UsersResource } from "./resources/users.js";
+import { DEFAULT_BASE_URL, USER_AGENT } from "./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)
+ */
+export class Likyly {
+    items;
+    users;
+    events;
+    recommendations;
+    placements;
+    constructor(options) {
+        if (!options || typeof options.apiKey !== "string" || options.apiKey.trim() === "") {
+            throw new 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 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 ValidationError("no fetch implementation found: use Node 18+ or pass options.fetch");
+        const http = new HttpClient({
+            apiKey: options.apiKey,
+            baseUrl: (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, ""),
+            catalog: options.catalog,
+            timeout: options.timeout ?? 10_000,
+            maxRetries: options.maxRetries ?? 2,
+            userAgent: options.userAgent ? `${USER_AGENT} ${options.userAgent}` : USER_AGENT,
+            fetch: fetchImpl,
+            sleep: options._internal?.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+            random: options._internal?.random ?? Math.random,
+        });
+        this.items = new ItemsResource(http);
+        this.users = new UsersResource(http);
+        this.events = new EventsResource(http);
+        this.recommendations = new RecommendationsResource(http);
+        this.placements = new PlacementsResource(http, options.cache === false ? null : new 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();
+    }
+}

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

@@ -0,0 +1,31 @@
+import { ValidationError } from "./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.
+ */
+export 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. */
+export function requireId(value, name) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new 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. */
+export function requirePathSafeId(value, name) {
+    const id = requireId(value, name);
+    if (id.includes("/")) {
+        throw new 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. */
+export function compact(obj) {
+    const out = {};
+    for (const [key, value] of Object.entries(obj))
+        if (value !== undefined)
+            out[key] = value;
+    return out;
+}

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

@@ -0,0 +1,69 @@
+export 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;
+    }
+}
+export class NetworkError extends LikylyError {
+}
+export class TimeoutError extends LikylyError {
+}
+export class ValidationError extends LikylyError {
+}
+/** LIKYLY failed moments ago: the SDK skips calls for a short pause (see `cache.pauseSeconds`). */
+export class PausedError extends LikylyError {
+}
+export class ApiError extends LikylyError {
+}
+export class AuthenticationError extends ApiError {
+}
+export class PermissionDeniedError extends ApiError {
+}
+export class NotFoundError extends ApiError {
+}
+export class RateLimitError extends ApiError {
+}
+export 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;
+}

package/dist/esm/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>;