@zappie/sdk 0.0.0-stage → 0.1.1

package/dist/visits/index.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The string storage interface used to retain visit attribution and reached steps.
+ */
+type VisitStorage = {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+};
+/**
+ * A page-view payload with attribution and flags for a new visit and a newly reached page kind.
+ */
+type PageView = {
+    path: string;
+    title: string;
+    source: string;
+    campaign: string;
+    new: boolean;
+    step: boolean;
+};
+/**
+ * Supported visit events: adding an item or viewing the bag.
+ */
+type VisitEventName = "add" | "bag";
+/**
+ * A visit event with its path, attribution and whether this event is a new step.
+ */
+type VisitEvent = {
+    event: VisitEventName;
+    path: string;
+    source: string;
+    campaign: string;
+    step: boolean;
+};
+/**
+ * Page location, title, referrer and store name plus the storage used to track the visit.
+ */
+type PageViewInput = {
+    path: string;
+    search: string;
+    title: string;
+    referrer: string;
+    storeName: string;
+    storage: VisitStorage;
+};
+/**
+ * Build a page-view payload and save visit attribution and reached steps in your storage.
+ * On the first page, utm_source takes precedence over the referrer and utm_campaign supplies the campaign.
+ *
+ * @returns The payload with the store name removed from its title and visit/step flags. Does not send a request.
+ */
+declare function pageView(input: PageViewInput): PageView;
+/**
+ * Build a visit-event payload and record whether this event has already occurred in storage.
+ * Uses stored attribution or empty strings. Does not send a request.
+ */
+declare function visitEvent(event: VisitEventName, path: string, storage: VisitStorage): VisitEvent;
+/**
+ * Read the saved visit source and campaign from your storage, defaulting each to an empty string.
+ */
+declare function visitSource(storage: VisitStorage): {
+    source: string;
+    campaign: string;
+};
+
+/**
+ * Page-view details with an optional enabled flag. Browser session storage is supplied automatically.
+ */
+type CountPageInput = Omit<PageViewInput, "storage"> & {
+    enabled?: boolean;
+};
+/**
+ * Record a page view in session storage and send it to /_zappie/view when sendBeacon is available.
+ * Passing enabled: false disables this call and subsequent event counting until an enabled page is counted.
+ */
+declare function countPage(input: CountPageInput): void;
+/**
+ * Send an add or bag event for the current path after countPage has enabled counting.
+ * Does nothing without a browser window or sendBeacon support.
+ */
+declare function countEvent(event: VisitEventName): void;
+/**
+ * Read visit attribution from browser session storage.
+ * Returns empty source and campaign strings on the server or when no visit is stored.
+ */
+declare function currentSource(): {
+    source: string;
+    campaign: string;
+};
+
+export { type CountPageInput, type PageView, type PageViewInput, type VisitEvent, type VisitEventName, type VisitStorage, countEvent, countPage, currentSource, pageView, visitEvent, visitSource };

package/dist/visits/index.js

@@ -0,0 +1 @@
+var V="zappie_visit";function a(t){try{let e=t.getItem(V);return e?JSON.parse(e):null}catch{return null}}function v(t,e){try{t.setItem(V,JSON.stringify(e));}catch{}}function I(t){return t==="/"?"menu":t.startsWith("/item/")?"item":t==="/cart"?"bag":t==="/checkout"?"checkout":t.startsWith("/checkout/")?"payment":t.startsWith("/orders")?"order":"page"}function d(t,e,n){let i=e.steps??[];return i.includes(n)?false:(e.steps=[...i,n],v(t,e),true)}function E(t,e,n){let i=t.split(/\s+[·|–-]\s+/).filter(s=>s.trim()&&s.trim()!==e).join(" \xB7 ").trim();return i||(n==="/"?"Home":"")}function u(t){let{path:e,search:n,title:i,referrer:s,storeName:S,storage:o}=t,m=a(o),r=m;if(!r){let l=new URLSearchParams(n);r={source:l.get("utm_source")||s,campaign:l.get("utm_campaign")||""},v(o,r);}return {path:e,title:E(i,S,e),source:r.source,campaign:r.campaign,new:m===null,step:d(o,r,I(e))}}function g(t,e,n){let i=a(n)??{source:"",campaign:""};return {event:t,path:e,source:i.source,campaign:i.campaign,step:d(n,i,t)}}function c(t){let e=a(t);return {source:e?.source??"",campaign:e?.campaign??""}}var p=false,h={getItem:()=>null,setItem:()=>{}};function f(){try{return window.sessionStorage}catch{return h}}function y(){return typeof navigator<"u"&&typeof navigator.sendBeacon=="function"}function w(t){navigator.sendBeacon("/_zappie/view",JSON.stringify(t));}function P(t){if(p=false,t.enabled===false)return;let{enabled:e,...n}=t,i=u({...n,storage:f()});p=true,y()&&w(i);}function N(t){!p||typeof window>"u"||!y()||w(g(t,window.location.pathname,f()));}function k(){return typeof window>"u"?{source:"",campaign:""}:c(f())}export{N as countEvent,P as countPage,k as currentSource,u as pageView,g as visitEvent,c as visitSource};//# sourceMappingURL=index.js.map

package/dist/visits/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/visits/page-views.ts","../../src/visits/index.ts"],"names":["VISIT_KEY","stored","storage","raw","save","visit","kindOf","path","reached","kind","steps","titleOf","title","storeName","own","part","pageView","input","search","referrer","known","query","visitEvent","event","visitSource","counting","emptyStorage","session","canSend","send","body","countPage","_enabled","page","view","countEvent","currentSource"],"mappings":"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","file":"index.js","sourcesContent":["const VISIT_KEY = \"zappie_visit\";\n\n/**\n * The string storage interface used to retain visit attribution and reached steps.\n */\nexport type VisitStorage = {\n  getItem(key: string): string | null;\n  setItem(key: string, value: string): void;\n};\n\ntype Visit = { source: string; campaign: string; steps?: string[] };\n\n/**\n * A page-view payload with attribution and flags for a new visit and a newly reached page kind.\n */\nexport type PageView = {\n  path: string;\n  title: string;\n  source: string;\n  campaign: string;\n  new: boolean;\n  step: boolean;\n};\n\n/**\n * Supported visit events: adding an item or viewing the bag.\n */\nexport type VisitEventName = \"add\" | \"bag\";\n\n/**\n * A visit event with its path, attribution and whether this event is a new step.\n */\nexport type VisitEvent = {\n  event: VisitEventName;\n  path: string;\n  source: string;\n  campaign: string;\n  step: boolean;\n};\n\n/**\n * Page location, title, referrer and store name plus the storage used to track the visit.\n */\nexport type PageViewInput = {\n  path: string;\n  search: string;\n  title: string;\n  referrer: string;\n  storeName: string;\n  storage: VisitStorage;\n};\n\nfunction stored(storage: VisitStorage): Visit | null {\n  try {\n    const raw = storage.getItem(VISIT_KEY);\n    if (raw) {\n      return JSON.parse(raw) as Visit;\n    }\n    return null;\n  } catch {\n    return null;\n  }\n}\n\nfunction save(storage: VisitStorage, visit: Visit): void {\n  try {\n    storage.setItem(VISIT_KEY, JSON.stringify(visit));\n  } catch {\n    // Without storage, each page is its own visit.\n  }\n}\n\nfunction kindOf(path: string): string {\n  if (path === \"/\") {\n    return \"menu\";\n  }\n  if (path.startsWith(\"/item/\")) {\n    return \"item\";\n  }\n  if (path === \"/cart\") {\n    return \"bag\";\n  }\n  if (path === \"/checkout\") {\n    return \"checkout\";\n  }\n  if (path.startsWith(\"/checkout/\")) {\n    return \"payment\";\n  }\n  if (path.startsWith(\"/orders\")) {\n    return \"order\";\n  }\n  return \"page\";\n}\n\nfunction reached(storage: VisitStorage, visit: Visit, kind: string): boolean {\n  const steps = visit.steps ?? [];\n  if (steps.includes(kind)) {\n    return false;\n  }\n  visit.steps = [...steps, kind];\n  save(storage, visit);\n  return true;\n}\n\nfunction titleOf(title: string, storeName: string, path: string): string {\n  const own = title\n    .split(/\\s+[·|–-]\\s+/)\n    .filter((part) => part.trim() && part.trim() !== storeName)\n    .join(\" · \")\n    .trim();\n  if (own) {\n    return own;\n  }\n  if (path === \"/\") {\n    return \"Home\";\n  }\n  return \"\";\n}\n\n/**\n * Build a page-view payload and save visit attribution and reached steps in your storage.\n * On the first page, utm_source takes precedence over the referrer and utm_campaign supplies the campaign.\n *\n * @returns The payload with the store name removed from its title and visit/step flags. Does not send a request.\n */\nexport function pageView(input: PageViewInput): PageView {\n  const { path, search, title, referrer, storeName, storage } = input;\n  const known = stored(storage);\n  let visit = known;\n  if (!visit) {\n    const query = new URLSearchParams(search);\n    visit = {\n      source: query.get(\"utm_source\") || referrer,\n      campaign: query.get(\"utm_campaign\") || \"\",\n    };\n    save(storage, visit);\n  }\n  return {\n    path,\n    title: titleOf(title, storeName, path),\n    source: visit.source,\n    campaign: visit.campaign,\n    new: known === null,\n    step: reached(storage, visit, kindOf(path)),\n  };\n}\n\n/**\n * Build a visit-event payload and record whether this event has already occurred in storage.\n * Uses stored attribution or empty strings. Does not send a request.\n */\nexport function visitEvent(\n  event: VisitEventName,\n  path: string,\n  storage: VisitStorage,\n): VisitEvent {\n  const visit = stored(storage) ?? { source: \"\", campaign: \"\" };\n  return {\n    event,\n    path,\n    source: visit.source,\n    campaign: visit.campaign,\n    step: reached(storage, visit, event),\n  };\n}\n\n/**\n * Read the saved visit source and campaign from your storage, defaulting each to an empty string.\n */\nexport function visitSource(storage: VisitStorage): {\n  source: string;\n  campaign: string;\n} {\n  const visit = stored(storage);\n  return {\n    source: visit?.source ?? \"\",\n    campaign: visit?.campaign ?? \"\",\n  };\n}\n","import {\n  pageView,\n  visitEvent,\n  visitSource,\n  type PageViewInput,\n  type VisitEventName,\n  type VisitStorage,\n} from \"./page-views\";\n\nexport {\n  pageView,\n  visitEvent,\n  visitSource,\n  type PageView,\n  type PageViewInput,\n  type VisitEvent,\n  type VisitEventName,\n  type VisitStorage,\n} from \"./page-views\";\n\n/**\n * Page-view details with an optional enabled flag. Browser session storage is supplied automatically.\n */\nexport type CountPageInput = Omit<PageViewInput, \"storage\"> & {\n  enabled?: boolean;\n};\n\nlet counting = false;\n\nconst emptyStorage: VisitStorage = {\n  getItem: () => null,\n  setItem: () => undefined,\n};\n\nfunction session(): VisitStorage {\n  try {\n    return window.sessionStorage;\n  } catch {\n    return emptyStorage;\n  }\n}\n\nfunction canSend(): boolean {\n  return (\n    typeof navigator !== \"undefined\" &&\n    typeof navigator.sendBeacon === \"function\"\n  );\n}\n\nfunction send(body: unknown): void {\n  navigator.sendBeacon(\"/_zappie/view\", JSON.stringify(body));\n}\n\n/**\n * Record a page view in session storage and send it to /_zappie/view when sendBeacon is available.\n * Passing enabled: false disables this call and subsequent event counting until an enabled page is counted.\n */\nexport function countPage(input: CountPageInput): void {\n  counting = false;\n  if (input.enabled === false) {\n    return;\n  }\n  const { enabled: _enabled, ...page } = input;\n  // The visit is recorded even without a beacon, so checkout can still name its source.\n  const view = pageView({ ...page, storage: session() });\n  counting = true;\n  if (canSend()) {\n    send(view);\n  }\n}\n\n/**\n * Send an add or bag event for the current path after countPage has enabled counting.\n * Does nothing without a browser window or sendBeacon support.\n */\nexport function countEvent(event: VisitEventName): void {\n  if (!counting || typeof window === \"undefined\" || !canSend()) {\n    return;\n  }\n  send(visitEvent(event, window.location.pathname, session()));\n}\n\n/**\n * Read visit attribution from browser session storage.\n * Returns empty source and campaign strings on the server or when no visit is stored.\n */\nexport function currentSource(): { source: string; campaign: string } {\n  if (typeof window === \"undefined\") {\n    return { source: \"\", campaign: \"\" };\n  }\n  return visitSource(session());\n}\n"]}

package/package.json

@@ -1,6 +1,108 @@
 {
   "name": "@zappie/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Typed, framework-agnostic client for Zappie menus, carts, checkout, auth and events.",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.js"
+    },
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "import": "./dist/config/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
+    },
+    "./url": {
+      "types": "./dist/url/index.d.ts",
+      "import": "./dist/url/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    },
+    "./cart/item": {
+      "types": "./dist/cart/item.d.ts",
+      "import": "./dist/cart/item.js"
+    },
+    "./checkout": {
+      "types": "./dist/checkout/index.d.ts",
+      "import": "./dist/checkout/index.js"
+    },
+    "./customer": {
+      "types": "./dist/customer/index.d.ts",
+      "import": "./dist/customer/index.js"
+    },
+    "./customer/react": {
+      "types": "./dist/customer/react.d.ts",
+      "import": "./dist/customer/react.js"
+    },
+    "./places": {
+      "types": "./dist/places/index.d.ts",
+      "import": "./dist/places/index.js"
+    },
+    "./visits": {
+      "types": "./dist/visits/index.d.ts",
+      "import": "./dist/visits/index.js"
+    },
+    "./template": {
+      "types": "./dist/template/index.d.ts",
+      "import": "./dist/template/index.js"
+    },
+    "./template/react": {
+      "types": "./dist/template/react.d.ts",
+      "import": "./dist/template/react.js"
+    },
+    "./persist/catalogue": {
+      "types": "./dist/persist/catalogue.d.ts",
+      "import": "./dist/persist/catalogue.js"
+    },
+    "./transport/selected-menu": {
+      "types": "./dist/transport/selected-menu.d.ts",
+      "import": "./dist/transport/selected-menu.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "peerDependencies": {
+    "react": "^18.2.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zappie/storefront.git",
+    "directory": "packages/sdk"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/zappie/storefront#readme",
+  "bugs": {
+    "url": "https://github.com/zappie/storefront/issues"
+  },
+  "scripts": {
+    "build": "tsup && tsup --config tsup.checkout.config.ts && tsup --config tsup.customer.config.ts && tsup --config tsup.places.config.ts && tsup --config tsup.url.config.ts && tsup --config tsup.visits.config.ts && tsup --config tsup.site-config.config.ts && tsup --config tsup.template.config.ts",
+    "test": "vitest run --root ../.. packages/sdk/test",
+    "size": "size-limit"
+  }
 }