@storewatch/schema 0.0.0-stage → 0.2.0

package/dist/index.js

@@ -0,0 +1,217 @@
+import {
+  CANONICAL_EVENTS,
+  EPHEMERAL_EVENTS,
+  EVENT_NAME_PATTERN,
+  LIMITS,
+  SERVER_AUTHORITATIVE_EVENTS,
+  currencyExponent,
+  isCanonicalEvent,
+  money,
+  toMajor
+} from "./chunk-MEHWUFJG.js";
+
+// src/primitives.ts
+import { z } from "zod";
+var knownCurrencies = new Set(Intl.supportedValuesOf("currency"));
+var CurrencySchema = z.string().regex(/^[A-Z]{3}$/, "must be an upper-case ISO-4217 code").refine((c) => knownCurrencies.has(c), "unknown ISO-4217 currency");
+var MoneySchema = z.strictObject({
+  amount: z.number().int("money amounts are integer minor units").safe(),
+  currency: CurrencySchema
+});
+var IdSchema = z.string().min(1).max(LIMITS.idMaxLength);
+var ShortString = z.string().max(LIMITS.stringMaxLength);
+var UrlString = z.string().max(LIMITS.urlMaxLength);
+function jsonDepth(value) {
+  if (value === null || typeof value !== "object") return 0;
+  const children = Array.isArray(value) ? value : Object.values(value);
+  let max = 0;
+  for (const child of children) max = Math.max(max, jsonDepth(child));
+  return max + 1;
+}
+var JsonValueSchema = z.lazy(
+  () => z.union([
+    z.string().max(LIMITS.stringMaxLength),
+    z.number().refine(Number.isFinite, "must be finite"),
+    z.boolean(),
+    z.null(),
+    z.array(JsonValueSchema),
+    z.record(z.string().max(LIMITS.eventNameMaxLength), JsonValueSchema)
+  ])
+);
+var utf8 = new TextEncoder();
+var PropertiesSchema = z.record(z.string().max(LIMITS.eventNameMaxLength), JsonValueSchema).superRefine((value, ctx) => {
+  if (jsonDepth(value) > LIMITS.propertiesMaxDepth) {
+    ctx.addIssue({ code: "custom", message: `nesting deeper than ${LIMITS.propertiesMaxDepth}` });
+  }
+  if (utf8.encode(JSON.stringify(value)).length > LIMITS.propertiesMaxBytes) {
+    ctx.addIssue({ code: "custom", message: `larger than ${LIMITS.propertiesMaxBytes} bytes` });
+  }
+});
+
+// src/events.ts
+import { z as z2 } from "zod";
+var props = z2.looseObject;
+var OrderItemSchema = z2.looseObject({
+  productId: IdSchema,
+  variantId: IdSchema.optional(),
+  name: ShortString.optional(),
+  quantity: z2.number().int().positive(),
+  price: MoneySchema
+});
+var CANONICAL_PROPERTY_SCHEMAS = {
+  page_viewed: props({ pageType: z2.string().max(32).optional() }),
+  product_viewed: props({
+    productId: IdSchema,
+    variantId: IdSchema.optional(),
+    name: ShortString.optional(),
+    price: MoneySchema.optional()
+  }),
+  collection_viewed: props({ collectionId: IdSchema, name: ShortString.optional() }),
+  search_performed: props({
+    query: z2.string().max(LIMITS.searchQueryMaxLength),
+    resultCount: z2.number().int().nonnegative().optional()
+  }),
+  add_to_cart: props({
+    productId: IdSchema,
+    variantId: IdSchema.optional(),
+    name: ShortString.optional(),
+    quantity: z2.number().int().positive(),
+    cartId: IdSchema.optional(),
+    price: MoneySchema.optional(),
+    cartValue: MoneySchema.optional()
+  }),
+  remove_from_cart: props({
+    productId: IdSchema,
+    variantId: IdSchema.optional(),
+    quantity: z2.number().int().positive(),
+    cartId: IdSchema.optional(),
+    cartValue: MoneySchema.optional()
+  }),
+  cart_updated: props({
+    cartId: IdSchema,
+    cartValue: MoneySchema,
+    itemCount: z2.number().int().nonnegative()
+  }),
+  checkout_started: props({ checkoutId: IdSchema, cartId: IdSchema.optional(), cartValue: MoneySchema }),
+  checkout_step_viewed: props({ checkoutId: IdSchema, step: z2.string().max(32) }),
+  // Deliberately carries no field contents: only that the step happened.
+  customer_information_entered: z2.strictObject({ checkoutId: IdSchema }),
+  shipping_selected: props({
+    checkoutId: IdSchema,
+    method: ShortString.optional(),
+    shippingCost: MoneySchema.optional()
+  }),
+  payment_started: props({ checkoutId: IdSchema, provider: z2.string().max(64).optional() }),
+  payment_failed: props({
+    checkoutId: IdSchema,
+    provider: z2.string().max(64).optional(),
+    // A provider error *code*, never a free-text message (those leak PII).
+    reason: z2.string().max(64).optional(),
+    amount: MoneySchema.optional()
+  }),
+  payment_authorized: props({
+    checkoutId: IdSchema,
+    provider: z2.string().max(64).optional(),
+    amount: MoneySchema
+  }),
+  order_completed: props({
+    orderId: IdSchema,
+    checkoutId: IdSchema.optional(),
+    cartId: IdSchema.optional(),
+    total: MoneySchema,
+    items: z2.array(OrderItemSchema).max(LIMITS.orderMaxItems)
+  }),
+  order_cancelled: props({ orderId: IdSchema, reason: z2.string().max(64).optional() }),
+  refund_created: props({ orderId: IdSchema, amount: MoneySchema }),
+  session_heartbeat: props({})
+};
+
+// src/envelope.ts
+import { z as z3 } from "zod";
+var HexId = (length) => z3.string().regex(new RegExp(`^[0-9a-f]{${length}}$`));
+var ContextSchema = z3.object({
+  page: z3.object({
+    url: UrlString.optional(),
+    path: UrlString.optional(),
+    referrer: UrlString.optional(),
+    title: ShortString.optional()
+  }).optional(),
+  utm: z3.object({
+    source: ShortString.optional(),
+    medium: ShortString.optional(),
+    campaign: ShortString.optional(),
+    term: ShortString.optional(),
+    content: ShortString.optional()
+  }).optional(),
+  locale: z3.string().max(35).optional(),
+  timezone: z3.string().max(64).optional(),
+  currency: CurrencySchema.optional(),
+  screen: z3.object({ width: z3.number().int().nonnegative(), height: z3.number().int().nonnegative() }).optional(),
+  trace: z3.object({ traceId: HexId(32), spanId: HexId(16).optional() }).optional(),
+  library: z3.object({ name: z3.string().max(64), version: z3.string().max(32) }).optional(),
+  consent: z3.enum(["pending", "granted", "denied"]).optional()
+});
+var WireEventSchema = z3.object({
+  eventId: z3.uuid(),
+  name: z3.string().regex(EVENT_NAME_PATTERN, "event names are snake_case, \u2264 64 chars"),
+  timestamp: z3.iso.datetime({ offset: true }),
+  sessionId: z3.string().min(1).max(LIMITS.sessionIdMaxLength),
+  anonymousId: z3.string().min(1).max(LIMITS.sessionIdMaxLength).optional(),
+  customerId: IdSchema.optional(),
+  properties: PropertiesSchema.optional(),
+  context: ContextSchema.optional()
+});
+var WireBatchSchema = z3.object({
+  sentAt: z3.iso.datetime({ offset: true }).optional(),
+  key: z3.string().max(128).optional(),
+  // Elements are validated one by one so a bad event doesn't sink the batch.
+  batch: z3.array(z3.unknown()).min(1).max(LIMITS.batchMaxEvents)
+});
+function toIssues(error, prefix = "") {
+  return error.issues.map((i) => ({
+    path: [prefix, ...i.path.map(String)].filter(Boolean).join("."),
+    message: i.message
+  }));
+}
+function validateEvent(raw) {
+  const envelope = WireEventSchema.safeParse(raw);
+  if (!envelope.success) {
+    const eventId = typeof raw === "object" && raw !== null && "eventId" in raw && typeof raw.eventId === "string" ? raw.eventId : void 0;
+    return { ok: false, eventId, issues: toIssues(envelope.error) };
+  }
+  const { properties = {}, ...rest } = envelope.data;
+  if (!isCanonicalEvent(rest.name)) {
+    return { ok: true, event: { ...rest, kind: "custom", properties } };
+  }
+  const parsed = CANONICAL_PROPERTY_SCHEMAS[rest.name].safeParse(properties);
+  if (!parsed.success) {
+    return { ok: false, eventId: rest.eventId, issues: toIssues(parsed.error, "properties") };
+  }
+  return {
+    ok: true,
+    event: { ...rest, kind: "canonical", name: rest.name, properties: parsed.data }
+  };
+}
+export {
+  CANONICAL_EVENTS,
+  CANONICAL_PROPERTY_SCHEMAS,
+  ContextSchema,
+  CurrencySchema,
+  EPHEMERAL_EVENTS,
+  EVENT_NAME_PATTERN,
+  IdSchema,
+  LIMITS,
+  MoneySchema,
+  PropertiesSchema,
+  SERVER_AUTHORITATIVE_EVENTS,
+  ShortString,
+  UrlString,
+  WireBatchSchema,
+  WireEventSchema,
+  currencyExponent,
+  isCanonicalEvent,
+  jsonDepth,
+  money,
+  toMajor,
+  validateEvent
+};

package/dist/primitives.d.cts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+export declare const CurrencySchema: z.ZodString;
+export declare const MoneySchema: z.ZodObject<{
+    amount: z.ZodNumber;
+    currency: z.ZodString;
+}, z.core.$strict>;
+export declare const IdSchema: z.ZodString;
+export declare const ShortString: z.ZodString;
+export declare const UrlString: z.ZodString;
+export type Json = string | number | boolean | null | Json[] | {
+    [key: string]: Json;
+};
+/** Depth of a JSON value: scalars are 0, `{a:1}` is 1. */
+export declare function jsonDepth(value: unknown): number;
+/** Free-form properties with byte-size and depth limits. */
+export declare const PropertiesSchema: z.ZodRecord<z.ZodString, z.ZodType<Json, unknown, z.core.$ZodTypeInternals<Json, unknown>>>;

package/dist/primitives.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+export declare const CurrencySchema: z.ZodString;
+export declare const MoneySchema: z.ZodObject<{
+    amount: z.ZodNumber;
+    currency: z.ZodString;
+}, z.core.$strict>;
+export declare const IdSchema: z.ZodString;
+export declare const ShortString: z.ZodString;
+export declare const UrlString: z.ZodString;
+export type Json = string | number | boolean | null | Json[] | {
+    [key: string]: Json;
+};
+/** Depth of a JSON value: scalars are 0, `{a:1}` is 1. */
+export declare function jsonDepth(value: unknown): number;
+/** Free-form properties with byte-size and depth limits. */
+export declare const PropertiesSchema: z.ZodRecord<z.ZodString, z.ZodType<Json, unknown, z.core.$ZodTypeInternals<Json, unknown>>>;

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@storewatch/schema",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Storewatch canonical commerce event contract.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./constants": {
+      "import": {
+        "types": "./dist/constants.d.ts",
+        "default": "./dist/constants.js"
+      },
+      "require": {
+        "types": "./dist/constants.d.cts",
+        "default": "./dist/constants.cjs"
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "tsup": "^9.0.0",
+    "@storewatch/config": "0.0.0"
+  },
+  "keywords": [
+    "storewatch",
+    "analytics",
+    "ecommerce"
+  ],
+  "scripts": {
+    "typecheck": "tsc -p .",
+    "test": "vitest run",
+    "build": "rm -rf dist && tsup && tsc -p tsconfig.build.json && node ../../scripts/dual-dts.mjs dist"
+  }
 }