@spindlecommerce/storefront-next 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The SpindleCommerce authors
+
+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,31 @@
-# Temporary Holding Version
+# @spindlecommerce/storefront-next
 
-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.
+Next.js App Router integration for [SpindleCommerce](https://spindlecommerce.com) storefronts, on [`@spindlecommerce/storefront-client`](https://www.npmjs.com/package/@spindlecommerce/storefront-client).
+
+```ts
+// lib/storefront.ts
+import { createNextStorefront } from "@spindlecommerce/storefront-next";
+
+export const storefront = createNextStorefront({
+  url: process.env.SPINDLE_API_URL!,
+  market: async () => ({ channel: "eu", locale: "en-GB", currency: "GBP" }),
+});
+```
+
+- **Reads** (`getRoute`, `getSite`, `getNewestProducts`, `getCategoryProducts`, `getLocalizedPath`, `getSitemap`) are cached under tags (`TAG`) and refetched after `revalidate` seconds (300). In draft mode they read fresh, with the preview token. `reader(tags)` gives a client for your own cached queries.
+- **The cart** lives in an httpOnly cookie: `const cart = await storefront.cart()`, then `cart.add(lines)`, `cart.update(lineId, quantity)`, `cart.move({ locale, currency })` or `cart.checkout.placeOrder(…)`. Make changes in Server Actions or Route Handlers.
+- **Routes** for the platform's preview and webhooks:
+
+```ts
+// app/api/draft/route.ts
+export const GET = createDraftRoute(storefront, { channel: "eu" });
+// app/api/draft/disable/route.ts
+const route = createDraftDisableRoute();
+export const GET = route.GET;
+export const POST = route.POST;
+// app/api/revalidate/route.ts: verifies x-spindle-signature with SPINDLE_REVALIDATE_SECRET
+export const POST = createRevalidateRoute();
+```
+
+- **In the browser** (`@spindlecommerce/storefront-next/client`): `<VisualEditing adminOrigin bridgeUrl />` connects draft pages to the admin's editor, and `useCartCount()` and `notifyCartChanged()` keep a cart badge current without making pages dynamic.
+- **Images** (`@spindlecommerce/storefront-next/images`): `imagePatterns({ apiUrl, mediaHosts })` for `images.remotePatterns`, and `isOptimizable(src, patterns)`.

package/dist/client.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Connects the page to the admin's editor when framed there. A saved draft re-renders through
+ * router.refresh(); the bridge is told once the new content has committed. `localize` turns the
+ * admin's paths, which have no language, into this page's.
+ */
+export declare function VisualEditing({ adminOrigin, bridgeUrl, localize }: {
+    adminOrigin: string;
+    bridgeUrl: string;
+    localize?: (path: string) => string;
+}): import("react").JSX.Element;
+/** After a cart change in this tab, so useCartCount reads the count again. */
+export declare const notifyCartChanged: () => boolean;
+/** The cart's item count, read from a cookie in the browser so pages stay cacheable. 0 on the server. */
+export declare const useCartCount: () => number;

package/dist/client.js

@@ -0,0 +1,52 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { visualEditingBridge } from "@spindlecommerce/storefront-client";
+import { useRouter } from "next/navigation";
+import Script from "next/script";
+import { useEffect, useRef, useSyncExternalStore, useTransition } from "react";
+import { CART_COUNT_COOKIE } from "./cookies.js";
+/**
+ * Connects the page to the admin's editor when framed there. A saved draft re-renders through
+ * router.refresh(); the bridge is told once the new content has committed. `localize` turns the
+ * admin's paths, which have no language, into this page's.
+ */
+export function VisualEditing({ adminOrigin, bridgeUrl, localize }) {
+    const router = useRouter();
+    const [refreshing, startTransition] = useTransition();
+    const awaitingRender = useRef(false);
+    useEffect(() => {
+        // Runs after the refreshed server components have been committed to the DOM.
+        if (refreshing || !awaitingRender.current)
+            return;
+        awaitingRender.current = false;
+        visualEditingBridge()?.rendered();
+    }, [refreshing]);
+    const connect = () => {
+        visualEditingBridge()?.init({
+            adminOrigin,
+            onRefresh: () => {
+                awaitingRender.current = true;
+                startTransition(() => router.refresh());
+            },
+            navigate: (path) => router.push(localize ? localize(path) : path),
+        });
+    };
+    return _jsx(Script, { src: bridgeUrl, strategy: "afterInteractive", onReady: connect });
+}
+const CART_CHANGED = "spindle:cart-changed";
+const readCount = () => {
+    const match = document.cookie.match(new RegExp(`(?:^|;\\s*)${CART_COUNT_COOKIE}=(\\d+)`));
+    return match ? Number(match[1]) : 0;
+};
+const subscribe = (onChange) => {
+    window.addEventListener(CART_CHANGED, onChange);
+    window.addEventListener("focus", onChange);
+    return () => {
+        window.removeEventListener(CART_CHANGED, onChange);
+        window.removeEventListener("focus", onChange);
+    };
+};
+/** After a cart change in this tab, so useCartCount reads the count again. */
+export const notifyCartChanged = () => window.dispatchEvent(new Event(CART_CHANGED));
+/** The cart's item count, read from a cookie in the browser so pages stay cacheable. 0 on the server. */
+export const useCartCount = () => useSyncExternalStore(subscribe, readCount, () => 0);

package/dist/cookies.d.ts

@@ -0,0 +1,4 @@
+/** httpOnly: the cart's id is a bearer secret for reading and changing the cart. */
+export declare const CART_COOKIE = "spindle_cart";
+/** Readable in the browser, for the header's item count. */
+export declare const CART_COUNT_COOKIE = "spindle_cart_count";

package/dist/cookies.js

@@ -0,0 +1,4 @@
+/** httpOnly: the cart's id is a bearer secret for reading and changing the cart. */
+export const CART_COOKIE = "spindle_cart";
+/** Readable in the browser, for the header's item count. */
+export const CART_COUNT_COOKIE = "spindle_cart_count";

package/dist/images.d.ts

@@ -0,0 +1,18 @@
+/** next/image settings for the platform's media. No Next.js imports: next.config.ts loads this. */
+export type ImagePattern = {
+    protocol: "http" | "https";
+    hostname: string;
+    port?: string;
+    pathname?: string;
+};
+/**
+ * Remote patterns for the platform's media: uploads it stores itself, a Vercel Blob store, and
+ * `mediaHosts`. Those are URLs or bare hostnames, comma or space separated; a path limits a host
+ * to that prefix, and `*.` matches one subdomain level.
+ */
+export declare const imagePatterns: ({ apiUrl, mediaHosts }: {
+    apiUrl: string;
+    mediaHosts?: string;
+}) => ImagePattern[];
+/** Whether next/image may optimize this absolute URL with these patterns. */
+export declare const isOptimizable: (src: string, patterns: ImagePattern[]) => boolean;

package/dist/images.js

@@ -0,0 +1,51 @@
+/** next/image settings for the platform's media. No Next.js imports: next.config.ts loads this. */
+/**
+ * Remote patterns for the platform's media: uploads it stores itself, a Vercel Blob store, and
+ * `mediaHosts`. Those are URLs or bare hostnames, comma or space separated; a path limits a host
+ * to that prefix, and `*.` matches one subdomain level.
+ */
+export const imagePatterns = ({ apiUrl, mediaHosts = "" }) => {
+    const api = new URL(apiUrl);
+    const hosts = mediaHosts
+        .split(/[\s,]+/)
+        .filter(Boolean)
+        .flatMap((entry) => {
+        try {
+            const url = new URL(/^https?:\/\//.test(entry) ? entry : `https://${entry}`);
+            const path = url.pathname.replace(/\/+$/, "");
+            return [{ protocol: url.protocol === "http:" ? "http" : "https", hostname: url.hostname, port: url.port, ...(path ? { pathname: `${path}/**` } : {}) }];
+        }
+        catch {
+            return [];
+        }
+    });
+    return [
+        { protocol: api.protocol === "https:" ? "https" : "http", hostname: api.hostname, port: api.port, pathname: `${api.pathname.replace(/\/+$/, "")}/media/**` },
+        { protocol: "https", hostname: "*.public.blob.vercel-storage.com" },
+        ...hosts,
+    ];
+};
+/** The optimizer refuses local addresses (SSRF protection), so those are served as is. */
+const isLocalHost = (host) => host === "localhost" || host.endsWith(".localhost") || host === "[::1]" || /^127\./.test(host) || /^10\./.test(host) || /^192\.168\./.test(host) || /^172\.(1[6-9]|2\d|3[01])\./.test(host);
+/** Next.js host matching: `*.` is one subdomain level, `**.` any number. */
+const hostMatches = (host, pattern) => {
+    if (pattern.startsWith("**."))
+        return host.endsWith(pattern.slice(2));
+    if (pattern.startsWith("*."))
+        return host.endsWith(pattern.slice(1)) && !host.slice(0, -(pattern.length - 1)).includes(".");
+    return host === pattern;
+};
+const matches = (url, pattern) => url.protocol === `${pattern.protocol}:` &&
+    hostMatches(url.hostname, pattern.hostname) &&
+    (!pattern.port || url.port === pattern.port) &&
+    (!pattern.pathname || url.pathname.startsWith(pattern.pathname.replace(/\*\*$/, "")));
+/** Whether next/image may optimize this absolute URL with these patterns. */
+export const isOptimizable = (src, patterns) => {
+    try {
+        const url = new URL(src);
+        return !isLocalHost(url.hostname) && patterns.some((p) => matches(url, p));
+    }
+    catch {
+        return false;
+    }
+};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { CART_COOKIE, CART_COUNT_COOKIE } from "./cookies.ts";
+export { PREVIEW_COOKIE } from "./preview.ts";
+export { createDraftDisableRoute, createDraftRoute, createRevalidateRoute, type DraftRouteOptions } from "./routes.ts";
+export { createNextStorefront, type Market, type NextStorefront, type NextStorefrontOptions, type Scope } from "./storefront.ts";
+export { TAG, tagsFor } from "./tags.ts";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { CART_COOKIE, CART_COUNT_COOKIE } from "./cookies.js";
+export { PREVIEW_COOKIE } from "./preview.js";
+export { createDraftDisableRoute, createDraftRoute, createRevalidateRoute } from "./routes.js";
+export { createNextStorefront } from "./storefront.js";
+export { TAG, tagsFor } from "./tags.js";

package/dist/preview.d.ts

@@ -0,0 +1,25 @@
+/** Cookies the preview route sets next to Next.js's own draft mode cookie. */
+export declare const PREVIEW_COOKIE: {
+    readonly token: "spindle_preview_token";
+    /** The channel being previewed. The language is the path's prefix. */
+    readonly channel: "spindle_preview_channel";
+    /** The admin origin the visual editing bridge may talk to. */
+    readonly adminOrigin: "spindle_preview_admin";
+};
+/** Next.js's draft mode cookie, set by draftMode().enable(). */
+export declare const BYPASS_COOKIE = "__prerender_bypass";
+type CookieOptions = {
+    httpOnly: boolean;
+    path: string;
+    secure?: boolean;
+    sameSite: "lax" | "none";
+    partitioned?: boolean;
+    expires?: Date;
+};
+/**
+ * Over HTTPS, SameSite=None and Partitioned (CHIPS) so the cookies work when an admin on another
+ * site frames the storefront. Over HTTP (local development, all on localhost), SameSite=Lax.
+ */
+export declare const previewCookieOptions: (secure: boolean, expires?: Date) => CookieOptions;
+export declare const isSecureRequest: (request: Request) => boolean;
+export {};

package/dist/preview.js

@@ -0,0 +1,21 @@
+/** Cookies the preview route sets next to Next.js's own draft mode cookie. */
+export const PREVIEW_COOKIE = {
+    token: "spindle_preview_token",
+    /** The channel being previewed. The language is the path's prefix. */
+    channel: "spindle_preview_channel",
+    /** The admin origin the visual editing bridge may talk to. */
+    adminOrigin: "spindle_preview_admin",
+};
+/** Next.js's draft mode cookie, set by draftMode().enable(). */
+export const BYPASS_COOKIE = "__prerender_bypass";
+/**
+ * Over HTTPS, SameSite=None and Partitioned (CHIPS) so the cookies work when an admin on another
+ * site frames the storefront. Over HTTP (local development, all on localhost), SameSite=Lax.
+ */
+export const previewCookieOptions = (secure, expires) => ({
+    httpOnly: true,
+    path: "/",
+    ...(secure ? { secure: true, sameSite: "none", partitioned: true } : { sameSite: "lax" }),
+    ...(expires ? { expires } : {}),
+});
+export const isSecureRequest = (request) => new URL(request.url).protocol === "https:" || request.headers.get("x-forwarded-proto")?.split(",")[0]?.trim() === "https";

package/dist/routes.d.ts

@@ -0,0 +1,25 @@
+import type { NextStorefront } from "./storefront.ts";
+export type DraftRouteOptions = {
+    /** The channel to preview when the admin names none. */
+    channel: string;
+    /** Where the preview opens; by default `path`. Add the preview's language here if the storefront shows it in the URL. */
+    location?: (path: string, preview: {
+        locale: string | null;
+        channel: string | null;
+    }) => string;
+};
+/**
+ * The preview route the admin frames: ?token=…&path=/summer-sale[&locale=de-DE][&channel=eu].
+ * Checks the token with the API, turns on draft mode and keeps the token in an httpOnly cookie.
+ */
+export declare const createDraftRoute: (storefront: Pick<NextStorefront, "previewSession">, options: DraftRouteOptions) => (request: Request) => Promise<Response>;
+/** Leaves draft mode: GET ?path=/summer-sale, or a form POST with a `path` field. */
+export declare const createDraftDisableRoute: () => {
+    GET: (request: Request) => Promise<Response>;
+    /** 303, so the browser follows with a GET. */
+    POST: (request: Request) => Promise<Response>;
+};
+/** The revalidate route: platform webhooks expire the cached reads they affect. `secret` defaults to SPINDLE_REVALIDATE_SECRET. */
+export declare const createRevalidateRoute: (options?: {
+    secret?: string | null;
+}) => (request: Request) => Promise<Response>;

package/dist/routes.js

@@ -0,0 +1,115 @@
+import { changesFor, parseWebhookEvent, safeLocalPath, verifyWebhookSignature } from "@spindlecommerce/storefront-client";
+import { revalidateTag } from "next/cache";
+import { cookies, draftMode } from "next/headers";
+import { BYPASS_COOKIE, isSecureRequest, PREVIEW_COOKIE, previewCookieOptions } from "./preview.js";
+import { tagsFor } from "./tags.js";
+const NO_STORE = { "cache-control": "no-store" };
+const reject = (status, message) => new Response(`${message}\n`, { status, headers: { "content-type": "text/plain; charset=utf-8", ...NO_STORE } });
+const json = (status, body) => Response.json(body, { status, headers: NO_STORE });
+const LOCALE = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
+const CHANNEL_CODE = /^[A-Za-z0-9_-]{1,64}$/;
+const originOf = (value) => {
+    if (!value)
+        return null;
+    try {
+        const url = new URL(value);
+        return /^https?:$/.test(url.protocol) ? url.origin : null;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * The preview route the admin frames: ?token=…&path=/summer-sale[&locale=de-DE][&channel=eu].
+ * Checks the token with the API, turns on draft mode and keeps the token in an httpOnly cookie.
+ */
+export const createDraftRoute = (storefront, options) => async function GET(request) {
+    const params = new URL(request.url).searchParams;
+    const token = params.get("token");
+    const path = safeLocalPath(params.get("path") || "/");
+    const locale = params.get("locale")?.trim() || null;
+    const channel = params.get("channel")?.trim() || null;
+    if (!token)
+        return reject(401, "Missing preview token.");
+    if (!path)
+        return reject(400, "path must be a path on this storefront, e.g. /summer-sale.");
+    if (locale && !LOCALE.test(locale))
+        return reject(400, "Invalid locale.");
+    if (channel && !CHANNEL_CODE.test(channel))
+        return reject(400, "Invalid channel.");
+    let session;
+    try {
+        session = await storefront.previewSession(token, { channel: channel ?? options.channel, locale });
+    }
+    catch (error) {
+        console.error("Preview session check failed", error);
+        return reject(401, "The preview could not be checked with the SpindleCommerce API. Try again from the admin.");
+    }
+    if (!session)
+        return reject(401, "The preview link is invalid or has expired. Open the preview again from the admin.");
+    (await draftMode()).enable();
+    const jar = await cookies();
+    const secure = isSecureRequest(request);
+    const expires = new Date(session.expiresAt);
+    const cookie = previewCookieOptions(secure, Number.isNaN(expires.getTime()) ? undefined : expires);
+    const keep = (name, value) => (value ? jar.set(name, value, cookie) : jar.delete({ name, path: cookie.path, ...(secure ? { secure: true, sameSite: "none", partitioned: true } : {}) }));
+    keep(PREVIEW_COOKIE.token, token);
+    keep(PREVIEW_COOKIE.channel, channel);
+    keep(PREVIEW_COOKIE.adminOrigin, originOf(session.adminOrigin));
+    if (secure) {
+        // Next.js does not partition its draft mode cookie. Partition it so it survives in browsers
+        // that block third-party cookies when the admin frames us.
+        const bypass = jar.get(BYPASS_COOKIE);
+        if (bypass?.value)
+            jar.set(BYPASS_COOKIE, bypass.value, previewCookieOptions(true));
+    }
+    // A relative Location keeps the frame on this origin, whatever host the request came in on.
+    const location = options.location ? options.location(path, { locale, channel }) : path;
+    return new Response(null, { status: 307, headers: { location, ...NO_STORE } });
+};
+/** Leaves draft mode: GET ?path=/summer-sale, or a form POST with a `path` field. */
+export const createDraftDisableRoute = () => {
+    const exit = async (request, path, status) => {
+        (await draftMode()).disable();
+        const jar = await cookies();
+        const secure = isSecureRequest(request);
+        const attributes = secure ? { secure: true, sameSite: "none", partitioned: true } : {};
+        for (const name of Object.values(PREVIEW_COOKIE))
+            jar.delete({ name, path: "/", ...attributes });
+        // The partitioned draft mode cookie needs a partitioned deletion (see createDraftRoute).
+        if (secure)
+            jar.set(BYPASS_COOKIE, "", { ...previewCookieOptions(true), expires: new Date(0) });
+        return new Response(null, { status, headers: { location: safeLocalPath(path) ?? "/", ...NO_STORE } });
+    };
+    return {
+        GET: (request) => exit(request, new URL(request.url).searchParams.get("path"), 307),
+        /** 303, so the browser follows with a GET. */
+        POST: async (request) => {
+            const form = await request.formData().catch(() => null);
+            const path = form?.get("path");
+            return exit(request, typeof path === "string" ? path : null, 303);
+        },
+    };
+};
+const MAX_BODY_BYTES = 1024 * 1024;
+/** The revalidate route: platform webhooks expire the cached reads they affect. `secret` defaults to SPINDLE_REVALIDATE_SECRET. */
+export const createRevalidateRoute = (options = {}) => async function POST(request) {
+    const secret = options.secret ?? process.env.SPINDLE_REVALIDATE_SECRET;
+    if (!secret)
+        return json(503, { revalidated: false, error: "Revalidation is off: set SPINDLE_REVALIDATE_SECRET to the signing secret the admin showed for this storefront." });
+    if (Number(request.headers.get("content-length") ?? 0) > MAX_BODY_BYTES)
+        return json(413, { revalidated: false, error: "Body too large" });
+    // The signature covers the exact bytes sent: read the body as text and verify before parsing.
+    const body = await request.text();
+    if (!(await verifyWebhookSignature(secret, body, request.headers.get("x-spindle-signature"))))
+        return json(401, { revalidated: false, error: "Invalid or expired signature" });
+    const event = parseWebhookEvent(body);
+    if (!event)
+        return json(400, { revalidated: false, error: "Expected an event: { id, type, occurredAt, data }" });
+    // The type is read from the signed body; the x-spindle-event header is not signed.
+    const { changes, immediate } = changesFor(event);
+    const tags = tagsFor(changes);
+    for (const tag of tags)
+        revalidateTag(tag, immediate ? { expire: 0 } : "max");
+    return json(200, { revalidated: tags.length > 0, event: event.type, id: event.id ?? null, tags, immediate, now: Date.now() });
+};

package/dist/storefront.d.ts

@@ -0,0 +1,152 @@
+import "server-only";
+import { type CategoryTreeNode, type ContentNode, type ProductSort, type RouteResult, type StorefrontClient } from "@spindlecommerce/storefront-client";
+/** The channel, language and currency a request shows. */
+export type Market = {
+    channel: string;
+    locale: string | null;
+    currency: string | null;
+};
+/** The request's market, as draft mode and the preview cookies change it. */
+export type Scope = Market & {
+    draft: boolean;
+    previewToken: string | null;
+};
+export type NextStorefrontOptions = {
+    /** The platform's URL. */
+    url: string;
+    /** The request's market, e.g. from the URL. Called once per request. */
+    market: () => Market | Promise<Market>;
+    /** Seconds a cached read lasts. Publishing expires reads sooner, through the revalidate route. */
+    revalidate?: number;
+    /** The content types of the header and footer pages. */
+    site?: {
+        header?: string;
+        footer?: string;
+    };
+    /** Whether a stored cart is still this storefront's, e.g. in one of its currencies. By default, while it is open. */
+    isUsableCart?: (cart: {
+        isOpen: boolean;
+        currencyCode: string | null;
+    }) => boolean;
+};
+type Root = {
+    id: string;
+    component: string;
+};
+/** The Storefront API for a Next.js App Router storefront. Server-side only. */
+export declare const createNextStorefront: (options: NextStorefrontOptions) => {
+    url: string;
+    getScope: () => Promise<Scope>;
+    reader: (tags?: string[], language?: string) => Promise<StorefrontClient>;
+    privateClient: () => Promise<{
+        url: string;
+        scope: {
+            channel: string;
+            locale: string | null;
+            currency: string | null;
+        };
+        previewToken: string | null;
+        with: (changes: Partial<import("@spindlecommerce/storefront-client").StorefrontClientOptions>) => any;
+        query: <T>(document: string, variables?: Record<string, unknown>, request?: import("@spindlecommerce/storefront-client").RequestOptions) => Promise<T>;
+        mediaUrl: (src: string) => string;
+        route: (path: string, request?: import("@spindlecommerce/storefront-client").RequestOptions) => Promise<import("@spindlecommerce/storefront-client").RouteData | null>;
+        routeTemplate: (path: string, request?: import("@spindlecommerce/storefront-client").RequestOptions) => Promise<import("@spindlecommerce/storefront-client").TemplatePage | null>;
+        routeSections: (path: string, request?: import("@spindlecommerce/storefront-client").RequestOptions) => Promise<import("@spindlecommerce/storefront-client").BuilderPage | null>;
+        site: <Header extends {
+            id: string;
+            component: string;
+        } = ContentNode, Footer extends {
+            id: string;
+            component: string;
+        } = ContentNode>(types?: {
+            header?: string;
+            footer?: string;
+        }, request?: import("@spindlecommerce/storefront-client").RequestOptions) => Promise<import("@spindlecommerce/storefront-client").SiteData<Header, Footer>>;
+        newestProducts: (first: number, request?: import("@spindlecommerce/storefront-client").RequestOptions) => Promise<import("@spindlecommerce/storefront-client").ProductSummary[]>;
+        categoryProducts: (id: string, page: {
+            first: number;
+            after?: string | null;
+            sort?: ProductSort | null;
+        }, request?: import("@spindlecommerce/storefront-client").RequestOptions) => Promise<{
+            products: import("@spindlecommerce/storefront-client").ProductSummary[];
+            totalCount: number;
+            endCursor: string | null;
+        }>;
+        pages: (page: {
+            type?: string | null;
+            first: number;
+            after?: string | null;
+        }, request?: import("@spindlecommerce/storefront-client").RequestOptions) => Promise<import("@spindlecommerce/storefront-client").Connection<import("@spindlecommerce/storefront-client").PageEntry> | null>;
+        productSlugs: (after: string | null, request?: import("@spindlecommerce/storefront-client").RequestOptions) => Promise<import("@spindlecommerce/storefront-client").Connection<{
+            slug: string;
+        }> | null>;
+        categoryTree: (request?: import("@spindlecommerce/storefront-client").RequestOptions) => Promise<CategoryTreeNode[]>;
+        localizedPath: (id: string, request?: import("@spindlecommerce/storefront-client").RequestOptions) => Promise<string | null>;
+        previewSession: (request?: import("@spindlecommerce/storefront-client").RequestOptions) => Promise<import("@spindlecommerce/storefront-client").PreviewSession | null>;
+        countries: (request?: import("@spindlecommerce/storefront-client").RequestOptions) => Promise<{
+            locale: string | null;
+            countries: import("@spindlecommerce/storefront-client").Country[];
+        }>;
+        guestOrder: (lookup: {
+            email: string;
+            number: string;
+            postalCode: string;
+            cartId: string;
+        }, request?: import("@spindlecommerce/storefront-client").RequestOptions) => Promise<{
+            order: import("@spindlecommerce/storefront-client").PlacedOrder;
+            paymentMethod: {
+                code: string;
+                name: string | null;
+                instructions: string | null;
+            } | null;
+        } | null>;
+    }>;
+    getRoute: (path: string) => Promise<RouteResult | null>;
+    getSite: <Header extends Root = ContentNode, Footer extends Root = ContentNode>() => Promise<import("@spindlecommerce/storefront-client").SiteData<Header, Footer>>;
+    getNewestProducts: (first: number) => Promise<import("@spindlecommerce/storefront-client").ProductSummary[]>;
+    getCategoryProducts: (id: string, first: number, after?: string | null, sort?: ProductSort | null) => Promise<{
+        products: import("@spindlecommerce/storefront-client").ProductSummary[];
+        totalCount: number;
+        endCursor: string | null;
+    }>;
+    getLocalizedPath: (id: string, language: string) => Promise<string | null>;
+    getSitemap: (type: string) => Promise<{
+        pages: import("@spindlecommerce/storefront-client").PageEntry[];
+        productSlugs: string[];
+        categoryPaths: string[];
+    }>;
+    previewSession: (token: string, scope: {
+        channel: string;
+        locale: string | null;
+    }) => Promise<import("@spindlecommerce/storefront-client").PreviewSession | null>;
+    cart: () => Promise<{
+        id: () => string | Promise<string | null> | null;
+        get: () => Promise<import("@spindlecommerce/storefront-client").Cart | null>;
+        add: (lines: {
+            variantId: string;
+            quantity: number;
+        }[]) => Promise<import("@spindlecommerce/storefront-client").Cart>;
+        update: (lineId: string, quantity: number) => Promise<import("@spindlecommerce/storefront-client").Cart>;
+        move: (to: {
+            locale: string;
+            currency: string;
+        }) => Promise<void>;
+        forget: () => void | Promise<void>;
+        checkout: {
+            get: () => Promise<import("@spindlecommerce/storefront-client").CheckoutCart | null>;
+            update: (input: import("@spindlecommerce/storefront-client").CartUpdateInput) => Promise<import("@spindlecommerce/storefront-client").CartChange>;
+            applyCoupon: (code: string) => Promise<import("@spindlecommerce/storefront-client").CartChange>;
+            removeCoupon: (code: string) => Promise<import("@spindlecommerce/storefront-client").CartChange>;
+            createPaymentSession: () => Promise<import("@spindlecommerce/storefront-client").PaymentSessionResult>;
+            placeOrder: (order: {
+                idempotencyKey: string;
+                payment?: {
+                    token?: string;
+                };
+                input?: import("@spindlecommerce/storefront-client").CartUpdateInput;
+            }) => Promise<import("@spindlecommerce/storefront-client").PlaceOrderResult>;
+        };
+    }>;
+};
+export type NextStorefront = ReturnType<typeof createNextStorefront>;
+export {};

package/dist/storefront.js

@@ -0,0 +1,117 @@
+import "server-only";
+import { allNodes, categoryPath, createCartSession, createStorefrontClient, isPreviewExpired, normalizePath, PreviewExpiredError, productPath, } from "@spindlecommerce/storefront-client";
+import { cookies, draftMode } from "next/headers";
+import { unstable_rethrow } from "next/navigation";
+import { cache } from "react";
+import { CART_COOKIE, CART_COUNT_COOKIE } from "./cookies.js";
+import { PREVIEW_COOKIE } from "./preview.js";
+import { TAG } from "./tags.js";
+/** Only /products/… and /categories/… render a template; other URLs for them redirect. */
+const templateKindOf = (path) => {
+    const normalized = normalizePath(path);
+    if (normalized.startsWith(productPath("")))
+        return "product";
+    if (normalized.startsWith(categoryPath("")))
+        return "category";
+    return null;
+};
+/** The cart's id in an httpOnly cookie, its item count in a readable one for the header. */
+const cookieCartStore = {
+    get: async () => (await cookies()).get(CART_COOKIE)?.value ?? null,
+    set: async (cart) => {
+        const jar = await cookies();
+        const secure = process.env.NODE_ENV === "production";
+        const maxAge = 60 * 60 * 24 * 30;
+        jar.set(CART_COOKIE, cart.id, { httpOnly: true, sameSite: "lax", secure, path: "/", maxAge });
+        jar.set(CART_COUNT_COOKIE, String(cart.totalQuantity), { httpOnly: false, sameSite: "lax", secure, path: "/", maxAge });
+    },
+    clear: async () => {
+        const jar = await cookies();
+        jar.delete(CART_COOKIE);
+        jar.delete(CART_COUNT_COOKIE);
+    },
+};
+/** The Storefront API for a Next.js App Router storefront. Server-side only. */
+export const createNextStorefront = (options) => {
+    const revalidate = options.revalidate ?? 300;
+    const headerType = options.site?.header ?? "site_header";
+    const footerType = options.site?.footer ?? "site_footer";
+    /**
+     * Cookies are read only in draft mode, so published pages stay cacheable. Previewing another
+     * channel uses that channel's default language and currency.
+     */
+    const getScope = cache(async () => {
+        const market = await options.market();
+        const { isEnabled } = await draftMode();
+        if (!isEnabled)
+            return { ...market, draft: false, previewToken: null };
+        const jar = await cookies();
+        const channel = jar.get(PREVIEW_COOKIE.channel)?.value || market.channel;
+        const own = channel === market.channel;
+        return { draft: true, previewToken: jar.get(PREVIEW_COOKIE.token)?.value || null, channel, locale: own ? market.locale : null, currency: own ? market.currency : null };
+    });
+    /**
+     * A client for reads, cached under `tags` outside draft mode and fetched fresh with the preview
+     * token in it. `language` replaces the market's, e.g. for hreflang alternates.
+     */
+    const reader = async (tags = [], language) => {
+        const scope = await getScope();
+        const base = { url: options.url, channel: scope.channel, locale: language ?? scope.locale, currency: scope.currency };
+        if (!scope.draft)
+            return createStorefrontClient({ ...base, init: { next: { tags: [TAG.all, ...tags], revalidate } } });
+        if (!scope.previewToken)
+            throw new PreviewExpiredError();
+        return createStorefrontClient({ ...base, previewToken: scope.previewToken, init: { cache: "no-store" } });
+    };
+    /** A client for carts, checkout and other private data: never cached, never with the preview token. */
+    const privateClient = async () => {
+        const scope = await getScope();
+        return createStorefrontClient({ url: options.url, channel: scope.channel, locale: scope.locale, currency: scope.currency, init: { cache: "no-store" } });
+    };
+    /** Content a product or category page can do without: visitors get the page without it, editors the error. */
+    const optional = async (load, what) => {
+        try {
+            return await load();
+        }
+        catch (error) {
+            unstable_rethrow(error);
+            if (isPreviewExpired(error) || (await getScope()).draft)
+                throw error;
+            console.error(`Could not load ${what}`, error);
+            return null;
+        }
+    };
+    /** A storefront URL. Products and categories come with their template and own sections. */
+    const getRoute = cache(async (path) => {
+        const kind = templateKindOf(path);
+        const [route, template, sections] = await Promise.all([
+            reader([TAG.pages, TAG.catalog, TAG.path(path)]).then((client) => client.route(path)),
+            // Tagged with the catalog too, since a product's categories pick its template.
+            kind ? optional(async () => (await reader([TAG.templates(kind), TAG.pages, TAG.catalog])).routeTemplate(path), `the template for ${path}`) : null,
+            kind ? optional(async () => (await reader([TAG.sections(kind), TAG.pages, TAG.catalog])).routeSections(path), `the sections for ${path}`) : null,
+        ]);
+        return route?.__typename === "Product" || route?.__typename === "Category" ? { ...route, template, sections } : route;
+    });
+    /** The header and footer, and the language and currency the API answers in. */
+    const getSite = cache(async () => (await reader([TAG.pages, TAG.catalog, TAG.singleton(headerType), TAG.singleton(footerType)])).site({ header: headerType, footer: footerType }));
+    const getNewestProducts = cache(async (first) => (await reader([TAG.catalog])).newestProducts(first));
+    /** A page of a category's products, its subcategories' included. */
+    const getCategoryProducts = cache(async (id, first, after = null, sort = null) => (await reader([TAG.catalog])).categoryProducts(id, { first, after, sort }));
+    /** A product's slug or category's path in another of the market's languages, for hreflang. */
+    const getLocalizedPath = async (id, language) => (await reader([TAG.catalog], language)).localizedPath(id);
+    /** Published pages of one content type, and every product and category. */
+    const getSitemap = async (type) => {
+        const flatten = (nodes) => nodes.flatMap((c) => [c.path, ...flatten(c.children ?? [])]);
+        const [pages, products, tree] = await Promise.all([
+            reader([TAG.pages]).then((client) => allNodes((after) => client.pages({ type, first: 100, after }))),
+            reader([TAG.catalog]).then((client) => allNodes((after) => client.productSlugs(after), 20)),
+            reader([TAG.catalog]).then((client) => client.categoryTree()),
+        ]);
+        return { pages, productSlugs: products.map((p) => p.slug), categoryPaths: flatten(tree) };
+    };
+    /** Checks a preview token before draft mode is turned on; null when the API refuses it. */
+    const previewSession = (token, scope) => createStorefrontClient({ url: options.url, ...scope, previewToken: token, init: { cache: "no-store" } }).previewSession();
+    /** The shopper's cart and checkout, kept in cookies. Changes set cookies: make them in Server Actions or Route Handlers. */
+    const cart = async () => createCartSession(await privateClient(), cookieCartStore, { isUsable: options.isUsableCart });
+    return { url: options.url, getScope, reader, privateClient, getRoute, getSite, getNewestProducts, getCategoryProducts, getLocalizedPath, getSitemap, previewSession, cart };
+};

package/dist/tags.d.ts

@@ -0,0 +1,19 @@
+import { type ContentChange, type TemplateKind } from "@spindlecommerce/storefront-client";
+/** Cache tags on reads. The revalidate route maps webhook events onto them. */
+export declare const TAG: {
+    /** Every read: component library changes expire everything. */
+    all: string;
+    /** Builder pages. One tag for all of them, since pages link to each other. */
+    pages: string;
+    /** Products and categories, including links and references to them in pages. */
+    catalog: string;
+    /** route(path) for one URL path. */
+    path: (path: string) => string;
+    /** A singleton page such as the site header. */
+    singleton: (type: string) => string;
+    /** Product or category pages, which hold the template they render with. */
+    templates: (kind: TemplateKind) => string;
+    /** Product or category pages' own sections. */
+    sections: (kind: TemplateKind) => string;
+};
+export declare const tagsFor: (changes: ContentChange[]) => string[];

package/dist/tags.js

@@ -0,0 +1,37 @@
+import { normalizePath } from "@spindlecommerce/storefront-client";
+/** Cache tags on reads. The revalidate route maps webhook events onto them. */
+export const TAG = {
+    /** Every read: component library changes expire everything. */
+    all: "spindle",
+    /** Builder pages. One tag for all of them, since pages link to each other. */
+    pages: "spindle:pages",
+    /** Products and categories, including links and references to them in pages. */
+    catalog: "spindle:catalog",
+    /** route(path) for one URL path. */
+    path: (path) => `spindle:path:${normalizePath(path)}`.slice(0, 256),
+    /** A singleton page such as the site header. */
+    singleton: (type) => `spindle:singleton:${type}`.slice(0, 256),
+    /** Product or category pages, which hold the template they render with. */
+    templates: (kind) => `spindle:templates:${kind}`,
+    /** Product or category pages' own sections. */
+    sections: (kind) => `spindle:sections:${kind}`,
+};
+const tagFor = (change) => {
+    switch (change.kind) {
+        case "everything":
+            return TAG.all;
+        case "pages":
+            return TAG.pages;
+        case "catalog":
+            return TAG.catalog;
+        case "path":
+            return TAG.path(change.path);
+        case "templates":
+            return TAG.templates(change.for);
+        case "sections":
+            return TAG.sections(change.for);
+        case "singleton":
+            return TAG.singleton(change.type);
+    }
+};
+export const tagsFor = (changes) => [...new Set(changes.map(tagFor))];

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@spindlecommerce/storefront-next",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Next.js integration for SpindleCommerce storefronts: cached reads, carts in cookies, previews, visual editing and revalidation.",
+  "keywords": [
+    "spindlecommerce",
+    "storefront"
+  ],
+  "homepage": "https://github.com/spindlecommerce/storefront-sdk/tree/main/packages/storefront-next#readme",
+  "bugs": "https://github.com/spindlecommerce/storefront-sdk/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/spindlecommerce/storefront-sdk.git",
+    "directory": "packages/storefront-next"
+  },
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./images": {
+      "types": "./dist/images.d.ts",
+      "default": "./dist/images.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "server-only": "^0.0.1",
+    "@spindlecommerce/storefront-client": "^0.1.0"
+  },
+  "peerDependencies": {
+    "next": "^16.0.0",
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "26.6.5",
+    "@types/react": "19.3.0",
+    "next": "16.4.1",
+    "react": "19.3.1",
+    "react-dom": "19.3.1"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json"
+  }
 }