@businessdash/sdk 0.9.60

package/src/parallel-pages.ts

@@ -0,0 +1,192 @@
+/**
+ * Code-first declaration of a programmatic-SEO ("parallel") page.
+ * The consumer writes:
+ *
+ *   import { defineParallelPage } from "@businessdash/sdk";
+ *
+ *   const repairAreaPage = defineParallelPage({
+ *     key: "repair-area",
+ *     routePattern: "/repair/[service]/[area]",
+ *     variables: {
+ *       service: {
+ *         source: { section: "repairTypesCatalog" },
+ *         slugField: "type",
+ *         tokenFields: ["type", "description"],
+ *       },
+ *       area: {
+ *         source: { section: "serviceAreas", path: "areas" },
+ *         slugField: "slug",
+ *         tokenFields: ["name", "state", "slug"],
+ *       },
+ *     },
+ *     meta: {
+ *       title: "{service.type} in {area.name} | {company.shortName}",
+ *       description:
+ *         "Professional {service.type} in {area.name}, {area.state}. Call {company.phone}.",
+ *     },
+ *     templateRef: "repairAreaTemplate",
+ *   });
+ *
+ * `defineParallelPage` is a pure builder — no DB writes, no HTTP. It
+ * returns a frozen, type-checked artifact. Push to the BIAB server
+ * later via `biab-dev sync-parallel-pages` (or the SDK's
+ * `client.parallelPages.upsertDefinition()` when wired).
+ */
+
+import { parseParallelPagePattern } from "./url-pattern.js";
+
+export type ParallelPageVariableInput = {
+	source: {
+		section: string;
+		path?: string;
+	};
+	slugField: string;
+	tokenFields?: ReadonlyArray<string>;
+};
+
+export type ParallelPageMetaInput = {
+	title: string;
+	description: string;
+	canonical?: string;
+	ogImage?: string;
+};
+
+export type ParallelPageInput<
+	V extends Record<string, ParallelPageVariableInput>,
+> = {
+	key: string;
+	routePattern: string;
+	variables: V;
+	meta: ParallelPageMetaInput;
+	/**
+	 * For SDK-defined pages, a schema section key naming the body
+	 * template. The dashboard renders the matching section's content
+	 * for the parallel-page body. Site-builder pages use a different
+	 * pointer scheme (`cms:<contentId>`) — set transparently by the
+	 * dashboard.
+	 */
+	templateRef: string;
+	/**
+	 * Per-page robots directive. Defaults to `inherit` (defer to the
+	 * site-wide robots config). Set `noindex` for variants that
+	 * shouldn't appear in search (e.g. dynamic catch-alls used as
+	 * fallbacks).
+	 */
+	crawlRule?: "inherit" | "index" | "noindex";
+};
+
+export type ParallelPageDefinition<
+	V extends Record<string, ParallelPageVariableInput>,
+> = {
+	readonly $kind: "biab.parallelPage";
+	readonly key: string;
+	readonly routePattern: string;
+	readonly variables: ReadonlyArray<{
+		readonly name: keyof V & string;
+		readonly source: { readonly section: string; readonly path?: string };
+		readonly slugField: string;
+		readonly tokenFields: ReadonlyArray<string>;
+	}>;
+	readonly meta: Readonly<ParallelPageMetaInput>;
+	readonly templateRef: string;
+	readonly crawlRule: "inherit" | "index" | "noindex";
+};
+
+/**
+ * Validate + freeze a parallel-page declaration. Throws on:
+ *   - Empty / malformed `routePattern`
+ *   - `[variable]` segments in the pattern that aren't in `variables`
+ *   - `variables` keys that don't appear in the pattern
+ *   - Duplicate variable names
+ *   - Missing `slugField` on any binding
+ */
+export function defineParallelPage<
+	V extends Record<string, ParallelPageVariableInput>,
+>(input: ParallelPageInput<V>): ParallelPageDefinition<V> {
+	if (!input.key || typeof input.key !== "string") {
+		throw new Error("defineParallelPage: `key` is required.");
+	}
+	if (!/^[a-z][a-z0-9-]*$/.test(input.key)) {
+		throw new Error(
+			`defineParallelPage: \`key\` must be kebab-case (got "${input.key}").`,
+		);
+	}
+
+	const parsed = parseParallelPagePattern(input.routePattern);
+
+	const inputNames = new Set(Object.keys(input.variables));
+	const patternNames = new Set(parsed.variableNames);
+
+	for (const patternName of patternNames) {
+		if (!inputNames.has(patternName)) {
+			throw new Error(
+				`defineParallelPage("${input.key}"): pattern uses "[${patternName}]" ` +
+					`but \`variables\` has no binding for "${patternName}".`,
+			);
+		}
+	}
+	for (const inputName of inputNames) {
+		if (!patternNames.has(inputName)) {
+			throw new Error(
+				`defineParallelPage("${input.key}"): \`variables\` declares "${inputName}" ` +
+					`but the pattern "${input.routePattern}" has no "[${inputName}]" segment.`,
+			);
+		}
+	}
+
+	const variables: ParallelPageDefinition<V>["variables"] =
+		parsed.variableNames.map((name) => {
+			const raw = input.variables[name]!;
+			if (!raw.source?.section) {
+				throw new Error(
+					`defineParallelPage("${input.key}"): variable "${name}" is missing \`source.section\`.`,
+				);
+			}
+			if (!raw.slugField) {
+				throw new Error(
+					`defineParallelPage("${input.key}"): variable "${name}" is missing \`slugField\`.`,
+				);
+			}
+			const tokenFields = raw.tokenFields ?? [raw.slugField];
+			return Object.freeze({
+				name: name as keyof V & string,
+				source: Object.freeze({
+					section: raw.source.section,
+					...(raw.source.path !== undefined ? { path: raw.source.path } : {}),
+				}),
+				slugField: raw.slugField,
+				tokenFields: Object.freeze([...tokenFields]),
+			});
+		});
+
+	if (!input.meta?.title || !input.meta?.description) {
+		throw new Error(
+			`defineParallelPage("${input.key}"): \`meta.title\` and \`meta.description\` are required.`,
+		);
+	}
+
+	return Object.freeze({
+		$kind: "biab.parallelPage",
+		key: input.key,
+		routePattern: input.routePattern,
+		variables: Object.freeze(variables),
+		meta: Object.freeze({ ...input.meta }),
+		templateRef: input.templateRef,
+		crawlRule: input.crawlRule ?? "inherit",
+	}) as ParallelPageDefinition<V>;
+}
+
+/**
+ * Type guard for the artifact `defineParallelPage` returns. Useful
+ * when consumers export a mixed array of marketing + parallel-page
+ * declarations from one `biab.config.ts`.
+ */
+export function isParallelPageDefinition(
+	value: unknown,
+): value is ParallelPageDefinition<Record<string, ParallelPageVariableInput>> {
+	return (
+		!!value &&
+		typeof value === "object" &&
+		(value as { $kind?: unknown }).$kind === "biab.parallelPage"
+	);
+}

package/src/payment-icons.ts

@@ -0,0 +1,205 @@
+/**
+ * Payment-method brand icons — framework-agnostic.
+ *
+ * The SDK ships the SVG path data for every payment method a Company Profile can
+ * enable, plus `paymentIconSvg()`, which returns a ready-to-inject `<svg>`
+ * markup string. No framework dependency: drop the string into React
+ * (`dangerouslySetInnerHTML`), Vue (`v-html`), Svelte (`{@html}`), Angular
+ * (`[innerHTML]`), or the DOM (`el.innerHTML`). For full control,
+ * `paymentIconData()` returns the raw `{ viewBox, paths }`.
+ *
+ * Theming — the icon is "the color of the text" by default:
+ *  - default `fill="currentColor"` → inherits the surrounding text color, so it
+ *    adapts to light/dark automatically.
+ *  - `theme: "light" | "dark"` → lock to a fixed neutral permanently.
+ *  - `color`: any CSS color (e.g. "#1a1a1a") → explicit; wins over `theme`.
+ *  - text-only is simply not calling this — render the label by itself (icons are
+ *    additive). Unknown / custom ("additional") methods return `null` so callers
+ *    fall back to text.
+ *
+ * Icon sources: Font Awesome Free (CC BY 4.0) and Simple Icons (CC0).
+ *
+ * GENERATED from react-icons path data — do not edit the data by hand; see
+ * scripts that produced PAYMENT_ICONS.
+ */
+
+/** Every payment method the Company Profile can toggle on. */
+export type PaymentMethodIconKey =
+	| "cash"
+	| "visa"
+	| "mastercard"
+	| "discover"
+	| "americanExpress"
+	| "personalCheck"
+	| "paypal"
+	| "venmo"
+	| "cashApp"
+	| "zelle"
+	| "applePay";
+
+export type PaymentIconData = {
+	/** SVG viewBox, e.g. "0 0 576 512". */
+	viewBox: string;
+	/** Human-readable label, e.g. "American Express". */
+	label: string;
+	/** One or more SVG path `d` strings, drawn with the resolved fill color. */
+	paths: string[];
+};
+
+/** Force a fixed neutral instead of inheriting the text color. */
+export type PaymentIconTheme = "light" | "dark";
+
+export type PaymentIconOptions = {
+	/** Explicit CSS color (e.g. "#1a1a1a" or "var(--brand)"). Wins over `theme`. */
+	color?: string;
+	/** Lock the icon to a fixed neutral: light bg → dark icon, dark bg → light. */
+	theme?: PaymentIconTheme;
+	/** Width/height. Number → px; string → used as-is. Default "1em". */
+	size?: number | string;
+	/** Accessible label. Defaults to the method label; pass "" to hide it. */
+	title?: string;
+};
+
+/** Brand icon data, keyed by Company Profile payment method. */
+export const PAYMENT_ICONS: Record<PaymentMethodIconKey, PaymentIconData> = {
+	cash: {
+		viewBox: "0 0 512 512",
+		label: "Cash",
+		paths: [
+			"M32 96v256h448V96H32zm160.5 224h-80.4c0-26.6-21.5-48.1-48.1-48.1V192c35.3 0 64-28.7 64-64h64.5c-19.9 23.5-32.5 57.8-32.5 96s12.6 72.5 32.5 96zM448 271.9c-26 0-48 21.5-48 48.1h-80.5c19.9-23.5 32.5-57.8 32.5-96s-12.6-72.5-32.5-96H384c0 35.3 28.7 64 64 64v79.9zM32 384h448v32H32z",
+		],
+	},
+	visa: {
+		viewBox: "0 0 576 512",
+		label: "Visa",
+		paths: [
+			"M470.1 231.3s7.6 37.2 9.3 45H446c3.3-8.9 16-43.5 16-43.5-.2.3 3.3-9.1 5.3-14.9l2.8 13.4zM576 80v352c0 26.5-21.5 48-48 48H48c-26.5 0-48-21.5-48-48V80c0-26.5 21.5-48 48-48h480c26.5 0 48 21.5 48 48zM152.5 331.2L215.7 176h-42.5l-39.3 106-4.3-21.5-14-71.4c-2.3-9.9-9.4-12.7-18.2-13.1H32.7l-.7 3.1c15.8 4 29.9 9.8 42.2 17.1l35.8 135h42.5zm94.4.2L272.1 176h-40.2l-25.1 155.4h40.1zm139.9-50.8c.2-17.7-10.6-31.2-33.7-42.3-14.1-7.1-22.7-11.9-22.7-19.2.2-6.6 7.3-13.4 23.1-13.4 13.1-.3 22.7 2.8 29.9 5.9l3.6 1.7 5.5-33.6c-7.9-3.1-20.5-6.6-36-6.6-39.7 0-67.6 21.2-67.8 51.4-.3 22.3 20 34.7 35.2 42.2 15.5 7.6 20.8 12.6 20.8 19.3-.2 10.4-12.6 15.2-24.1 15.2-16 0-24.6-2.5-37.7-8.3l-5.3-2.5-5.6 34.9c9.4 4.3 26.8 8.1 44.8 8.3 42.2.1 69.7-20.8 70-53zM528 331.4L495.6 176h-31.1c-9.6 0-16.9 2.8-21 12.9l-59.7 142.5H426s6.9-19.2 8.4-23.3H486c1.2 5.5 4.8 23.3 4.8 23.3H528z",
+		],
+	},
+	mastercard: {
+		viewBox: "0 0 576 512",
+		label: "Mastercard",
+		paths: [
+			"M482.9 410.3c0 6.8-4.6 11.7-11.2 11.7-6.8 0-11.2-5.2-11.2-11.7 0-6.5 4.4-11.7 11.2-11.7 6.6 0 11.2 5.2 11.2 11.7zm-310.8-11.7c-7.1 0-11.2 5.2-11.2 11.7 0 6.5 4.1 11.7 11.2 11.7 6.5 0 10.9-4.9 10.9-11.7-.1-6.5-4.4-11.7-10.9-11.7zm117.5-.3c-5.4 0-8.7 3.5-9.5 8.7h19.1c-.9-5.7-4.4-8.7-9.6-8.7zm107.8.3c-6.8 0-10.9 5.2-10.9 11.7 0 6.5 4.1 11.7 10.9 11.7 6.8 0 11.2-4.9 11.2-11.7 0-6.5-4.4-11.7-11.2-11.7zm105.9 26.1c0 .3.3.5.3 1.1 0 .3-.3.5-.3 1.1-.3.3-.3.5-.5.8-.3.3-.5.5-1.1.5-.3.3-.5.3-1.1.3-.3 0-.5 0-1.1-.3-.3 0-.5-.3-.8-.5-.3-.3-.5-.5-.5-.8-.3-.5-.3-.8-.3-1.1 0-.5 0-.8.3-1.1 0-.5.3-.8.5-1.1.3-.3.5-.3.8-.5.5-.3.8-.3 1.1-.3.5 0 .8 0 1.1.3.5.3.8.3 1.1.5s.2.6.5 1.1zm-2.2 1.4c.5 0 .5-.3.8-.3.3-.3.3-.5.3-.8 0-.3 0-.5-.3-.8-.3 0-.5-.3-1.1-.3h-1.6v3.5h.8V426h.3l1.1 1.4h.8l-1.1-1.3zM576 81v352c0 26.5-21.5 48-48 48H48c-26.5 0-48-21.5-48-48V81c0-26.5 21.5-48 48-48h480c26.5 0 48 21.5 48 48zM64 220.6c0 76.5 62.1 138.5 138.5 138.5 27.2 0 53.9-8.2 76.5-23.1-72.9-59.3-72.4-171.2 0-230.5-22.6-15-49.3-23.1-76.5-23.1-76.4-.1-138.5 62-138.5 138.2zm224 108.8c70.5-55 70.2-162.2 0-217.5-70.2 55.3-70.5 162.6 0 217.5zm-142.3 76.3c0-8.7-5.7-14.4-14.7-14.7-4.6 0-9.5 1.4-12.8 6.5-2.4-4.1-6.5-6.5-12.2-6.5-3.8 0-7.6 1.4-10.6 5.4V392h-8.2v36.7h8.2c0-18.9-2.5-30.2 9-30.2 10.2 0 8.2 10.2 8.2 30.2h7.9c0-18.3-2.5-30.2 9-30.2 10.2 0 8.2 10 8.2 30.2h8.2v-23zm44.9-13.7h-7.9v4.4c-2.7-3.3-6.5-5.4-11.7-5.4-10.3 0-18.2 8.2-18.2 19.3 0 11.2 7.9 19.3 18.2 19.3 5.2 0 9-1.9 11.7-5.4v4.6h7.9V392zm40.5 25.6c0-15-22.9-8.2-22.9-15.2 0-5.7 11.9-4.8 18.5-1.1l3.3-6.5c-9.4-6.1-30.2-6-30.2 8.2 0 14.3 22.9 8.3 22.9 15 0 6.3-13.5 5.8-20.7.8l-3.5 6.3c11.2 7.6 32.6 6 32.6-7.5zm35.4 9.3l-2.2-6.8c-3.8 2.1-12.2 4.4-12.2-4.1v-16.6h13.1V392h-13.1v-11.2h-8.2V392h-7.6v7.3h7.6V416c0 17.6 17.3 14.4 22.6 10.9zm13.3-13.4h27.5c0-16.2-7.4-22.6-17.4-22.6-10.6 0-18.2 7.9-18.2 19.3 0 20.5 22.6 23.9 33.8 14.2l-3.8-6c-7.8 6.4-19.6 5.8-21.9-4.9zm59.1-21.5c-4.6-2-11.6-1.8-15.2 4.4V392h-8.2v36.7h8.2V408c0-11.6 9.5-10.1 12.8-8.4l2.4-7.6zm10.6 18.3c0-11.4 11.6-15.1 20.7-8.4l3.8-6.5c-11.6-9.1-32.7-4.1-32.7 15 0 19.8 22.4 23.8 32.7 15l-3.8-6.5c-9.2 6.5-20.7 2.6-20.7-8.6zm66.7-18.3H408v4.4c-8.3-11-29.9-4.8-29.9 13.9 0 19.2 22.4 24.7 29.9 13.9v4.6h8.2V392zm33.7 0c-2.4-1.2-11-2.9-15.2 4.4V392h-7.9v36.7h7.9V408c0-11 9-10.3 12.8-8.4l2.4-7.6zm40.3-14.9h-7.9v19.3c-8.2-10.9-29.9-5.1-29.9 13.9 0 19.4 22.5 24.6 29.9 13.9v4.6h7.9v-51.7zm7.6-75.1v4.6h.8V302h1.9v-.8h-4.6v.8h1.9zm6.6 123.8c0-.5 0-1.1-.3-1.6-.3-.3-.5-.8-.8-1.1-.3-.3-.8-.5-1.1-.8-.5 0-1.1-.3-1.6-.3-.3 0-.8.3-1.4.3-.5.3-.8.5-1.1.8-.5.3-.8.8-.8 1.1-.3.5-.3 1.1-.3 1.6 0 .3 0 .8.3 1.4 0 .3.3.8.8 1.1.3.3.5.5 1.1.8.5.3 1.1.3 1.4.3.5 0 1.1 0 1.6-.3.3-.3.8-.5 1.1-.8.3-.3.5-.8.8-1.1.3-.6.3-1.1.3-1.4zm3.2-124.7h-1.4l-1.6 3.5-1.6-3.5h-1.4v5.4h.8v-4.1l1.6 3.5h1.1l1.4-3.5v4.1h1.1v-5.4zm4.4-80.5c0-76.2-62.1-138.3-138.5-138.3-27.2 0-53.9 8.2-76.5 23.1 72.1 59.3 73.2 171.5 0 230.5 22.6 15 49.5 23.1 76.5 23.1 76.4.1 138.5-61.9 138.5-138.4z",
+		],
+	},
+	discover: {
+		viewBox: "0 0 576 512",
+		label: "Discover",
+		paths: [
+			"M520.4 196.1c0-7.9-5.5-12.1-15.6-12.1h-4.9v24.9h4.7c10.3 0 15.8-4.4 15.8-12.8zM528 32H48C21.5 32 0 53.5 0 80v352c0 26.5 21.5 48 48 48h480c26.5 0 48-21.5 48-48V80c0-26.5-21.5-48-48-48zm-44.1 138.9c22.6 0 52.9-4.1 52.9 24.4 0 12.6-6.6 20.7-18.7 23.2l25.8 34.4h-19.6l-22.2-32.8h-2.2v32.8h-16zm-55.9.1h45.3v14H444v18.2h28.3V217H444v22.2h29.3V253H428zm-68.7 0l21.9 55.2 22.2-55.2h17.5l-35.5 84.2h-8.6l-35-84.2zm-55.9-3c24.7 0 44.6 20 44.6 44.6 0 24.7-20 44.6-44.6 44.6-24.7 0-44.6-20-44.6-44.6 0-24.7 20-44.6 44.6-44.6zm-49.3 6.1v19c-20.1-20.1-46.8-4.7-46.8 19 0 25 27.5 38.5 46.8 19.2v19c-29.7 14.3-63.3-5.7-63.3-38.2 0-31.2 33.1-53 63.3-38zm-97.2 66.3c11.4 0 22.4-15.3-3.3-24.4-15-5.5-20.2-11.4-20.2-22.7 0-23.2 30.6-31.4 49.7-14.3l-8.4 10.8c-10.4-11.6-24.9-6.2-24.9 2.5 0 4.4 2.7 6.9 12.3 10.3 18.2 6.6 23.6 12.5 23.6 25.6 0 29.5-38.8 37.4-56.6 11.3l10.3-9.9c3.7 7.1 9.9 10.8 17.5 10.8zM55.4 253H32v-82h23.4c26.1 0 44.1 17 44.1 41.1 0 18.5-13.2 40.9-44.1 40.9zm67.5 0h-16v-82h16zM544 433c0 8.2-6.8 15-15 15H128c189.6-35.6 382.7-139.2 416-160zM74.1 191.6c-5.2-4.9-11.6-6.6-21.9-6.6H48v54.2h4.2c10.3 0 17-2 21.9-6.4 5.7-5.2 8.9-12.8 8.9-20.7s-3.2-15.5-8.9-20.5z",
+		],
+	},
+	americanExpress: {
+		viewBox: "0 0 576 512",
+		label: "American Express",
+		paths: [
+			"M325.1 167.8c0-16.4-14.1-18.4-27.4-18.4l-39.1-.3v69.3H275v-25.1h18c18.4 0 14.5 10.3 14.8 25.1h16.6v-13.5c0-9.2-1.5-15.1-11-18.4 7.4-3 11.8-10.7 11.7-18.7zm-29.4 11.3H275v-15.3h21c5.1 0 10.7 1 10.7 7.4 0 6.6-5.3 7.9-11 7.9zM279 268.6h-52.7l-21 22.8-20.5-22.8h-66.5l-.1 69.3h65.4l21.3-23 20.4 23h32.2l.1-23.3c18.9 0 49.3 4.6 49.3-23.3 0-17.3-12.3-22.7-27.9-22.7zm-103.8 54.7h-40.6v-13.8h36.3v-14.1h-36.3v-12.5h41.7l17.9 20.2zm65.8 8.2l-25.3-28.1L241 276zm37.8-31h-21.2v-17.6h21.5c5.6 0 10.2 2.3 10.2 8.4 0 6.4-4.6 9.2-10.5 9.2zm-31.6-136.7v-14.6h-55.5v69.3h55.5v-14.3h-38.9v-13.8h37.8v-14.1h-37.8v-12.5zM576 255.4h-.2zm-194.6 31.9c0-16.4-14.1-18.7-27.1-18.7h-39.4l-.1 69.3h16.6l.1-25.3h17.6c11 0 14.8 2 14.8 13.8l-.1 11.5h16.6l.1-13.8c0-8.9-1.8-15.1-11-18.4 7.7-3.1 11.8-10.8 11.9-18.4zm-29.2 11.2h-20.7v-15.6h21c5.1 0 10.7 1 10.7 7.4 0 6.9-5.4 8.2-11 8.2zm-172.8-80v-69.3h-27.6l-19.7 47-21.7-47H83.3v65.7l-28.1-65.7H30.7L1 218.5h17.9l6.4-15.3h34.5l6.4 15.3H100v-54.2l24 54.2h14.6l24-54.2v54.2zM31.2 188.8l11.2-27.6 11.5 27.6zm477.4 158.9v-4.5c-10.8 5.6-3.9 4.5-156.7 4.5 0-25.2.1-23.9 0-25.2-1.7-.1-3.2-.1-9.4-.1 0 17.9-.1 6.8-.1 25.3h-39.6c0-12.1.1-15.3.1-29.2-10 6-22.8 6.4-34.3 6.2 0 14.7-.1 8.3-.1 23h-48.9c-5.1-5.7-2.7-3.1-15.4-17.4-3.2 3.5-12.8 13.9-16.1 17.4h-82v-92.3h83.1c5 5.6 2.8 3.1 15.5 17.2 3.2-3.5 12.2-13.4 15.7-17.2h58c9.8 0 18 1.9 24.3 5.6v-5.6c54.3 0 64.3-1.4 75.7 5.1v-5.1h78.2v5.2c11.4-6.9 19.6-5.2 64.9-5.2v5c10.3-5.9 16.6-5.2 54.3-5V80c0-26.5-21.5-48-48-48h-480c-26.5 0-48 21.5-48 48v109.8c9.4-21.9 19.7-46 23.1-53.9h39.7c4.3 10.1 1.6 3.7 9 21.1v-21.1h46c2.9 6.2 11.1 24 13.9 30 5.8-13.6 10.1-23.9 12.6-30h103c0-.1 11.5 0 11.6 0 43.7.2 53.6-.8 64.4 5.3v-5.3H363v9.3c7.6-6.1 17.9-9.3 30.7-9.3h27.6c0 .5 1.9.3 2.3.3H456c4.2 9.8 2.6 6 8.8 20.6v-20.6h43.3c4.9 8-1-1.8 11.2 18.4v-18.4h39.9v92h-41.6c-5.4-9-1.4-2.2-13.2-21.9v21.9h-52.8c-6.4-14.8-.1-.3-6.6-15.3h-19c-4.2 10-2.2 5.2-6.4 15.3h-26.8c-12.3 0-22.3-3-29.7-8.9v8.9h-66.5c-.3-13.9-.1-24.8-.1-24.8-1.8-.3-3.4-.2-9.8-.2v25.1H151.2v-11.4c-2.5 5.6-2.7 5.9-5.1 11.4h-29.5c-4-8.9-2.9-6.4-5.1-11.4v11.4H58.6c-4.2-10.1-2.2-5.3-6.4-15.3H33c-4.2 10-2.2 5.2-6.4 15.3H0V432c0 26.5 21.5 48 48 48h480.1c26.5 0 48-21.5 48-48v-90.4c-12.7 8.3-32.7 6.1-67.5 6.1zm36.3-64.5H575v-14.6h-32.9c-12.8 0-23.8 6.6-23.8 20.7 0 33 42.7 12.8 42.7 27.4 0 5.1-4.3 6.4-8.4 6.4h-32l-.1 14.8h32c8.4 0 17.6-1.8 22.5-8.9v-25.8c-10.5-13.8-39.3-1.3-39.3-13.5 0-5.8 4.6-6.5 9.2-6.5zm-57 39.8h-32.2l-.1 14.8h32.2c14.8 0 26.2-5.6 26.2-22 0-33.2-42.9-11.2-42.9-26.3 0-5.6 4.9-6.4 9.2-6.4h30.4v-14.6h-33.2c-12.8 0-23.5 6.6-23.5 20.7 0 33 42.7 12.5 42.7 27.4-.1 5.4-4.7 6.4-8.8 6.4zm-42.2-40.1v-14.3h-55.2l-.1 69.3h55.2l.1-14.3-38.6-.3v-13.8H445v-14.1h-37.8v-12.5zm-56.3-108.1c-.3.2-1.4 2.2-1.4 7.6 0 6 .9 7.7 1.1 7.9.2.1 1.1.5 3.4.5l7.3-16.9c-1.1 0-2.1-.1-3.1-.1-5.6 0-7 .7-7.3 1zm20.4-10.5h-.1zm-16.2-15.2c-23.5 0-34 12-34 35.3 0 22.2 10.2 34 33 34h19.2l6.4-15.3h34.3l6.6 15.3h33.7v-51.9l31.2 51.9h23.6v-69h-16.9v48.1l-29.1-48.1h-25.3v65.4l-27.9-65.4h-24.8l-23.5 54.5h-7.4c-13.3 0-16.1-8.1-16.1-19.9 0-23.8 15.7-20 33.1-19.7v-15.2zm42.1 12.1l11.2 27.6h-22.8zm-101.1-12v69.3h16.9v-69.3z",
+		],
+	},
+	personalCheck: {
+		viewBox: "0 0 640 512",
+		label: "Personal Check",
+		paths: [
+			"M0 448c0 17.67 14.33 32 32 32h576c17.67 0 32-14.33 32-32V128H0v320zm448-208c0-8.84 7.16-16 16-16h96c8.84 0 16 7.16 16 16v32c0 8.84-7.16 16-16 16h-96c-8.84 0-16-7.16-16-16v-32zm0 120c0-4.42 3.58-8 8-8h112c4.42 0 8 3.58 8 8v16c0 4.42-3.58 8-8 8H456c-4.42 0-8-3.58-8-8v-16zM64 264c0-4.42 3.58-8 8-8h304c4.42 0 8 3.58 8 8v16c0 4.42-3.58 8-8 8H72c-4.42 0-8-3.58-8-8v-16zm0 96c0-4.42 3.58-8 8-8h176c4.42 0 8 3.58 8 8v16c0 4.42-3.58 8-8 8H72c-4.42 0-8-3.58-8-8v-16zM624 32H16C7.16 32 0 39.16 0 48v48h640V48c0-8.84-7.16-16-16-16z",
+		],
+	},
+	paypal: {
+		viewBox: "0 0 576 512",
+		label: "PayPal",
+		paths: [
+			"M186.3 258.2c0 12.2-9.7 21.5-22 21.5-9.2 0-16-5.2-16-15 0-12.2 9.5-22 21.7-22 9.3 0 16.3 5.7 16.3 15.5zM80.5 209.7h-4.7c-1.5 0-3 1-3.2 2.7l-4.3 26.7 8.2-.3c11 0 19.5-1.5 21.5-14.2 2.3-13.4-6.2-14.9-17.5-14.9zm284 0H360c-1.8 0-3 1-3.2 2.7l-4.2 26.7 8-.3c13 0 22-3 22-18-.1-10.6-9.6-11.1-18.1-11.1zM576 80v352c0 26.5-21.5 48-48 48H48c-26.5 0-48-21.5-48-48V80c0-26.5 21.5-48 48-48h480c26.5 0 48 21.5 48 48zM128.3 215.4c0-21-16.2-28-34.7-28h-40c-2.5 0-5 2-5.2 4.7L32 294.2c-.3 2 1.2 4 3.2 4h19c2.7 0 5.2-2.9 5.5-5.7l4.5-26.6c1-7.2 13.2-4.7 18-4.7 28.6 0 46.1-17 46.1-45.8zm84.2 8.8h-19c-3.8 0-4 5.5-4.2 8.2-5.8-8.5-14.2-10-23.7-10-24.5 0-43.2 21.5-43.2 45.2 0 19.5 12.2 32.2 31.7 32.2 9 0 20.2-4.9 26.5-11.9-.5 1.5-1 4.7-1 6.2 0 2.3 1 4 3.2 4H200c2.7 0 5-2.9 5.5-5.7l10.2-64.3c.3-1.9-1.2-3.9-3.2-3.9zm40.5 97.9l63.7-92.6c.5-.5.5-1 .5-1.7 0-1.7-1.5-3.5-3.2-3.5h-19.2c-1.7 0-3.5 1-4.5 2.5l-26.5 39-11-37.5c-.8-2.2-3-4-5.5-4h-18.7c-1.7 0-3.2 1.8-3.2 3.5 0 1.2 19.5 56.8 21.2 62.1-2.7 3.8-20.5 28.6-20.5 31.6 0 1.8 1.5 3.2 3.2 3.2h19.2c1.8-.1 3.5-1.1 4.5-2.6zm159.3-106.7c0-21-16.2-28-34.7-28h-39.7c-2.7 0-5.2 2-5.5 4.7l-16.2 102c-.2 2 1.3 4 3.2 4h20.5c2 0 3.5-1.5 4-3.2l4.5-29c1-7.2 13.2-4.7 18-4.7 28.4 0 45.9-17 45.9-45.8zm84.2 8.8h-19c-3.8 0-4 5.5-4.3 8.2-5.5-8.5-14-10-23.7-10-24.5 0-43.2 21.5-43.2 45.2 0 19.5 12.2 32.2 31.7 32.2 9.3 0 20.5-4.9 26.5-11.9-.3 1.5-1 4.7-1 6.2 0 2.3 1 4 3.2 4H484c2.7 0 5-2.9 5.5-5.7l10.2-64.3c.3-1.9-1.2-3.9-3.2-3.9zm47.5-33.3c0-2-1.5-3.5-3.2-3.5h-18.5c-1.5 0-3 1.2-3.2 2.7l-16.2 104-.3.5c0 1.8 1.5 3.5 3.5 3.5h16.5c2.5 0 5-2.9 5.2-5.7L544 191.2v-.3zm-90 51.8c-12.2 0-21.7 9.7-21.7 22 0 9.7 7 15 16.2 15 12 0 21.7-9.2 21.7-21.5.1-9.8-6.9-15.5-16.2-15.5z",
+		],
+	},
+	venmo: {
+		viewBox: "0 0 24 24",
+		label: "Venmo",
+		paths: [
+			"M21.772 13.119c-.267 0-.381-.251-.38-.655 0-.533.121-1.575.712-1.575.267 0 .357.243.357.598 0 .533-.13 1.632-.689 1.632Zm.502-3.377c-1.677 0-2.405 1.285-2.405 2.658 0 1.042.421 1.874 1.693 1.874 1.717 0 2.438-1.406 2.438-2.763 0-1.025-.462-1.769-1.726-1.769Zm-3.833 0c-.558 0-.964.17-1.393.477-.154-.275-.462-.477-.932-.477-.542 0-.947.219-1.247.437l-.04-.364H13.54l-.688 4.354h1.506l.479-3.053c.129-.065.323-.154.518-.154.145 0 .267.049.267.267 0 .056-.016.145-.024.218l-.429 2.722h1.498l.478-3.053c.138-.073.324-.154.51-.154.146 0 .268.049.268.267 0 .056-.017.145-.025.218l-.429 2.722h1.499l.461-2.908c.025-.153.049-.388.049-.549 0-.582-.267-.97-1.037-.97Zm-6.871 0c-.575 0-.98.219-1.287.421l-.017-.348H8.962l-.689 4.354H9.78l.478-3.053c.13-.065.324-.154.518-.154.147 0 .268.049.268.242 0 .081-.024.227-.032.299l-.422 2.666h1.499l.462-2.908c.024-.153.049-.388.049-.549 0-.582-.268-.97-1.03-.97Zm-5.631 1.834c.041-.485.413-.824.697-.824.162 0 .299.097.299.291 0 .404-.713.533-.996.533Zm.843-1.834c-1.604 0-2.382 1.39-2.382 2.698 0 1.01.478 1.817 1.814 1.817.527 0 1.07-.113 1.418-.282l.186-1.26c-.494.25-.874.347-1.271.347-.365 0-.64-.194-.64-.687.826-.008 2.252-.347 2.252-1.453 0-.687-.494-1.18-1.377-1.18Zm-4.239.267c.089.186.146.412.146.743 0 .606-.429 1.494-.777 2.06l-.373-2.989L0 9.969l.705 4.2h1.757c.77-1.01 1.718-2.448 1.718-3.554 0-.347-.073-.622-.235-.889l-1.402.283Z",
+		],
+	},
+	cashApp: {
+		viewBox: "0 0 24 24",
+		label: "Cash App",
+		paths: [
+			"M23.59 3.475a5.1 5.1 0 00-3.05-3.05c-1.31-.42-2.5-.42-4.92-.42H8.36c-2.4 0-3.61 0-4.9.4a5.1 5.1 0 00-3.05 3.06C0 4.765 0 5.965 0 8.365v7.27c0 2.41 0 3.6.4 4.9a5.1 5.1 0 003.05 3.05c1.3.41 2.5.41 4.9.41h7.28c2.41 0 3.61 0 4.9-.4a5.1 5.1 0 003.06-3.06c.41-1.3.41-2.5.41-4.9v-7.25c0-2.41 0-3.61-.41-4.91zm-6.17 4.63l-.93.93a.5.5 0 01-.67.01 5 5 0 00-3.22-1.18c-.97 0-1.94.32-1.94 1.21 0 .9 1.04 1.2 2.24 1.65 2.1.7 3.84 1.58 3.84 3.64 0 2.24-1.74 3.78-4.58 3.95l-.26 1.2a.49.49 0 01-.48.39H9.63l-.09-.01a.5.5 0 01-.38-.59l.28-1.27a6.54 6.54 0 01-2.88-1.57v-.01a.48.48 0 010-.68l1-.97a.49.49 0 01.67 0c.91.86 2.13 1.34 3.39 1.32 1.3 0 2.17-.55 2.17-1.42 0-.87-.88-1.1-2.54-1.72-1.76-.63-3.43-1.52-3.43-3.6 0-2.42 2.01-3.6 4.39-3.71l.25-1.23a.48.48 0 01.48-.38h1.78l.1.01c.26.06.43.31.37.57l-.27 1.37c.9.3 1.75.77 2.48 1.39l.02.02c.19.2.19.5 0 .68z",
+		],
+	},
+	zelle: {
+		viewBox: "0 0 24 24",
+		label: "Zelle",
+		paths: [
+			"M13.559 24h-2.841a.483.483 0 0 1-.483-.483v-2.765H5.638a.667.667 0 0 1-.666-.666v-2.234a.67.67 0 0 1 .142-.412l8.139-10.382h-7.25a.667.667 0 0 1-.667-.667V3.914c0-.367.299-.666.666-.666h4.23V.483c0-.266.217-.483.483-.483h2.841c.266 0 .483.217.483.483v2.765h4.323c.367 0 .666.299.666.666v2.137a.67.67 0 0 1-.141.41l-8.19 10.481h7.665c.367 0 .666.299.666.666v2.477a.667.667 0 0 1-.666.667h-4.32v2.765a.483.483 0 0 1-.483.483Z",
+		],
+	},
+	applePay: {
+		viewBox: "0 0 576 512",
+		label: "Apple Pay",
+		paths: [
+			"M302.2 218.4c0 17.2-10.5 27.1-29 27.1h-24.3v-54.2h24.4c18.4 0 28.9 9.8 28.9 27.1zm47.5 62.6c0 8.3 7.2 13.7 18.5 13.7 14.4 0 25.2-9.1 25.2-21.9v-7.7l-23.5 1.5c-13.3.9-20.2 5.8-20.2 14.4zM576 79v352c0 26.5-21.5 48-48 48H48c-26.5 0-48-21.5-48-48V79c0-26.5 21.5-48 48-48h480c26.5 0 48 21.5 48 48zM127.8 197.2c8.4.7 16.8-4.2 22.1-10.4 5.2-6.4 8.6-15 7.7-23.7-7.4.3-16.6 4.9-21.9 11.3-4.8 5.5-8.9 14.4-7.9 22.8zm60.6 74.5c-.2-.2-19.6-7.6-19.8-30-.2-18.7 15.3-27.7 16-28.2-8.8-13-22.4-14.4-27.1-14.7-12.2-.7-22.6 6.9-28.4 6.9-5.9 0-14.7-6.6-24.3-6.4-12.5.2-24.2 7.3-30.5 18.6-13.1 22.6-3.4 56 9.3 74.4 6.2 9.1 13.7 19.1 23.5 18.7 9.3-.4 13-6 24.2-6 11.3 0 14.5 6 24.3 5.9 10.2-.2 16.5-9.1 22.8-18.2 6.9-10.4 9.8-20.4 10-21zm135.4-53.4c0-26.6-18.5-44.8-44.9-44.8h-51.2v136.4h21.2v-46.6h29.3c26.8 0 45.6-18.4 45.6-45zm90 23.7c0-19.7-15.8-32.4-40-32.4-22.5 0-39.1 12.9-39.7 30.5h19.1c1.6-8.4 9.4-13.9 20-13.9 13 0 20.2 6 20.2 17.2v7.5l-26.4 1.6c-24.6 1.5-37.9 11.6-37.9 29.1 0 17.7 13.7 29.4 33.4 29.4 13.3 0 25.6-6.7 31.2-17.4h.4V310h19.6v-68zM516 210.9h-21.5l-24.9 80.6h-.4l-24.9-80.6H422l35.9 99.3-1.9 6c-3.2 10.2-8.5 14.2-17.9 14.2-1.7 0-4.9-.2-6.2-.3v16.4c1.2.4 6.5.5 8.1.5 20.7 0 30.4-7.9 38.9-31.8L516 210.9z",
+		],
+	},
+};
+
+/** All supported payment-method keys. */
+export const PAYMENT_ICON_KEYS = Object.keys(
+	PAYMENT_ICONS,
+) as PaymentMethodIconKey[];
+
+const THEME_COLORS: Record<PaymentIconTheme, string> = {
+	light: "#1a1a1a",
+	dark: "#f5f5f5",
+};
+
+function resolveColor(options: PaymentIconOptions): string {
+	if (options.color) return options.color;
+	if (options.theme) return THEME_COLORS[options.theme];
+	return "currentColor";
+}
+
+function escapeAttr(value: string): string {
+	return value
+		.replace(/&/g, "&amp;")
+		.replace(/"/g, "&quot;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;");
+}
+
+/**
+ * Look up the raw icon data for a payment method. Returns `null` for unknown or
+ * custom methods so callers can fall back to a text-only label.
+ */
+export function paymentIconData(method: string): PaymentIconData | null {
+	if (!method) return null;
+	return PAYMENT_ICONS[method as PaymentMethodIconKey] ?? null;
+}
+
+/**
+ * Render a payment-method icon as an `<svg>` markup string, ready to inject in
+ * any framework. Returns `null` for unknown/custom methods (render text instead).
+ *
+ * @example
+ *   el.innerHTML = paymentIconSvg("visa") ?? "";              // currentColor
+ *   paymentIconSvg("applePay", { theme: "dark", size: 28 });  // forced light icon
+ *   paymentIconSvg("zelle", { color: "#6d1ed4" });            // brand color
+ */
+export function paymentIconSvg(
+	method: string,
+	options: PaymentIconOptions = {},
+): string | null {
+	const data = paymentIconData(method);
+	if (!data) return null;
+	const color = resolveColor(options);
+	const size =
+		options.size === undefined
+			? "1em"
+			: typeof options.size === "number"
+				? String(options.size)
+				: options.size;
+	const title = options.title === undefined ? data.label : options.title;
+	const a11y = title
+		? `role="img" aria-label="${escapeAttr(title)}"`
+		: 'aria-hidden="true" focusable="false"';
+	const body = data.paths.map((d) => `<path d="${d}"/>`).join("");
+	return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${data.viewBox}" width="${size}" height="${size}" fill="${color}" ${a11y}>${body}</svg>`;
+}

package/src/proxy.ts

@@ -0,0 +1,173 @@
+import {
+	BiabDevClient,
+	type BiabDevClientOptions,
+	BiabDevCustomerPortalClient,
+} from "./client.js";
+
+/**
+ * Browser-safe customer-portal client.
+ *
+ * The platform's Package API requires a bearer key — exposing it to a browser
+ * would let any visitor read all of the org's data. This client never sends
+ * the key directly; it calls a *same-origin* proxy route on your tenant
+ * server, and the proxy injects the key + customer-portal org pin server-side.
+ *
+ * Pattern (Next.js example) — your tenant ships:
+ *   - this client in browser bundles, configured with `proxyBaseUrl`
+ *     (e.g. `/api/biab/customer-portal`).
+ *   - a route at that path that calls {@link createCustomerPortalProxyHandler}
+ *     with your real BIAB API key + the BIAB org id this site is pinned to.
+ *
+ * The browser client only knows the proxy URL. The bearer key never leaves
+ * the tenant server.
+ */
+export type BrowserCustomerPortalClientOptions = {
+	/** Same-origin proxy path or absolute URL (e.g. "/api/biab/customer-portal"). */
+	proxyBaseUrl: string;
+	fetch?: typeof fetch;
+};
+
+class BrowserBiabDevClient extends BiabDevClient {
+	constructor(options: BrowserCustomerPortalClientOptions) {
+		// Pass a placeholder API key — the proxy ignores the Authorization
+		// header from the browser and substitutes its own.
+		const init: BiabDevClientOptions = {
+			baseUrl: options.proxyBaseUrl,
+			apiKey: "browser-proxy",
+		};
+		if (options.fetch) {
+			init.fetch = options.fetch;
+		}
+		super(init);
+	}
+}
+
+/**
+ * Browser-only client that talks to your tenant's same-origin proxy route.
+ * The proxy injects the BIAB API key and the `X-BIAB-Customer-Portal-Org`
+ * pin, so the browser never sees either secret.
+ */
+export function createBrowserCustomerPortalClient(
+	options: BrowserCustomerPortalClientOptions,
+) {
+	const inner = new BrowserBiabDevClient(options);
+	return new BiabDevCustomerPortalClient(inner, null);
+}
+
+/**
+ * Helper for the *server-side* proxy route a tenant ships. Returns a fetch
+ * handler that:
+ *   - rewrites incoming request paths to the BIAB host's customer-portal API
+ *   - injects the BIAB API key and `X-BIAB-Customer-Portal-Org` header
+ *   - forwards the response unchanged.
+ *
+ * @example // app/api/biab/customer-portal/[...path]/route.ts
+ * export const GET = createCustomerPortalProxyHandler({
+ *   biabBaseUrl: "https://biab.app/api/package/v1",
+ *   apiKey: process.env.BIAB_API_KEY!,
+ *   organizationId: process.env.BIAB_ORG_ID!,
+ * });
+ * export const POST = GET;
+ */
+export type CustomerPortalProxyOptions = {
+	biabBaseUrl: string;
+	apiKey: string;
+	/** The BIAB organization id (`org.id` from the portal context) this site is
+	 *  pinned to. Sent as the `X-BIAB-Customer-Portal-Org` header. */
+	organizationId?: string;
+	/**
+	 * @deprecated Use {@link organizationId} (the BIAB org id). Still accepted —
+	 * the platform resolves the pin header by BIAB id or the legacy provider id —
+	 * but new integrations should pass the BIAB org id and drop any
+	 * provider-specific env var.
+	 */
+	workosOrganizationId?: string;
+	fetch?: typeof fetch;
+	/**
+	 * Origin to send to the platform. Required when the API key has Allowed
+	 * Host configured on the host (server-to-server `fetch` does not send
+	 * `Origin`). Accepts a full URL or bare hostname.
+	 */
+	siteOrigin?: string;
+};
+
+function normalizeSiteOriginForProxy(
+	raw: string | undefined,
+): string | undefined {
+	if (!raw) return undefined;
+	const trimmed = raw.trim();
+	if (!trimmed) return undefined;
+	const withScheme = /^https?:\/\//i.test(trimmed)
+		? trimmed
+		: `https://${trimmed}`;
+	try {
+		const url = new URL(withScheme);
+		return `${url.protocol}//${url.host}`;
+	} catch {
+		return undefined;
+	}
+}
+
+export function createCustomerPortalProxyHandler(
+	options: CustomerPortalProxyOptions,
+) {
+	const fetchImpl = options.fetch ?? fetch;
+	const base = options.biabBaseUrl.endsWith("/")
+		? options.biabBaseUrl
+		: `${options.biabBaseUrl}/`;
+	const siteOrigin = normalizeSiteOriginForProxy(options.siteOrigin);
+	// Prefer the BIAB org id; fall back to the deprecated provider-id alias so
+	// existing integrations keep working until they migrate.
+	const orgPin = options.organizationId ?? options.workosOrganizationId;
+	if (!orgPin) {
+		throw new Error(
+			"createCustomerPortalProxyHandler: `organizationId` is required.",
+		);
+	}
+
+	return async (request: Request) => {
+		const reqUrl = new URL(request.url);
+		// Strip the tenant-side mount prefix and forward everything to the
+		// platform's `/customer-portal/...` namespace. The browser client
+		// always calls `<proxy>/<verb>` (e.g. `<proxy>/context`) so we just
+		// preserve the trailing path.
+		const tenantMount = reqUrl.pathname.split("/").pop() ?? "";
+		const upstreamPath = `customer-portal/${tenantMount}${reqUrl.search}`;
+		const upstream = new URL(upstreamPath, base);
+
+		const upstreamHeaders = new Headers();
+		upstreamHeaders.set("Authorization", `Bearer ${options.apiKey}`);
+		upstreamHeaders.set("X-BIAB-Customer-Portal-Org", orgPin);
+		upstreamHeaders.set("Accept", "application/json");
+		if (siteOrigin) {
+			upstreamHeaders.set("Origin", siteOrigin);
+		} else {
+			const incomingOrigin = request.headers.get("origin");
+			if (incomingOrigin && incomingOrigin !== "null") {
+				upstreamHeaders.set("Origin", incomingOrigin);
+			}
+		}
+		const incomingContentType = request.headers.get("content-type");
+		if (incomingContentType) {
+			upstreamHeaders.set("Content-Type", incomingContentType);
+		}
+
+		const init: RequestInit = {
+			method: request.method,
+			headers: upstreamHeaders,
+		};
+		if (request.method !== "GET" && request.method !== "HEAD") {
+			init.body = await request.text();
+		}
+
+		const upstreamRes = await fetchImpl(upstream, init);
+		const body = await upstreamRes.text();
+		return new Response(body, {
+			status: upstreamRes.status,
+			headers: {
+				"content-type":
+					upstreamRes.headers.get("content-type") ?? "application/json",
+			},
+		});
+	};
+}