znode-plugin 0.0.0-stage → 0.1.1

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "znode-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Build, check, pack and deploy Znode runtime plugins and themes: the SDK behind every create-znode-plugin project.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "znode": "lib/znode-package.mjs"
+  },
+  "files": [
+    "lib",
+    "types",
+    "tsconfig.json",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "znode",
+    "runtime-plugin",
+    "theme",
+    "nextjs"
+  ],
+  "dependencies": {
+    "adm-zip": "0.5.16",
+    "postcss": "8.4.38",
+    "rollup": "4.59.0",
+    "typescript": "5.9.3"
+  },
+  "publishConfig": { "registry": "https://registry.npmjs.org/", "access": "public" }
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  // The preset a plugin project's tsconfig extends (through tsconfig.store.json): JSX as Next.js compiles it, modern
+  // modules, no emit (the build compiles file by file, `znode build`). `znode link-store <storeRepo>` adds the store's
+  // own tsconfig.base.json, so every @znode alias resolves to the store's real source and types.
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "lib": ["es2022", "dom", "dom.iterable"],
+    "jsx": "react-jsx",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": []
+  }
+}

package/types/extension-api.d.ts

@@ -0,0 +1,227 @@
+// Znode runtime extension API, version 1: what a theme, plugin or widget package builds against.
+// A package imports nothing from the webstore; everything comes in through these hooks and the browser host.
+
+// ---- server part (IRuntimePlugin, the default export of the server bundle) ------------------------------------
+
+export type IRuntimeData = Record<string, unknown>;
+
+export interface IRuntimeHookContext {
+  store: { code: string };
+  // this package's settings for the store (registry)
+  settings: Record<string, unknown>;
+  cookies: { get: (name: string) => string | undefined; delete: (name: string) => void };
+}
+
+export interface IRuntimeCartLine {
+  id: string;
+  sku: string;
+  quantity: number;
+  totalPrice: number;
+  personalization: { code: string; value: string }[];
+}
+
+export interface ICartHookContext {
+  store: { code: string };
+  cart: { cartNumber: string; lines: IRuntimeCartLine[] };
+  settings: Record<string, unknown>;
+  actions: {
+    addItem: (item: { sku: string; parentSku?: string; quantity: number; personalization?: { code: string; value: string }[] }) => Promise<boolean>;
+    removeLine: (lineId: string) => Promise<boolean>;
+  };
+}
+
+// A plugin's own server endpoints: /api/extensions/plugins/<plugin>/<route> (GET, POST, PUT, DELETE), only for a
+// store the plugin is enabled for. The browser part calls them; the context brings the store, settings, the shopper's
+// cart and user, and Znode's API with the store's headers.
+export interface IPluginRouteRequest {
+  method: string;
+  query: Record<string, string>;
+  // JSON parsed, a form as its fields, other types (XML, CSV) as text; null when empty
+  body: unknown;
+  // the body exactly as sent, for a signature check
+  rawBody: string;
+  // lower-cased, without the shopper's cookies
+  headers: Record<string, string>;
+  // files of a multipart/form-data request: only with the "uploads" permission, up to 5 MB; the text fields are in body
+  files?: { field: string; name: string; type: string; size: number; data: string /* base64 */ }[];
+}
+
+export interface IPluginRouteContext {
+  // attribute(code): one store attribute's value ("" when missing); attributes: all of them by lower-cased code
+  store: { code: string; portalId: number; localeId: number; attribute: (code: string) => string; attributes: Record<string, string> };
+  // all of this package's settings, with those bound to Znode attributes (settingsSchema "attribute") already taken
+  // from the store, and from the buyer's account and user where the field allows those levels
+  settings: Record<string, unknown>;
+  cartNumber: string;
+  // the signed-in buyer, with the B2B fields Znode keeps on the session (0 / "" when not set)
+  user: {
+    userId: number;
+    userName: string;
+    accountId: number;
+    accountCode: string;
+    roleName: string;
+    permissionCode: string;
+    profileId: number;
+    budgetAmount: number;
+  } | null;
+  // path relative to the API root: "v1/WebStoreLocator/List?filter=..." or "commerceapi/v1/carts/..."
+  znode: (path: string, init?: { method?: string; body?: unknown }) => Promise<{ status: number; data: unknown }>;
+  // when this route takes over a store route (znode-package.json "overrides"): that store route as the browser called
+  // it (method, shopper's cookies; pass a body to send another). Call it and change its answer, or don't and replace it.
+  original: (init?: { method?: string; body?: unknown }) => Promise<{ status: number; data: unknown }>;
+  // for routes other systems call (ERP, payment, punchout): the HMAC of rawBody with the secret, in constant time
+  verifySignature: (rawBody: string, signature: string | null | undefined, secret: string, options?: { algorithm?: string; encoding?: "hex" | "base64"; prefix?: string }) => boolean;
+}
+
+// Next.js in a package: import it as a Next.js app does, in server and browser parts alike:
+//   import Image from "next/image";  import Link from "next/link";  import { useRouter, redirect } from "next/navigation";
+//   import { createElement as h, Fragment } from "react";  (the JSX factory, in a server part)
+//   import { Montserrat } from "next/font/google";  const montserrat = Montserrat({ subsets: ["latin"], weight: ["700"] });
+// The package build (sdk/next-imports.mjs) points the first four at the store's own modules at runtime, so the store's
+// images config, router and React apply; next/font/google is built into the package (files downloaded from Google,
+// className / style.fontFamily / variable as in Next.js; options must be a literal object). Other next/* modules stop
+// the build. Server-only functions (redirect, notFound) work in server parts, hooks (useRouter) in browser parts.
+
+// What a server slot gets besides its props: the store's server React (createElement and Fragment: a server component
+// has no hooks; bind your JSX factory to it), the store, and all of this package's settings (never sent to the browser).
+export interface IServerSlotContext {
+  React: { createElement: (type: unknown, props?: unknown, ...children: unknown[]) => unknown; Fragment: unknown };
+  store: { code: string };
+  settings: Record<string, unknown>;
+}
+
+export interface IRuntimePlugin {
+  name: string;
+  apiVersion: number;
+  // a route answers JSON (any value), or a Response for anything else (a CSV or PDF download, a redirect). Limits: 64 KB
+  // body, 15 s, 120 calls a minute per shopper address (the store can change them)
+  routes?: Record<string, (request: IPluginRouteRequest, context: IPluginRouteContext) => Promise<unknown>>;
+  // server components by slot name: rendered on the server only, in the page's HTML; may be async and return async
+  // components (fetch data, call an API); no hooks, window or document. props.children is what is there so far: keep
+  // it, add to it or replace it. Not in a sandboxed package.
+  //   layout.root          every page, header to footer   props: storeCode, theme; children = the store's page layout
+  //                        (header, page, footer); the body is a flex column: keep wrappers flex: 1 so the footer stays down
+  //   login.layout         the login route's layout       props: storeCode; children = the login page (with its loading
+  //                        state); stays mounted while the page inside loads
+  //   login.page           the login page's content       props: storeCode, isLoginRequired; children = the login form
+  //                        (with the login.form slot inside it)
+  serverSlots?: Record<string, (props: any, context: IServerSlotContext) => unknown>;
+  // whole pages at new URLs, by path: { "/apex-offers": { render, metadata } }. A server component the store renders in
+  // its layout, at that URL (the browser keeps it); list the same paths in znode-package.json "serverPages". Lowercase
+  // paths, not under /api, /login or another store route. Not in a sandboxed package.
+  serverPages?: Record<string, IServerPage>;
+  hooks: {
+    // the cart was read (cart page, checkout): bring it in line with the plugin's rules through the actions
+    onCartChanged?: (context: ICartHookContext) => Promise<void>;
+    // an add-to-cart request before it goes to Znode: return it changed
+    beforeAddToCart?: (request: IRuntimeData, context: IRuntimeHookContext) => Promise<IRuntimeData | void>;
+    afterAddToCart?: (response: IRuntimeData, context: IRuntimeHookContext) => Promise<void>;
+    // the cart's lines before the cart page or checkout shows them: return them changed
+    mapCartItems?: (cartItems: IRuntimeData, context: IRuntimeHookContext) => Promise<IRuntimeData | void>;
+  };
+}
+
+export interface IServerPage {
+  // the page: its path and the query string's values; may be async (fetch data); redirect() / notFound() work
+  render: (props: { path: string; searchParams: Record<string, string> }, context: IServerSlotContext) => unknown;
+  // the page's <title> and description
+  metadata?: { title?: string; description?: string };
+}
+
+// ---- browser part (default export of the browser bundle: setup(host) => IBrowserPlugin) ----------------------
+
+// What the checkout slots hand a plugin: the store's own calls for saving a shipping address, so a plugin follows the
+// store's checkout instead of calling its endpoints itself.
+export interface ICheckoutApi {
+  shippingOptionId: number | null;
+  refreshCartSummary: () => void;
+  getCartNumber: () => Promise<string>;
+  saveAddress: (address: Record<string, unknown>, isFormChange: boolean, addressType: string) => Promise<{ addressModel?: Record<string, unknown>; status?: boolean; error?: string } | null>;
+  createGuestAccount: (address: Record<string, unknown>, email: string, baseUrl: string) => Promise<{ userId?: number } | null>;
+  createGuestAddressIds: (request: { address?: unknown; shippingAddress?: unknown; isBothBillingShipping: boolean }) => Promise<{ shippingAddressId?: number; billingAddressId?: number; billingAddress?: unknown; hasError?: boolean } | null>;
+  updateAddressIds: (shippingAddressId: number, billingAddressId: number, shippingOptionId: number | null) => Promise<boolean>;
+  getGuestUser: (cartNumber: string) => { guestUserId?: number; shippingAddressId?: number; billingAddressId?: number; billingAddress?: unknown } | null;
+  saveGuestUser: (cartNumber: string, details: { guestUserId: number; shippingAddressId: number; billingAddressId: number; billingAddress?: unknown }) => void;
+}
+
+export interface IReact {
+  createElement: (type: unknown, props?: unknown, ...children: unknown[]) => unknown;
+  Fragment: unknown;
+  useState: <T>(initial: T | (() => T)) => [T, (next: T | ((previous: T) => T)) => void];
+  useEffect: (effect: () => void | (() => void), deps?: unknown[]) => void;
+  useRef: <T>(initial: T) => { current: T };
+  useMemo: <T>(factory: () => T, deps: unknown[]) => T;
+  cloneElement: (element: unknown, props?: unknown, ...children: unknown[]) => unknown;
+  isValidElement: (value: unknown) => boolean;
+  useSyncExternalStore: <T>(subscribe: (listener: () => void) => () => void, getSnapshot: () => T, getServerSnapshot?: () => T) => T;
+}
+
+export interface IReactDOM {
+  createPortal: (children: unknown, container: Element) => unknown;
+}
+
+export interface IBrowserHost {
+  apiVersion: number;
+  // the store's React and react-dom: one React, so hooks work
+  React: IReact;
+  ReactDOM: IReactDOM;
+  store: { code: string };
+  theme: string;
+  // this package's browser-safe settings (settingsSchema keys marked "browser": true)
+  settings: Record<string, unknown>;
+  // the store's own state, as hooks (call them inside components)
+  stores: { useCartCount: () => number; useUser: () => { userId: number; userName: string } | null };
+}
+
+// Slots: a component gets the slot's props plus children (what the store renders there) and decides whether to keep it.
+//   layout.head          every page's <head>              props: store, theme (<title>, <meta>, <link>, <script async>)
+//   layout.header        every page's header              props: the Header widget's props
+//   layout.footer        the end of every page
+//   header.search        the header's search box          props: SearchBox's own (dataTestSelector, isMobile,
+//                        isTypeaheadSearch, isHydratedSearch, ...); children = the store's search box (desktop
+//                        and mobile render it once each)
+//   login.form           the login page's form            props: storeCode, isLoginRequired; children = the store's
+//                        Login (rendered on the server: keep the first render free of window, document and Date.now())
+//   product.image      product page image               props: product, isQuickView
+//   product.addToCart    product page Add to Cart         props: product, isQuickView
+//   product.layout       the whole product details area   props: product, configurableProducts (the page's variants:
+//                        render options from them, not from a fetch, so they are in the server HTML),
+//                        part(name) => ref (parts: product.image, product.variants, product.addToCart moved into
+//                        your layout, logic intact)
+//   product.card         a product card                   props: product, selectedMode
+//   productList.layout   a category / search listing      props: productData, isFromSearch
+//   addToCart.notification  the added-to-cart popup       props: data
+//   checkout.address     the checkout's address section   props: its props (updateShippingOptions, userDetails,
+//                        addressData, ...) and checkout: the store's own address calls (ICheckoutApi)
+//   checkout.shippingOptions  the shipping-method list    props: its props (shippingOptions, ...) and checkout
+// Transforms: addToCart.notificationData, productList.data
+// Widgets: page-builder widget types by name: a component, or an IEditorWidget (shown in the page builder's widget
+// list with its settings). A type the store already has (ProductsCarousel) keeps the store's fields and adds these.
+export interface IEditorWidget {
+  render: (props: any) => unknown;
+  label: string;
+  // the page builder's widget-list group (default "Store widgets")
+  category?: string;
+  // Puck 0.17 field definitions: text, textarea, number, select, radio, array, object, custom
+  fields: Record<string, Record<string, unknown>>;
+  // the props a newly placed widget starts with
+  defaultProps?: Record<string, unknown>;
+}
+
+export interface IBrowserPlugin {
+  slots?: Record<string, (props: any) => unknown>;
+  transforms?: Record<string, (value: any) => unknown>;
+  widgets?: Record<string, ((props: any) => unknown) | IEditorWidget>;
+}
+
+declare global {
+  namespace JSX {
+    type Element = any;
+    interface IntrinsicAttributes {
+      key?: string | number;
+    }
+    interface IntrinsicElements {
+      [name: string]: any;
+    }
+  }
+}