@likyly/sdk 0.0.0-stage → 1.1.1

package/dist/esm/resources/placements.js

@@ -0,0 +1,93 @@
+import { compact, encodeSegment, requireId } from "../encoding.js";
+import { toRecommendedItem } from "./recommendations.js";
+import { LikylyError, NetworkError, PausedError, RateLimitError, TimeoutError } from "../errors.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 class PlacementsResource {
+    http;
+    cache;
+    constructor(http, 
+    /** null when the client was built with `cache: false`. */
+    cache = null) {
+        this.http = http;
+        this.cache = cache;
+    }
+    /**
+     * 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.
+     */
+    async recommend(opts, options) {
+        const placement = requireId(opts.placement, "placement");
+        const body = compact({ context: contextBody(opts.context), limit: opts.limit });
+        const key = this.cache ? cacheKey(placement, body) : "";
+        const cached = this.cache?.get(key);
+        if (cached)
+            return cached;
+        if (this.cache?.isPaused()) {
+            throw new PausedError(`LIKYLY did not answer a moment ago: calls resume in ${this.cache.pauseRemaining()}s`);
+        }
+        try {
+            const res = await this.http.request({
+                method: "POST",
+                path: `/placements/${encodeSegment(placement)}/recommend`,
+                body,
+                // A read in effect, but each call mints a fresh recommendationId server-side - repeating
+                // it on retry is exactly what you'd want for a dropped connection, not a duplicate write.
+                idempotent: true,
+                options,
+            });
+            const result = toPlacementRecommendation(res.data);
+            this.cache?.recordSuccess();
+            this.cache?.set(key, result);
+            return result;
+        }
+        catch (error) {
+            if (isOutage(error))
+                this.cache?.recordFailure();
+            throw error;
+        }
+    }
+}
+function contextBody(context) {
+    if (!context)
+        return undefined;
+    return compact({
+        current_item_id: context.itemId,
+        category_id: context.categoryId,
+        collection_id: context.collectionId,
+        user_id: context.userId,
+        anonymous_id: context.anonymousId,
+        session_id: context.sessionId,
+        cart_item_ids: context.cartItemIds,
+        locale: context.locale,
+        custom_context: context.customContext,
+    });
+}
+function toPlacementRecommendation(w) {
+    return {
+        recommendationId: w.recommendation_id,
+        placement: w.placement,
+        strategyUsed: w.strategy_used,
+        items: w.items.map(toRecommendedItem),
+    };
+}
+/** Same placement, limit and context = same answer; who the anonymous visitor is does not count. */
+function cacheKey(placement, body) {
+    const context = { ...(body.context ?? {}) };
+    delete context.session_id;
+    delete context.anonymous_id;
+    const sorted = Object.fromEntries(Object.entries(context).sort(([a], [b]) => a.localeCompare(b)));
+    return `${placement}|${body.limit ?? ""}|${JSON.stringify(sorted)}`;
+}
+/** LIKYLY down or overloaded, as opposed to a mistake in the call (4xx). */
+function isOutage(error) {
+    if (error instanceof NetworkError || error instanceof TimeoutError || error instanceof RateLimitError)
+        return true;
+    return error instanceof LikylyError && (error.statusCode ?? 0) >= 500;
+}

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

@@ -0,0 +1,54 @@
+import type { HttpClient } from "../http.js";
+import type { CollaborativeOptions, Explanation, HybridOptions, PopularOptions, RecommendationRequest, RecommendationResponse, RecommendedItem, RequestOptions, SessionOptions, SimilarOptions } from "../types.js";
+/**
+ * `likyly.recommendations`. Use {@link get}: send what you know and LIKYLY picks the best strategy.
+ * The other methods are the *Advanced Recommendations* - one strategy at a time.
+ */
+export declare class RecommendationsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Recommendations for a user, an anonymous session, an item being viewed, viewed items - or
+     * nothing at all (then you get what is popular). You never choose the algorithm; `strategy` in the
+     * response says what was used. Send `recommendationId` back on the events that follow.
+     */
+    get(request?: RecommendationRequest, options?: RequestOptions): Promise<RecommendationResponse>;
+    /** The most popular items - the fallback for a visitor with no history at all. */
+    popular(opts?: PopularOptions, options?: RequestOptions): Promise<RecommendationResponse>;
+    /** Items similar to one item (content similarity). No user needed. */
+    similar(opts: SimilarOptions, options?: RequestOptions): Promise<RecommendationResponse>;
+    /** Collaborative filtering: what users with similar histories liked. Needs a trained model. */
+    collaborative(opts: CollaborativeOptions, options?: RequestOptions): Promise<RecommendationResponse>;
+    /** Similar items, personalized for a user. `alpha` (0-1) weighs the collaborative signal against content similarity. */
+    hybrid(opts: HybridOptions, options?: RequestOptions): Promise<RecommendationResponse>;
+    /**
+     * Recency-weighted recommendations from what was viewed: pass `viewedItemIds` (an explicit list,
+     * oldest first) **or** `userId` (LIKYLY's own history of that user's views) - exactly one.
+     */
+    session(opts: SessionOptions, options?: RequestOptions): Promise<RecommendationResponse>;
+    private advanced;
+}
+export interface WireExplanation {
+    reason: string;
+    content_similarity?: number | null;
+    semantic_similarity?: number | null;
+    popularity_score?: number | null;
+    interaction_count?: number | null;
+    interaction_label?: string | null;
+    collaborative_score?: number | null;
+    source_item_ids?: string[] | null;
+    similar_users?: {
+        user_id: string;
+        shared_item_ids?: string[];
+    }[] | null;
+}
+export interface WireRecommendedItem {
+    item_id: string;
+    score?: number | null;
+    title?: string | null;
+    description?: string | null;
+    properties?: Record<string, unknown>;
+    explanation?: WireExplanation | null;
+}
+export declare function toExplanation(w: WireExplanation): Explanation;
+export declare function toRecommendedItem(w: WireRecommendedItem): RecommendedItem;

package/dist/esm/resources/recommendations.js

@@ -0,0 +1,124 @@
+import { compact, encodeSegment, requireId, requirePathSafeId } from "../encoding.js";
+import { ValidationError } from "../errors.js";
+const DEFAULT_LIMIT = 10;
+/**
+ * `likyly.recommendations`. Use {@link get}: send what you know and LIKYLY picks the best strategy.
+ * The other methods are the *Advanced Recommendations* - one strategy at a time.
+ */
+export class RecommendationsResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Recommendations for a user, an anonymous session, an item being viewed, viewed items - or
+     * nothing at all (then you get what is popular). You never choose the algorithm; `strategy` in the
+     * response says what was used. Send `recommendationId` back on the events that follow.
+     */
+    async get(request = {}, options) {
+        const res = await this.http.request({
+            method: "POST",
+            path: "/getRec",
+            body: compact({
+                user_id: request.userId !== undefined ? requireId(request.userId, "userId") : undefined,
+                session_id: request.sessionId !== undefined ? requireId(request.sessionId, "sessionId") : undefined,
+                item_id: request.itemId !== undefined ? requireId(request.itemId, "itemId") : undefined,
+                viewed_item_ids: request.viewedItemIds?.map((id) => requireId(id, "viewedItemIds[]")),
+                placement: request.placement,
+                count: request.limit,
+                debug: request.debug,
+            }),
+            idempotent: true, // a read: repeating it only mints another recommendationId
+            options,
+        });
+        return toRecommendation(res.data);
+    }
+    // ---- Advanced Recommendations ------------------------------------------------------------
+    // One strategy at a time, for expert use. Ids travel in the URL path here, so they cannot contain "/".
+    /** The most popular items - the fallback for a visitor with no history at all. */
+    async popular(opts = {}, options) {
+        return this.advanced(`/getRec/popular/${limitOf(opts)}`, opts, {}, options);
+    }
+    /** Items similar to one item (content similarity). No user needed. */
+    async similar(opts, options) {
+        return this.advanced(`/getRec/content/${encodeSegment(requirePathSafeId(opts.itemId, "itemId"))}/${limitOf(opts)}`, opts, {}, options);
+    }
+    /** Collaborative filtering: what users with similar histories liked. Needs a trained model. */
+    async collaborative(opts, options) {
+        return this.advanced(`/getRec/collaborative/${encodeSegment(requirePathSafeId(opts.userId, "userId"))}/${limitOf(opts)}`, opts, {}, options);
+    }
+    /** Similar items, personalized for a user. `alpha` (0-1) weighs the collaborative signal against content similarity. */
+    async hybrid(opts, options) {
+        const path = `/getRec/hybrid/${encodeSegment(requirePathSafeId(opts.userId, "userId"))}/${encodeSegment(requirePathSafeId(opts.itemId, "itemId"))}/${limitOf(opts)}`;
+        return this.advanced(path, opts, { alpha: opts.alpha }, options);
+    }
+    /**
+     * Recency-weighted recommendations from what was viewed: pass `viewedItemIds` (an explicit list,
+     * oldest first) **or** `userId` (LIKYLY's own history of that user's views) - exactly one.
+     */
+    async session(opts, options) {
+        const hasList = opts.viewedItemIds !== undefined;
+        const hasUser = opts.userId !== undefined;
+        if (hasList === hasUser)
+            throw new ValidationError("session() needs either viewedItemIds or userId (exactly one)");
+        if (hasUser) {
+            return this.advanced(`/getRec/sessionForUser/${encodeSegment(requirePathSafeId(opts.userId, "userId"))}/${limitOf(opts)}`, opts, {}, options);
+        }
+        const ids = (opts.viewedItemIds ?? []).map((id) => requireId(id, "viewedItemIds[]"));
+        if (ids.length === 0)
+            throw new ValidationError("viewedItemIds must contain at least one item id");
+        if (ids.some((id) => id.includes(","))) {
+            throw new ValidationError('an item id containing "," cannot be sent in this endpoint\'s comma-separated list - use recommendations.get()');
+        }
+        return this.advanced("/getRec/session", opts, { viewed_item_ids: ids.join(","), count: limitOf(opts) }, options);
+    }
+    async advanced(path, opts, extra, options) {
+        const res = await this.http.request({
+            method: "GET",
+            path,
+            // response_format=object: always the same {recommendation_id, strategy, items} envelope
+            query: { response_format: "object", placement: opts.placement, session_id: opts.sessionId, ...extra },
+            idempotent: true,
+            options,
+        });
+        return toRecommendation(res.data);
+    }
+}
+function limitOf(opts) {
+    const limit = opts.limit ?? DEFAULT_LIMIT;
+    if (!Number.isInteger(limit) || limit < 1)
+        throw new ValidationError("limit must be a positive integer");
+    return limit;
+}
+const opt = (v) => (v === null || v === undefined ? undefined : v);
+export function toExplanation(w) {
+    return {
+        reason: w.reason,
+        contentSimilarity: opt(w.content_similarity),
+        semanticSimilarity: opt(w.semantic_similarity),
+        popularityScore: opt(w.popularity_score),
+        interactionCount: opt(w.interaction_count),
+        interactionLabel: opt(w.interaction_label),
+        collaborativeScore: opt(w.collaborative_score),
+        sourceItemIds: opt(w.source_item_ids),
+        similarUsers: w.similar_users?.map((u) => ({ userId: u.user_id, sharedItemIds: u.shared_item_ids ?? [] })),
+    };
+}
+export function toRecommendedItem(w) {
+    return {
+        itemId: w.item_id,
+        score: opt(w.score),
+        title: opt(w.title),
+        description: opt(w.description),
+        properties: w.properties ?? {},
+        explanation: w.explanation ? toExplanation(w.explanation) : undefined,
+    };
+}
+function toRecommendation(w) {
+    return {
+        recommendationId: w.recommendation_id,
+        strategy: w.strategy,
+        placement: opt(w.placement),
+        items: w.items.map(toRecommendedItem),
+    };
+}

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

@@ -0,0 +1,19 @@
+import type { HttpClient } from "../http.js";
+import type { BatchResult, ListOptions, RequestOptions, User, UserImport, UserInput, UserList } from "../types.js";
+/**
+ * `likyly.users` - optional user profiles. Needs the **secret** API key (profiles are personal data).
+ * You don't have to create a user before sending events for them.
+ */
+export declare class UsersResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    get(userId: string, options?: RequestOptions): Promise<User>;
+    /** One page of users. Pagination is `limit` + `offset`; without `limit` the API returns every user. */
+    list(listOptions?: ListOptions, options?: RequestOptions): Promise<UserList>;
+    /** Creates or replaces the profile (idempotent). `properties` is free-form: country, segment, language, ... */
+    upsert(userId: string, user?: UserInput, options?: RequestOptions): Promise<User>;
+    /** Erases the user: the profile **and every event recorded for them**. */
+    delete(userId: string, options?: RequestOptions): Promise<void>;
+    /** Batch upsert (1-1000 users). A failing entry is reported in `errors`. */
+    import(users: UserImport[], options?: RequestOptions): Promise<BatchResult>;
+}

package/dist/esm/resources/users.js

@@ -0,0 +1,60 @@
+import { compact, encodeSegment, requireId } from "../encoding.js";
+import { ValidationError } from "../errors.js";
+import { toBatch } from "./items.js";
+/**
+ * `likyly.users` - optional user profiles. Needs the **secret** API key (profiles are personal data).
+ * You don't have to create a user before sending events for them.
+ */
+export class UsersResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    async get(userId, options) {
+        const res = await this.http.request({ method: "GET", path: `/users/${encodeSegment(requireId(userId, "userId"))}`, idempotent: true, options });
+        return toUser(res.data);
+    }
+    /** One page of users. Pagination is `limit` + `offset`; without `limit` the API returns every user. */
+    async list(listOptions = {}, options) {
+        const res = await this.http.request({
+            method: "GET",
+            path: "/users",
+            query: { limit: listOptions.limit, offset: listOptions.offset },
+            idempotent: true,
+            options,
+        });
+        const total = res.headers.get("x-total-count");
+        return { users: res.data.map(toUser), total: total === null ? undefined : Number(total), limit: listOptions.limit, offset: listOptions.offset ?? 0 };
+    }
+    /** Creates or replaces the profile (idempotent). `properties` is free-form: country, segment, language, ... */
+    async upsert(userId, user = {}, options) {
+        const res = await this.http.request({
+            method: "PUT",
+            path: `/users/${encodeSegment(requireId(userId, "userId"))}`,
+            body: compact({ properties: user.properties }),
+            idempotent: true,
+            options,
+        });
+        return toUser(res.data);
+    }
+    /** Erases the user: the profile **and every event recorded for them**. */
+    async delete(userId, options) {
+        await this.http.request({ method: "DELETE", path: `/users/${encodeSegment(requireId(userId, "userId"))}`, idempotent: true, options });
+    }
+    /** Batch upsert (1-1000 users). A failing entry is reported in `errors`. */
+    async import(users, options) {
+        if (!Array.isArray(users) || users.length === 0)
+            throw new ValidationError("users must be a non-empty array");
+        const res = await this.http.request({
+            method: "POST",
+            path: "/users/import",
+            body: { users: users.map((u) => ({ user_id: requireId(u.userId, "userId"), ...compact({ properties: u.properties }) })) },
+            idempotent: true,
+            options,
+        });
+        return toBatch(res.data);
+    }
+}
+function toUser(w) {
+    return { userId: w.user_id, properties: w.properties ?? {} };
+}

package/dist/esm/session.d.ts

@@ -0,0 +1,32 @@
+import type { Likyly } from "./client.js";
+import type { IdentifyResult } from "./types.js";
+export interface LikylySessionOptions {
+    /** Override the localStorage key - e.g. to namespace multiple LIKYLY-powered apps on one domain. Defaults to "likyly_anonymous_id". */
+    storageKey?: string;
+}
+/**
+ * A first-party, cookieless anonymous visitor id - generated once per browser and persisted in
+ * `localStorage` (never a third-party cookie, never sent to anyone but LIKYLY). Use it as
+ * `context.anonymousId` / `sessionId` for recommendations and event tracking until the visitor
+ * is identified, then call {@link identify} to attach their history to the now-known user.
+ *
+ * SSR-safe: every method degrades to a no-op (`undefined`) outside a real browser (no
+ * `window`/`localStorage`, private-mode storage that throws, ...) rather than throwing - a
+ * server-rendered pass simply has no anonymous id yet, which is correct, not an error.
+ */
+export declare class LikylySession {
+    private readonly storageKey;
+    private cachedId;
+    constructor(options?: LikylySessionOptions);
+    /** The visitor's anonymous id, creating and persisting one on first call. `undefined` when
+     * there is nowhere to persist it (SSR, Node, storage disabled). */
+    getAnonymousId(): string | undefined;
+    /**
+     * Call once you know the visitor's `userId` (e.g. right after login): attaches this
+     * session's *past* interactions to them server-side (`likyly.events.identify`), so they
+     * count as that user's history from then on. Safe to call more than once, and safe even if
+     * there is no anonymous id yet (a no-op). Both `userId` and the anonymous id remain fine to
+     * keep sending together afterwards - this doesn't need to be the last time you use either.
+     */
+    identify(likyly: Pick<Likyly, "events">, userId: string): Promise<IdentifyResult | undefined>;
+}

package/dist/esm/session.js

@@ -0,0 +1,72 @@
+const DEFAULT_STORAGE_KEY = "likyly_anonymous_id";
+/**
+ * A first-party, cookieless anonymous visitor id - generated once per browser and persisted in
+ * `localStorage` (never a third-party cookie, never sent to anyone but LIKYLY). Use it as
+ * `context.anonymousId` / `sessionId` for recommendations and event tracking until the visitor
+ * is identified, then call {@link identify} to attach their history to the now-known user.
+ *
+ * SSR-safe: every method degrades to a no-op (`undefined`) outside a real browser (no
+ * `window`/`localStorage`, private-mode storage that throws, ...) rather than throwing - a
+ * server-rendered pass simply has no anonymous id yet, which is correct, not an error.
+ */
+export class LikylySession {
+    storageKey;
+    cachedId;
+    constructor(options = {}) {
+        this.storageKey = options.storageKey ?? DEFAULT_STORAGE_KEY;
+    }
+    /** The visitor's anonymous id, creating and persisting one on first call. `undefined` when
+     * there is nowhere to persist it (SSR, Node, storage disabled). */
+    getAnonymousId() {
+        if (this.cachedId)
+            return this.cachedId;
+        const storage = safeLocalStorage();
+        if (!storage)
+            return undefined;
+        try {
+            let id = storage.getItem(this.storageKey);
+            if (!id) {
+                id = generateAnonymousId();
+                storage.setItem(this.storageKey, id);
+            }
+            this.cachedId = id;
+            return id;
+        }
+        catch {
+            return undefined; // full/blocked storage - degrade to "no session", never throw
+        }
+    }
+    /**
+     * Call once you know the visitor's `userId` (e.g. right after login): attaches this
+     * session's *past* interactions to them server-side (`likyly.events.identify`), so they
+     * count as that user's history from then on. Safe to call more than once, and safe even if
+     * there is no anonymous id yet (a no-op). Both `userId` and the anonymous id remain fine to
+     * keep sending together afterwards - this doesn't need to be the last time you use either.
+     */
+    async identify(likyly, userId) {
+        const sessionId = this.getAnonymousId();
+        if (!sessionId)
+            return undefined;
+        return likyly.events.identify({ userId, sessionId });
+    }
+}
+function safeLocalStorage() {
+    try {
+        const storage = globalThis.localStorage;
+        if (!storage)
+            return undefined;
+        const probeKey = "__likyly_probe__";
+        storage.setItem(probeKey, "1"); // some private-mode browsers only throw on write, not on presence
+        storage.removeItem(probeKey);
+        return storage;
+    }
+    catch {
+        return undefined;
+    }
+}
+function generateAnonymousId() {
+    const cryptoObj = globalThis.crypto;
+    if (typeof cryptoObj?.randomUUID === "function")
+        return `anon_${cryptoObj.randomUUID()}`;
+    return `anon_${Date.now().toString(36)}${Math.random().toString(36).slice(2)}`;
+}