@storewatch/schema 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Edin Skeja
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# @storewatch/schema
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Storewatch event contract: canonical commerce events, their property
+schemas (Zod) and the money helpers every Storewatch SDK shares.
+
+```ts
+import { validateEvent } from "@storewatch/schema";
+import { money, toMajor } from "@storewatch/schema/constants";
+
+money(1249, "SEK"); // { amount: 124900, currency: "SEK" }: integer minor units
+validateEvent(event); // { ok: true, event } | { ok: false, issues }
+```
+
+You rarely need this package directly: the browser, React, Next.js, Node and
+Medusa SDKs depend on it.

package/dist/chunk-MEHWUFJG.js

@@ -0,0 +1,71 @@
+// src/constants.ts
+var CANONICAL_EVENTS = [
+  "page_viewed",
+  "product_viewed",
+  "collection_viewed",
+  "search_performed",
+  "add_to_cart",
+  "remove_from_cart",
+  "cart_updated",
+  "checkout_started",
+  "checkout_step_viewed",
+  "customer_information_entered",
+  "shipping_selected",
+  "payment_started",
+  "payment_failed",
+  "payment_authorized",
+  "order_completed",
+  "order_cancelled",
+  "refund_created",
+  "session_heartbeat"
+];
+var canonicalSet = new Set(CANONICAL_EVENTS);
+function isCanonicalEvent(name) {
+  return canonicalSet.has(name);
+}
+var SERVER_AUTHORITATIVE_EVENTS = /* @__PURE__ */ new Set([
+  "payment_failed",
+  "payment_authorized",
+  "order_completed",
+  "order_cancelled",
+  "refund_created"
+]);
+var EPHEMERAL_EVENTS = /* @__PURE__ */ new Set(["session_heartbeat"]);
+var LIMITS = {
+  batchMaxEvents: 100,
+  batchMaxBytes: 256 * 1024,
+  propertiesMaxBytes: 4 * 1024,
+  propertiesMaxDepth: 4,
+  stringMaxLength: 1024,
+  urlMaxLength: 2048,
+  idMaxLength: 128,
+  sessionIdMaxLength: 64,
+  eventNameMaxLength: 64,
+  searchQueryMaxLength: 100,
+  orderMaxItems: 100
+};
+var EVENT_NAME_PATTERN = /^[a-z][a-z0-9_.]{0,63}$/;
+function currencyExponent(currency) {
+  const digits = new Intl.NumberFormat("en", { style: "currency", currency }).resolvedOptions().maximumFractionDigits;
+  return digits ?? 2;
+}
+function money(major, currency) {
+  const code = currency.toUpperCase();
+  const factor = 10 ** currencyExponent(code);
+  return { amount: Math.round(major * factor), currency: code };
+}
+function toMajor(value) {
+  return value.amount / 10 ** currencyExponent(value.currency);
+}
+
+export {
+  CANONICAL_EVENTS,
+  isCanonicalEvent,
+  SERVER_AUTHORITATIVE_EVENTS,
+  EPHEMERAL_EVENTS,
+  LIMITS,
+  EVENT_NAME_PATTERN,
+  currencyExponent,
+  money,
+  toMajor
+};

package/dist/constants.cjs

@@ -0,0 +1,103 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/constants.ts
+var constants_exports = {};
+__export(constants_exports, {
+  CANONICAL_EVENTS: () => CANONICAL_EVENTS,
+  EPHEMERAL_EVENTS: () => EPHEMERAL_EVENTS,
+  EVENT_NAME_PATTERN: () => EVENT_NAME_PATTERN,
+  LIMITS: () => LIMITS,
+  SERVER_AUTHORITATIVE_EVENTS: () => SERVER_AUTHORITATIVE_EVENTS,
+  currencyExponent: () => currencyExponent,
+  isCanonicalEvent: () => isCanonicalEvent,
+  money: () => money,
+  toMajor: () => toMajor
+});
+module.exports = __toCommonJS(constants_exports);
+var CANONICAL_EVENTS = [
+  "page_viewed",
+  "product_viewed",
+  "collection_viewed",
+  "search_performed",
+  "add_to_cart",
+  "remove_from_cart",
+  "cart_updated",
+  "checkout_started",
+  "checkout_step_viewed",
+  "customer_information_entered",
+  "shipping_selected",
+  "payment_started",
+  "payment_failed",
+  "payment_authorized",
+  "order_completed",
+  "order_cancelled",
+  "refund_created",
+  "session_heartbeat"
+];
+var canonicalSet = new Set(CANONICAL_EVENTS);
+function isCanonicalEvent(name) {
+  return canonicalSet.has(name);
+}
+var SERVER_AUTHORITATIVE_EVENTS = /* @__PURE__ */ new Set([
+  "payment_failed",
+  "payment_authorized",
+  "order_completed",
+  "order_cancelled",
+  "refund_created"
+]);
+var EPHEMERAL_EVENTS = /* @__PURE__ */ new Set(["session_heartbeat"]);
+var LIMITS = {
+  batchMaxEvents: 100,
+  batchMaxBytes: 256 * 1024,
+  propertiesMaxBytes: 4 * 1024,
+  propertiesMaxDepth: 4,
+  stringMaxLength: 1024,
+  urlMaxLength: 2048,
+  idMaxLength: 128,
+  sessionIdMaxLength: 64,
+  eventNameMaxLength: 64,
+  searchQueryMaxLength: 100,
+  orderMaxItems: 100
+};
+var EVENT_NAME_PATTERN = /^[a-z][a-z0-9_.]{0,63}$/;
+function currencyExponent(currency) {
+  const digits = new Intl.NumberFormat("en", { style: "currency", currency }).resolvedOptions().maximumFractionDigits;
+  return digits ?? 2;
+}
+function money(major, currency) {
+  const code = currency.toUpperCase();
+  const factor = 10 ** currencyExponent(code);
+  return { amount: Math.round(major * factor), currency: code };
+}
+function toMajor(value) {
+  return value.amount / 10 ** currencyExponent(value.currency);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CANONICAL_EVENTS,
+  EPHEMERAL_EVENTS,
+  EVENT_NAME_PATTERN,
+  LIMITS,
+  SERVER_AUTHORITATIVE_EVENTS,
+  currencyExponent,
+  isCanonicalEvent,
+  money,
+  toMajor
+});

package/dist/constants.d.cts

@@ -0,0 +1,43 @@
+/**
+ * Zod-free part of the event contract. Safe to import from the browser SDK:
+ * it must stay dependency-free so the SDK stays under its size budget.
+ */
+export declare const CANONICAL_EVENTS: readonly ["page_viewed", "product_viewed", "collection_viewed", "search_performed", "add_to_cart", "remove_from_cart", "cart_updated", "checkout_started", "checkout_step_viewed", "customer_information_entered", "shipping_selected", "payment_started", "payment_failed", "payment_authorized", "order_completed", "order_cancelled", "refund_created", "session_heartbeat"];
+export type CanonicalEventName = (typeof CANONICAL_EVENTS)[number];
+export declare function isCanonicalEvent(name: string): name is CanonicalEventName;
+/**
+ * Events that move or confirm money. Only server (secret-key) ingestion may
+ * produce authoritative versions; from a browser key they are recorded with
+ * source = "browser" and treated as hints.
+ */
+export declare const SERVER_AUTHORITATIVE_EVENTS: ReadonlySet<CanonicalEventName>;
+/** Ephemeral events that update live presence but are never persisted. */
+export declare const EPHEMERAL_EVENTS: ReadonlySet<CanonicalEventName>;
+export declare const LIMITS: {
+    readonly batchMaxEvents: 100;
+    readonly batchMaxBytes: number;
+    readonly propertiesMaxBytes: number;
+    readonly propertiesMaxDepth: 4;
+    readonly stringMaxLength: 1024;
+    readonly urlMaxLength: 2048;
+    readonly idMaxLength: 128;
+    readonly sessionIdMaxLength: 64;
+    readonly eventNameMaxLength: 64;
+    readonly searchQueryMaxLength: 100;
+    readonly orderMaxItems: 100;
+};
+export declare const EVENT_NAME_PATTERN: RegExp;
+/** Money in integer minor units (öre, cents) with an explicit ISO-4217 code. */
+export type Money = {
+    amount: number;
+    currency: string;
+};
+/** Number of minor-unit digits for a currency (SEK → 2, JPY → 0, KWD → 3). */
+export declare function currencyExponent(currency: string): number;
+/**
+ * Build a Money value from a *major*-unit amount, e.g. `money(1249, "SEK")`
+ * → `{ amount: 124900, currency: "SEK" }`. Throws on an unknown currency.
+ */
+export declare function money(major: number, currency: string): Money;
+/** Inverse of `money()`: minor units → major-unit number, for display. */
+export declare function toMajor(value: Money): number;

package/dist/constants.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Zod-free part of the event contract. Safe to import from the browser SDK:
+ * it must stay dependency-free so the SDK stays under its size budget.
+ */
+export declare const CANONICAL_EVENTS: readonly ["page_viewed", "product_viewed", "collection_viewed", "search_performed", "add_to_cart", "remove_from_cart", "cart_updated", "checkout_started", "checkout_step_viewed", "customer_information_entered", "shipping_selected", "payment_started", "payment_failed", "payment_authorized", "order_completed", "order_cancelled", "refund_created", "session_heartbeat"];
+export type CanonicalEventName = (typeof CANONICAL_EVENTS)[number];
+export declare function isCanonicalEvent(name: string): name is CanonicalEventName;
+/**
+ * Events that move or confirm money. Only server (secret-key) ingestion may
+ * produce authoritative versions; from a browser key they are recorded with
+ * source = "browser" and treated as hints.
+ */
+export declare const SERVER_AUTHORITATIVE_EVENTS: ReadonlySet<CanonicalEventName>;
+/** Ephemeral events that update live presence but are never persisted. */
+export declare const EPHEMERAL_EVENTS: ReadonlySet<CanonicalEventName>;
+export declare const LIMITS: {
+    readonly batchMaxEvents: 100;
+    readonly batchMaxBytes: number;
+    readonly propertiesMaxBytes: number;
+    readonly propertiesMaxDepth: 4;
+    readonly stringMaxLength: 1024;
+    readonly urlMaxLength: 2048;
+    readonly idMaxLength: 128;
+    readonly sessionIdMaxLength: 64;
+    readonly eventNameMaxLength: 64;
+    readonly searchQueryMaxLength: 100;
+    readonly orderMaxItems: 100;
+};
+export declare const EVENT_NAME_PATTERN: RegExp;
+/** Money in integer minor units (öre, cents) with an explicit ISO-4217 code. */
+export type Money = {
+    amount: number;
+    currency: string;
+};
+/** Number of minor-unit digits for a currency (SEK → 2, JPY → 0, KWD → 3). */
+export declare function currencyExponent(currency: string): number;
+/**
+ * Build a Money value from a *major*-unit amount, e.g. `money(1249, "SEK")`
+ * → `{ amount: 124900, currency: "SEK" }`. Throws on an unknown currency.
+ */
+export declare function money(major: number, currency: string): Money;
+/** Inverse of `money()`: minor units → major-unit number, for display. */
+export declare function toMajor(value: Money): number;

package/dist/constants.js

@@ -0,0 +1,22 @@
+import {
+  CANONICAL_EVENTS,
+  EPHEMERAL_EVENTS,
+  EVENT_NAME_PATTERN,
+  LIMITS,
+  SERVER_AUTHORITATIVE_EVENTS,
+  currencyExponent,
+  isCanonicalEvent,
+  money,
+  toMajor
+} from "./chunk-MEHWUFJG.js";
+export {
+  CANONICAL_EVENTS,
+  EPHEMERAL_EVENTS,
+  EVENT_NAME_PATTERN,
+  LIMITS,
+  SERVER_AUTHORITATIVE_EVENTS,
+  currencyExponent,
+  isCanonicalEvent,
+  money,
+  toMajor
+};

package/dist/envelope.d.cts

@@ -0,0 +1,114 @@
+import { z } from "zod";
+import { type CanonicalEventName } from "./constants.cjs";
+import { type CanonicalProperties } from "./events.cjs";
+import { type Json } from "./primitives.cjs";
+export declare const ContextSchema: z.ZodObject<{
+    page: z.ZodOptional<z.ZodObject<{
+        url: z.ZodOptional<z.ZodString>;
+        path: z.ZodOptional<z.ZodString>;
+        referrer: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    utm: z.ZodOptional<z.ZodObject<{
+        source: z.ZodOptional<z.ZodString>;
+        medium: z.ZodOptional<z.ZodString>;
+        campaign: z.ZodOptional<z.ZodString>;
+        term: z.ZodOptional<z.ZodString>;
+        content: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    locale: z.ZodOptional<z.ZodString>;
+    timezone: z.ZodOptional<z.ZodString>;
+    currency: z.ZodOptional<z.ZodString>;
+    screen: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>>;
+    trace: z.ZodOptional<z.ZodObject<{
+        traceId: z.ZodString;
+        spanId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    library: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+    }, z.core.$strip>>;
+    consent: z.ZodOptional<z.ZodEnum<{
+        denied: "denied";
+        granted: "granted";
+        pending: "pending";
+    }>>;
+}, z.core.$strip>;
+/** Envelope fields. Tenant fields (org/project/environment) are deliberately absent. */
+export declare const WireEventSchema: z.ZodObject<{
+    eventId: z.ZodUUID;
+    name: z.ZodString;
+    timestamp: z.ZodISODateTime;
+    sessionId: z.ZodString;
+    anonymousId: z.ZodOptional<z.ZodString>;
+    customerId: z.ZodOptional<z.ZodString>;
+    properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<Json, unknown, z.core.$ZodTypeInternals<Json, unknown>>>>;
+    context: z.ZodOptional<z.ZodObject<{
+        page: z.ZodOptional<z.ZodObject<{
+            url: z.ZodOptional<z.ZodString>;
+            path: z.ZodOptional<z.ZodString>;
+            referrer: z.ZodOptional<z.ZodString>;
+            title: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        utm: z.ZodOptional<z.ZodObject<{
+            source: z.ZodOptional<z.ZodString>;
+            medium: z.ZodOptional<z.ZodString>;
+            campaign: z.ZodOptional<z.ZodString>;
+            term: z.ZodOptional<z.ZodString>;
+            content: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        locale: z.ZodOptional<z.ZodString>;
+        timezone: z.ZodOptional<z.ZodString>;
+        currency: z.ZodOptional<z.ZodString>;
+        screen: z.ZodOptional<z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>>;
+        trace: z.ZodOptional<z.ZodObject<{
+            traceId: z.ZodString;
+            spanId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        library: z.ZodOptional<z.ZodObject<{
+            name: z.ZodString;
+            version: z.ZodString;
+        }, z.core.$strip>>;
+        consent: z.ZodOptional<z.ZodEnum<{
+            denied: "denied";
+            granted: "granted";
+            pending: "pending";
+        }>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const WireBatchSchema: z.ZodObject<{
+    sentAt: z.ZodOptional<z.ZodISODateTime>;
+    key: z.ZodOptional<z.ZodString>;
+    batch: z.ZodArray<z.ZodUnknown>;
+}, z.core.$strip>;
+export type WireEvent = z.infer<typeof WireEventSchema>;
+export type WireBatch = z.infer<typeof WireBatchSchema>;
+export type EventContext = z.infer<typeof ContextSchema>;
+export type ValidatedEvent = (Omit<WireEvent, "name" | "properties"> & {
+    kind: "canonical";
+    name: CanonicalEventName;
+    properties: CanonicalProperties[CanonicalEventName];
+}) | (Omit<WireEvent, "properties"> & {
+    kind: "custom";
+    properties: Record<string, Json>;
+});
+export type ValidationIssue = {
+    path: string;
+    message: string;
+};
+export type ValidationResult = {
+    ok: true;
+    event: ValidatedEvent;
+} | {
+    ok: false;
+    eventId: string | undefined;
+    issues: ValidationIssue[];
+};
+/** Validate one raw event: envelope first, then canonical properties by name. */
+export declare function validateEvent(raw: unknown): ValidationResult;

package/dist/envelope.d.ts

@@ -0,0 +1,114 @@
+import { z } from "zod";
+import { type CanonicalEventName } from "./constants.js";
+import { type CanonicalProperties } from "./events.js";
+import { type Json } from "./primitives.js";
+export declare const ContextSchema: z.ZodObject<{
+    page: z.ZodOptional<z.ZodObject<{
+        url: z.ZodOptional<z.ZodString>;
+        path: z.ZodOptional<z.ZodString>;
+        referrer: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    utm: z.ZodOptional<z.ZodObject<{
+        source: z.ZodOptional<z.ZodString>;
+        medium: z.ZodOptional<z.ZodString>;
+        campaign: z.ZodOptional<z.ZodString>;
+        term: z.ZodOptional<z.ZodString>;
+        content: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    locale: z.ZodOptional<z.ZodString>;
+    timezone: z.ZodOptional<z.ZodString>;
+    currency: z.ZodOptional<z.ZodString>;
+    screen: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>>;
+    trace: z.ZodOptional<z.ZodObject<{
+        traceId: z.ZodString;
+        spanId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    library: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+    }, z.core.$strip>>;
+    consent: z.ZodOptional<z.ZodEnum<{
+        denied: "denied";
+        granted: "granted";
+        pending: "pending";
+    }>>;
+}, z.core.$strip>;
+/** Envelope fields. Tenant fields (org/project/environment) are deliberately absent. */
+export declare const WireEventSchema: z.ZodObject<{
+    eventId: z.ZodUUID;
+    name: z.ZodString;
+    timestamp: z.ZodISODateTime;
+    sessionId: z.ZodString;
+    anonymousId: z.ZodOptional<z.ZodString>;
+    customerId: z.ZodOptional<z.ZodString>;
+    properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<Json, unknown, z.core.$ZodTypeInternals<Json, unknown>>>>;
+    context: z.ZodOptional<z.ZodObject<{
+        page: z.ZodOptional<z.ZodObject<{
+            url: z.ZodOptional<z.ZodString>;
+            path: z.ZodOptional<z.ZodString>;
+            referrer: z.ZodOptional<z.ZodString>;
+            title: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        utm: z.ZodOptional<z.ZodObject<{
+            source: z.ZodOptional<z.ZodString>;
+            medium: z.ZodOptional<z.ZodString>;
+            campaign: z.ZodOptional<z.ZodString>;
+            term: z.ZodOptional<z.ZodString>;
+            content: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        locale: z.ZodOptional<z.ZodString>;
+        timezone: z.ZodOptional<z.ZodString>;
+        currency: z.ZodOptional<z.ZodString>;
+        screen: z.ZodOptional<z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>>;
+        trace: z.ZodOptional<z.ZodObject<{
+            traceId: z.ZodString;
+            spanId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        library: z.ZodOptional<z.ZodObject<{
+            name: z.ZodString;
+            version: z.ZodString;
+        }, z.core.$strip>>;
+        consent: z.ZodOptional<z.ZodEnum<{
+            denied: "denied";
+            granted: "granted";
+            pending: "pending";
+        }>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const WireBatchSchema: z.ZodObject<{
+    sentAt: z.ZodOptional<z.ZodISODateTime>;
+    key: z.ZodOptional<z.ZodString>;
+    batch: z.ZodArray<z.ZodUnknown>;
+}, z.core.$strip>;
+export type WireEvent = z.infer<typeof WireEventSchema>;
+export type WireBatch = z.infer<typeof WireBatchSchema>;
+export type EventContext = z.infer<typeof ContextSchema>;
+export type ValidatedEvent = (Omit<WireEvent, "name" | "properties"> & {
+    kind: "canonical";
+    name: CanonicalEventName;
+    properties: CanonicalProperties[CanonicalEventName];
+}) | (Omit<WireEvent, "properties"> & {
+    kind: "custom";
+    properties: Record<string, Json>;
+});
+export type ValidationIssue = {
+    path: string;
+    message: string;
+};
+export type ValidationResult = {
+    ok: true;
+    event: ValidatedEvent;
+} | {
+    ok: false;
+    eventId: string | undefined;
+    issues: ValidationIssue[];
+};
+/** Validate one raw event: envelope first, then canonical properties by name. */
+export declare function validateEvent(raw: unknown): ValidationResult;