@businessdash/sdk 0.9.60 → 0.9.80

package/src/store-core/index.ts

@@ -0,0 +1,426 @@
+/**
+ * `@businessdash/sdk/store` — the headless storefront + cart controller.
+ *
+ * ## Why this exists
+ *
+ * Until now the only storefront the SDK offered was `<Storefront>`: a
+ * BusinessDash-hosted page in a sandboxed iframe. It works, and it ships fast,
+ * but it renders OUR markup inside YOUR app — your design system stops at the
+ * iframe boundary, and there is no way to put a product card in your own grid.
+ * That was true in every binding, React included.
+ *
+ * This is the native path. It owns all of the behaviour — pagination, category
+ * filtering, the cart, coupons, the product detail — and none of the markup.
+ * Exactly the split `createFormController` already uses for forms: one
+ * framework-agnostic controller, and a thin reactive view per framework.
+ *
+ * A binding subscribes to `snapshot()` and renders it. That is the whole
+ * contract, and it is why React, Solid, Vue, Svelte, Qwik, Angular and plain
+ * DOM can each expose a native storefront without any of them reimplementing
+ * what "add to cart" means.
+ *
+ * ## Money
+ *
+ * Every price crossing this boundary is an INTEGER of the currency's minor unit
+ * — cents for USD. The controller never divides, rounds or formats: it passes
+ * what the API sent straight to your renderer. Format at the edge, where you
+ * know the locale.
+ *
+ * @module
+ */
+
+import type {
+	CartAddItemInput,
+	CartSnapshot,
+	StorefrontCategory,
+	StorefrontProductDetail,
+	StorefrontProductRow,
+} from "../contracts.js";
+
+/**
+ * The client surface this controller needs. Declared structurally rather than
+ * importing `BiabDevClient`, so a consumer can hand in a same-origin proxy, a
+ * test double, or a narrowed client without the controller caring.
+ */
+export type StoreCoreClient = {
+	storefront: {
+		listProducts(input?: {
+			limit?: number;
+			cursor?: number | null;
+			categoryId?: string;
+		}): Promise<{ items: StorefrontProductRow[]; nextCursor: number | null }>;
+		listCategories(): Promise<{ items: StorefrontCategory[] }>;
+		getProduct(productId: string): Promise<StorefrontProductDetail>;
+	};
+	cart: {
+		get(): Promise<CartSnapshot>;
+		addItem(input: CartAddItemInput): Promise<CartSnapshot>;
+		updateItem(
+			itemId: string,
+			input: { quantity: number },
+		): Promise<CartSnapshot>;
+		removeItem(itemId: string): Promise<CartSnapshot>;
+		applyCoupon(input: { code: string }): Promise<CartSnapshot>;
+		removeCoupon(): Promise<CartSnapshot>;
+		clear(): Promise<CartSnapshot>;
+	};
+};
+
+export type StoreStatus = "idle" | "loading" | "ready" | "error";
+
+/**
+ * What a binding renders. Field names are STABLE and load-bearing for every
+ * framework binding — renaming one is a breaking change in eight places.
+ */
+export type StoreSnapshot = {
+	status: StoreStatus;
+	/** The current page of products, accumulated across `loadMore()`. */
+	products: readonly StorefrontProductRow[];
+	categories: readonly StorefrontCategory[];
+	/** `null` until the first cart read resolves. */
+	cart: CartSnapshot | null;
+	/** The product opened via `openProduct()`, if any. */
+	activeProduct: StorefrontProductDetail | null;
+	/** Active category filter, or `null` for everything. */
+	categoryId: string | null;
+	/** Whether `loadMore()` would fetch anything. */
+	hasMore: boolean;
+	/** Last failure. Cleared on the next successful action. */
+	error: Error | null;
+	/**
+	 * In-flight work, so a binding can disable a button without inventing its
+	 * own loading state. `cart` covers every mutation — add, update, remove,
+	 * coupon, clear — because they all serialise onto the same cart.
+	 */
+	pending: {
+		products: boolean;
+		categories: boolean;
+		product: boolean;
+		cart: boolean;
+	};
+	/** Convenience mirrors of `cart`, so a badge doesn't need a null check. */
+	itemCount: number;
+	subtotal: number;
+	currency: string | null;
+};
+
+export type StoreController = {
+	snapshot(): StoreSnapshot;
+	/**
+	 * Subscribe to snapshot changes. Returns an unsubscribe function. The
+	 * callback is NOT invoked on subscribe — read `snapshot()` for the initial
+	 * value, the same contract `createFormController` uses.
+	 */
+	subscribe(callback: (snapshot: StoreSnapshot) => void): () => void;
+	/** Fetch products, categories and the cart. Safe to call more than once. */
+	load(): Promise<void>;
+	/** Append the next page. No-op when `hasMore` is false or a page is in flight. */
+	loadMore(): Promise<void>;
+	/** Filter by category (or `null` for all) and reset pagination. */
+	filterByCategory(categoryId: string | null): Promise<void>;
+	/** Load one product's detail into `activeProduct`. */
+	openProduct(productId: string): Promise<void>;
+	closeProduct(): void;
+	addToCart(input: CartAddItemInput): Promise<void>;
+	/** Quantity 0 removes the line, matching the API's own semantics. */
+	updateQuantity(itemId: string, quantity: number): Promise<void>;
+	removeItem(itemId: string): Promise<void>;
+	applyCoupon(code: string): Promise<void>;
+	removeCoupon(): Promise<void>;
+	clearCart(): Promise<void>;
+	/** Re-read the cart without touching products. */
+	refreshCart(): Promise<void>;
+	/** Stop notifying and drop all subscribers. */
+	destroy(): void;
+};
+
+export type CreateStoreControllerOptions = {
+	client: StoreCoreClient;
+	/** Products per page. Default 24. */
+	pageSize?: number;
+	/** Start filtered to a category. */
+	categoryId?: string | null;
+	/** Called on every failure, in addition to landing in `snapshot().error`. */
+	onError?: (error: Error) => void;
+};
+
+const DEFAULT_PAGE_SIZE = 24;
+
+function toError(cause: unknown, fallback: string): Error {
+	return cause instanceof Error ? cause : new Error(fallback);
+}
+
+export function createStoreController(
+	options: CreateStoreControllerOptions,
+): StoreController {
+	const { client, onError } = options;
+	const pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE;
+
+	let destroyed = false;
+	let cursor: number | null = null;
+	/**
+	 * Guards against a stale page landing after the category changed. Every
+	 * product fetch captures the token it started under and drops its result if
+	 * the token moved on — otherwise clicking two categories quickly can leave
+	 * the second one's products under the first one's heading.
+	 */
+	let requestToken = 0;
+
+	const subscribers = new Set<(s: StoreSnapshot) => void>();
+
+	const state: {
+		status: StoreStatus;
+		products: StorefrontProductRow[];
+		categories: StorefrontCategory[];
+		cart: CartSnapshot | null;
+		activeProduct: StorefrontProductDetail | null;
+		categoryId: string | null;
+		hasMore: boolean;
+		error: Error | null;
+		pending: StoreSnapshot["pending"];
+	} = {
+		status: "idle",
+		products: [],
+		categories: [],
+		cart: null,
+		activeProduct: null,
+		categoryId: options.categoryId ?? null,
+		hasMore: false,
+		error: null,
+		pending: {
+			products: false,
+			categories: false,
+			product: false,
+			cart: false,
+		},
+	};
+
+	let cached: StoreSnapshot | null = null;
+
+	function snapshot(): StoreSnapshot {
+		if (!cached) {
+			cached = {
+				status: state.status,
+				products: state.products,
+				categories: state.categories,
+				cart: state.cart,
+				activeProduct: state.activeProduct,
+				categoryId: state.categoryId,
+				hasMore: state.hasMore,
+				error: state.error,
+				pending: state.pending,
+				itemCount: state.cart?.itemCount ?? 0,
+				subtotal: state.cart?.subtotal ?? 0,
+				currency: state.cart?.currency ?? null,
+			};
+		}
+		return cached;
+	}
+
+	function notify(): void {
+		if (destroyed) return;
+		cached = null;
+		const next = snapshot();
+		for (const cb of subscribers) cb(next);
+	}
+
+	function fail(cause: unknown, fallback: string): void {
+		const error = toError(cause, fallback);
+		state.error = error;
+		if (state.status !== "ready") state.status = "error";
+		onError?.(error);
+	}
+
+	/** Run a cart mutation, keeping `pending.cart` honest even on failure. */
+	async function cartAction(
+		run: () => Promise<CartSnapshot>,
+		fallback: string,
+	): Promise<void> {
+		if (destroyed) return;
+		state.pending.cart = true;
+		state.error = null;
+		notify();
+		try {
+			const cart = await run();
+			if (destroyed) return;
+			state.cart = cart;
+		} catch (cause) {
+			if (destroyed) return;
+			fail(cause, fallback);
+		} finally {
+			if (!destroyed) {
+				state.pending.cart = false;
+				notify();
+			}
+		}
+	}
+
+	async function fetchProducts(append: boolean): Promise<void> {
+		const token = ++requestToken;
+		state.pending.products = true;
+		if (!append) state.error = null;
+		notify();
+		try {
+			const page = await client.storefront.listProducts({
+				limit: pageSize,
+				...(append && cursor !== null ? { cursor } : {}),
+				...(state.categoryId ? { categoryId: state.categoryId } : {}),
+			});
+			// A newer request superseded this one — its result is now wrong.
+			if (destroyed || token !== requestToken) return;
+			state.products = append ? [...state.products, ...page.items] : page.items;
+			cursor = page.nextCursor;
+			state.hasMore = page.nextCursor !== null;
+			state.status = "ready";
+		} catch (cause) {
+			if (destroyed || token !== requestToken) return;
+			fail(cause, "Failed to load products.");
+		} finally {
+			if (!destroyed && token === requestToken) {
+				state.pending.products = false;
+				notify();
+			}
+		}
+	}
+
+	return {
+		snapshot,
+
+		subscribe(callback) {
+			subscribers.add(callback);
+			return () => {
+				subscribers.delete(callback);
+			};
+		},
+
+		async load() {
+			if (destroyed) return;
+			if (state.status === "idle") state.status = "loading";
+			state.pending.categories = true;
+			notify();
+
+			// Categories and the cart are independent of the product page, so all
+			// three go out together rather than waterfalling.
+			const categories = client.storefront
+				.listCategories()
+				.then((res) => {
+					if (destroyed) return;
+					state.categories = res.items;
+				})
+				.catch((cause) => {
+					if (!destroyed) fail(cause, "Failed to load categories.");
+				})
+				.finally(() => {
+					if (!destroyed) state.pending.categories = false;
+				});
+
+			const cart = client.cart
+				.get()
+				.then((res) => {
+					if (destroyed) return;
+					state.cart = res;
+				})
+				.catch((cause) => {
+					// A visitor with no cart yet is normal, not an error worth
+					// surfacing — leave `cart` null and let the products render.
+					void cause;
+				});
+
+			await Promise.all([fetchProducts(false), categories, cart]);
+			if (!destroyed) notify();
+		},
+
+		async loadMore() {
+			if (destroyed || !state.hasMore || state.pending.products) return;
+			await fetchProducts(true);
+		},
+
+		async filterByCategory(categoryId) {
+			if (destroyed) return;
+			state.categoryId = categoryId;
+			cursor = null;
+			await fetchProducts(false);
+		},
+
+		async openProduct(productId) {
+			if (destroyed) return;
+			state.pending.product = true;
+			state.error = null;
+			notify();
+			try {
+				const detail = await client.storefront.getProduct(productId);
+				if (destroyed) return;
+				state.activeProduct = detail;
+			} catch (cause) {
+				if (!destroyed) fail(cause, "Failed to load the product.");
+			} finally {
+				if (!destroyed) {
+					state.pending.product = false;
+					notify();
+				}
+			}
+		},
+
+		closeProduct() {
+			if (destroyed) return;
+			state.activeProduct = null;
+			notify();
+		},
+
+		addToCart(input) {
+			return cartAction(
+				() => client.cart.addItem(input),
+				"Failed to add the item to the cart.",
+			);
+		},
+
+		updateQuantity(itemId, quantity) {
+			// The API treats 0 as a removal; going through `removeItem` keeps that
+			// explicit rather than relying on every binding knowing the convention.
+			if (quantity <= 0) {
+				return cartAction(
+					() => client.cart.removeItem(itemId),
+					"Failed to remove the item.",
+				);
+			}
+			return cartAction(
+				() => client.cart.updateItem(itemId, { quantity }),
+				"Failed to update the quantity.",
+			);
+		},
+
+		removeItem(itemId) {
+			return cartAction(
+				() => client.cart.removeItem(itemId),
+				"Failed to remove the item.",
+			);
+		},
+
+		applyCoupon(code) {
+			return cartAction(
+				() => client.cart.applyCoupon({ code }),
+				"That coupon could not be applied.",
+			);
+		},
+
+		removeCoupon() {
+			return cartAction(
+				() => client.cart.removeCoupon(),
+				"Failed to remove the coupon.",
+			);
+		},
+
+		clearCart() {
+			return cartAction(() => client.cart.clear(), "Failed to clear the cart.");
+		},
+
+		refreshCart() {
+			return cartAction(() => client.cart.get(), "Failed to read the cart.");
+		},
+
+		destroy() {
+			destroyed = true;
+			subscribers.clear();
+		},
+	};
+}

package/src/store.ts

@@ -0,0 +1,12 @@
+/**
+ * `@businessdash/sdk/store` — the framework-agnostic storefront + cart core.
+ *
+ * Bindings shipped as SOURCE (Vue / Svelte / Solid / Qwik / Angular) import
+ * through this public subpath rather than a relative path, so the consumer's
+ * bundler resolves it exactly as their own code would. `forms` works the same
+ * way.
+ *
+ * @module
+ */
+
+export * from "./store-core/index.js";

package/src/svelte/SocialLinks.svelte

@@ -0,0 +1,84 @@
+<!--
+  The company's social profiles as icon links.
+
+  Every decision that could drift between frameworks — which platforms exist,
+  how a handle becomes a URL, where the brand icon comes from — lives in
+  `social-core`. This file is only the markup, which is the one part that
+  genuinely cannot be shared.
+-->
+<script lang="ts">
+	import {
+		resolveSocialLinks,
+		SOCIAL_FALLBACK_GLYPH,
+		SOCIAL_LIST_STYLE_STRING,
+	} from "../social-core/index.js";
+
+	type Props = {
+		/** The company profile's `socials` record. */
+		socials: unknown;
+		/** Icon colour — hex without `#`, or a CSS keyword. */
+		color?: string;
+		/** Icon edge length in px. */
+		size?: number;
+		linkClass?: string;
+		iconClass?: string;
+	};
+
+	let {
+		socials,
+		color = undefined,
+		size = 20,
+		linkClass = undefined,
+		iconClass = undefined,
+	}: Props = $props();
+
+	const rows = $derived(resolveSocialLinks(socials, { color }));
+</script>
+
+<!-- Nothing at all rather than an empty <ul> in a footer. -->
+{#if rows.length}
+	<ul style={SOCIAL_LIST_STYLE_STRING}>
+		{#each rows as row (row.key)}
+			<li>
+				<a
+					href={row.url}
+					target="_blank"
+					rel="noopener noreferrer"
+					title={row.label}
+					aria-label={row.label}
+					class={linkClass}
+				>
+					{#if row.iconUrl}
+						<img
+							src={row.iconUrl}
+							alt={row.label}
+							width={size}
+							height={size}
+							loading="lazy"
+							class={iconClass}
+						/>
+					{:else}
+						<svg
+							viewBox={SOCIAL_FALLBACK_GLYPH.viewBox}
+							width={size}
+							height={size}
+							fill="none"
+							stroke="currentColor"
+							stroke-width={SOCIAL_FALLBACK_GLYPH.strokeWidth}
+							aria-hidden="true"
+							class={iconClass}
+						>
+							<title>{row.label}</title>
+							<circle
+								cx={SOCIAL_FALLBACK_GLYPH.circle.cx}
+								cy={SOCIAL_FALLBACK_GLYPH.circle.cy}
+								r={SOCIAL_FALLBACK_GLYPH.circle.r}
+							/>
+							<path d={SOCIAL_FALLBACK_GLYPH.path} />
+						</svg>
+					{/if}
+				</a>
+			</li>
+		{/each}
+	</ul>
+{/if}