@businessdash/sdk 0.9.60 → 0.9.70

package/src/angular/headless.ts

@@ -0,0 +1,519 @@
+/**
+ * `@businessdash/sdk/angular` — headless storefront + chat.
+ *
+ * `<Storefront>` and `<Chatbot>` are hosted pages in a sandboxed iframe. These
+ * are the native path: all behaviour, no markup.
+ *
+ * Everything real lives in `store-core` / `chat-core`, shared with every other
+ * binding. This file bridges a controller's subscribe/snapshot observable into
+ * an Angular signal.
+ *
+ * @module
+ */
+
+import { Component, Input, type Signal, signal } from "@angular/core";
+
+import {
+	type BlogController,
+	type BlogSnapshot,
+	createBlogController,
+} from "../blog-core/index.js";
+import {
+	type ChatController,
+	type ChatSnapshot,
+	createChatController,
+} from "../chat-core/index.js";
+import { BiabDevClient } from "../client.js";
+import {
+	createPortalController,
+	type PortalSnapshot,
+} from "../portal-core/index.js";
+
+import {
+	createMarketingController,
+	type MarketingController,
+	type MarketingSnapshot,
+} from "../marketing-core/index.js";
+import {
+	createVerifyController,
+	type CreateVerifyControllerOptions,
+	type VerifyController,
+	type VerifySnapshot,
+} from "../verify-core/index.js";
+
+import {
+	createFollowersController,
+	createUserController,
+	type FollowersController,
+	type FollowersSnapshot,
+	type UserController,
+	type UserSnapshot,
+} from "../account-core/index.js";
+import {
+	type CheckoutController,
+	type CheckoutSnapshot,
+	createCheckoutController,
+} from "../checkout-core/index.js";
+import { createBiabClient } from "../sdk.js";
+
+import type {
+	BlogCommentPostInput,
+	CartAddItemInput,
+	ChatbotFormSubmitInput,
+	ChatbotRequestHumanInput,
+	CustomerPortalMessagePostInput,
+} from "../contracts.js";
+import {
+	createStoreController,
+	type StoreController,
+	type StoreSnapshot,
+} from "../store-core/index.js";
+
+type Observable<TSnapshot> = {
+	snapshot(): TSnapshot;
+	subscribe(cb: (s: TSnapshot) => void): () => void;
+	destroy(): void;
+};
+
+/**
+ * Bridge a controller into a signal, and hand back the teardown.
+ *
+ * Teardown is RETURNED rather than registered with `DestroyRef`, because these
+ * are plain functions — they can be called from a service, a route resolver or
+ * a test, not only from an injection context. Callers inside a component
+ * should pass it to `inject(DestroyRef).onDestroy(...)`; the `destroy()` on
+ * each handle below is that function.
+ */
+function bridge<TSnapshot>(
+	// Structural, not a second generic — see the note in the Vue binding:
+	// TypeScript cannot infer `TSnapshot` from a constraint alone, so it would
+	// resolve to `unknown` and strip the snapshot's type from every caller.
+	controller: Observable<TSnapshot>,
+	start?: () => void,
+): { state: Signal<TSnapshot>; dispose: () => void } {
+	// Seeded from `snapshot()` because the cores do not replay on subscribe.
+	const state = signal<TSnapshot>(controller.snapshot());
+	const unsubscribe = controller.subscribe((next) => state.set(next));
+	start?.();
+	return {
+		state: state.asReadonly(),
+		dispose: () => {
+			unsubscribe();
+			controller.destroy();
+		},
+	};
+}
+
+export type CreateStorefrontOptions = {
+	apiKey: string;
+	baseUrl: string;
+	pageSize?: number;
+	categoryId?: string | null;
+};
+
+export type StorefrontHandle = {
+	state: Signal<StoreSnapshot>;
+	/** Unsubscribe and destroy. Wire to `DestroyRef.onDestroy` in a component. */
+	destroy: () => void;
+} & Omit<StoreController, "snapshot" | "subscribe" | "destroy" | "load">;
+
+/**
+ * Headless storefront + cart.
+ *
+ * ```ts
+ * export class ShopComponent {
+ *   private store = createStorefront({ apiKey, baseUrl });
+ *   products = computed(() => this.store.state().products);
+ *   constructor() { inject(DestroyRef).onDestroy(this.store.destroy); }
+ * }
+ * ```
+ */
+export function createStorefront(
+	options: CreateStorefrontOptions,
+): StorefrontHandle {
+	const controller = createStoreController({
+		client: new BiabDevClient({
+			apiKey: options.apiKey,
+			baseUrl: options.baseUrl,
+		}),
+		...(options.pageSize ? { pageSize: options.pageSize } : {}),
+		...(options.categoryId ? { categoryId: options.categoryId } : {}),
+	});
+
+	const { state, dispose } = bridge(controller, () => void controller.load());
+
+	return {
+		state,
+		destroy: dispose,
+		loadMore: () => controller.loadMore(),
+		filterByCategory: (id: string | null) => controller.filterByCategory(id),
+		openProduct: (id: string) => controller.openProduct(id),
+		closeProduct: () => controller.closeProduct(),
+		addToCart: (input: CartAddItemInput) => controller.addToCart(input),
+		updateQuantity: (itemId: string, quantity: number) =>
+			controller.updateQuantity(itemId, quantity),
+		removeItem: (itemId: string) => controller.removeItem(itemId),
+		applyCoupon: (code: string) => controller.applyCoupon(code),
+		removeCoupon: () => controller.removeCoupon(),
+		clearCart: () => controller.clearCart(),
+		refreshCart: () => controller.refreshCart(),
+	};
+}
+
+export type CreateChatOptions = { apiKey: string; baseUrl: string };
+
+export type ChatHandle = {
+	state: Signal<ChatSnapshot>;
+	destroy: () => void;
+} & Omit<ChatController, "snapshot" | "subscribe" | "destroy">;
+
+/** Headless Front Desk chat — the native alternative to `<Chatbot>`. */
+export function createChat(options: CreateChatOptions): ChatHandle {
+	const controller = createChatController({
+		client: new BiabDevClient({
+			apiKey: options.apiKey,
+			baseUrl: options.baseUrl,
+		}),
+	});
+
+	const { state, dispose } = bridge(controller);
+
+	return {
+		state,
+		destroy: dispose,
+		send: (content: string) => controller.send(content),
+		reset: () => controller.reset(),
+		loadConfig: () => controller.loadConfig(),
+		refreshAvailability: () => controller.refreshAvailability(),
+		getForm: (slug: string) => controller.getForm(slug),
+		submitForm: (slug: string, input: ChatbotFormSubmitInput) =>
+			controller.submitForm(slug, input),
+		requestHuman: (input: ChatbotRequestHumanInput) =>
+			controller.requestHuman(input),
+	};
+}
+
+export type CreateBlogOptions = {
+	apiKey: string;
+	baseUrl: string;
+	pageSize?: number;
+	categoryId?: string | null;
+};
+
+export type BlogHandle = {
+	state: Signal<BlogSnapshot>;
+	destroy: () => void;
+} & Omit<BlogController, "snapshot" | "subscribe" | "destroy" | "load">;
+
+/** Headless blog — the native alternative to `<Blog>`. */
+export function createBlog(options: CreateBlogOptions): BlogHandle {
+	const controller = createBlogController({
+		client: new BiabDevClient({
+			apiKey: options.apiKey,
+			baseUrl: options.baseUrl,
+		}),
+		...(options.pageSize ? { pageSize: options.pageSize } : {}),
+		...(options.categoryId ? { categoryId: options.categoryId } : {}),
+	});
+
+	const { state, dispose } = bridge(controller, () => void controller.load());
+
+	return {
+		state,
+		destroy: dispose,
+		loadMore: () => controller.loadMore(),
+		filterByCategory: (id: string | null) => controller.filterByCategory(id),
+		openPost: (slug: string) => controller.openPost(slug),
+		closePost: () => controller.closePost(),
+		loadComments: () => controller.loadComments(),
+		loadMoreComments: () => controller.loadMoreComments(),
+		postComment: (input: BlogCommentPostInput) =>
+			controller.postComment(input),
+		toggleLike: () => controller.toggleLike(),
+	};
+}
+
+export type CreateCheckoutOptions = { apiKey: string; baseUrl: string };
+export type CheckoutHandle = {
+	state: Signal<CheckoutSnapshot>;
+	destroy: () => void;
+} & Omit<CheckoutController, "snapshot" | "subscribe" | "destroy">;
+
+/** Headless checkout. `start()` mints a session; `redirect()` navigates. */
+export function createCheckout(
+	options: CreateCheckoutOptions,
+): CheckoutHandle {
+	const controller = createCheckoutController({
+		client: new BiabDevClient({
+			apiKey: options.apiKey,
+			baseUrl: options.baseUrl,
+		}),
+	});
+	const { state, dispose } = bridge(controller);
+	return {
+		state,
+		destroy: dispose,
+		start: (input) => controller.start(input),
+		redirect: () => controller.redirect(),
+		resolve: (sessionId: string) => controller.resolve(sessionId),
+		reset: () => controller.reset(),
+	};
+}
+
+export type UserHandle = {
+	state: Signal<UserSnapshot>;
+	destroy: () => void;
+	refresh: () => Promise<UserSnapshot>;
+};
+
+/** The signed-in customer, from the auth handler's `/me`. */
+export function createUser(options: { basePath?: string } = {}): UserHandle {
+	const controller = createUserController(options);
+	const { state, dispose } = bridge(controller, () => controller.start());
+	return { state, destroy: dispose, refresh: () => controller.refresh() };
+}
+
+export type CreateFollowersOptions = {
+	token: string;
+	siteId: string;
+	baseUrl?: string;
+};
+export type FollowersHandle = {
+	state: Signal<FollowersSnapshot>;
+	destroy: () => void;
+} & Omit<FollowersController, "snapshot" | "subscribe" | "destroy">;
+
+/** Newsletter / follower subscribe with the local already-subscribed hint. */
+export function createFollowers(
+	options: CreateFollowersOptions,
+): FollowersHandle {
+	const controller = createFollowersController({
+		client: createBiabClient({
+			apiKey: options.token,
+			siteId: options.siteId,
+			...(options.baseUrl ? { baseUrl: options.baseUrl } : {}),
+		}),
+		siteId: options.siteId,
+	});
+	const { state, dispose } = bridge(controller);
+	return {
+		state,
+		destroy: dispose,
+		join: (input) => controller.join(input),
+		leave: (email: string) => controller.leave(email),
+		me: (email: string) => controller.me(email),
+		edit: (email: string, patch: { name?: string; source?: string }) =>
+			controller.edit(email, patch),
+	};
+}
+
+export {
+	signIn,
+	signInHref,
+	signOut,
+	signOutHref,
+	signUp,
+	signUpHref,
+} from "../account-core/index.js";
+
+export type CreateMarketingOptions = {
+	token: string;
+	siteId: string;
+	baseUrl?: string;
+};
+
+/** Headless marketing pages — the index, plus one page at a time. */
+export function createMarketing(options: CreateMarketingOptions) {
+	const controller = createMarketingController({
+		client: createBiabClient({
+			apiKey: options.token,
+			siteId: options.siteId,
+			...(options.baseUrl ? { baseUrl: options.baseUrl } : {}),
+		}),
+	});
+	const { state, dispose } = bridge(controller, () => void controller.load());
+	return {
+		state,
+		destroy: dispose,
+		open: (pageKey?: string, opts?: { skipCache?: boolean }) =>
+			controller.open(pageKey, opts),
+		prefetch: (pageKey?: string) => controller.prefetch(pageKey),
+		close: () => controller.close(),
+	};
+}
+
+export type CreateVerifyOptions = {
+	apiKey: string;
+	baseUrl: string;
+} & Omit<CreateVerifyControllerOptions, "client">;
+
+/** Headless email / phone verification. Read `state().flow` before rendering. */
+export function createVerify(options: CreateVerifyOptions) {
+	const { apiKey, baseUrl, ...rest } = options;
+	const controller = createVerifyController({
+		client: new BiabDevClient({ apiKey, baseUrl }),
+		...rest,
+	});
+	const { state, dispose } = bridge(controller);
+	return {
+		state,
+		destroy: dispose,
+		start: (destination: string) => controller.start(destination),
+		resend: () => controller.resend(),
+		confirm: (token: string) => controller.confirm(token),
+		canResend: (now?: number) => controller.canResend(now),
+		reset: () => controller.reset(),
+	};
+}
+
+export type CreatePortalOptions = {
+	apiKey: string;
+	baseUrl: string;
+	sessionToken: string;
+};
+
+/**
+ * The signed-in customer's portal — work, quotes, contracts, invoices, orders,
+ * downloads, shipping, reviews, referrals, profile and notification settings.
+ *
+ * `sessionToken` is required: every portal route is scoped to the signed-in
+ * customer, and without one the portal renders empty rather than signed-out.
+ *
+ * Note two things the API itself imposes. There are no list endpoints for
+ * invoices, quotes, contracts or shipments — `state.work` carries the counts
+ * and you open each by id. And a submitted review is queued for staff approval,
+ * so it will not appear in `state.reviews`; watch `reviewAwaitingModeration`.
+ */
+export function createPortal(options: CreatePortalOptions) {
+	const controller = createPortalController({
+		client: new BiabDevClient({
+			apiKey: options.apiKey,
+			baseUrl: options.baseUrl,
+		}),
+		sessionToken: options.sessionToken,
+	});
+	const { state, dispose } = bridge(controller, () => void controller.load());
+	return {
+		state: state as Signal<PortalSnapshot>,
+		destroy: dispose,
+		load: () => controller.load(),
+		loadOrders: (opts?: { limit?: number }) => controller.loadOrders(opts),
+		loadInvoices: (opts?: {
+			limit?: number;
+			status?: string;
+			unpaid?: boolean;
+		}) => controller.loadInvoices(opts),
+		loadQuotes: (opts?: { limit?: number; status?: string }) =>
+			controller.loadQuotes(opts),
+		loadContracts: (opts?: { limit?: number; status?: string }) =>
+			controller.loadContracts(opts),
+		loadShipments: (opts?: { limit?: number; active?: boolean }) =>
+			controller.loadShipments(opts),
+		loadMessages: (opts?: { limit?: number; jobId?: string }) =>
+			controller.loadMessages(opts),
+		postMessage: (input: CustomerPortalMessagePostInput) =>
+			controller.postMessage(input),
+		markMessagesRead: () => controller.markMessagesRead(),
+		loadPayments: (opts?: { limit?: number }) => controller.loadPayments(opts),
+		loadReviews: () => controller.loadReviews(),
+		loadReferrals: () => controller.loadReferrals(),
+		loadNotificationPreferences: () => controller.loadNotificationPreferences(),
+		loadOtherOrgs: () => controller.loadOtherOrgs(),
+		openJob: (id: string) => controller.openJob(id),
+		openOrder: (id: string) => controller.openOrder(id),
+		openInvoice: (id: string) => controller.openInvoice(id),
+		openQuote: (id: string) => controller.openQuote(id),
+		openContract: (id: string) => controller.openContract(id),
+		trackShipment: (id: string) => controller.trackShipment(id),
+		closeDetail: () => controller.closeDetail(),
+		postJobComment: controller.postJobComment,
+		acceptQuote: (id: string) => controller.acceptQuote(id),
+		rejectQuote: (id: string) => controller.rejectQuote(id),
+		signContract: (id: string) => controller.signContract(id),
+		payInvoice: controller.payInvoice,
+		updateProfile: controller.updateProfile,
+		updateNotificationPreferences: controller.updateNotificationPreferences,
+		submitReview: controller.submitReview,
+		submitReturnRequest: controller.submitReturnRequest,
+		contactCompany: controller.contactCompany,
+	};
+}
+
+import {
+	resolveSocialLinks,
+	SOCIAL_FALLBACK_GLYPH,
+	SOCIAL_LIST_STYLE_STRING,
+	type SocialLinkRow,
+} from "../social-core/index.js";
+
+/**
+ * The company's social profiles as icon links.
+ *
+ * Standalone with an inline template so it needs no NgModule and no separate
+ * `.html`, which keeps it inside this package's typecheck.
+ */
+@Component({
+	selector: "biab-social-links",
+	standalone: true,
+	template: `
+		<ul *ngIf="rows.length" [attr.style]="listStyle">
+			<li *ngFor="let row of rows">
+				<a
+					[href]="row.url"
+					target="_blank"
+					rel="noopener noreferrer"
+					[title]="row.label"
+					[attr.aria-label]="row.label"
+					[class]="linkClass"
+				>
+					<img
+						*ngIf="row.iconUrl"
+						[src]="row.iconUrl"
+						[alt]="row.label"
+						[width]="size"
+						[height]="size"
+						loading="lazy"
+						[class]="iconClass"
+					/>
+					<svg
+						*ngIf="!row.iconUrl"
+						[attr.viewBox]="glyph.viewBox"
+						[attr.width]="size"
+						[attr.height]="size"
+						fill="none"
+						stroke="currentColor"
+						[attr.stroke-width]="glyph.strokeWidth"
+						aria-hidden="true"
+						[class]="iconClass"
+					>
+						<title>{{ row.label }}</title>
+						<circle
+							[attr.cx]="glyph.circle.cx"
+							[attr.cy]="glyph.circle.cy"
+							[attr.r]="glyph.circle.r"
+						/>
+						<path [attr.d]="glyph.path" />
+					</svg>
+				</a>
+			</li>
+		</ul>
+	`,
+})
+export class BiabSocialLinksComponent {
+	/** The company profile's `socials` record. */
+	@Input() set socials(value: unknown) {
+		this.rows = resolveSocialLinks(value, { color: this.color });
+	}
+	/** Icon colour — hex without `#`, or a CSS keyword. */
+	@Input() color?: string;
+	/** Icon edge length in px. */
+	@Input() size = 20;
+	@Input() linkClass?: string;
+	@Input() iconClass?: string;
+
+	rows: SocialLinkRow[] = [];
+	readonly listStyle = SOCIAL_LIST_STYLE_STRING;
+	readonly glyph = SOCIAL_FALLBACK_GLYPH;
+}
+
+export { resolveSocialLinks } from "../social-core/index.js";

package/src/angular/index.ts

@@ -24,3 +24,6 @@ export {
 // Re-export the headless core (controller + validation + SDK form types) so a
 // consumer reaches the full forms surface from the single `/angular` entry.
 export * from "../forms-core/index.js";
+
+// Headless storefront + chat — the native (non-iframe) surfaces.
+export * from "./headless.js";

package/src/auth-links.ts

@@ -0,0 +1,76 @@
+/**
+ * URL construction for the tenant auth handler, shared by every binding.
+ *
+ * The handler (`createAuthHandler`) is the one server-side piece a consumer
+ * mounts; the sign-in / sign-up / sign-out surfaces in each framework are just
+ * links into it. Framework-free so a second binding doesn't fork the
+ * query-parameter contract.
+ *
+ * @module
+ */
+
+/** Where `createAuthHandler` is mounted unless the consumer says otherwise. */
+export const DEFAULT_AUTH_BASE_PATH = "/api/biab-auth";
+
+export type AuthHrefOptions = {
+	/** Where to send the user after auth completes. */
+	returnTo?: string | undefined;
+	/** Pre-fill the email field on the platform-hosted page. */
+	loginHint?: string | undefined;
+	/** Override the basePath the auth handler is mounted at. */
+	basePath?: string | undefined;
+};
+
+/** Build the href for one of the auth handler's routes. */
+export function buildAuthHref(
+	subroute: "sign-in" | "sign-up" | "sign-out",
+	options: AuthHrefOptions,
+): string {
+	const base = (options.basePath ?? DEFAULT_AUTH_BASE_PATH).replace(/\/$/, "");
+	const params = new URLSearchParams();
+	if (options.returnTo) params.set("returnTo", options.returnTo);
+	if (options.loginHint) params.set("loginHint", options.loginHint);
+	const qs = params.toString();
+	return `${base}/${subroute}${qs ? `?${qs}` : ""}`;
+}
+
+/** Local-storage bookkeeping for the "this browser already subscribed" hint. */
+export type LocalFollow = { email: string; at: number };
+
+export const FOLLOWER_STORE_PREFIX = "biab.followers.";
+
+export function followerStoreKey(siteId: string): string {
+	return `${FOLLOWER_STORE_PREFIX}${siteId}`;
+}
+
+export function readLocalFollow(key: string): LocalFollow | null {
+	if (typeof window === "undefined") return null;
+	try {
+		const raw = window.localStorage.getItem(key);
+		if (!raw) return null;
+		const parsed = JSON.parse(raw) as Partial<LocalFollow>;
+		return typeof parsed?.email === "string"
+			? { email: parsed.email, at: Number(parsed.at) || 0 }
+			: null;
+	} catch {
+		return null;
+	}
+}
+
+export function writeLocalFollow(key: string, value: LocalFollow): void {
+	if (typeof window === "undefined") return;
+	try {
+		window.localStorage.setItem(key, JSON.stringify(value));
+	} catch {
+		// storage disabled / quota — the local hint is best-effort.
+	}
+}
+
+export function clearLocalFollow(key: string): void {
+	if (typeof window === "undefined") return;
+	try {
+		window.localStorage.removeItem(key);
+	} catch {
+		// ignore
+	}
+}