@canopypay/checkout-sdk 0.2.0

package/dist/canopy.global.js

@@ -0,0 +1 @@
+"use strict";(()=>{(function(){"use strict";if(typeof window=="undefined")return;let f="width=460,height=640",m=2500,y="Pay with Canopy",h=500,g="canopy",v="cnpy_pk_live_";function b(){let e=document.currentScript;if(e&&e.src)try{return new URL(e.src).origin}catch(o){}let n=document.getElementsByTagName("script");for(let o=0;o<n.length;o+=1){let r=n[o].src;if(r&&/\/v1\/(?:[^/]+\/)?canopy\.js(?:[?#].*)?$/.test(r))try{return new URL(r).origin}catch(t){}}return null}function k(e){let n;try{n=new URL(e)}catch(t){return{ok:!1,code:"canopy_origin_invalid"}}if(!((n.pathname===""||n.pathname==="/")&&n.search===""&&n.hash===""))return{ok:!1,code:"canopy_origin_not_bare"};let r=n.hostname==="localhost"||n.hostname==="127.0.0.1";return n.protocol!=="https:"&&!r?{ok:!1,code:"canopy_origin_insecure"}:{ok:!0,origin:n.origin}}function _(e){if(e!==void 0)return k(e);let n=b();return n?{ok:!0,origin:n}:{ok:!1,code:"canopy_origin_undiscoverable"}}function c(e){let n=new URL("/customer-pay",e.origin);return n.searchParams.set("merchant",e.merchant),n.hash="cap="+encodeURIComponent(e.capability||""),n.toString()}function i(e,n,o){if(!e.destroyed)try{e.onEvent(Object.assign({type:n},o))}catch(r){}}function l(e){e.handshakeTimer&&(clearTimeout(e.handshakeTimer),e.handshakeTimer=null),e.resizeObserver&&(e.resizeObserver.disconnect(),e.resizeObserver=null),e.frame&&(e.frame.parentNode&&e.frame.parentNode.removeChild(e.frame),e.frame=null),e.lastHeight=null}function E(e){e.popupPollTimer&&clearInterval(e.popupPollTimer),e.popupPollTimer=setInterval(function(){try{e.popupWin&&e.popupWin.closed&&(e.popupPollTimer&&clearInterval(e.popupPollTimer),e.popupPollTimer=null,e.popupWin=null,i(e,"close",{via:"popup"}))}catch(n){e.popupPollTimer&&clearInterval(e.popupPollTimer),e.popupPollTimer=null}},h)}function p(e,n){if(!e.destroyed){if(!n){i(e,"error",{code:"popup_blocked"});return}if(!e.capability){try{n.close()}catch(o){}i(e,"error",{code:"capability_unavailable"});return}try{n.location.href=c(e)}catch(o){i(e,"error",{code:"popup_navigation_failed"});return}e.popupWin=n,E(e)}}function T(e){let n=document.createElement("button");n.type="button",n.textContent=e.fallbackLabel;let o=n.style;o.background="#1A7A4C",o.color="#FFFFFF",o.border="none",o.borderRadius="8px",o.height="48px",o.padding="0 20px",o.fontSize="16px",o.fontFamily="inherit",o.cursor="pointer",o.maxWidth="100%",o.overflow="hidden",o.textOverflow="ellipsis",o.whiteSpace="nowrap",o.display="inline-block",n.addEventListener("click",function(){let r=window.open("","canopy_checkout",f);p(e,r)}),e.node.appendChild(n),e.fallbackButton=n,i(e,"fallback_offered",{surface:"popup",reason:"iframe_unavailable"})}function w(e){let n=document.createElement("iframe");n.src=c(e),n.style.width="100%",n.style.border="none",e.node.appendChild(n),e.frame=n,typeof ResizeObserver!="undefined"&&(e.resizeObserver=new ResizeObserver(function(o){for(let r=0;r<o.length;r+=1){let t=Math.round(o[r].contentRect.height);t>0&&t!==e.lastHeight&&(e.lastHeight=t,i(e,"resize",{height:t}))}}),e.resizeObserver.observe(n)),e.handshakeTimer=setTimeout(function(){e.handshakeTimer=null,i(e,"surface_unavailable",{attempted:"iframe"}),l(e),e.surface==="auto"?T(e):i(e,"error",{code:"iframe_blocked"})},e.handshakeTimeoutMs)}function O(e,n){if(n.origin!==e.origin)return;let o=n.data;if(!(!o||o.source!==g)){if(o.type==="ready"){e.handshakeTimer&&(clearTimeout(e.handshakeTimer),e.handshakeTimer=null),i(e,"ready");return}if(o.type==="resize"&&typeof o.height=="number"&&e.frame){e.frame.style.height=o.height+"px";return}if(o.type==="paid"){i(e,"paid",o);return}if(o.type==="close"){i(e,"close");return}}}let s=new WeakMap;function L(e){if(typeof e.merchant!="string"||e.merchant.indexOf(v)!==0){try{(e.onEvent||function(){})({type:"error",code:"invalid_merchant_key"})}catch(a){}return{openNow:function(){},destroy:function(){}}}let n=_(e.canopyOrigin);if(!n.ok){try{(e.onEvent||function(){})({type:"error",code:n.code})}catch(a){}return{openNow:function(){},destroy:function(){}}}let o=typeof e.target=="string"?document.querySelector(e.target):e.target;if(!o)return{openNow:function(){},destroy:function(){}};let r=s.get(o);if(r)return r;let t={node:o,capability:e.capability,merchant:e.merchant,origin:n.origin,surface:e.surface||"popup",handshakeTimeoutMs:e.handshakeTimeoutMs||m,fallbackLabel:e.fallbackLabel||y,onEvent:e.onEvent||function(){},destroyed:!1,messageListener:function(){},handshakeTimer:null,resizeObserver:null,frame:null,fallbackButton:null,lastHeight:null,popupWin:null,popupPollTimer:null};t.messageListener=function(a){O(t,a)},window.addEventListener("message",t.messageListener),(t.surface==="iframe"||t.surface==="auto")&&w(t);let d={openNow:function(a){p(t,a)},destroy:function(){t.destroyed||(t.destroyed=!0,window.removeEventListener("message",t.messageListener),l(t),t.popupPollTimer&&(clearInterval(t.popupPollTimer),t.popupPollTimer=null),t.fallbackButton&&(t.fallbackButton.parentNode&&t.fallbackButton.parentNode.removeChild(t.fallbackButton),t.fallbackButton=null),s.delete(o))}};return s.set(o,d),d}let u=window;u.Canopy&&u.Canopy.__version==="2"||(u.Canopy={mount:L,__version:"2"})})();})();

package/dist/index.cjs

@@ -0,0 +1,347 @@
+"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 src_exports = {};
+__export(src_exports, {
+  mount: () => mount,
+  version: () => version
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/loader.ts
+var LOADER_VERSION = "2";
+(function() {
+  "use strict";
+  if (typeof window === "undefined") return;
+  const POPUP_FEATURES = "width=460,height=640";
+  const DEFAULT_HANDSHAKE_TIMEOUT_MS = 2500;
+  const DEFAULT_FALLBACK_LABEL = "Pay with Canopy";
+  const POPUP_POLL_INTERVAL_MS = 500;
+  const MESSAGE_SOURCE = "canopy";
+  const PUBLISHABLE_KEY_PREFIX = "cnpy_pk_live_";
+  function resolveOrigin() {
+    const current = document.currentScript;
+    if (current && current.src) {
+      try {
+        return new URL(current.src).origin;
+      } catch {
+      }
+    }
+    const scripts = document.getElementsByTagName("script");
+    for (let i = 0; i < scripts.length; i += 1) {
+      const src = scripts[i].src;
+      if (src && /\/v1\/(?:[^/]+\/)?canopy\.js(?:[?#].*)?$/.test(src)) {
+        try {
+          return new URL(src).origin;
+        } catch {
+        }
+      }
+    }
+    return null;
+  }
+  function validateExplicitOrigin(raw) {
+    let url;
+    try {
+      url = new URL(raw);
+    } catch {
+      return { ok: false, code: "canopy_origin_invalid" };
+    }
+    const isBare = (url.pathname === "" || url.pathname === "/") && url.search === "" && url.hash === "";
+    if (!isBare) {
+      return { ok: false, code: "canopy_origin_not_bare" };
+    }
+    const isDevHost = url.hostname === "localhost" || url.hostname === "127.0.0.1";
+    if (url.protocol !== "https:" && !isDevHost) {
+      return { ok: false, code: "canopy_origin_insecure" };
+    }
+    return { ok: true, origin: url.origin };
+  }
+  function resolveMountOrigin(explicit) {
+    if (explicit !== void 0) {
+      return validateExplicitOrigin(explicit);
+    }
+    const scriptOrigin = resolveOrigin();
+    if (scriptOrigin) {
+      return { ok: true, origin: scriptOrigin };
+    }
+    return { ok: false, code: "canopy_origin_undiscoverable" };
+  }
+  function buildCheckoutUrl(internal) {
+    const url = new URL("/customer-pay", internal.origin);
+    url.searchParams.set("merchant", internal.merchant);
+    url.hash = "cap=" + encodeURIComponent(internal.capability || "");
+    return url.toString();
+  }
+  function emit(internal, type, data) {
+    if (internal.destroyed) return;
+    try {
+      internal.onEvent(Object.assign({ type }, data));
+    } catch {
+    }
+  }
+  function teardownFrame(internal) {
+    if (internal.handshakeTimer) {
+      clearTimeout(internal.handshakeTimer);
+      internal.handshakeTimer = null;
+    }
+    if (internal.resizeObserver) {
+      internal.resizeObserver.disconnect();
+      internal.resizeObserver = null;
+    }
+    if (internal.frame) {
+      if (internal.frame.parentNode)
+        internal.frame.parentNode.removeChild(internal.frame);
+      internal.frame = null;
+    }
+    internal.lastHeight = null;
+  }
+  function startPopupClosePolling(internal) {
+    if (internal.popupPollTimer) clearInterval(internal.popupPollTimer);
+    internal.popupPollTimer = setInterval(function() {
+      try {
+        if (internal.popupWin && internal.popupWin.closed) {
+          if (internal.popupPollTimer) clearInterval(internal.popupPollTimer);
+          internal.popupPollTimer = null;
+          internal.popupWin = null;
+          emit(internal, "close", { via: "popup" });
+        }
+      } catch {
+        if (internal.popupPollTimer) clearInterval(internal.popupPollTimer);
+        internal.popupPollTimer = null;
+      }
+    }, POPUP_POLL_INTERVAL_MS);
+  }
+  function openNowInternal(internal, win) {
+    if (internal.destroyed) return;
+    if (!win) {
+      emit(internal, "error", { code: "popup_blocked" });
+      return;
+    }
+    if (!internal.capability) {
+      try {
+        win.close();
+      } catch {
+      }
+      emit(internal, "error", { code: "capability_unavailable" });
+      return;
+    }
+    try {
+      win.location.href = buildCheckoutUrl(internal);
+    } catch {
+      emit(internal, "error", { code: "popup_navigation_failed" });
+      return;
+    }
+    internal.popupWin = win;
+    startPopupClosePolling(internal);
+  }
+  function offerFallback(internal) {
+    const button = document.createElement("button");
+    button.type = "button";
+    button.textContent = internal.fallbackLabel;
+    const style = button.style;
+    style.background = "#1A7A4C";
+    style.color = "#FFFFFF";
+    style.border = "none";
+    style.borderRadius = "8px";
+    style.height = "48px";
+    style.padding = "0 20px";
+    style.fontSize = "16px";
+    style.fontFamily = "inherit";
+    style.cursor = "pointer";
+    style.maxWidth = "100%";
+    style.overflow = "hidden";
+    style.textOverflow = "ellipsis";
+    style.whiteSpace = "nowrap";
+    style.display = "inline-block";
+    button.addEventListener("click", function() {
+      const win = window.open("", "canopy_checkout", POPUP_FEATURES);
+      openNowInternal(internal, win);
+    });
+    internal.node.appendChild(button);
+    internal.fallbackButton = button;
+    emit(internal, "fallback_offered", {
+      surface: "popup",
+      reason: "iframe_unavailable"
+    });
+  }
+  function createFrame(internal) {
+    const iframe = document.createElement("iframe");
+    iframe.src = buildCheckoutUrl(internal);
+    iframe.style.width = "100%";
+    iframe.style.border = "none";
+    internal.node.appendChild(iframe);
+    internal.frame = iframe;
+    if (typeof ResizeObserver !== "undefined") {
+      internal.resizeObserver = new ResizeObserver(function(entries) {
+        for (let i = 0; i < entries.length; i += 1) {
+          const height = Math.round(entries[i].contentRect.height);
+          if (height > 0 && height !== internal.lastHeight) {
+            internal.lastHeight = height;
+            emit(internal, "resize", { height });
+          }
+        }
+      });
+      internal.resizeObserver.observe(iframe);
+    }
+    internal.handshakeTimer = setTimeout(function() {
+      internal.handshakeTimer = null;
+      emit(internal, "surface_unavailable", { attempted: "iframe" });
+      teardownFrame(internal);
+      if (internal.surface === "auto") {
+        offerFallback(internal);
+      } else {
+        emit(internal, "error", { code: "iframe_blocked" });
+      }
+    }, internal.handshakeTimeoutMs);
+  }
+  function handleMessage(internal, event) {
+    if (event.origin !== internal.origin) return;
+    const data = event.data;
+    if (!data || data.source !== MESSAGE_SOURCE) return;
+    if (data.type === "ready") {
+      if (internal.handshakeTimer) {
+        clearTimeout(internal.handshakeTimer);
+        internal.handshakeTimer = null;
+      }
+      emit(internal, "ready");
+      return;
+    }
+    if (data.type === "resize" && typeof data.height === "number" && internal.frame) {
+      internal.frame.style.height = data.height + "px";
+      return;
+    }
+    if (data.type === "paid") {
+      emit(internal, "paid", data);
+      return;
+    }
+    if (data.type === "close") {
+      emit(internal, "close");
+      return;
+    }
+  }
+  const mounts = /* @__PURE__ */ new WeakMap();
+  function mount2(opts) {
+    if (typeof opts.merchant !== "string" || opts.merchant.indexOf(PUBLISHABLE_KEY_PREFIX) !== 0) {
+      try {
+        (opts.onEvent || function() {
+        })({
+          type: "error",
+          code: "invalid_merchant_key"
+        });
+      } catch {
+      }
+      return { openNow: function() {
+      }, destroy: function() {
+      } };
+    }
+    const originResolution = resolveMountOrigin(opts.canopyOrigin);
+    if (!originResolution.ok) {
+      try {
+        (opts.onEvent || function() {
+        })({
+          type: "error",
+          code: originResolution.code
+        });
+      } catch {
+      }
+      return { openNow: function() {
+      }, destroy: function() {
+      } };
+    }
+    const node = typeof opts.target === "string" ? document.querySelector(opts.target) : opts.target;
+    if (!node) {
+      return { openNow: function() {
+      }, destroy: function() {
+      } };
+    }
+    const existing = mounts.get(node);
+    if (existing) return existing;
+    const internal = {
+      node,
+      capability: opts.capability,
+      merchant: opts.merchant,
+      origin: originResolution.origin,
+      surface: opts.surface || "popup",
+      handshakeTimeoutMs: opts.handshakeTimeoutMs || DEFAULT_HANDSHAKE_TIMEOUT_MS,
+      fallbackLabel: opts.fallbackLabel || DEFAULT_FALLBACK_LABEL,
+      onEvent: opts.onEvent || function() {
+      },
+      destroyed: false,
+      messageListener: function() {
+      },
+      handshakeTimer: null,
+      resizeObserver: null,
+      frame: null,
+      fallbackButton: null,
+      lastHeight: null,
+      popupWin: null,
+      popupPollTimer: null
+    };
+    internal.messageListener = function(event) {
+      handleMessage(internal, event);
+    };
+    window.addEventListener("message", internal.messageListener);
+    if (internal.surface === "iframe" || internal.surface === "auto") {
+      createFrame(internal);
+    }
+    const handle = {
+      openNow: function(win) {
+        openNowInternal(internal, win);
+      },
+      destroy: function() {
+        if (internal.destroyed) return;
+        internal.destroyed = true;
+        window.removeEventListener("message", internal.messageListener);
+        teardownFrame(internal);
+        if (internal.popupPollTimer) {
+          clearInterval(internal.popupPollTimer);
+          internal.popupPollTimer = null;
+        }
+        if (internal.fallbackButton) {
+          if (internal.fallbackButton.parentNode) {
+            internal.fallbackButton.parentNode.removeChild(
+              internal.fallbackButton
+            );
+          }
+          internal.fallbackButton = null;
+        }
+        mounts.delete(node);
+      }
+    };
+    mounts.set(node, handle);
+    return handle;
+  }
+  const globalWindow = window;
+  if (globalWindow.Canopy && globalWindow.Canopy.__version === LOADER_VERSION) {
+    return;
+  }
+  globalWindow.Canopy = { mount: mount2, __version: LOADER_VERSION };
+})();
+
+// src/index.ts
+function mount(opts) {
+  if (typeof window === "undefined" || !window.Canopy) {
+    throw new Error("@canopypay/checkout-sdk: loader did not initialise");
+  }
+  return window.Canopy.mount(opts);
+}
+function version() {
+  return typeof window === "undefined" ? void 0 : window.Canopy?.__version;
+}

package/dist/index.d.cts

@@ -0,0 +1,120 @@
+/**
+ * Canopy checkout SDK loader (Phase 23 Plan 08, SDK-01 / SDK-04 / API-03).
+ *
+ * The whole merchant integration, measured (`sdk-loader-contract.md`):
+ *
+ * ```html
+ * <script src="https://canopy.example/v1/canopy.js"></script>
+ * <script type="module">
+ * const { capability } = await (await fetch("/my-server/create-canopy-intent")).json();
+ *
+ * const handle = Canopy.mount({
+ *   target: "#checkout",
+ *   capability,
+ *   merchant: "cnpy_pk_live_abc123",
+ *   onEvent: (e) => {
+ *     // SDK-04: `paid` is advisory only -- it drives UI, never fulfilment.
+ *     // Fulfilment reads a webhook or a server-side status call.
+ *     if (e.type === "paid") showBanner("Payment sent — we'll confirm shortly");
+ *   },
+ * });
+ *
+ * payButton.addEventListener("click", () => {
+ *   // The gesture cannot be manufactured -- open synchronously inside the
+ *   // merchant's own click handler, then hand the blank window to the SDK.
+ *   handle.openNow(window.open("", "canopy_checkout", "width=460,height=640"));
+ * });
+ * </script>
+ * ```
+ *
+ * One entry point (`mount`), one option surface (`surface: "popup" | "iframe"
+ * | "auto"`, default `"popup"`), seven events (`ready`, `resize`, `paid`,
+ * `error`, `close`, `surface_unavailable`, `fallback_offered`). See
+ * `.claude/skills/spike-findings-Canopy/references/sdk-loader-contract.md`
+ * and `.claude/skills/spike-findings-Canopy/references/embed-surface-selection.md`
+ * for the full contract this file implements.
+ *
+ * Bump LOADER_VERSION whenever this file's runtime behaviour changes.
+ * `scripts/build-checkout-sdk.ts` extracts this exact literal by regex from
+ * this source file (not the built bundle) so the immutable serving path
+ * (`/v1/{version}/canopy.js`) and this loader's own `Canopy.__version`
+ * self-report are always the same value by construction.
+ *
+ * Phase 31 Plan 02 (DIST-01, DIST-04): the five types below are hoisted
+ * above the IIFE and `export type`-ed so `packages/checkout-sdk/src/index.ts`
+ * (the npm entry) can re-export a real merchant-facing surface instead of
+ * shipping a 13-byte `export { }` declaration file. This is byte-safe --
+ * type-only exports are erased before esbuild picks its format wrapper, so
+ * the IIFE build this script tag serves is unaffected (verified sha
+ * `644fbe336e875f4f` both ways, spike 100 exp2/exp3). `Internal` stays
+ * inside the IIFE: it is not part of the merchant-facing surface.
+ */
+type CanopyEventType = "ready" | "resize" | "paid" | "error" | "close" | "surface_unavailable" | "fallback_offered";
+type CanopyEvent = {
+    type: CanopyEventType;
+    [key: string]: unknown;
+};
+type Surface = "popup" | "iframe" | "auto";
+type MountOptions = {
+    target: string | Element;
+    capability?: string;
+    merchant: string;
+    surface?: Surface;
+    onEvent?: (event: CanopyEvent) => void;
+    handshakeTimeoutMs?: number;
+    fallbackLabel?: string;
+    /**
+     * Phase 31 Plan 05 (DIST-02): the Canopy origin `mount()` builds the
+     * checkout URL against and pins the `postMessage` listener to. A
+     * `<script src="https://.../v1/canopy.js">` tag can be discovered
+     * automatically; a bundled npm consumer has no such tag, so it MUST state
+     * this explicitly or `mount()` refuses with `canopy_origin_undiscoverable`.
+     * There is no default -- baking one in would turn that loud, diagnosable
+     * refusal into a silent wrong-origin checkout for every sandbox or
+     * self-hosted integration (31-RESEARCH.md Pitfall 5). Must be a bare
+     * origin (no path, search, or hash) and `https`, except for the
+     * `localhost` / `127.0.0.1` development affordance. Wins over a present
+     * script tag when both are available.
+     */
+    canopyOrigin?: string;
+};
+type CanopyHandle = {
+    openNow: (win: Window | null) => void;
+    destroy: () => void;
+};
+
+/**
+ * Canopy checkout SDK npm entry (Phase 31 Plan 02, DIST-01 / DIST-04).
+ *
+ * This is the `npm i @canopypay/checkout-sdk` consumer surface -- it delegates
+ * to `./loader`'s IIFE (imported here for its side effect of installing
+ * `window.Canopy`) rather than re-implementing `mount()`. A second
+ * implementation of the security-relevant origin pinning and the
+ * publishable-key prefix check would fork exactly the mechanism DIST-01
+ * exists to keep singular. See
+ * `.claude/skills/spike-findings-Canopy/references/sdk-package-distribution.md`
+ * § "How to Build It" step 2 for the verified shape this file follows.
+ */
+
+declare global {
+    interface Window {
+        Canopy?: {
+            mount: (o: MountOptions) => CanopyHandle;
+            __version: string;
+        };
+    }
+}
+/**
+ * Delegates directly to `window.Canopy.mount` -- the loader's side-effect
+ * import above must have already run and installed the global by the time
+ * a bundler-consuming merchant calls this. Throws (rather than degrading to
+ * a no-op handle, which is the script-tag loader's own integration-error
+ * fallback) because a bundled consumer with no `window.Canopy` indicates the
+ * package itself failed to initialise, not a merchant mistake.
+ */
+declare function mount(opts: MountOptions): CanopyHandle;
+/** Reports the running loader's self-declared `LOADER_VERSION`, or
+ * `undefined` server-side / before the loader has installed the global. */
+declare function version(): string | undefined;
+
+export { type CanopyEvent, type CanopyEventType, type CanopyHandle, type MountOptions, type Surface, mount, version };

package/dist/index.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Canopy checkout SDK loader (Phase 23 Plan 08, SDK-01 / SDK-04 / API-03).
+ *
+ * The whole merchant integration, measured (`sdk-loader-contract.md`):
+ *
+ * ```html
+ * <script src="https://canopy.example/v1/canopy.js"></script>
+ * <script type="module">
+ * const { capability } = await (await fetch("/my-server/create-canopy-intent")).json();
+ *
+ * const handle = Canopy.mount({
+ *   target: "#checkout",
+ *   capability,
+ *   merchant: "cnpy_pk_live_abc123",
+ *   onEvent: (e) => {
+ *     // SDK-04: `paid` is advisory only -- it drives UI, never fulfilment.
+ *     // Fulfilment reads a webhook or a server-side status call.
+ *     if (e.type === "paid") showBanner("Payment sent — we'll confirm shortly");
+ *   },
+ * });
+ *
+ * payButton.addEventListener("click", () => {
+ *   // The gesture cannot be manufactured -- open synchronously inside the
+ *   // merchant's own click handler, then hand the blank window to the SDK.
+ *   handle.openNow(window.open("", "canopy_checkout", "width=460,height=640"));
+ * });
+ * </script>
+ * ```
+ *
+ * One entry point (`mount`), one option surface (`surface: "popup" | "iframe"
+ * | "auto"`, default `"popup"`), seven events (`ready`, `resize`, `paid`,
+ * `error`, `close`, `surface_unavailable`, `fallback_offered`). See
+ * `.claude/skills/spike-findings-Canopy/references/sdk-loader-contract.md`
+ * and `.claude/skills/spike-findings-Canopy/references/embed-surface-selection.md`
+ * for the full contract this file implements.
+ *
+ * Bump LOADER_VERSION whenever this file's runtime behaviour changes.
+ * `scripts/build-checkout-sdk.ts` extracts this exact literal by regex from
+ * this source file (not the built bundle) so the immutable serving path
+ * (`/v1/{version}/canopy.js`) and this loader's own `Canopy.__version`
+ * self-report are always the same value by construction.
+ *
+ * Phase 31 Plan 02 (DIST-01, DIST-04): the five types below are hoisted
+ * above the IIFE and `export type`-ed so `packages/checkout-sdk/src/index.ts`
+ * (the npm entry) can re-export a real merchant-facing surface instead of
+ * shipping a 13-byte `export { }` declaration file. This is byte-safe --
+ * type-only exports are erased before esbuild picks its format wrapper, so
+ * the IIFE build this script tag serves is unaffected (verified sha
+ * `644fbe336e875f4f` both ways, spike 100 exp2/exp3). `Internal` stays
+ * inside the IIFE: it is not part of the merchant-facing surface.
+ */
+type CanopyEventType = "ready" | "resize" | "paid" | "error" | "close" | "surface_unavailable" | "fallback_offered";
+type CanopyEvent = {
+    type: CanopyEventType;
+    [key: string]: unknown;
+};
+type Surface = "popup" | "iframe" | "auto";
+type MountOptions = {
+    target: string | Element;
+    capability?: string;
+    merchant: string;
+    surface?: Surface;
+    onEvent?: (event: CanopyEvent) => void;
+    handshakeTimeoutMs?: number;
+    fallbackLabel?: string;
+    /**
+     * Phase 31 Plan 05 (DIST-02): the Canopy origin `mount()` builds the
+     * checkout URL against and pins the `postMessage` listener to. A
+     * `<script src="https://.../v1/canopy.js">` tag can be discovered
+     * automatically; a bundled npm consumer has no such tag, so it MUST state
+     * this explicitly or `mount()` refuses with `canopy_origin_undiscoverable`.
+     * There is no default -- baking one in would turn that loud, diagnosable
+     * refusal into a silent wrong-origin checkout for every sandbox or
+     * self-hosted integration (31-RESEARCH.md Pitfall 5). Must be a bare
+     * origin (no path, search, or hash) and `https`, except for the
+     * `localhost` / `127.0.0.1` development affordance. Wins over a present
+     * script tag when both are available.
+     */
+    canopyOrigin?: string;
+};
+type CanopyHandle = {
+    openNow: (win: Window | null) => void;
+    destroy: () => void;
+};
+
+/**
+ * Canopy checkout SDK npm entry (Phase 31 Plan 02, DIST-01 / DIST-04).
+ *
+ * This is the `npm i @canopypay/checkout-sdk` consumer surface -- it delegates
+ * to `./loader`'s IIFE (imported here for its side effect of installing
+ * `window.Canopy`) rather than re-implementing `mount()`. A second
+ * implementation of the security-relevant origin pinning and the
+ * publishable-key prefix check would fork exactly the mechanism DIST-01
+ * exists to keep singular. See
+ * `.claude/skills/spike-findings-Canopy/references/sdk-package-distribution.md`
+ * § "How to Build It" step 2 for the verified shape this file follows.
+ */
+
+declare global {
+    interface Window {
+        Canopy?: {
+            mount: (o: MountOptions) => CanopyHandle;
+            __version: string;
+        };
+    }
+}
+/**
+ * Delegates directly to `window.Canopy.mount` -- the loader's side-effect
+ * import above must have already run and installed the global by the time
+ * a bundler-consuming merchant calls this. Throws (rather than degrading to
+ * a no-op handle, which is the script-tag loader's own integration-error
+ * fallback) because a bundled consumer with no `window.Canopy` indicates the
+ * package itself failed to initialise, not a merchant mistake.
+ */
+declare function mount(opts: MountOptions): CanopyHandle;
+/** Reports the running loader's self-declared `LOADER_VERSION`, or
+ * `undefined` server-side / before the loader has installed the global. */
+declare function version(): string | undefined;
+
+export { type CanopyEvent, type CanopyEventType, type CanopyHandle, type MountOptions, type Surface, mount, version };

package/dist/index.js

@@ -0,0 +1,324 @@
+// src/loader.ts
+var LOADER_VERSION = "2";
+(function() {
+  "use strict";
+  if (typeof window === "undefined") return;
+  const POPUP_FEATURES = "width=460,height=640";
+  const DEFAULT_HANDSHAKE_TIMEOUT_MS = 2500;
+  const DEFAULT_FALLBACK_LABEL = "Pay with Canopy";
+  const POPUP_POLL_INTERVAL_MS = 500;
+  const MESSAGE_SOURCE = "canopy";
+  const PUBLISHABLE_KEY_PREFIX = "cnpy_pk_live_";
+  function resolveOrigin() {
+    const current = document.currentScript;
+    if (current && current.src) {
+      try {
+        return new URL(current.src).origin;
+      } catch {
+      }
+    }
+    const scripts = document.getElementsByTagName("script");
+    for (let i = 0; i < scripts.length; i += 1) {
+      const src = scripts[i].src;
+      if (src && /\/v1\/(?:[^/]+\/)?canopy\.js(?:[?#].*)?$/.test(src)) {
+        try {
+          return new URL(src).origin;
+        } catch {
+        }
+      }
+    }
+    return null;
+  }
+  function validateExplicitOrigin(raw) {
+    let url;
+    try {
+      url = new URL(raw);
+    } catch {
+      return { ok: false, code: "canopy_origin_invalid" };
+    }
+    const isBare = (url.pathname === "" || url.pathname === "/") && url.search === "" && url.hash === "";
+    if (!isBare) {
+      return { ok: false, code: "canopy_origin_not_bare" };
+    }
+    const isDevHost = url.hostname === "localhost" || url.hostname === "127.0.0.1";
+    if (url.protocol !== "https:" && !isDevHost) {
+      return { ok: false, code: "canopy_origin_insecure" };
+    }
+    return { ok: true, origin: url.origin };
+  }
+  function resolveMountOrigin(explicit) {
+    if (explicit !== void 0) {
+      return validateExplicitOrigin(explicit);
+    }
+    const scriptOrigin = resolveOrigin();
+    if (scriptOrigin) {
+      return { ok: true, origin: scriptOrigin };
+    }
+    return { ok: false, code: "canopy_origin_undiscoverable" };
+  }
+  function buildCheckoutUrl(internal) {
+    const url = new URL("/customer-pay", internal.origin);
+    url.searchParams.set("merchant", internal.merchant);
+    url.hash = "cap=" + encodeURIComponent(internal.capability || "");
+    return url.toString();
+  }
+  function emit(internal, type, data) {
+    if (internal.destroyed) return;
+    try {
+      internal.onEvent(Object.assign({ type }, data));
+    } catch {
+    }
+  }
+  function teardownFrame(internal) {
+    if (internal.handshakeTimer) {
+      clearTimeout(internal.handshakeTimer);
+      internal.handshakeTimer = null;
+    }
+    if (internal.resizeObserver) {
+      internal.resizeObserver.disconnect();
+      internal.resizeObserver = null;
+    }
+    if (internal.frame) {
+      if (internal.frame.parentNode)
+        internal.frame.parentNode.removeChild(internal.frame);
+      internal.frame = null;
+    }
+    internal.lastHeight = null;
+  }
+  function startPopupClosePolling(internal) {
+    if (internal.popupPollTimer) clearInterval(internal.popupPollTimer);
+    internal.popupPollTimer = setInterval(function() {
+      try {
+        if (internal.popupWin && internal.popupWin.closed) {
+          if (internal.popupPollTimer) clearInterval(internal.popupPollTimer);
+          internal.popupPollTimer = null;
+          internal.popupWin = null;
+          emit(internal, "close", { via: "popup" });
+        }
+      } catch {
+        if (internal.popupPollTimer) clearInterval(internal.popupPollTimer);
+        internal.popupPollTimer = null;
+      }
+    }, POPUP_POLL_INTERVAL_MS);
+  }
+  function openNowInternal(internal, win) {
+    if (internal.destroyed) return;
+    if (!win) {
+      emit(internal, "error", { code: "popup_blocked" });
+      return;
+    }
+    if (!internal.capability) {
+      try {
+        win.close();
+      } catch {
+      }
+      emit(internal, "error", { code: "capability_unavailable" });
+      return;
+    }
+    try {
+      win.location.href = buildCheckoutUrl(internal);
+    } catch {
+      emit(internal, "error", { code: "popup_navigation_failed" });
+      return;
+    }
+    internal.popupWin = win;
+    startPopupClosePolling(internal);
+  }
+  function offerFallback(internal) {
+    const button = document.createElement("button");
+    button.type = "button";
+    button.textContent = internal.fallbackLabel;
+    const style = button.style;
+    style.background = "#1A7A4C";
+    style.color = "#FFFFFF";
+    style.border = "none";
+    style.borderRadius = "8px";
+    style.height = "48px";
+    style.padding = "0 20px";
+    style.fontSize = "16px";
+    style.fontFamily = "inherit";
+    style.cursor = "pointer";
+    style.maxWidth = "100%";
+    style.overflow = "hidden";
+    style.textOverflow = "ellipsis";
+    style.whiteSpace = "nowrap";
+    style.display = "inline-block";
+    button.addEventListener("click", function() {
+      const win = window.open("", "canopy_checkout", POPUP_FEATURES);
+      openNowInternal(internal, win);
+    });
+    internal.node.appendChild(button);
+    internal.fallbackButton = button;
+    emit(internal, "fallback_offered", {
+      surface: "popup",
+      reason: "iframe_unavailable"
+    });
+  }
+  function createFrame(internal) {
+    const iframe = document.createElement("iframe");
+    iframe.src = buildCheckoutUrl(internal);
+    iframe.style.width = "100%";
+    iframe.style.border = "none";
+    internal.node.appendChild(iframe);
+    internal.frame = iframe;
+    if (typeof ResizeObserver !== "undefined") {
+      internal.resizeObserver = new ResizeObserver(function(entries) {
+        for (let i = 0; i < entries.length; i += 1) {
+          const height = Math.round(entries[i].contentRect.height);
+          if (height > 0 && height !== internal.lastHeight) {
+            internal.lastHeight = height;
+            emit(internal, "resize", { height });
+          }
+        }
+      });
+      internal.resizeObserver.observe(iframe);
+    }
+    internal.handshakeTimer = setTimeout(function() {
+      internal.handshakeTimer = null;
+      emit(internal, "surface_unavailable", { attempted: "iframe" });
+      teardownFrame(internal);
+      if (internal.surface === "auto") {
+        offerFallback(internal);
+      } else {
+        emit(internal, "error", { code: "iframe_blocked" });
+      }
+    }, internal.handshakeTimeoutMs);
+  }
+  function handleMessage(internal, event) {
+    if (event.origin !== internal.origin) return;
+    const data = event.data;
+    if (!data || data.source !== MESSAGE_SOURCE) return;
+    if (data.type === "ready") {
+      if (internal.handshakeTimer) {
+        clearTimeout(internal.handshakeTimer);
+        internal.handshakeTimer = null;
+      }
+      emit(internal, "ready");
+      return;
+    }
+    if (data.type === "resize" && typeof data.height === "number" && internal.frame) {
+      internal.frame.style.height = data.height + "px";
+      return;
+    }
+    if (data.type === "paid") {
+      emit(internal, "paid", data);
+      return;
+    }
+    if (data.type === "close") {
+      emit(internal, "close");
+      return;
+    }
+  }
+  const mounts = /* @__PURE__ */ new WeakMap();
+  function mount2(opts) {
+    if (typeof opts.merchant !== "string" || opts.merchant.indexOf(PUBLISHABLE_KEY_PREFIX) !== 0) {
+      try {
+        (opts.onEvent || function() {
+        })({
+          type: "error",
+          code: "invalid_merchant_key"
+        });
+      } catch {
+      }
+      return { openNow: function() {
+      }, destroy: function() {
+      } };
+    }
+    const originResolution = resolveMountOrigin(opts.canopyOrigin);
+    if (!originResolution.ok) {
+      try {
+        (opts.onEvent || function() {
+        })({
+          type: "error",
+          code: originResolution.code
+        });
+      } catch {
+      }
+      return { openNow: function() {
+      }, destroy: function() {
+      } };
+    }
+    const node = typeof opts.target === "string" ? document.querySelector(opts.target) : opts.target;
+    if (!node) {
+      return { openNow: function() {
+      }, destroy: function() {
+      } };
+    }
+    const existing = mounts.get(node);
+    if (existing) return existing;
+    const internal = {
+      node,
+      capability: opts.capability,
+      merchant: opts.merchant,
+      origin: originResolution.origin,
+      surface: opts.surface || "popup",
+      handshakeTimeoutMs: opts.handshakeTimeoutMs || DEFAULT_HANDSHAKE_TIMEOUT_MS,
+      fallbackLabel: opts.fallbackLabel || DEFAULT_FALLBACK_LABEL,
+      onEvent: opts.onEvent || function() {
+      },
+      destroyed: false,
+      messageListener: function() {
+      },
+      handshakeTimer: null,
+      resizeObserver: null,
+      frame: null,
+      fallbackButton: null,
+      lastHeight: null,
+      popupWin: null,
+      popupPollTimer: null
+    };
+    internal.messageListener = function(event) {
+      handleMessage(internal, event);
+    };
+    window.addEventListener("message", internal.messageListener);
+    if (internal.surface === "iframe" || internal.surface === "auto") {
+      createFrame(internal);
+    }
+    const handle = {
+      openNow: function(win) {
+        openNowInternal(internal, win);
+      },
+      destroy: function() {
+        if (internal.destroyed) return;
+        internal.destroyed = true;
+        window.removeEventListener("message", internal.messageListener);
+        teardownFrame(internal);
+        if (internal.popupPollTimer) {
+          clearInterval(internal.popupPollTimer);
+          internal.popupPollTimer = null;
+        }
+        if (internal.fallbackButton) {
+          if (internal.fallbackButton.parentNode) {
+            internal.fallbackButton.parentNode.removeChild(
+              internal.fallbackButton
+            );
+          }
+          internal.fallbackButton = null;
+        }
+        mounts.delete(node);
+      }
+    };
+    mounts.set(node, handle);
+    return handle;
+  }
+  const globalWindow = window;
+  if (globalWindow.Canopy && globalWindow.Canopy.__version === LOADER_VERSION) {
+    return;
+  }
+  globalWindow.Canopy = { mount: mount2, __version: LOADER_VERSION };
+})();
+
+// src/index.ts
+function mount(opts) {
+  if (typeof window === "undefined" || !window.Canopy) {
+    throw new Error("@canopypay/checkout-sdk: loader did not initialise");
+  }
+  return window.Canopy.mount(opts);
+}
+function version() {
+  return typeof window === "undefined" ? void 0 : window.Canopy?.__version;
+}
+export {
+  mount,
+  version
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@canopypay/checkout-sdk",
+  "private": false,
+  "version": "0.2.0",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "unpkg": "./dist/canopy.global.js",
+  "jsdelivr": "./dist/canopy.global.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./canopy.js": "./dist/canopy.global.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/index.js",
+    "dist/index.cjs",
+    "dist/index.d.ts",
+    "dist/index.d.cts",
+    "dist/canopy.global.js"
+  ],
+  "scripts": {
+    "build": "tsup --config tsup.config.ts",
+    "build:npm": "tsup --config tsup.npm.config.ts"
+  },
+  "canopy": {
+    "loaderVersion": "2",
+    "apiVersion": "2026-09-01"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}