@storewatch/medusa 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,24 @@
-# Temporary Holding Version
+# @storewatch/medusa
 
-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.
+Storewatch for Medusa v2: server-confirmed orders, cancellations and refunds,
+tied to the shopper's live session.
+
+```ts
+// src/subscribers/storewatch-order-placed.ts (one file per event)
+export { orderPlacedSubscriber as default, orderPlacedConfig as config } from "@storewatch/medusa";
+// also: orderCanceledSubscriber/orderCanceledConfig, paymentRefundedSubscriber/paymentRefundedConfig
+```
+
+Set `STOREWATCH_SECRET_KEY` and `STOREWATCH_ENDPOINT` in the backend. Without
+them the subscribers do nothing; with them they never throw into Medusa.
+
+On the storefront, put the session on the cart (Medusa copies cart metadata
+to the order):
+
+```ts
+import { storewatchCartMetadata } from "@storewatch/medusa/storefront";
+await sdk.store.cart.update(cart.id, { metadata: { ...cart.metadata, ...storewatchCartMetadata(getStorewatch().ids()) } });
+```
+
+For failed payments (Medusa has no event for them), call `trackPaymentFailed`
+from your payment webhook. ESM and CommonJS.

package/dist/chunk-DQHAPSCU.js

@@ -0,0 +1,15 @@
+// src/storefront.ts
+var METADATA_KEY = "storewatch";
+function storewatchCartMetadata(ids) {
+  return { [METADATA_KEY]: { sessionId: ids.sessionId, ...ids.anonymousId ? { anonymousId: ids.anonymousId } : {} } };
+}
+function cartHasSession(metadata, sessionId) {
+  const current = metadata?.[METADATA_KEY];
+  return typeof current === "object" && current !== null && current.sessionId === sessionId;
+}
+
+export {
+  METADATA_KEY,
+  storewatchCartMetadata,
+  cartHasSession
+};

package/dist/index.cjs

@@ -0,0 +1,238 @@
+"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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  METADATA_KEY: () => METADATA_KEY,
+  ORDER_FIELDS: () => ORDER_FIELDS,
+  configureStorewatch: () => configureStorewatch,
+  orderCanceledConfig: () => orderCanceledConfig,
+  orderCanceledSubscriber: () => orderCanceledSubscriber,
+  orderCompletedEvent: () => orderCompletedEvent,
+  orderPlacedConfig: () => orderPlacedConfig,
+  orderPlacedSubscriber: () => orderPlacedSubscriber,
+  paymentRefundedConfig: () => paymentRefundedConfig,
+  paymentRefundedSubscriber: () => paymentRefundedSubscriber,
+  resetStorewatchForTests: () => resetStorewatchForTests,
+  sessionOf: () => sessionOf,
+  toMinor: () => toMinor,
+  toNumber: () => toNumber,
+  trackPaymentFailed: () => trackPaymentFailed
+});
+module.exports = __toCommonJS(index_exports);
+var import_node = require("@storewatch/node");
+var import_constants = require("@storewatch/schema/constants");
+
+// src/storefront.ts
+var METADATA_KEY = "storewatch";
+
+// src/index.ts
+function toNumber(amount) {
+  if (amount === null || amount === void 0) return 0;
+  if (typeof amount === "number") return amount;
+  if (typeof amount === "string") return Number(amount);
+  const a = amount;
+  if (typeof a.numeric === "number") return a.numeric;
+  if (a.value !== void 0) return Number(a.value);
+  if (typeof a.toJSON === "function") return Number(a.toJSON());
+  return Number(String(amount));
+}
+var ORDER_FIELDS = [
+  "id",
+  "display_id",
+  "currency_code",
+  "total",
+  "created_at",
+  "customer_id",
+  "metadata",
+  "items.id",
+  "items.product_id",
+  "items.variant_id",
+  "items.title",
+  "items.product_title",
+  "items.quantity",
+  "items.unit_price"
+];
+function toMinor(amount, currency) {
+  const major = toNumber(amount);
+  if (!Number.isFinite(major)) return 0;
+  return Math.round(major * 10 ** (0, import_constants.currencyExponent)(currency));
+}
+function sessionOf(order) {
+  const meta = order.metadata?.[METADATA_KEY];
+  if (meta && typeof meta === "object") {
+    const { sessionId, anonymousId } = meta;
+    if (typeof sessionId === "string" && sessionId.length > 0 && sessionId.length <= import_constants.LIMITS.sessionIdMaxLength) {
+      return { sessionId, ...typeof anonymousId === "string" && anonymousId ? { anonymousId } : {}, linked: true };
+    }
+  }
+  return { sessionId: `srv_${order.id}`.slice(0, import_constants.LIMITS.sessionIdMaxLength), linked: false };
+}
+function sessionFields(order) {
+  const { linked: _linked, ...fields } = sessionOf(order);
+  return fields;
+}
+function orderCompletedEvent(order) {
+  const currency = order.currency_code.toUpperCase();
+  const money = (amount) => ({ amount: toMinor(amount, currency), currency });
+  return {
+    ...sessionFields(order),
+    ...order.customer_id ? { customerId: order.customer_id } : {},
+    eventId: (0, import_node.eventIdFor)("order_completed", order.id),
+    ...order.created_at ? { timestamp: new Date(order.created_at) } : {},
+    properties: {
+      orderId: order.id,
+      ...order.display_id != null ? { orderNumber: String(order.display_id) } : {},
+      total: money(order.total),
+      items: (order.items ?? []).slice(0, import_constants.LIMITS.orderMaxItems).map((item) => ({
+        productId: item.product_id ?? item.id,
+        ...item.variant_id ? { variantId: item.variant_id } : {},
+        ...item.product_title || item.title ? { name: String(item.product_title || item.title).slice(0, 200) } : {},
+        quantity: Math.max(1, Math.round(toNumber(item.quantity) || 1)),
+        price: money(item.unit_price)
+      }))
+    }
+  };
+}
+var client;
+var warnedUnconfigured = false;
+function configureStorewatch(storewatch) {
+  client = storewatch;
+}
+function getClient(logger) {
+  if (client !== void 0) return client;
+  const secretKey = process.env.STOREWATCH_SECRET_KEY;
+  const endpoint = process.env.STOREWATCH_ENDPOINT;
+  if (!secretKey || !endpoint) {
+    if (!warnedUnconfigured) logger?.warn("[storewatch] STOREWATCH_SECRET_KEY / STOREWATCH_ENDPOINT not set; Medusa events are not sent.");
+    warnedUnconfigured = true;
+    return null;
+  }
+  client = (0, import_node.createStorewatch)({ secretKey, endpoint, onError: (e) => logger?.warn(`[storewatch] ${e.message}`) });
+  return client;
+}
+var resolveSafe = (container, key) => {
+  try {
+    return container.resolve(key);
+  } catch {
+    return void 0;
+  }
+};
+async function failOpen(container, label, run) {
+  const logger = resolveSafe(container, "logger");
+  try {
+    const storewatch = getClient(logger);
+    const query = resolveSafe(container, "query");
+    if (!storewatch || !query) return;
+    await run(query, storewatch);
+  } catch (error) {
+    logger?.warn(`[storewatch] ${label} failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+async function fetchOrder(query, id) {
+  const { data } = await query.graph({ entity: "order", fields: ORDER_FIELDS, filters: { id } });
+  return data[0];
+}
+async function orderPlacedSubscriber({ event, container }) {
+  await failOpen(container, "order.placed", async (query, storewatch) => {
+    const order = await fetchOrder(query, event.data.id);
+    if (!order) return;
+    storewatch.track("order_completed", orderCompletedEvent(order));
+  });
+}
+var orderPlacedConfig = { event: "order.placed", context: { subscriberId: "storewatch-order-placed" } };
+async function orderCanceledSubscriber({ event, container }) {
+  await failOpen(container, "order.canceled", async (query, storewatch) => {
+    const order = await fetchOrder(query, event.data.id);
+    if (!order) return;
+    storewatch.track("order_cancelled", {
+      ...sessionFields(order),
+      eventId: (0, import_node.eventIdFor)("order_cancelled", order.id),
+      properties: { orderId: order.id }
+    });
+  });
+}
+var orderCanceledConfig = { event: "order.canceled", context: { subscriberId: "storewatch-order-canceled" } };
+async function paymentRefundedSubscriber({ event, container }) {
+  await failOpen(container, "payment.refunded", async (query, storewatch) => {
+    const { data: payments } = await query.graph({
+      entity: "payment",
+      fields: ["id", "currency_code", "payment_collection_id", "refunds.id", "refunds.amount", "refunds.created_at"],
+      filters: { id: event.data.id }
+    });
+    const payment = payments[0];
+    if (!payment?.payment_collection_id || !payment.refunds?.length) return;
+    const { data: links } = await query.graph({
+      entity: "order_payment_collection",
+      fields: ["order_id"],
+      filters: { payment_collection_id: payment.payment_collection_id }
+    });
+    const orderId = links[0]?.order_id;
+    if (!orderId) return;
+    const order = await fetchOrder(query, orderId);
+    const currency = payment.currency_code.toUpperCase();
+    for (const refund of payment.refunds) {
+      storewatch.track("refund_created", {
+        ...sessionFields(order ?? { id: orderId }),
+        eventId: (0, import_node.eventIdFor)("refund_created", refund.id),
+        ...refund.created_at ? { timestamp: new Date(refund.created_at) } : {},
+        properties: { orderId, refundId: refund.id, amount: { amount: toMinor(refund.amount, currency), currency } }
+      });
+    }
+  });
+}
+var paymentRefundedConfig = { event: "payment.refunded", context: { subscriberId: "storewatch-payment-refunded" } };
+function trackPaymentFailed(input) {
+  try {
+    getClient(void 0)?.track("payment_failed", {
+      ...sessionFields(input.cart),
+      eventId: (0, import_node.eventIdFor)("payment_failed", input.failureId),
+      properties: {
+        checkoutId: input.cart.id,
+        ...input.provider ? { provider: input.provider } : {},
+        ...input.reason ? { reason: input.reason } : {},
+        ...input.amount ? { amount: input.amount } : {}
+      }
+    });
+  } catch {
+  }
+}
+function resetStorewatchForTests() {
+  client = void 0;
+  warnedUnconfigured = false;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  METADATA_KEY,
+  ORDER_FIELDS,
+  configureStorewatch,
+  orderCanceledConfig,
+  orderCanceledSubscriber,
+  orderCompletedEvent,
+  orderPlacedConfig,
+  orderPlacedSubscriber,
+  paymentRefundedConfig,
+  paymentRefundedSubscriber,
+  resetStorewatchForTests,
+  sessionOf,
+  toMinor,
+  toNumber,
+  trackPaymentFailed
+});

package/dist/index.d.cts

@@ -0,0 +1,152 @@
+/**
+ * Storewatch for Medusa v2. Your Medusa backend becomes the source of truth
+ * for revenue: placed orders, cancellations and refunds are sent from the
+ * server, tied to the shopper's live session through cart metadata.
+ *
+ * One subscriber file per event in your Medusa project (Medusa reads each
+ * file's default export and `config`):
+ *
+ *   // src/subscribers/storewatch-order-placed.ts
+ *   export { orderPlacedSubscriber as default, orderPlacedConfig as config } from "@storewatch/medusa";
+ *
+ * Configure with STOREWATCH_SECRET_KEY and STOREWATCH_ENDPOINT, or call
+ * `configureStorewatch()` once at startup. Without configuration the
+ * subscribers log once and do nothing. They never throw into Medusa.
+ */
+import { type Storewatch } from "@storewatch/node";
+import { METADATA_KEY } from "./storefront.cjs";
+type Container = {
+    resolve(key: string): unknown;
+};
+export type SubscriberArgs<T> = {
+    event: {
+        data: T;
+        name?: string;
+    };
+    container: Container;
+};
+/**
+ * Medusa returns amounts and quantities as numbers, numeric strings, `raw_*`
+ * objects (`{ value, precision }`) or BigNumber class instances (computed
+ * totals, order item quantities), in major units.
+ */
+type Amount = number | string | {
+    value: number | string;
+} | {
+    numeric: number;
+} | object | null | undefined;
+/** Any of Medusa's amount shapes → a plain number (NaN when unreadable). */
+export declare function toNumber(amount: Amount): number;
+export type MedusaOrder = {
+    id: string;
+    display_id?: number | null;
+    currency_code: string;
+    total: Amount;
+    created_at?: string | Date | null;
+    customer_id?: string | null;
+    metadata?: Record<string, unknown> | null;
+    items?: {
+        id: string;
+        product_id?: string | null;
+        variant_id?: string | null;
+        title?: string | null;
+        product_title?: string | null;
+        quantity: Amount;
+        unit_price: Amount;
+    }[] | null;
+};
+export declare const ORDER_FIELDS: string[];
+/** Medusa v2 amounts are major units ("1299.5"); Storewatch uses integer minor units. */
+export declare function toMinor(amount: Amount, currency: string): number;
+export { METADATA_KEY };
+/**
+ * The shopper's Storewatch session, if the storefront put it on the cart
+ * (Medusa copies cart metadata to the order). Otherwise a stable per-order
+ * id: the order still counts as revenue, it just isn't tied to a visitor.
+ */
+export declare function sessionOf(order: Pick<MedusaOrder, "id" | "metadata">): {
+    sessionId: string;
+    anonymousId?: string;
+    linked: boolean;
+};
+export declare function orderCompletedEvent(order: MedusaOrder): {
+    sessionId: string;
+    anonymousId?: string;
+    customerId?: string;
+    eventId: string;
+    timestamp?: Date;
+    properties: {
+        orderId: string;
+        orderNumber?: string;
+        total: {
+            amount: number;
+            currency: string;
+        };
+        items: {
+            productId: string;
+            variantId?: string;
+            name?: string;
+            quantity: number;
+            price: {
+                amount: number;
+                currency: string;
+            };
+        }[];
+    };
+};
+/** Use your own client (e.g. with OpenTelemetry trace context). Call once at startup. */
+export declare function configureStorewatch(storewatch: Storewatch): void;
+export declare function orderPlacedSubscriber({ event, container }: SubscriberArgs<{
+    id: string;
+}>): Promise<void>;
+export declare const orderPlacedConfig: {
+    event: string;
+    context: {
+        subscriberId: string;
+    };
+};
+export declare function orderCanceledSubscriber({ event, container }: SubscriberArgs<{
+    id: string;
+}>): Promise<void>;
+export declare const orderCanceledConfig: {
+    event: string;
+    context: {
+        subscriberId: string;
+    };
+};
+/**
+ * `payment.refunded` carries the payment id. Every refund on the payment is
+ * sent with an id derived from the refund, so earlier ones dedupe at ingest.
+ */
+export declare function paymentRefundedSubscriber({ event, container }: SubscriberArgs<{
+    id: string;
+}>): Promise<void>;
+export declare const paymentRefundedConfig: {
+    event: string;
+    context: {
+        subscriberId: string;
+    };
+};
+/**
+ * Medusa has no event for a failed payment attempt. Call this where you see
+ * one (a payment webhook, a failed cart completion) so the live checkout
+ * health view shows it.
+ */
+export declare function trackPaymentFailed(input: {
+    /** The cart being paid for: its metadata links the failure to the shopper's session. */
+    cart: {
+        id: string;
+        metadata?: Record<string, unknown> | null;
+    };
+    provider?: string;
+    /** A provider error code (e.g. "card_declined"), never a free-text message: those can contain personal data. */
+    reason?: string;
+    amount?: {
+        amount: number;
+        currency: string;
+    };
+    /** Identifies this failure (e.g. the provider's event id) so a retried webhook counts once. */
+    failureId: string;
+}): void;
+/** For tests: forget the configured client. */
+export declare function resetStorewatchForTests(): void;

package/dist/index.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Storewatch for Medusa v2. Your Medusa backend becomes the source of truth
+ * for revenue: placed orders, cancellations and refunds are sent from the
+ * server, tied to the shopper's live session through cart metadata.
+ *
+ * One subscriber file per event in your Medusa project (Medusa reads each
+ * file's default export and `config`):
+ *
+ *   // src/subscribers/storewatch-order-placed.ts
+ *   export { orderPlacedSubscriber as default, orderPlacedConfig as config } from "@storewatch/medusa";
+ *
+ * Configure with STOREWATCH_SECRET_KEY and STOREWATCH_ENDPOINT, or call
+ * `configureStorewatch()` once at startup. Without configuration the
+ * subscribers log once and do nothing. They never throw into Medusa.
+ */
+import { type Storewatch } from "@storewatch/node";
+import { METADATA_KEY } from "./storefront.js";
+type Container = {
+    resolve(key: string): unknown;
+};
+export type SubscriberArgs<T> = {
+    event: {
+        data: T;
+        name?: string;
+    };
+    container: Container;
+};
+/**
+ * Medusa returns amounts and quantities as numbers, numeric strings, `raw_*`
+ * objects (`{ value, precision }`) or BigNumber class instances (computed
+ * totals, order item quantities), in major units.
+ */
+type Amount = number | string | {
+    value: number | string;
+} | {
+    numeric: number;
+} | object | null | undefined;
+/** Any of Medusa's amount shapes → a plain number (NaN when unreadable). */
+export declare function toNumber(amount: Amount): number;
+export type MedusaOrder = {
+    id: string;
+    display_id?: number | null;
+    currency_code: string;
+    total: Amount;
+    created_at?: string | Date | null;
+    customer_id?: string | null;
+    metadata?: Record<string, unknown> | null;
+    items?: {
+        id: string;
+        product_id?: string | null;
+        variant_id?: string | null;
+        title?: string | null;
+        product_title?: string | null;
+        quantity: Amount;
+        unit_price: Amount;
+    }[] | null;
+};
+export declare const ORDER_FIELDS: string[];
+/** Medusa v2 amounts are major units ("1299.5"); Storewatch uses integer minor units. */
+export declare function toMinor(amount: Amount, currency: string): number;
+export { METADATA_KEY };
+/**
+ * The shopper's Storewatch session, if the storefront put it on the cart
+ * (Medusa copies cart metadata to the order). Otherwise a stable per-order
+ * id: the order still counts as revenue, it just isn't tied to a visitor.
+ */
+export declare function sessionOf(order: Pick<MedusaOrder, "id" | "metadata">): {
+    sessionId: string;
+    anonymousId?: string;
+    linked: boolean;
+};
+export declare function orderCompletedEvent(order: MedusaOrder): {
+    sessionId: string;
+    anonymousId?: string;
+    customerId?: string;
+    eventId: string;
+    timestamp?: Date;
+    properties: {
+        orderId: string;
+        orderNumber?: string;
+        total: {
+            amount: number;
+            currency: string;
+        };
+        items: {
+            productId: string;
+            variantId?: string;
+            name?: string;
+            quantity: number;
+            price: {
+                amount: number;
+                currency: string;
+            };
+        }[];
+    };
+};
+/** Use your own client (e.g. with OpenTelemetry trace context). Call once at startup. */
+export declare function configureStorewatch(storewatch: Storewatch): void;
+export declare function orderPlacedSubscriber({ event, container }: SubscriberArgs<{
+    id: string;
+}>): Promise<void>;
+export declare const orderPlacedConfig: {
+    event: string;
+    context: {
+        subscriberId: string;
+    };
+};
+export declare function orderCanceledSubscriber({ event, container }: SubscriberArgs<{
+    id: string;
+}>): Promise<void>;
+export declare const orderCanceledConfig: {
+    event: string;
+    context: {
+        subscriberId: string;
+    };
+};
+/**
+ * `payment.refunded` carries the payment id. Every refund on the payment is
+ * sent with an id derived from the refund, so earlier ones dedupe at ingest.
+ */
+export declare function paymentRefundedSubscriber({ event, container }: SubscriberArgs<{
+    id: string;
+}>): Promise<void>;
+export declare const paymentRefundedConfig: {
+    event: string;
+    context: {
+        subscriberId: string;
+    };
+};
+/**
+ * Medusa has no event for a failed payment attempt. Call this where you see
+ * one (a payment webhook, a failed cart completion) so the live checkout
+ * health view shows it.
+ */
+export declare function trackPaymentFailed(input: {
+    /** The cart being paid for: its metadata links the failure to the shopper's session. */
+    cart: {
+        id: string;
+        metadata?: Record<string, unknown> | null;
+    };
+    provider?: string;
+    /** A provider error code (e.g. "card_declined"), never a free-text message: those can contain personal data. */
+    reason?: string;
+    amount?: {
+        amount: number;
+        currency: string;
+    };
+    /** Identifies this failure (e.g. the provider's event id) so a retried webhook counts once. */
+    failureId: string;
+}): void;
+/** For tests: forget the configured client. */
+export declare function resetStorewatchForTests(): void;

package/dist/index.js

@@ -0,0 +1,198 @@
+import {
+  METADATA_KEY
+} from "./chunk-DQHAPSCU.js";
+
+// src/index.ts
+import { createStorewatch, eventIdFor } from "@storewatch/node";
+import { currencyExponent, LIMITS } from "@storewatch/schema/constants";
+function toNumber(amount) {
+  if (amount === null || amount === void 0) return 0;
+  if (typeof amount === "number") return amount;
+  if (typeof amount === "string") return Number(amount);
+  const a = amount;
+  if (typeof a.numeric === "number") return a.numeric;
+  if (a.value !== void 0) return Number(a.value);
+  if (typeof a.toJSON === "function") return Number(a.toJSON());
+  return Number(String(amount));
+}
+var ORDER_FIELDS = [
+  "id",
+  "display_id",
+  "currency_code",
+  "total",
+  "created_at",
+  "customer_id",
+  "metadata",
+  "items.id",
+  "items.product_id",
+  "items.variant_id",
+  "items.title",
+  "items.product_title",
+  "items.quantity",
+  "items.unit_price"
+];
+function toMinor(amount, currency) {
+  const major = toNumber(amount);
+  if (!Number.isFinite(major)) return 0;
+  return Math.round(major * 10 ** currencyExponent(currency));
+}
+function sessionOf(order) {
+  const meta = order.metadata?.[METADATA_KEY];
+  if (meta && typeof meta === "object") {
+    const { sessionId, anonymousId } = meta;
+    if (typeof sessionId === "string" && sessionId.length > 0 && sessionId.length <= LIMITS.sessionIdMaxLength) {
+      return { sessionId, ...typeof anonymousId === "string" && anonymousId ? { anonymousId } : {}, linked: true };
+    }
+  }
+  return { sessionId: `srv_${order.id}`.slice(0, LIMITS.sessionIdMaxLength), linked: false };
+}
+function sessionFields(order) {
+  const { linked: _linked, ...fields } = sessionOf(order);
+  return fields;
+}
+function orderCompletedEvent(order) {
+  const currency = order.currency_code.toUpperCase();
+  const money = (amount) => ({ amount: toMinor(amount, currency), currency });
+  return {
+    ...sessionFields(order),
+    ...order.customer_id ? { customerId: order.customer_id } : {},
+    eventId: eventIdFor("order_completed", order.id),
+    ...order.created_at ? { timestamp: new Date(order.created_at) } : {},
+    properties: {
+      orderId: order.id,
+      ...order.display_id != null ? { orderNumber: String(order.display_id) } : {},
+      total: money(order.total),
+      items: (order.items ?? []).slice(0, LIMITS.orderMaxItems).map((item) => ({
+        productId: item.product_id ?? item.id,
+        ...item.variant_id ? { variantId: item.variant_id } : {},
+        ...item.product_title || item.title ? { name: String(item.product_title || item.title).slice(0, 200) } : {},
+        quantity: Math.max(1, Math.round(toNumber(item.quantity) || 1)),
+        price: money(item.unit_price)
+      }))
+    }
+  };
+}
+var client;
+var warnedUnconfigured = false;
+function configureStorewatch(storewatch) {
+  client = storewatch;
+}
+function getClient(logger) {
+  if (client !== void 0) return client;
+  const secretKey = process.env.STOREWATCH_SECRET_KEY;
+  const endpoint = process.env.STOREWATCH_ENDPOINT;
+  if (!secretKey || !endpoint) {
+    if (!warnedUnconfigured) logger?.warn("[storewatch] STOREWATCH_SECRET_KEY / STOREWATCH_ENDPOINT not set; Medusa events are not sent.");
+    warnedUnconfigured = true;
+    return null;
+  }
+  client = createStorewatch({ secretKey, endpoint, onError: (e) => logger?.warn(`[storewatch] ${e.message}`) });
+  return client;
+}
+var resolveSafe = (container, key) => {
+  try {
+    return container.resolve(key);
+  } catch {
+    return void 0;
+  }
+};
+async function failOpen(container, label, run) {
+  const logger = resolveSafe(container, "logger");
+  try {
+    const storewatch = getClient(logger);
+    const query = resolveSafe(container, "query");
+    if (!storewatch || !query) return;
+    await run(query, storewatch);
+  } catch (error) {
+    logger?.warn(`[storewatch] ${label} failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+async function fetchOrder(query, id) {
+  const { data } = await query.graph({ entity: "order", fields: ORDER_FIELDS, filters: { id } });
+  return data[0];
+}
+async function orderPlacedSubscriber({ event, container }) {
+  await failOpen(container, "order.placed", async (query, storewatch) => {
+    const order = await fetchOrder(query, event.data.id);
+    if (!order) return;
+    storewatch.track("order_completed", orderCompletedEvent(order));
+  });
+}
+var orderPlacedConfig = { event: "order.placed", context: { subscriberId: "storewatch-order-placed" } };
+async function orderCanceledSubscriber({ event, container }) {
+  await failOpen(container, "order.canceled", async (query, storewatch) => {
+    const order = await fetchOrder(query, event.data.id);
+    if (!order) return;
+    storewatch.track("order_cancelled", {
+      ...sessionFields(order),
+      eventId: eventIdFor("order_cancelled", order.id),
+      properties: { orderId: order.id }
+    });
+  });
+}
+var orderCanceledConfig = { event: "order.canceled", context: { subscriberId: "storewatch-order-canceled" } };
+async function paymentRefundedSubscriber({ event, container }) {
+  await failOpen(container, "payment.refunded", async (query, storewatch) => {
+    const { data: payments } = await query.graph({
+      entity: "payment",
+      fields: ["id", "currency_code", "payment_collection_id", "refunds.id", "refunds.amount", "refunds.created_at"],
+      filters: { id: event.data.id }
+    });
+    const payment = payments[0];
+    if (!payment?.payment_collection_id || !payment.refunds?.length) return;
+    const { data: links } = await query.graph({
+      entity: "order_payment_collection",
+      fields: ["order_id"],
+      filters: { payment_collection_id: payment.payment_collection_id }
+    });
+    const orderId = links[0]?.order_id;
+    if (!orderId) return;
+    const order = await fetchOrder(query, orderId);
+    const currency = payment.currency_code.toUpperCase();
+    for (const refund of payment.refunds) {
+      storewatch.track("refund_created", {
+        ...sessionFields(order ?? { id: orderId }),
+        eventId: eventIdFor("refund_created", refund.id),
+        ...refund.created_at ? { timestamp: new Date(refund.created_at) } : {},
+        properties: { orderId, refundId: refund.id, amount: { amount: toMinor(refund.amount, currency), currency } }
+      });
+    }
+  });
+}
+var paymentRefundedConfig = { event: "payment.refunded", context: { subscriberId: "storewatch-payment-refunded" } };
+function trackPaymentFailed(input) {
+  try {
+    getClient(void 0)?.track("payment_failed", {
+      ...sessionFields(input.cart),
+      eventId: eventIdFor("payment_failed", input.failureId),
+      properties: {
+        checkoutId: input.cart.id,
+        ...input.provider ? { provider: input.provider } : {},
+        ...input.reason ? { reason: input.reason } : {},
+        ...input.amount ? { amount: input.amount } : {}
+      }
+    });
+  } catch {
+  }
+}
+function resetStorewatchForTests() {
+  client = void 0;
+  warnedUnconfigured = false;
+}
+export {
+  METADATA_KEY,
+  ORDER_FIELDS,
+  configureStorewatch,
+  orderCanceledConfig,
+  orderCanceledSubscriber,
+  orderCompletedEvent,
+  orderPlacedConfig,
+  orderPlacedSubscriber,
+  paymentRefundedConfig,
+  paymentRefundedSubscriber,
+  resetStorewatchForTests,
+  sessionOf,
+  toMinor,
+  toNumber,
+  trackPaymentFailed
+};

package/dist/storefront.cjs

@@ -0,0 +1,41 @@
+"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/storefront.ts
+var storefront_exports = {};
+__export(storefront_exports, {
+  METADATA_KEY: () => METADATA_KEY,
+  cartHasSession: () => cartHasSession,
+  storewatchCartMetadata: () => storewatchCartMetadata
+});
+module.exports = __toCommonJS(storefront_exports);
+var METADATA_KEY = "storewatch";
+function storewatchCartMetadata(ids) {
+  return { [METADATA_KEY]: { sessionId: ids.sessionId, ...ids.anonymousId ? { anonymousId: ids.anonymousId } : {} } };
+}
+function cartHasSession(metadata, sessionId) {
+  const current = metadata?.[METADATA_KEY];
+  return typeof current === "object" && current !== null && current.sessionId === sessionId;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  METADATA_KEY,
+  cartHasSession,
+  storewatchCartMetadata
+});

package/dist/storefront.d.cts

@@ -0,0 +1,28 @@
+/**
+ * Storefront side of the Medusa integration: put the shopper's Storewatch
+ * session on the cart, so the order Medusa creates from it carries the link
+ * back to their live journey. Browser-safe, no dependencies.
+ *
+ *   import { getStorewatch } from "@storewatch/browser";
+ *   import { storewatchCartMetadata } from "@storewatch/medusa/storefront";
+ *
+ *   await sdk.store.cart.update(cart.id, {
+ *     metadata: { ...cart.metadata, ...storewatchCartMetadata(getStorewatch().ids()) },
+ *   });
+ *
+ * Spread the cart's existing metadata in, so other keys (attribution,
+ * consent) are kept.
+ */
+export declare const METADATA_KEY = "storewatch";
+export type StorewatchCartMetadata = {
+    [METADATA_KEY]: {
+        sessionId: string;
+        anonymousId?: string;
+    };
+};
+export declare function storewatchCartMetadata(ids: {
+    sessionId: string;
+    anonymousId: string | null;
+}): StorewatchCartMetadata;
+/** True when the cart already points at this session (skip the update). */
+export declare function cartHasSession(metadata: Record<string, unknown> | null | undefined, sessionId: string): boolean;

package/dist/storefront.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Storefront side of the Medusa integration: put the shopper's Storewatch
+ * session on the cart, so the order Medusa creates from it carries the link
+ * back to their live journey. Browser-safe, no dependencies.
+ *
+ *   import { getStorewatch } from "@storewatch/browser";
+ *   import { storewatchCartMetadata } from "@storewatch/medusa/storefront";
+ *
+ *   await sdk.store.cart.update(cart.id, {
+ *     metadata: { ...cart.metadata, ...storewatchCartMetadata(getStorewatch().ids()) },
+ *   });
+ *
+ * Spread the cart's existing metadata in, so other keys (attribution,
+ * consent) are kept.
+ */
+export declare const METADATA_KEY = "storewatch";
+export type StorewatchCartMetadata = {
+    [METADATA_KEY]: {
+        sessionId: string;
+        anonymousId?: string;
+    };
+};
+export declare function storewatchCartMetadata(ids: {
+    sessionId: string;
+    anonymousId: string | null;
+}): StorewatchCartMetadata;
+/** True when the cart already points at this session (skip the update). */
+export declare function cartHasSession(metadata: Record<string, unknown> | null | undefined, sessionId: string): boolean;

package/dist/storefront.js

@@ -0,0 +1,10 @@
+import {
+  METADATA_KEY,
+  cartHasSession,
+  storewatchCartMetadata
+} from "./chunk-DQHAPSCU.js";
+export {
+  METADATA_KEY,
+  cartHasSession,
+  storewatchCartMetadata
+};

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@storewatch/medusa",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Storewatch for Medusa v2: server-confirmed orders, cancellations and refunds, tied to the shopper's live session.",
+  "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"
+      }
+    },
+    "./storefront": {
+      "import": {
+        "types": "./dist/storefront.d.ts",
+        "default": "./dist/storefront.js"
+      },
+      "require": {
+        "types": "./dist/storefront.d.cts",
+        "default": "./dist/storefront.cjs"
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@storewatch/node": "0.2.0",
+    "@storewatch/schema": "0.2.0"
+  },
+  "devDependencies": {
+    "tsup": "^9.0.0",
+    "@storewatch/config": "0.0.0"
+  },
+  "keywords": [
+    "storewatch",
+    "analytics",
+    "ecommerce"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsup && tsc -p tsconfig.build.json && node ../../scripts/dual-dts.mjs dist",
+    "typecheck": "tsc -p .",
+    "test": "vitest run"
+  }
 }