@businessdash/sdk 0.9.60 → 0.9.80

package/src/vanilla.ts

@@ -1288,3 +1288,370 @@ function observeReveal(node: HTMLElement): void {
 	);
 	obs.observe(node);
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Native storefront + chat, framework-free
+//
+// There is no reactivity system here to bridge into, so the controllers ARE the
+// binding: subscribe, render, call the actions. That is also why these are the
+// reference implementations — every framework binding is a wrapper around
+// exactly these objects.
+//
+//   const store = createStorefront({ apiKey, baseUrl });
+//   store.subscribe((s) => render(s.products));
+//   await store.load();
+//
+// Remember to `destroy()` when the surface goes away.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import {
+	type ChatController,
+	createChatController,
+} from "./chat-core/index.js";
+import { BiabDevClient as BiabDevClientForSurfaces } from "./client.js";
+import {
+	createStoreController,
+	type StoreController,
+} from "./store-core/index.js";
+
+export type CreateStorefrontOptions = {
+	apiKey: string;
+	baseUrl: string;
+	pageSize?: number;
+	categoryId?: string | null;
+	onError?: (error: Error) => void;
+};
+
+/** Headless storefront + cart. Call `load()` to populate it. */
+export function createStorefront(
+	options: CreateStorefrontOptions,
+): StoreController {
+	return createStoreController({
+		client: new BiabDevClientForSurfaces({
+			apiKey: options.apiKey,
+			baseUrl: options.baseUrl,
+		}),
+		...(options.pageSize ? { pageSize: options.pageSize } : {}),
+		...(options.categoryId ? { categoryId: options.categoryId } : {}),
+		...(options.onError ? { onError: options.onError } : {}),
+	});
+}
+
+export type CreateChatOptions = {
+	apiKey: string;
+	baseUrl: string;
+	onError?: (error: Error) => void;
+};
+
+/** Headless Front Desk chat — the native alternative to the iframe widget. */
+export function createChat(options: CreateChatOptions): ChatController {
+	return createChatController({
+		client: new BiabDevClientForSurfaces({
+			apiKey: options.apiKey,
+			baseUrl: options.baseUrl,
+		}),
+		...(options.onError ? { onError: options.onError } : {}),
+	});
+}
+
+export type { ChatController, ChatSnapshot } from "./chat-core/index.js";
+export type {
+	StoreController,
+	StoreSnapshot,
+} from "./store-core/index.js";
+
+import {
+	type BlogController,
+	createBlogController,
+} from "./blog-core/index.js";
+
+export type CreateBlogOptions = {
+	apiKey: string;
+	baseUrl: string;
+	pageSize?: number;
+	commentPageSize?: number;
+	categoryId?: string | null;
+	onError?: (error: Error) => void;
+};
+
+/** Headless blog — posts, taxonomy, a single post, comments and likes. */
+export function createBlog(options: CreateBlogOptions): BlogController {
+	return createBlogController({
+		client: new BiabDevClientForSurfaces({
+			apiKey: options.apiKey,
+			baseUrl: options.baseUrl,
+		}),
+		...(options.pageSize ? { pageSize: options.pageSize } : {}),
+		...(options.commentPageSize
+			? { commentPageSize: options.commentPageSize }
+			: {}),
+		...(options.categoryId ? { categoryId: options.categoryId } : {}),
+		...(options.onError ? { onError: options.onError } : {}),
+	});
+}
+
+export type { BlogController, BlogSnapshot } from "./blog-core/index.js";
+
+import {
+	createFollowersController,
+	createUserController,
+	type FollowersController,
+	type UserController,
+} from "./account-core/index.js";
+import {
+	type CheckoutController,
+	createCheckoutController,
+} from "./checkout-core/index.js";
+import { createBiabClient as createBiabClientForFollowers } from "./sdk.js";
+
+/** Headless checkout — mint a Stripe session, then `redirect()` or render it. */
+export function createCheckout(options: {
+	apiKey: string;
+	baseUrl: string;
+	onError?: (error: Error) => void;
+}): CheckoutController {
+	return createCheckoutController({
+		client: new BiabDevClientForSurfaces({
+			apiKey: options.apiKey,
+			baseUrl: options.baseUrl,
+		}),
+		...(options.onError ? { onError: options.onError } : {}),
+	});
+}
+
+/** The signed-in customer, read from the auth handler's `/me`. */
+export function createUser(
+	options: { basePath?: string } = {},
+): UserController {
+	return createUserController(options);
+}
+
+/** Newsletter / follower subscribe, bound to a publishable token. */
+export function createFollowers(options: {
+	token: string;
+	siteId: string;
+	baseUrl?: string;
+	onError?: (error: Error) => void;
+}): FollowersController {
+	// Followers hang off the PUBLISHABLE client (`createBiabClient`), not
+	// `BiabDevClient`: they are the one surface a browser calls directly with an
+	// origin-locked `pk_…` token and no backend.
+	return createFollowersController({
+		client: createBiabClientForFollowers({
+			apiKey: options.token,
+			siteId: options.siteId,
+			baseUrl: options.baseUrl ?? DEFAULT_PACKAGE_BASE_URL_FOR_SURFACES,
+		}),
+		siteId: options.siteId,
+		...(options.onError ? { onError: options.onError } : {}),
+	});
+}
+
+export type {
+	FollowersController,
+	FollowersSnapshot,
+	UserController,
+	UserSnapshot,
+} from "./account-core/index.js";
+export {
+	signIn,
+	signInHref,
+	signOut,
+	signOutHref,
+	signUp,
+	signUpHref,
+} from "./account-core/index.js";
+export type {
+	CheckoutController,
+	CheckoutSnapshot,
+} from "./checkout-core/index.js";
+
+/** Production package-API base, used when a surface doesn't specify one. */
+const DEFAULT_PACKAGE_BASE_URL_FOR_SURFACES =
+	"https://businessdash.us/api/package/v1";
+
+import {
+	createMarketingController,
+	type MarketingController,
+} from "./marketing-core/index.js";
+import {
+	type CreateVerifyControllerOptions,
+	createVerifyController,
+	type VerifyController,
+} from "./verify-core/index.js";
+
+/**
+ * Headless marketing pages — the index, plus one page at a time.
+ *
+ * Bound to the PUBLISHABLE client, like followers: marketing pages are a
+ * browser-readable surface keyed by site, so they need a `siteId` and work with
+ * an origin-locked `pk_…` token.
+ */
+export function createMarketing(options: {
+	token: string;
+	siteId: string;
+	baseUrl?: string;
+	onError?: (error: Error) => void;
+}): MarketingController {
+	return createMarketingController({
+		client: createBiabClientForFollowers({
+			apiKey: options.token,
+			siteId: options.siteId,
+			baseUrl: options.baseUrl ?? DEFAULT_PACKAGE_BASE_URL_FOR_SURFACES,
+		}),
+		...(options.onError ? { onError: options.onError } : {}),
+	});
+}
+
+/** Headless email / phone verification. Read `flow` before rendering a field. */
+export function createVerify(
+	options: {
+		apiKey: string;
+		baseUrl: string;
+	} & Omit<CreateVerifyControllerOptions, "client">,
+): VerifyController {
+	const { apiKey, baseUrl, ...rest } = options;
+	return createVerifyController({
+		client: new BiabDevClientForSurfaces({ apiKey, baseUrl }),
+		...rest,
+	});
+}
+
+export type {
+	MarketingController,
+	MarketingSnapshot,
+} from "./marketing-core/index.js";
+export type {
+	VerifyController,
+	VerifyFlow,
+	VerifySnapshot,
+} from "./verify-core/index.js";
+
+import {
+	createPortalController,
+	type PortalController,
+} from "./portal-core/index.js";
+
+/**
+ * The signed-in customer's portal. `sessionToken` is required — every portal
+ * route is scoped to the customer, and without one it renders empty rather than
+ * signed-out.
+ */
+export function createPortal(options: {
+	apiKey: string;
+	baseUrl: string;
+	sessionToken: string;
+	onError?: (error: Error) => void;
+}): PortalController {
+	return createPortalController({
+		client: new BiabDevClientForSurfaces({
+			apiKey: options.apiKey,
+			baseUrl: options.baseUrl,
+		}),
+		sessionToken: options.sessionToken,
+		...(options.onError ? { onError: options.onError } : {}),
+	});
+}
+
+export type { PortalController, PortalSnapshot } from "./portal-core/index.js";
+
+import {
+	resolveSocialLinks,
+	SOCIAL_FALLBACK_GLYPH,
+	SOCIAL_LIST_STYLE,
+	type SocialLinkRow,
+} from "./social-core/index.js";
+
+export type MountSocialLinksOptions = {
+	socials: unknown;
+	/** Icon colour — hex without `#`, or a CSS keyword. */
+	color?: string;
+	/** Icon edge length in px. Default 20. */
+	size?: number;
+	class?: string;
+	linkClass?: string;
+	iconClass?: string;
+};
+
+/**
+ * Render a company's social links into `target`, replacing its contents.
+ *
+ * Returns a `destroy()` that empties the element again, so a single-page app
+ * can tear it down. Renders nothing at all when there are no profiles — an
+ * empty `<ul>` in a footer is worse than no list.
+ */
+export function mountSocialLinks(
+	target: Element,
+	options: MountSocialLinksOptions,
+): { destroy: () => void } {
+	const size = options.size ?? 20;
+	const rows = resolveSocialLinks(options.socials, { color: options.color });
+	target.replaceChildren();
+	if (rows.length === 0) return { destroy: () => target.replaceChildren() };
+
+	const ul = document.createElement("ul");
+	if (options.class) ul.className = options.class;
+	for (const [prop, value] of Object.entries(SOCIAL_LIST_STYLE)) {
+		ul.style.setProperty(prop, value);
+	}
+
+	for (const row of rows) {
+		const li = document.createElement("li");
+		const a = document.createElement("a");
+		a.href = row.url;
+		a.target = "_blank";
+		a.rel = "noopener noreferrer";
+		a.title = row.label;
+		a.setAttribute("aria-label", row.label);
+		if (options.linkClass) a.className = options.linkClass;
+		a.append(socialGlyph(row, size, options.iconClass));
+		li.append(a);
+		ul.append(li);
+	}
+	target.append(ul);
+
+	return { destroy: () => target.replaceChildren() };
+}
+
+/** Brand icon when the platform has one, generic globe when it doesn't. */
+function socialGlyph(
+	row: SocialLinkRow,
+	size: number,
+	iconClass?: string,
+): Element {
+	if (row.iconUrl) {
+		const img = document.createElement("img");
+		img.src = row.iconUrl;
+		img.alt = row.label;
+		img.width = size;
+		img.height = size;
+		img.loading = "lazy";
+		if (iconClass) img.className = iconClass;
+		return img;
+	}
+
+	const ns = "http://www.w3.org/2000/svg";
+	const svg = document.createElementNS(ns, "svg");
+	svg.setAttribute("viewBox", SOCIAL_FALLBACK_GLYPH.viewBox);
+	svg.setAttribute("width", String(size));
+	svg.setAttribute("height", String(size));
+	svg.setAttribute("fill", "none");
+	svg.setAttribute("stroke", "currentColor");
+	svg.setAttribute("stroke-width", String(SOCIAL_FALLBACK_GLYPH.strokeWidth));
+	svg.setAttribute("aria-hidden", "true");
+	if (iconClass) svg.setAttribute("class", iconClass);
+
+	const title = document.createElementNS(ns, "title");
+	title.textContent = row.label;
+	const circle = document.createElementNS(ns, "circle");
+	circle.setAttribute("cx", String(SOCIAL_FALLBACK_GLYPH.circle.cx));
+	circle.setAttribute("cy", String(SOCIAL_FALLBACK_GLYPH.circle.cy));
+	circle.setAttribute("r", String(SOCIAL_FALLBACK_GLYPH.circle.r));
+	const path = document.createElementNS(ns, "path");
+	path.setAttribute("d", SOCIAL_FALLBACK_GLYPH.path);
+	svg.append(title, circle, path);
+	return svg;
+}
+
+export type { SocialLinkRow } from "./social-core/index.js";
+export { resolveSocialLinks } from "./social-core/index.js";

package/src/verify-core/index.ts

@@ -0,0 +1,288 @@
+/**
+ * `@businessdash/sdk/verify` — the headless email / phone verification flow.
+ *
+ * Both flows were React-only, as ~500 lines of multi-step component. The state
+ * machine underneath is small and identical for email and phone: ask for a
+ * token, wait, confirm it, handle it being wrong.
+ *
+ * Note `flow` on the snapshot. The server decides per request whether to send a
+ * one-time code or an emailed link, so a binding must read it rather than
+ * assume a code field is always wanted.
+ *
+ * This is that machine. The markup stays yours, which matters more here than
+ * elsewhere — a verification step sits inside a signup or a checkout, and an
+ * SDK-shaped panel in the middle of your own flow is jarring.
+ *
+ * ## Resend cooldown
+ *
+ * `resendAvailableAt` is a timestamp, not a ticking counter. A controller that
+ * ran its own interval would keep a timer alive for every mounted form and
+ * still be wrong after a tab sleeps. The binding renders the remaining seconds
+ * from the timestamp however its framework prefers, and `canResend()` answers
+ * the only question that actually gates the button.
+ *
+ * @module
+ */
+
+import type {
+	ConfirmVerificationInput,
+	ConfirmVerificationResponse,
+	StartVerificationInput,
+	StartVerificationResponse,
+} from "../contracts.js";
+
+export type VerifyCoreClient = {
+	notifications: {
+		startVerification(
+			input: StartVerificationInput,
+		): Promise<StartVerificationResponse>;
+		confirmVerification(
+			input: ConfirmVerificationInput,
+		): Promise<ConfirmVerificationResponse>;
+	};
+};
+
+/**
+ * How the platform chose to verify this destination.
+ *
+ * `otp` means a code the visitor types. `link` means an email they click, and
+ * there is NO code field to render — the page just waits. The server decides
+ * per request, so a binding must read `flow` rather than assume, or half its
+ * users stare at a box waiting for a code that is never coming.
+ */
+export type VerifyFlow = "link" | "otp";
+
+export type VerifyStep =
+	/** Nothing requested yet — show the address/number field. */
+	| "collecting"
+	/** A code has been sent — show the code field. */
+	| "awaiting-code"
+	/** Confirmed. */
+	| "verified";
+
+/** Field names are STABLE and load-bearing for every framework binding. */
+export type VerifySnapshot = {
+	step: VerifyStep;
+	/** The address or number a code was sent to. */
+	destination: string | null;
+	isPending: boolean;
+	/** The last failure — typically a wrong or expired code. */
+	error: Error | null;
+	/**
+	 * Epoch ms when a resend becomes allowed, or `null` when none is pending.
+	 * Render the countdown yourself; see the note above.
+	 */
+	resendAvailableAt: number | null;
+	/** `otp` (type a code) or `link` (click an email). `null` before starting. */
+	flow: VerifyFlow | null;
+	/** The server's own wording for what it just sent. Worth showing verbatim. */
+	message: string | null;
+	/** How many codes have been sent this session. */
+	attempts: number;
+};
+
+export type VerifyController = {
+	snapshot(): VerifySnapshot;
+	subscribe(callback: (snapshot: VerifySnapshot) => void): () => void;
+	/** Send a code to an address or number. Moves to `awaiting-code`. */
+	start(destination: string): Promise<boolean>;
+	/** Send another code. No-ops while the cooldown is active. */
+	resend(): Promise<boolean>;
+	/**
+	 * Submit the token from the code field or the emailed link. Moves to
+	 * `verified` on success; stays on `awaiting-code` when it is rejected.
+	 */
+	confirm(token: string): Promise<boolean>;
+	/** True when a resend is allowed right now. */
+	canResend(now?: number): boolean;
+	/** Back to `collecting`, e.g. the visitor mistyped their address. */
+	reset(): void;
+	destroy(): void;
+};
+
+export type CreateVerifyControllerOptions = {
+	client: VerifyCoreClient;
+	/** `email` or `phone` — passed straight through to the API. */
+	kind: StartVerificationInput["kind"];
+	/** Seconds before a resend is allowed. Default 30. */
+	resendCooldownSeconds?: number;
+	onError?: (error: Error) => void;
+	/** Called once the code is accepted. */
+	onVerified?: (destination: string) => void;
+};
+
+const DEFAULT_COOLDOWN_SECONDS = 30;
+
+function toError(cause: unknown, fallback: string): Error {
+	return cause instanceof Error ? cause : new Error(fallback);
+}
+
+export function createVerifyController(
+	options: CreateVerifyControllerOptions,
+): VerifyController {
+	const { client, kind, onError, onVerified } = options;
+	const cooldownMs =
+		(options.resendCooldownSeconds ?? DEFAULT_COOLDOWN_SECONDS) * 1000;
+
+	let destroyed = false;
+	const subscribers = new Set<(s: VerifySnapshot) => void>();
+
+	const state: {
+		step: VerifyStep;
+		destination: string | null;
+		isPending: boolean;
+		error: Error | null;
+		resendAvailableAt: number | null;
+		attempts: number;
+		flow: VerifyFlow | null;
+		message: string | null;
+	} = {
+		step: "collecting",
+		destination: null,
+		isPending: false,
+		error: null,
+		resendAvailableAt: null,
+		attempts: 0,
+		flow: null,
+		message: null,
+	};
+
+	let cached: VerifySnapshot | null = null;
+
+	function snapshot(): VerifySnapshot {
+		if (!cached) {
+			cached = {
+				step: state.step,
+				destination: state.destination,
+				isPending: state.isPending,
+				error: state.error,
+				resendAvailableAt: state.resendAvailableAt,
+				attempts: state.attempts,
+				flow: state.flow,
+				message: state.message,
+			};
+		}
+		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;
+		onError?.(error);
+	}
+
+	function canResend(now = Date.now()): boolean {
+		if (state.step !== "awaiting-code" || state.isPending) return false;
+		return state.resendAvailableAt === null || now >= state.resendAvailableAt;
+	}
+
+	async function send(destination: string): Promise<boolean> {
+		state.isPending = true;
+		state.error = null;
+		notify();
+		try {
+			const res = await client.notifications.startVerification({
+				kind,
+				destination,
+			});
+			if (destroyed) return false;
+			state.flow = res.flow;
+			state.message = res.message;
+			state.destination = destination;
+			state.step = "awaiting-code";
+			state.attempts += 1;
+			state.resendAvailableAt = Date.now() + cooldownMs;
+			return true;
+		} catch (cause) {
+			if (destroyed) return false;
+			fail(cause, "Could not send the code.");
+			return false;
+		} finally {
+			if (!destroyed) {
+				state.isPending = false;
+				notify();
+			}
+		}
+	}
+
+	return {
+		snapshot,
+
+		subscribe(callback) {
+			subscribers.add(callback);
+			return () => {
+				subscribers.delete(callback);
+			};
+		},
+
+		start(destination) {
+			if (destroyed) return Promise.resolve(false);
+			return send(destination);
+		},
+
+		async resend() {
+			// Guarded here rather than left to the binding: otherwise every
+			// framework reimplements the cooldown, and the one that gets it wrong
+			// lets a visitor spam themselves with texts.
+			if (destroyed || !canResend() || !state.destination) return false;
+			return send(state.destination);
+		},
+
+		async confirm(token) {
+			if (destroyed || !state.destination) return false;
+			state.isPending = true;
+			state.error = null;
+			notify();
+			try {
+				const res = await client.notifications.confirmVerification({ token });
+				if (destroyed) return false;
+				state.step = "verified";
+				// The response carries the destination the server actually verified,
+				// which is the authoritative one — a visitor can start a flow, edit
+				// the field, and confirm a token minted for the earlier value.
+				state.destination = res.destination;
+				onVerified?.(res.destination);
+				return true;
+			} catch (cause) {
+				if (destroyed) return false;
+				// The endpoint answers `{ ok: true }` or rejects, so a rejection here
+				// is the ordinary wrong-or-expired-code path, not an outage. It is
+				// reported as an error to render, and the step stays `awaiting-code`
+				// so the visitor can try again.
+				fail(cause, "That code didn't work. It may have expired.");
+				return false;
+			} finally {
+				if (!destroyed) {
+					state.isPending = false;
+					notify();
+				}
+			}
+		},
+
+		canResend,
+
+		reset() {
+			if (destroyed) return;
+			state.step = "collecting";
+			state.destination = null;
+			state.error = null;
+			state.resendAvailableAt = null;
+			state.isPending = false;
+			state.flow = null;
+			state.message = null;
+			notify();
+		},
+
+		destroy() {
+			destroyed = true;
+			subscribers.clear();
+		},
+	};
+}

package/src/verify.ts

@@ -0,0 +1,8 @@
+/**
+ * `@businessdash/sdk/verify` — the framework-agnostic email / phone
+ * verification core.
+ *
+ * @module
+ */
+
+export * from "./verify-core/index.js";