@likyly/sdk 0.0.0-stage → 1.1.1

package/dist/cjs/resources/items.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ItemsResource = void 0;
+exports.toItem = toItem;
+exports.toBatch = toBatch;
+const encoding_js_1 = require("../encoding.js");
+const errors_js_1 = require("../errors.js");
+/** `likyly.items` - your catalog. Needs the **secret** API key. */
+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/${(0, encoding_js_1.encodeSegment)((0, encoding_js_1.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/${(0, encoding_js_1.encodeSegment)((0, encoding_js_1.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/${(0, encoding_js_1.encodeSegment)((0, encoding_js_1.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 errors_js_1.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: (0, encoding_js_1.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 errors_js_1.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) => (0, encoding_js_1.requireId)(id, "itemId")) },
+            idempotent: true,
+            options,
+        });
+        return toBatch(res.data);
+    }
+}
+exports.ItemsResource = ItemsResource;
+function itemBody(item) {
+    if (item === null || typeof item !== "object" || typeof item.title !== "string" || item.title === "") {
+        throw new errors_js_1.ValidationError("an item needs a non-empty title");
+    }
+    return (0, encoding_js_1.compact)({ title: item.title, description: item.description, properties: item.properties });
+}
+function toItem(w) {
+    return { itemId: w.item_id, title: w.title, description: w.description ?? undefined, properties: w.properties ?? {} };
+}
+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/cjs/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>;
+}

package/dist/cjs/resources/placements.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlacementsResource = void 0;
+const encoding_js_1 = require("../encoding.js");
+const recommendations_js_1 = require("./recommendations.js");
+const errors_js_1 = require("../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.
+ */
+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 = (0, encoding_js_1.requireId)(opts.placement, "placement");
+        const body = (0, encoding_js_1.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 errors_js_1.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/${(0, encoding_js_1.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;
+        }
+    }
+}
+exports.PlacementsResource = PlacementsResource;
+function contextBody(context) {
+    if (!context)
+        return undefined;
+    return (0, encoding_js_1.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(recommendations_js_1.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 errors_js_1.NetworkError || error instanceof errors_js_1.TimeoutError || error instanceof errors_js_1.RateLimitError)
+        return true;
+    return error instanceof errors_js_1.LikylyError && (error.statusCode ?? 0) >= 500;
+}

package/dist/cjs/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/cjs/resources/recommendations.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecommendationsResource = void 0;
+exports.toExplanation = toExplanation;
+exports.toRecommendedItem = toRecommendedItem;
+const encoding_js_1 = require("../encoding.js");
+const errors_js_1 = require("../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.
+ */
+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: (0, encoding_js_1.compact)({
+                user_id: request.userId !== undefined ? (0, encoding_js_1.requireId)(request.userId, "userId") : undefined,
+                session_id: request.sessionId !== undefined ? (0, encoding_js_1.requireId)(request.sessionId, "sessionId") : undefined,
+                item_id: request.itemId !== undefined ? (0, encoding_js_1.requireId)(request.itemId, "itemId") : undefined,
+                viewed_item_ids: request.viewedItemIds?.map((id) => (0, encoding_js_1.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/${(0, encoding_js_1.encodeSegment)((0, encoding_js_1.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/${(0, encoding_js_1.encodeSegment)((0, encoding_js_1.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/${(0, encoding_js_1.encodeSegment)((0, encoding_js_1.requirePathSafeId)(opts.userId, "userId"))}/${(0, encoding_js_1.encodeSegment)((0, encoding_js_1.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 errors_js_1.ValidationError("session() needs either viewedItemIds or userId (exactly one)");
+        if (hasUser) {
+            return this.advanced(`/getRec/sessionForUser/${(0, encoding_js_1.encodeSegment)((0, encoding_js_1.requirePathSafeId)(opts.userId, "userId"))}/${limitOf(opts)}`, opts, {}, options);
+        }
+        const ids = (opts.viewedItemIds ?? []).map((id) => (0, encoding_js_1.requireId)(id, "viewedItemIds[]"));
+        if (ids.length === 0)
+            throw new errors_js_1.ValidationError("viewedItemIds must contain at least one item id");
+        if (ids.some((id) => id.includes(","))) {
+            throw new errors_js_1.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);
+    }
+}
+exports.RecommendationsResource = RecommendationsResource;
+function limitOf(opts) {
+    const limit = opts.limit ?? DEFAULT_LIMIT;
+    if (!Number.isInteger(limit) || limit < 1)
+        throw new errors_js_1.ValidationError("limit must be a positive integer");
+    return limit;
+}
+const opt = (v) => (v === null || v === undefined ? undefined : v);
+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 ?? [] })),
+    };
+}
+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/cjs/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/cjs/resources/users.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UsersResource = void 0;
+const encoding_js_1 = require("../encoding.js");
+const errors_js_1 = require("../errors.js");
+const items_js_1 = require("./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.
+ */
+class UsersResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    async get(userId, options) {
+        const res = await this.http.request({ method: "GET", path: `/users/${(0, encoding_js_1.encodeSegment)((0, encoding_js_1.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/${(0, encoding_js_1.encodeSegment)((0, encoding_js_1.requireId)(userId, "userId"))}`,
+            body: (0, encoding_js_1.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/${(0, encoding_js_1.encodeSegment)((0, encoding_js_1.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 errors_js_1.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: (0, encoding_js_1.requireId)(u.userId, "userId"), ...(0, encoding_js_1.compact)({ properties: u.properties }) })) },
+            idempotent: true,
+            options,
+        });
+        return (0, items_js_1.toBatch)(res.data);
+    }
+}
+exports.UsersResource = UsersResource;
+function toUser(w) {
+    return { userId: w.user_id, properties: w.properties ?? {} };
+}

package/dist/cjs/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/cjs/session.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LikylySession = void 0;
+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.
+ */
+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 });
+    }
+}
+exports.LikylySession = LikylySession;
+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)}`;
+}