@shop-on/theme-server 0.0.0-stage → 0.2.0

package/dist/LICENSE.md

@@ -0,0 +1,39 @@
+# Cody Theme Development License
+
+Copyright (c) 2026 Cody LLC. All rights reserved except as granted below.
+
+"The Software" is this package, its source, and its documentation. "The
+Platform" is Cody, the commerce platform operated by Cody LLC.
+
+## 1. Grant
+
+You may use, copy and modify the Software, and distribute modified copies, solely
+to develop, test, and distribute themes, apps and other extensions that run on
+the Platform.
+
+## 2. Restrictions
+
+You may not:
+
+1. use the Software, or anything derived from it, with any commerce platform,
+   storefront or hosting service other than the Platform;
+2. use the Software to build a product that competes with the Platform;
+3. sublicense the Software, or distribute it other than as part of a theme,
+   app or extension for the Platform;
+4. remove or alter this license or any copyright notice in the Software.
+
+## 3. Your work
+
+Themes, apps and extensions you build with the Software are yours. The parts of
+the Software they include stay under this license.
+
+## 4. Termination
+
+This license ends automatically if you break any of its terms. You must then
+stop using the Software and delete your copies of it.
+
+## 5. No warranty
+
+The Software is provided "as is", without warranty of any kind. Cody LLC is not
+liable for any claim, damages or other liability arising from the Software or
+its use.

package/dist/account.d.ts

@@ -0,0 +1,12 @@
+//#region src/account.d.ts
+export declare function normalizeReturnToPath(raw: unknown): string;
+export type AccountRedirectSubpath = "" | `/${string}`;
+export declare function getAccountRedirectUrl(data: {
+  subpath?: AccountRedirectSubpath;
+  returnToPath?: string;
+}): Promise<{
+  url: string;
+}>;
+export declare function handleCustomerLogoutPost(request: Request): Promise<Response>;
+export declare function renderLogoutForm(accountLogoutUrl: string, returnTo: string): string;
+//#endregion

package/dist/account.js

@@ -0,0 +1,72 @@
+import { fetchShopInfo } from "./shop.js";
+import { checkOrigin } from "./csrf.js";
+import { escapeHtmlAttr } from "./html.js";
+//#region src/account.ts
+const FORBIDDEN_RETURN_TO = /^(?:\/[^/]+)?\/(?:account|customer_logout)(?:\/|$)/;
+function normalizeReturnToPath(raw) {
+	if (typeof raw !== "string") return "/";
+	if (!raw.startsWith("/") || raw.startsWith("//")) return "/";
+	const pathOnly = raw.split(/[?#]/, 1)[0];
+	if (FORBIDDEN_RETURN_TO.test(pathOnly)) return "/";
+	return raw;
+}
+async function getAccountRedirectUrl(data) {
+	const shop = await fetchShopInfo();
+	if (!shop) throw new Error("[theme/account] shop info unavailable from Rails");
+	const subpath = data.subpath ?? "";
+	const target = new URL(`${shop.accountUrl}${subpath}`);
+	if (data.returnToPath !== void 0) {
+		const safePath = normalizeReturnToPath(data.returnToPath);
+		const { getRequestUrl } = await import("@tanstack/react-start/server");
+		const origin = getRequestUrl({
+			xForwardedHost: true,
+			xForwardedProto: true
+		}).origin;
+		target.searchParams.set("return_to", `${origin}${safePath}`);
+	}
+	return { url: target.toString() };
+}
+async function handleCustomerLogoutPost(request) {
+	const { getRequestUrl } = await import("@tanstack/react-start/server");
+	const expectedOrigin = getRequestUrl({
+		xForwardedHost: true,
+		xForwardedProto: true
+	}).origin;
+	const originHeader = request.headers.get("origin");
+	const originResult = checkOrigin(originHeader, expectedOrigin);
+	if (!originResult.ok) {
+		console.warn(JSON.stringify({
+			event: "theme_logout_csrf_blocked",
+			reason: originResult.reason,
+			originHeader,
+			expectedOrigin,
+			ts: Date.now()
+		}));
+		return new Response("Forbidden", { status: 403 });
+	}
+	const shopPromise = fetchShopInfo().catch(() => null);
+	const { revokeCustomerSession } = await import("./customer.js");
+	const { clearCustomerSession } = await import("./customer-session.js");
+	const { useCartSession } = await import("./cart-session.js");
+	await revokeCustomerSession();
+	await clearCustomerSession();
+	await (await useCartSession()).clear();
+	const shop = await shopPromise;
+	if (!shop) return new Response("shop unavailable", { status: 500 });
+	return new Response(renderLogoutForm(`${shop.accountUrl}/logout`, `${expectedOrigin}/`), {
+		status: 200,
+		headers: { "Content-Type": "text/html; charset=utf-8" }
+	});
+}
+function renderLogoutForm(accountLogoutUrl, returnTo) {
+	return `<!DOCTYPE html>
+<html><body>
+  <form action="${escapeHtmlAttr(accountLogoutUrl)}" method="POST">
+    <input type="hidden" name="return_to" value="${escapeHtmlAttr(returnTo)}">
+    <noscript><button type="submit">Continue</button></noscript>
+  </form>
+  <script>document.forms[0].submit()<\/script>
+</body></html>`;
+}
+//#endregion
+export { getAccountRedirectUrl, handleCustomerLogoutPost, normalizeReturnToPath, renderLogoutForm };

package/dist/activity.d.ts

@@ -0,0 +1,25 @@
+//#region src/activity.d.ts
+/**
+ * In-memory last-request tracker for a running storefront isolate. The
+ * orchestrator probes `/health` to prove an install renders before it publishes
+ * the store's route — the theme holds no connection to any platform
+ * infrastructure for this. `lastRequestAt` initializes to isolate start.
+ */
+export declare function createActivityTracker({ now }?: {
+  now?: () => number;
+}): {
+  record: () => void;
+  snapshot: () => {
+    status: "ok";
+    lastRequestAt: number;
+  };
+};
+/**
+ * Request middleware: every theme registers this in `src/start.ts`. Serves
+ * `/health` (a 200 JSON body with `lastRequestAt`) for the orchestrator's
+ * warm-up probe, and stamps the tracker for everything else. `/health` itself
+ * must not count as activity, which the short-circuit guarantees by returning
+ * before the record.
+ */
+export declare const storefrontActivityMiddleware: import("@tanstack/react-start").RequestMiddlewareAfterServer<{}, undefined, undefined>;
+//#endregion

package/dist/activity.js

@@ -0,0 +1,35 @@
+import { createMiddleware } from "@tanstack/react-start";
+//#region src/activity.ts
+/**
+* In-memory last-request tracker for a running storefront isolate. The
+* orchestrator probes `/health` to prove an install renders before it publishes
+* the store's route — the theme holds no connection to any platform
+* infrastructure for this. `lastRequestAt` initializes to isolate start.
+*/
+function createActivityTracker({ now = Date.now } = {}) {
+	let lastRequestAt = now();
+	return {
+		record: () => {
+			lastRequestAt = now();
+		},
+		snapshot: () => ({
+			status: "ok",
+			lastRequestAt
+		})
+	};
+}
+const tracker = createActivityTracker();
+/**
+* Request middleware: every theme registers this in `src/start.ts`. Serves
+* `/health` (a 200 JSON body with `lastRequestAt`) for the orchestrator's
+* warm-up probe, and stamps the tracker for everything else. `/health` itself
+* must not count as activity, which the short-circuit guarantees by returning
+* before the record.
+*/
+const storefrontActivityMiddleware = createMiddleware().server(async ({ next, request }) => {
+	if (new URL(request.url).pathname === "/health") return Response.json(tracker.snapshot());
+	tracker.record();
+	return next();
+});
+//#endregion
+export { createActivityTracker, storefrontActivityMiddleware };

package/dist/analytics-proxy.d.ts

@@ -0,0 +1,22 @@
+//#region src/analytics-proxy.d.ts
+declare const PATHS: {
+  readonly visits: "/storefront/analytics/visits";
+  readonly events: "/storefront/analytics/events";
+};
+export type AnalyticsEndpoint = keyof typeof PATHS;
+export declare function proxyAnalytics({ endpoint, body, visitToken, visitorToken, userAgent, clientIp, fbp, fbc, eventSourceUrl }: {
+  endpoint: AnalyticsEndpoint;
+  body: unknown;
+  visitToken?: string | null;
+  visitorToken?: string | null;
+  userAgent?: string | null;
+  clientIp?: string | null;
+  fbp?: string | null;
+  fbc?: string | null;
+  eventSourceUrl?: string | null;
+}): Promise<{
+  status: number;
+}>;
+export declare function extractClientIp(headers: Headers): string | null;
+//#endregion
+export {};

package/dist/analytics-proxy.js

@@ -0,0 +1,39 @@
+import { requestTraceHeaders } from "./trace.js";
+import { getStorefrontToken, storefrontApiUrl } from "./graphql.js";
+import { isIP } from "node:net";
+//#region src/analytics-proxy.ts
+const PATHS = {
+	visits: "/storefront/analytics/visits",
+	events: "/storefront/analytics/events"
+};
+async function proxyAnalytics({ endpoint, body, visitToken, visitorToken, userAgent, clientIp, fbp, fbc, eventSourceUrl }) {
+	const headers = {
+		Authorization: `Bearer ${await getStorefrontToken()}`,
+		"Content-Type": "application/json",
+		...requestTraceHeaders()
+	};
+	if (visitToken) headers["Ahoy-Visit"] = visitToken;
+	if (visitorToken) headers["Ahoy-Visitor"] = visitorToken;
+	if (userAgent) headers["User-Agent"] = userAgent;
+	if (clientIp) headers["X-Buyer-IP"] = clientIp;
+	if (fbp) headers["X-Marketing-Fbp"] = fbp;
+	if (fbc) headers["X-Marketing-Fbc"] = fbc;
+	if (eventSourceUrl) headers["X-Event-Source-Url"] = eventSourceUrl;
+	return { status: (await fetch(`${storefrontApiUrl()}${PATHS[endpoint]}`, {
+		method: "POST",
+		headers,
+		body: JSON.stringify(body ?? {})
+	})).status };
+}
+function extractClientIp(headers) {
+	const realIp = headers.get("x-real-ip");
+	if (realIp && isIP(realIp.trim())) return realIp.trim();
+	const xff = headers.get("x-forwarded-for");
+	if (xff) {
+		const first = xff.split(",")[0]?.trim();
+		if (first && isIP(first)) return first;
+	}
+	return null;
+}
+//#endregion
+export { extractClientIp, proxyAnalytics };

package/dist/analytics-script-proxy.d.ts

@@ -0,0 +1,18 @@
+//#region src/analytics-script-proxy.d.ts
+export interface AnalyticsScriptDocument {
+  body: string;
+  /** Rails' own `Cache-Control`, so the browser TTL stays a server decision. */
+  cacheControl: string | null;
+}
+/**
+ * The script body, memoized, under the hard `DEADLINE_MS` ceiling. Rejects when
+ * the deadline passes; the route turns any rejection into an empty 200.
+ *
+ * A rejection here abandons the read without keeping it alive for anyone else:
+ * on workerd its fetch dies with this request, and concurrent requests wait on
+ * the memo's lease rather than on this call, taking over once it lapses.
+ * `Promise.race` has already attached a handler to the memoized call, so a
+ * later failure can't surface as an unhandled rejection.
+ */
+export declare function getAnalyticsScript(): Promise<AnalyticsScriptDocument>;
+//#endregion

package/dist/analytics-script-proxy.js

@@ -0,0 +1,46 @@
+import { memoTTL } from "./cache.js";
+import { getStorefrontTokenWithin, storefrontApiUrl } from "./graphql.js";
+import { getContentVersion } from "./content-version.js";
+//#region src/analytics-script-proxy.ts
+const TIMEOUT_MS = 2e3;
+const DEADLINE_MS = 2500;
+async function fetchAnalyticsScript() {
+	const signal = AbortSignal.timeout(TIMEOUT_MS);
+	const token = await getStorefrontTokenWithin(signal);
+	const res = await fetch(`${storefrontApiUrl()}/storefront/analytics/script`, {
+		headers: { Authorization: `Bearer ${token}` },
+		signal
+	});
+	if (!res.ok) throw new Error(`[analytics-script-proxy] upstream ${res.status}`);
+	return {
+		body: await res.text(),
+		cacheControl: res.headers.get("cache-control")
+	};
+}
+const memoizedPixelScript = memoTTL(fetchAnalyticsScript, {
+	key: () => "analytics-script",
+	version: getContentVersion,
+	leaseMs: 2250
+});
+/**
+* The script body, memoized, under the hard `DEADLINE_MS` ceiling. Rejects when
+* the deadline passes; the route turns any rejection into an empty 200.
+*
+* A rejection here abandons the read without keeping it alive for anyone else:
+* on workerd its fetch dies with this request, and concurrent requests wait on
+* the memo's lease rather than on this call, taking over once it lapses.
+* `Promise.race` has already attached a handler to the memoized call, so a
+* later failure can't surface as an unhandled rejection.
+*/
+async function getAnalyticsScript() {
+	let timer;
+	try {
+		return await Promise.race([memoizedPixelScript(), new Promise((_resolve, reject) => {
+			timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`[analytics-script-proxy] read exceeded ${DEADLINE_MS}ms`)), DEADLINE_MS);
+		})]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+//#endregion
+export { getAnalyticsScript };

package/dist/blog.d.ts

@@ -0,0 +1,109 @@
+import { ImageFileInfo } from "./files.js";
+//#region src/blog.d.ts
+export type ArticleAuthor = {
+  name: string;
+};
+export type ArticleCardData = {
+  handle: string;
+  blogHandle: string;
+  title: string;
+  summary: string | null;
+  image: ImageFileInfo | null;
+  tags: string[];
+  author: ArticleAuthor | null;
+  publishedAt: string | null;
+  bodyExcerpt?: string;
+};
+export type ArticleData = ArticleCardData & {
+  bodyHtml: string;
+  summaryHtml: string | null;
+  updatedAt: string;
+  bodyPlain: string;
+  seo: {
+    title: string;
+    description: string;
+  };
+};
+export type BlogMeta = {
+  id: string;
+  handle: string;
+  title: string;
+};
+export type BlogData = {
+  handle: string;
+  title: string;
+  articles_count: number;
+  articles: ArticleCardData[];
+};
+export type BlogPageData = BlogData & {
+  tags: string[];
+  total_count: number;
+  page_info: {
+    end_cursor: string | null;
+    has_next_page: boolean;
+  };
+};
+/** Featured-blog / blog-card resolver fetcher. Returns `null` on missing
+ * blog or GraphQL error; pickers degrade silently. */
+export declare const fetchBlog: (data: {
+  handle: string;
+  first: number;
+  locale?: string;
+}) => Promise<BlogData | null>;
+type FetchBlogPageInput = {
+  handle: string;
+  first?: number;
+  after?: string;
+  tag?: string;
+  locale?: string;
+  imageWidth?: number;
+  excerptLength?: number;
+  withBodyExcerpt?: boolean;
+};
+/** Server-driven blog listing. Uncached because cursor + tag permutations would
+ * blow the TTL cache; the underlying API is fast. Returns `null` on missing
+ * blog so the route can map to `notFound()`. */
+export declare const fetchBlogPage: (data: FetchBlogPageInput) => Promise<BlogPageData | null>;
+/** Single-article fetch. Used by the `article` and `article_list` resolver
+ * specs; returns `null` on missing article so the resolver drops the entry. */
+export declare const fetchArticleByRef: (ref: string, locale?: string) => Promise<ArticleData | null>;
+/** Detail-page fetch by `(blogHandle, handle)`. Used by the article route
+ * loader. */
+export declare const fetchArticle: (params: {
+  blogHandle: string;
+  handle: string;
+  locale?: string;
+}) => Promise<ArticleData | null>;
+/** One picked article as a card, sized as `fetchBlogPage` sizes a listing's
+ * cards — for a picker whose article renders as a card, not a page. `ref` is
+ * what the `article` setting stores (`parseArticleRef`). `null` on a missing
+ * article or a failed read, so the card falls back rather than the page. */
+export declare const fetchArticleCard: (params: {
+  ref: string;
+  imageWidth?: number;
+  excerptLength?: number;
+  withBodyExcerpt?: boolean;
+  locale?: string;
+}) => Promise<ArticleCardData | null>;
+/** Lean blog lookup for breadcrumbs / contextual labels. Skips articles. */
+export declare const fetchBlogMeta: (h: string, locale?: string | undefined) => Promise<BlogMeta | null>;
+/** The posts either side of one in its blog, by publish date. Named by age
+ * rather than previous / next because the two conventions disagree: Liquid's
+ * `blog.previous_article` is the NEWER post and `next_article` the older.
+ * Null at either end, for a post with no publish date, and on a failed read.
+ * `imageWidth`, `excerptLength` and `withBodyExcerpt` size the cards as
+ * `fetchBlogPage`'s do. */
+export declare const fetchAdjacentArticles: (params: {
+  blogId: string;
+  handle: string;
+  publishedAt: string | null;
+  locale?: string;
+  imageWidth?: number;
+  excerptLength?: number;
+  withBodyExcerpt?: boolean;
+}) => Promise<{
+  newer: ArticleCardData | null;
+  older: ArticleCardData | null;
+}>;
+//#endregion
+export {};