@rudra-js/core 0.1.0

package/dist/tracking-input.d.ts

@@ -0,0 +1,258 @@
+import { z } from 'zod';
+/**
+ * The tracking-input contract — the boundary between the host application and
+ * rudra-js.
+ *
+ * rudra-js does not collect, store, or aggregate anything. The host owns its
+ * tracking pipeline (an event stream, a CDP, a warehouse) and hands the
+ * framework one JSON object per render. This module is that contract: one
+ * schema, validated at the edge, so a malformed payload fails loudly here
+ * rather than quietly producing a bad prompt several layers later.
+ *
+ * Every fixed-shape object below is a `strictObject`, so an unrecognised field
+ * is an error rather than being dropped. That matters more than it looks: with
+ * a lenient object, a host that misspells `recentSearches` gets a shopper who
+ * silently looks like a first-time visitor, and nothing anywhere reports it.
+ * The only dynamic shape is `interaction.meta`, which is a record by design.
+ */
+/**
+ * Every free-text field and every array is length-capped.
+ *
+ * These caps are not cosmetic. Host-supplied strings end up inside the prompt
+ * we send to a language model, and a model is billed per token — so an
+ * unbounded string is an unbounded bill, and an unbounded array of candidates
+ * is the same problem multiplied.
+ *
+ * What this buys is that no single field is unbounded. It is deliberately not
+ * an aggregate budget: the caps multiply out to far more than any context
+ * window, because rejecting a large-but-legitimate payload is the wrong
+ * response to one. Fitting a payload into a prompt is `digest`'s job, and it
+ * trims rather than throws.
+ */
+export declare const FIELD_LIMITS: {
+    readonly identifier: 128;
+    readonly shortText: 200;
+    readonly searchQuery: 200;
+    readonly tag: 64;
+    readonly tagsPerProduct: 20;
+    readonly metaEntries: 50;
+    readonly signalsPerCategory: 500;
+    readonly candidates: 200;
+    readonly productsPerBundle: 5;
+    readonly bundles: 20;
+};
+/** A product the generated component is permitted to place. */
+export declare const productSchema: z.ZodObject<{
+    sku: z.ZodString;
+    title: z.ZodString;
+    category: z.ZodString;
+    price: z.ZodNumber;
+    currency: z.ZodDefault<z.ZodString>;
+    imageUrl: z.ZodOptional<z.ZodString>;
+    rating: z.ZodOptional<z.ZodNumber>;
+    isInStock: z.ZodDefault<z.ZodBoolean>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type Product = z.infer<typeof productSchema>;
+/** Base shape for any signal that points at a single SKU. */
+export declare const skuSignalSchema: z.ZodObject<{
+    sku: z.ZodString;
+    category: z.ZodOptional<z.ZodString>;
+    at: z.ZodOptional<z.ZodNumber>;
+    weight: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type SkuSignal = z.infer<typeof skuSignalSchema>;
+export declare const viewSignalSchema: z.ZodObject<{
+    sku: z.ZodString;
+    category: z.ZodOptional<z.ZodString>;
+    at: z.ZodOptional<z.ZodNumber>;
+    weight: z.ZodOptional<z.ZodNumber>;
+    views: z.ZodDefault<z.ZodNumber>;
+    dwellMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type ViewSignal = z.infer<typeof viewSignalSchema>;
+export declare const purchaseSignalSchema: z.ZodObject<{
+    sku: z.ZodString;
+    category: z.ZodOptional<z.ZodString>;
+    at: z.ZodOptional<z.ZodNumber>;
+    weight: z.ZodOptional<z.ZodNumber>;
+    quantity: z.ZodDefault<z.ZodNumber>;
+    price: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type PurchaseSignal = z.infer<typeof purchaseSignalSchema>;
+/**
+ * Catch-all for everything else the shopper did. `type` is an open vocabulary
+ * on purpose — 'scroll_depth', 'wishlist', 'filter_applied', whatever the host
+ * already emits — so hosts do not have to map their events onto ours.
+ */
+export declare const interactionSchema: z.ZodObject<{
+    type: z.ZodString;
+    sku: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    at: z.ZodOptional<z.ZodNumber>;
+    value: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    meta: z.ZodOptional<z.ZodPipe<z.ZodCustom<Record<string, string | number | boolean>, Record<string, string | number | boolean>>, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>>;
+}, z.core.$strict>;
+export type Interaction = z.infer<typeof interactionSchema>;
+/** Where on the site this component is being rendered. */
+export declare const renderContextSchema: z.ZodObject<{
+    surface: z.ZodString;
+    slot: z.ZodDefault<z.ZodString>;
+    currentSku: z.ZodOptional<z.ZodString>;
+    currentCategory: z.ZodOptional<z.ZodString>;
+    searchQuery: z.ZodOptional<z.ZodString>;
+    locale: z.ZodDefault<z.ZodString>;
+    maxItems: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type RenderContext = z.infer<typeof renderContextSchema>;
+export declare const trackingSignalsSchema: z.ZodObject<{
+    likes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        sku: z.ZodString;
+        category: z.ZodOptional<z.ZodString>;
+        at: z.ZodOptional<z.ZodNumber>;
+        weight: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>>;
+    dislikes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        sku: z.ZodString;
+        category: z.ZodOptional<z.ZodString>;
+        at: z.ZodOptional<z.ZodNumber>;
+        weight: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>>;
+    mostViewed: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        sku: z.ZodString;
+        category: z.ZodOptional<z.ZodString>;
+        at: z.ZodOptional<z.ZodNumber>;
+        weight: z.ZodOptional<z.ZodNumber>;
+        views: z.ZodDefault<z.ZodNumber>;
+        dwellMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>>;
+    lastPurchased: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        sku: z.ZodString;
+        category: z.ZodOptional<z.ZodString>;
+        at: z.ZodOptional<z.ZodNumber>;
+        weight: z.ZodOptional<z.ZodNumber>;
+        quantity: z.ZodDefault<z.ZodNumber>;
+        price: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>>;
+    cart: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        sku: z.ZodString;
+        category: z.ZodOptional<z.ZodString>;
+        at: z.ZodOptional<z.ZodNumber>;
+        weight: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>>;
+    recentSearches: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    interactions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        sku: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+        at: z.ZodOptional<z.ZodNumber>;
+        value: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        meta: z.ZodOptional<z.ZodPipe<z.ZodCustom<Record<string, string | number | boolean>, Record<string, string | number | boolean>>, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type TrackingSignals = z.infer<typeof trackingSignalsSchema>;
+/** A set the shop sells together. The model never picks or invents one. */
+export declare const bundleSchema: z.ZodObject<{
+    id: z.ZodString;
+    skus: z.ZodArray<z.ZodString>;
+    price: z.ZodNumber;
+    currency: z.ZodDefault<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type Bundle = z.infer<typeof bundleSchema>;
+export declare const trackingInputSchema: z.ZodObject<{
+    schemaVersion: z.ZodDefault<z.ZodLiteral<"1">>;
+    user: z.ZodObject<{
+        id: z.ZodString;
+        segment: z.ZodOptional<z.ZodString>;
+        isReturning: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>;
+    context: z.ZodObject<{
+        surface: z.ZodString;
+        slot: z.ZodDefault<z.ZodString>;
+        currentSku: z.ZodOptional<z.ZodString>;
+        currentCategory: z.ZodOptional<z.ZodString>;
+        searchQuery: z.ZodOptional<z.ZodString>;
+        locale: z.ZodDefault<z.ZodString>;
+        maxItems: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>;
+    signals: z.ZodPrefault<z.ZodObject<{
+        likes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            sku: z.ZodString;
+            category: z.ZodOptional<z.ZodString>;
+            at: z.ZodOptional<z.ZodNumber>;
+            weight: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>>;
+        dislikes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            sku: z.ZodString;
+            category: z.ZodOptional<z.ZodString>;
+            at: z.ZodOptional<z.ZodNumber>;
+            weight: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>>;
+        mostViewed: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            sku: z.ZodString;
+            category: z.ZodOptional<z.ZodString>;
+            at: z.ZodOptional<z.ZodNumber>;
+            weight: z.ZodOptional<z.ZodNumber>;
+            views: z.ZodDefault<z.ZodNumber>;
+            dwellMs: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>>;
+        lastPurchased: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            sku: z.ZodString;
+            category: z.ZodOptional<z.ZodString>;
+            at: z.ZodOptional<z.ZodNumber>;
+            weight: z.ZodOptional<z.ZodNumber>;
+            quantity: z.ZodDefault<z.ZodNumber>;
+            price: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>>;
+        cart: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            sku: z.ZodString;
+            category: z.ZodOptional<z.ZodString>;
+            at: z.ZodOptional<z.ZodNumber>;
+            weight: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>>;
+        recentSearches: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        interactions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            type: z.ZodString;
+            sku: z.ZodOptional<z.ZodString>;
+            category: z.ZodOptional<z.ZodString>;
+            at: z.ZodOptional<z.ZodNumber>;
+            value: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+            meta: z.ZodOptional<z.ZodPipe<z.ZodCustom<Record<string, string | number | boolean>, Record<string, string | number | boolean>>, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+    candidates: z.ZodArray<z.ZodObject<{
+        sku: z.ZodString;
+        title: z.ZodString;
+        category: z.ZodString;
+        price: z.ZodNumber;
+        currency: z.ZodDefault<z.ZodString>;
+        imageUrl: z.ZodOptional<z.ZodString>;
+        rating: z.ZodOptional<z.ZodNumber>;
+        isInStock: z.ZodDefault<z.ZodBoolean>;
+        tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    bundles: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        skus: z.ZodArray<z.ZodString>;
+        price: z.ZodNumber;
+        currency: z.ZodDefault<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type TrackingInput = z.infer<typeof trackingInputSchema>;
+/** The shape a caller passes in, before defaults are applied. */
+export type TrackingInputDraft = z.input<typeof trackingInputSchema>;
+/**
+ * The result of a non-throwing parse. Exported so a consumer can type a
+ * validation failure without depending on zod directly.
+ */
+export type TrackingInputResult = z.ZodSafeParseResult<TrackingInput>;
+/**
+ * Validates a payload, throwing a `ZodError` if it does not satisfy the
+ * contract. An invalid payload is a caller bug, and it should be loud.
+ */
+export declare function parseTrackingInput(value: unknown): TrackingInput;
+/** Non-throwing variant, for callers that want to inspect the failure. */
+export declare function safeParseTrackingInput(value: unknown): TrackingInputResult;
+//# sourceMappingURL=tracking-input.d.ts.map

package/dist/tracking-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracking-input.d.ts","sourceRoot":"","sources":["../src/tracking-input.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,YAAY;aACvB,UAAU,EAAE,GAAG;aACf,SAAS,EAAE,GAAG;aACd,WAAW,EAAE,GAAG;aAChB,GAAG,EAAE,EAAE;aACP,cAAc,EAAE,EAAE;aAClB,WAAW,EAAE,EAAE;aACf,kBAAkB,EAAE,GAAG;aACvB,UAAU,EAAE,GAAG;aACf,iBAAiB,EAAE,CAAC;aACpB,OAAO,EAAE,EAAE;CACH,CAAC;AAmCX,+DAA+D;AAC/D,eAAO,MAAM,aAAa;;;;;;;;;;kBAoBxB,CAAC;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAEpD,6DAA6D;AAC7D,eAAO,MAAM,eAAe;;;;;kBAM1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,eAAO,MAAM,gBAAgB;;;;;;;kBAG3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,oBAAoB;;;;;;;kBAG/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAkClE;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;;;;;;;kBAO5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,0DAA0D;AAC1D,eAAO,MAAM,mBAAmB;;;;;;;;kBAW9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAKhE,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAQhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,2EAA2E;AAC3E,eAAO,MAAM,YAAY;;;;;;kBAiBvB,CAAC;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAElD,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAqD7B,CAAC;AAEJ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,iEAAiE;AACjE,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAErE;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,kBAAkB,CAAC,aAAa,CAAC,CAAC;AAEtE;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,CAEhE;AAED,0EAA0E;AAC1E,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAE1E"}

package/dist/tracking-input.js

@@ -0,0 +1,241 @@
+import { z } from 'zod';
+/**
+ * The tracking-input contract — the boundary between the host application and
+ * rudra-js.
+ *
+ * rudra-js does not collect, store, or aggregate anything. The host owns its
+ * tracking pipeline (an event stream, a CDP, a warehouse) and hands the
+ * framework one JSON object per render. This module is that contract: one
+ * schema, validated at the edge, so a malformed payload fails loudly here
+ * rather than quietly producing a bad prompt several layers later.
+ *
+ * Every fixed-shape object below is a `strictObject`, so an unrecognised field
+ * is an error rather than being dropped. That matters more than it looks: with
+ * a lenient object, a host that misspells `recentSearches` gets a shopper who
+ * silently looks like a first-time visitor, and nothing anywhere reports it.
+ * The only dynamic shape is `interaction.meta`, which is a record by design.
+ */
+/**
+ * Every free-text field and every array is length-capped.
+ *
+ * These caps are not cosmetic. Host-supplied strings end up inside the prompt
+ * we send to a language model, and a model is billed per token — so an
+ * unbounded string is an unbounded bill, and an unbounded array of candidates
+ * is the same problem multiplied.
+ *
+ * What this buys is that no single field is unbounded. It is deliberately not
+ * an aggregate budget: the caps multiply out to far more than any context
+ * window, because rejecting a large-but-legitimate payload is the wrong
+ * response to one. Fitting a payload into a prompt is `digest`'s job, and it
+ * trims rather than throws.
+ */
+export const FIELD_LIMITS = {
+    identifier: 128,
+    shortText: 200,
+    searchQuery: 200,
+    tag: 64,
+    tagsPerProduct: 20,
+    metaEntries: 50,
+    signalsPerCategory: 500,
+    candidates: 200,
+    productsPerBundle: 5,
+    bundles: 20,
+};
+/** Assigning this as an object key mutates the prototype instead of the object. */
+const RESERVED_META_KEY = '__proto__';
+/** Upper bound on any timestamp: 2100-01-01. */
+const MAX_EPOCH_MS = Date.UTC(2100, 0, 1);
+const identifier = () => z.string().min(1).max(FIELD_LIMITS.identifier);
+const optionalIdentifier = () => z.string().min(1).max(FIELD_LIMITS.identifier).optional();
+/**
+ * Epoch milliseconds, used only for recency ordering. Bounded because a
+ * negative or year-3000 timestamp does not fail anywhere downstream — it just
+ * sorts to one end and silently reorders the shopper's history.
+ */
+const epochMs = () => z.number().int().min(0).max(MAX_EPOCH_MS).optional();
+/**
+ * An absolute http(s) URL, or a root-relative path such as `/images/tr-102.png`.
+ * Anything else — a bare word, a `javascript:` URI, a protocol-relative `//host`
+ * — is rejected before it can reach an `<img src>`.
+ */
+const imageReference = () => z
+    .string()
+    .max(FIELD_LIMITS.shortText)
+    .refine((value) => value.startsWith('/') && !value.startsWith('//')
+    ? true
+    : z.url({ protocol: /^https?$/ }).safeParse(value).success, { message: 'expected an http(s) URL or a root-relative path' });
+/** A product the generated component is permitted to place. */
+export const productSchema = z.strictObject({
+    sku: identifier(),
+    title: z.string().min(1).max(FIELD_LIMITS.shortText),
+    category: identifier(),
+    price: z.number().nonnegative(),
+    currency: z
+        .string()
+        .regex(/^[A-Z]{3}$/, 'expected a three-letter ISO 4217 code')
+        .default('USD'),
+    // This lands in an `<img src>` the host did not write, so the scheme matters:
+    // a bare capped string would accept '' and 'javascript:'. Root-relative paths
+    // are allowed because most catalogs store images that way, and they carry no
+    // scheme to abuse.
+    imageUrl: imageReference().optional(),
+    rating: z.number().min(0).max(5).optional(),
+    isInStock: z.boolean().default(true),
+    tags: z
+        .array(z.string().min(1).max(FIELD_LIMITS.tag))
+        .max(FIELD_LIMITS.tagsPerProduct)
+        .default([]),
+});
+/** Base shape for any signal that points at a single SKU. */
+export const skuSignalSchema = z.strictObject({
+    sku: identifier(),
+    category: optionalIdentifier(),
+    at: epochMs(),
+    /** Caller-supplied strength, 0..1. Defaults to 1 when absent. */
+    weight: z.number().min(0).max(1).optional(),
+});
+export const viewSignalSchema = skuSignalSchema.extend({
+    views: z.number().int().positive().default(1),
+    dwellMs: z.number().nonnegative().optional(),
+});
+export const purchaseSignalSchema = skuSignalSchema.extend({
+    quantity: z.number().int().positive().default(1),
+    price: z.number().nonnegative().optional(),
+});
+/**
+ * `meta` is the one dynamic shape in the contract, so its key is checked before
+ * the record is parsed rather than after. Zod builds its result by assigning
+ * each key, and assigning `__proto__` sets the prototype instead of adding a
+ * key — so the entry would vanish from the parsed output with no error, which
+ * is the silent drop this module exists to prevent.
+ *
+ * `__proto__` is the only key that behaves this way. `constructor` and
+ * `prototype` are ordinary own properties: assigning either shadows it on that
+ * one object and leaves the prototype alone, so both survive a parse intact and
+ * are accepted. `meta` is a host-defined vocabulary, and a shop with a facet,
+ * filter, or CMS field by either name should get a component, not a throw.
+ */
+const metaKeysAreSafe = z.custom((value) => typeof value === 'object' && value !== null && !Object.hasOwn(value, RESERVED_META_KEY), { message: `meta may not use the reserved key ${RESERVED_META_KEY}` });
+// `z.record` bounds key and value shape but not how many entries a record may
+// carry, so the count is checked separately.
+const metaSchema = metaKeysAreSafe.pipe(z
+    .record(z.string().min(1).max(FIELD_LIMITS.identifier), z.union([z.string().max(FIELD_LIMITS.shortText), z.number(), z.boolean()]))
+    .refine((entries) => Object.keys(entries).length <= FIELD_LIMITS.metaEntries, {
+    message: `meta may carry at most ${FIELD_LIMITS.metaEntries} entries`,
+}));
+/**
+ * Catch-all for everything else the shopper did. `type` is an open vocabulary
+ * on purpose — 'scroll_depth', 'wishlist', 'filter_applied', whatever the host
+ * already emits — so hosts do not have to map their events onto ours.
+ */
+export const interactionSchema = z.strictObject({
+    type: identifier(),
+    sku: optionalIdentifier(),
+    category: optionalIdentifier(),
+    at: epochMs(),
+    value: z.union([z.string().max(FIELD_LIMITS.shortText), z.number(), z.boolean()]).optional(),
+    meta: metaSchema.optional(),
+});
+/** Where on the site this component is being rendered. */
+export const renderContextSchema = z.strictObject({
+    /** 'pdp', 'home', 'cart', 'search', or any host-defined surface. */
+    surface: identifier(),
+    /** Named placement, e.g. 'below-fold-recommendations'. */
+    slot: z.string().min(1).max(FIELD_LIMITS.identifier).default('recommendations'),
+    currentSku: optionalIdentifier(),
+    currentCategory: optionalIdentifier(),
+    searchQuery: z.string().max(FIELD_LIMITS.searchQuery).optional(),
+    locale: z.string().min(2).max(35).default('en-US'),
+    /** Upper bound on products across the whole generated component. */
+    maxItems: z.number().int().min(1).max(12).default(4),
+});
+const signalArray = (schema) => z.array(schema).max(FIELD_LIMITS.signalsPerCategory).default([]);
+export const trackingSignalsSchema = z.strictObject({
+    likes: signalArray(skuSignalSchema),
+    dislikes: signalArray(skuSignalSchema),
+    mostViewed: signalArray(viewSignalSchema),
+    lastPurchased: signalArray(purchaseSignalSchema),
+    cart: signalArray(skuSignalSchema),
+    recentSearches: signalArray(z.string().min(1).max(FIELD_LIMITS.searchQuery)),
+    interactions: signalArray(interactionSchema),
+});
+/** A set the shop sells together. The model never picks or invents one. */
+export const bundleSchema = z.strictObject({
+    id: identifier(),
+    skus: z
+        .array(identifier())
+        .min(2)
+        .max(FIELD_LIMITS.productsPerBundle)
+        .refine((skus) => new Set(skus).size === skus.length, {
+        message: 'a bundle must not list the same product twice',
+    }),
+    // The shop's price for the set — not derived from the parts, so the set says
+    // which money it is in rather than borrowing it from a member.
+    price: z.number().nonnegative(),
+    currency: z
+        .string()
+        .regex(/^[A-Z]{3}$/, 'expected a three-letter ISO 4217 code')
+        .default('USD'),
+    label: z.string().min(1).max(FIELD_LIMITS.shortText).optional(),
+});
+export const trackingInputSchema = z
+    .strictObject({
+    schemaVersion: z.literal('1').default('1'),
+    user: z.strictObject({
+        id: identifier(),
+        segment: optionalIdentifier(),
+        isReturning: z.boolean().optional(),
+    }),
+    context: renderContextSchema,
+    // A payload with no `signals` block at all is the cold-start case, not an
+    // error. Every category defaults to empty, so a first-time visitor needs no
+    // special handling from the host.
+    signals: trackingSignalsSchema.prefault({}),
+    /**
+     * The only products the generated component may place. Merchandising rules
+     * belong here: whatever the host leaves out cannot be recommended, which is
+     * what makes it impossible to surface a product that does not exist or is not
+     * merchandised for this shopper.
+     *
+     * SKUs must be unique — a duplicate is a host bug that spends prompt budget
+     * twice and invites the same product in two slots.
+     */
+    candidates: z
+        .array(productSchema)
+        .min(1)
+        .max(FIELD_LIMITS.candidates)
+        .refine((products) => new Set(products.map((product) => product.sku)).size === products.length, {
+        message: 'candidates must have unique SKUs',
+    }),
+    // Ids must be unique — the renderer looks a bundle up by id alone, so a
+    // duplicate would let it draw the wrong set at the wrong price.
+    bundles: z
+        .array(bundleSchema)
+        .max(FIELD_LIMITS.bundles)
+        .refine((bundles) => new Set(bundles.map((bundle) => bundle.id)).size === bundles.length, {
+        message: 'bundles must have unique ids',
+    })
+        .default([]),
+})
+    .refine((input) => {
+    const candidateSkus = new Set(input.candidates.map((product) => product.sku));
+    for (const bundle of input.bundles) {
+        for (const sku of bundle.skus) {
+            if (!candidateSkus.has(sku))
+                return false;
+        }
+    }
+    return true;
+}, { message: 'every product in a bundle must also be a candidate' });
+/**
+ * Validates a payload, throwing a `ZodError` if it does not satisfy the
+ * contract. An invalid payload is a caller bug, and it should be loud.
+ */
+export function parseTrackingInput(value) {
+    return trackingInputSchema.parse(value);
+}
+/** Non-throwing variant, for callers that want to inspect the failure. */
+export function safeParseTrackingInput(value) {
+    return trackingInputSchema.safeParse(value);
+}
+//# sourceMappingURL=tracking-input.js.map

package/dist/tracking-input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracking-input.js","sourceRoot":"","sources":["../src/tracking-input.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@rudra-js/core",
+  "version": "0.1.0",
+  "description": "The contracts and logic that turn one tracking payload into one renderable component specification",
+  "keywords": [
+    "llm",
+    "server-components",
+    "recommendations",
+    "ecommerce",
+    "personalization",
+    "ssr",
+    "zod"
+  ],
+  "license": "MIT",
+  "author": "Clive Dsouza",
+  "homepage": "https://github.com/clivedsouza1010/rudra-js/tree/main/packages/core#readme",
+  "bugs": {
+    "url": "https://github.com/clivedsouza1010/rudra-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clivedsouza1010/rudra-js.git",
+    "directory": "packages/core"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.1",
+    "zod": "^4.5.4"
+  }
+}