@businessdash/sdk 0.9.60 → 0.9.80

package/src/vue/headless.ts

@@ -0,0 +1,527 @@
+/**
+ * `@businessdash/sdk/vue` — headless storefront + chat.
+ *
+ * `<Storefront>` and `<Chatbot>` are hosted pages in a sandboxed iframe: quick
+ * to adopt, but they render BusinessDash's markup rather than yours. These
+ * composables are the native path — all behaviour, no markup.
+ *
+ * Everything real lives in `store-core` / `chat-core`, shared with every other
+ * binding. This file only bridges a controller's subscribe/snapshot observable
+ * into a Vue ref, and ties teardown to the component's scope.
+ *
+ * @module
+ */
+
+import { defineComponent, h, onScopeDispose, type PropType, type Ref, shallowRef } from "vue";
+
+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;
+};
+
+/**
+ * Seed a ref from `snapshot()`, then subscribe.
+ *
+ * The seed is not optional: the cores deliberately do NOT replay on subscribe,
+ * so a ref that only listened would render empty until the first change.
+ *
+ * `shallowRef` rather than `ref` — the snapshot is replaced wholesale on every
+ * notification, so deep reactivity would walk the entire product list on each
+ * update to discover what the controller already told us.
+ */
+function bridge<TSnapshot>(
+	// Typed structurally rather than as a second generic: with
+	// `<TSnapshot, TController extends Observable<TSnapshot>>` only `TController`
+	// is inferable from the argument, so `TSnapshot` silently falls back to
+	// `unknown` and every consumer loses the snapshot's type.
+	controller: Observable<TSnapshot>,
+	start?: () => void,
+): Ref<TSnapshot> {
+	const state = shallowRef<TSnapshot>(controller.snapshot());
+	const unsubscribe = controller.subscribe((next) => {
+		state.value = next;
+	});
+	start?.();
+	onScopeDispose(() => {
+		unsubscribe();
+		controller.destroy();
+	});
+	return state;
+}
+
+export type UseStorefrontOptions = {
+	apiKey: string;
+	baseUrl: string;
+	pageSize?: number;
+	categoryId?: string | null;
+};
+
+export type UseStorefrontResult = {
+	state: Ref<StoreSnapshot>;
+} & Omit<StoreController, "snapshot" | "subscribe" | "destroy" | "load">;
+
+/**
+ * Headless storefront + cart.
+ *
+ * ```vue
+ * <script setup lang="ts">
+ * const { state, addToCart } = useStorefront({ apiKey, baseUrl })
+ * </script>
+ * <template>
+ *   <MyCard v-for="p in state.products" :key="p.id" :product="p" />
+ * </template>
+ * ```
+ */
+export function useStorefront(
+	options: UseStorefrontOptions,
+): UseStorefrontResult {
+	const controller = createStoreController({
+		client: new BiabDevClient({
+			apiKey: options.apiKey,
+			baseUrl: options.baseUrl,
+		}),
+		...(options.pageSize ? { pageSize: options.pageSize } : {}),
+		...(options.categoryId ? { categoryId: options.categoryId } : {}),
+	});
+
+	const state = bridge(controller, () => void controller.load());
+
+	return {
+		state,
+		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 UseChatOptions = { apiKey: string; baseUrl: string };
+
+export type UseChatResult = {
+	state: Ref<ChatSnapshot>;
+} & Omit<ChatController, "snapshot" | "subscribe" | "destroy">;
+
+/**
+ * Headless Front Desk chat — the native alternative to `<Chatbot>`.
+ *
+ * ```vue
+ * <script setup lang="ts">
+ * const { state, send } = useChat({ apiKey, baseUrl })
+ * </script>
+ * <template>
+ *   <Bubble v-for="(m, i) in state.messages" :key="i" :message="m" />
+ * </template>
+ * ```
+ */
+export function useChat(options: UseChatOptions): UseChatResult {
+	const controller = createChatController({
+		client: new BiabDevClient({
+			apiKey: options.apiKey,
+			baseUrl: options.baseUrl,
+		}),
+	});
+
+	const state = bridge(controller);
+
+	return {
+		state,
+		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 UseBlogOptions = {
+	apiKey: string;
+	baseUrl: string;
+	pageSize?: number;
+	categoryId?: string | null;
+};
+
+export type UseBlogResult = {
+	state: Ref<BlogSnapshot>;
+} & Omit<BlogController, "snapshot" | "subscribe" | "destroy" | "load">;
+
+/** Headless blog — the native alternative to `<Blog>`. */
+export function useBlog(options: UseBlogOptions): UseBlogResult {
+	const controller = createBlogController({
+		client: new BiabDevClient({
+			apiKey: options.apiKey,
+			baseUrl: options.baseUrl,
+		}),
+		...(options.pageSize ? { pageSize: options.pageSize } : {}),
+		...(options.categoryId ? { categoryId: options.categoryId } : {}),
+	});
+
+	const state = bridge(controller, () => void controller.load());
+
+	return {
+		state,
+		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 UseCheckoutOptions = { apiKey: string; baseUrl: string };
+export type UseCheckoutResult = {
+	state: Ref<CheckoutSnapshot>;
+} & Omit<CheckoutController, "snapshot" | "subscribe" | "destroy">;
+
+/** Headless checkout. `start()` mints a session; `redirect()` navigates. */
+export function useCheckout(options: UseCheckoutOptions): UseCheckoutResult {
+	const controller = createCheckoutController({
+		client: new BiabDevClient({
+			apiKey: options.apiKey,
+			baseUrl: options.baseUrl,
+		}),
+	});
+	const state = bridge(controller);
+	return {
+		state,
+		start: (input) => controller.start(input),
+		redirect: () => controller.redirect(),
+		resolve: (sessionId: string) => controller.resolve(sessionId),
+		reset: () => controller.reset(),
+	};
+}
+
+export type UseUserResult = {
+	state: Ref<UserSnapshot>;
+	refresh: () => Promise<UserSnapshot>;
+};
+
+/** The signed-in customer, from the auth handler's `/me`. */
+export function useUser(options: { basePath?: string } = {}): UseUserResult {
+	const controller = createUserController(options);
+	const state = bridge(controller, () => controller.start());
+	return { state, refresh: () => controller.refresh() };
+}
+
+export type UseFollowersOptions = {
+	token: string;
+	siteId: string;
+	baseUrl?: string;
+};
+export type UseFollowersResult = {
+	state: Ref<FollowersSnapshot>;
+} & Omit<FollowersController, "snapshot" | "subscribe" | "destroy">;
+
+/** Newsletter / follower subscribe with the local already-subscribed hint. */
+export function useFollowers(
+	options: UseFollowersOptions,
+): UseFollowersResult {
+	const controller = createFollowersController({
+		client: createBiabClient({
+			apiKey: options.token,
+			siteId: options.siteId,
+			...(options.baseUrl ? { baseUrl: options.baseUrl } : {}),
+		}),
+		siteId: options.siteId,
+	});
+	const state = bridge(controller);
+	return {
+		state,
+		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 UseMarketingOptions = {
+	token: string;
+	siteId: string;
+	baseUrl?: string;
+};
+
+/** Headless marketing pages — the index, plus one page at a time. */
+export function useMarketing(options: UseMarketingOptions) {
+	const controller = createMarketingController({
+		client: createBiabClient({
+			apiKey: options.token,
+			siteId: options.siteId,
+			...(options.baseUrl ? { baseUrl: options.baseUrl } : {}),
+		}),
+	});
+	const state = bridge(controller, () => void controller.load());
+	return {
+		state,
+		open: (pageKey?: string, opts?: { skipCache?: boolean }) =>
+			controller.open(pageKey, opts),
+		prefetch: (pageKey?: string) => controller.prefetch(pageKey),
+		close: () => controller.close(),
+	};
+}
+
+export type UseVerifyOptions = {
+	apiKey: string;
+	baseUrl: string;
+} & Omit<CreateVerifyControllerOptions, "client">;
+
+/**
+ * Headless email / phone verification.
+ *
+ * Read `state.flow` before rendering: `otp` wants a code field, `link` wants a
+ * "check your email" message and no field at all.
+ */
+export function useVerify(options: UseVerifyOptions) {
+	const { apiKey, baseUrl, ...rest } = options;
+	const controller = createVerifyController({
+		client: new BiabDevClient({ apiKey, baseUrl }),
+		...rest,
+	});
+	const state = bridge(controller);
+	return {
+		state,
+		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 UsePortalOptions = {
+	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 usePortal(options: UsePortalOptions) {
+	const controller = createPortalController({
+		client: new BiabDevClient({
+			apiKey: options.apiKey,
+			baseUrl: options.baseUrl,
+		}),
+		sessionToken: options.sessionToken,
+	});
+	const state: Ref<PortalSnapshot> = bridge(controller, () => void controller.load());
+	return {
+		state,
+		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,
+} from "../social-core/index.js";
+
+/**
+ * The company's social profiles as icon links.
+ *
+ * Written as a render function rather than an SFC on purpose: an SFC would put
+ * this binding back outside the typechecker, and the markup is six elements.
+ */
+export const SocialLinks = defineComponent({
+	name: "BiabSocialLinks",
+	props: {
+		/** The company profile's `socials` record. */
+		socials: { type: null as unknown as PropType<unknown>, required: true },
+		/** Icon colour — hex without `#`, or a CSS keyword. */
+		color: { type: String, default: undefined },
+		/** Icon edge length in px. */
+		size: { type: Number, default: 20 },
+		linkClass: { type: String, default: undefined },
+		iconClass: { type: String, default: undefined },
+	},
+	setup(props) {
+		return () => {
+			const rows = resolveSocialLinks(props.socials, { color: props.color });
+			// Nothing at all rather than an empty list — a bare <ul> in a footer
+			// is worse than no list.
+			if (rows.length === 0) return null;
+
+			return h(
+				"ul",
+				{ style: SOCIAL_LIST_STYLE },
+				rows.map((row) =>
+					h("li", { key: row.key }, [
+						h(
+							"a",
+							{
+								href: row.url,
+								target: "_blank",
+								rel: "noopener noreferrer",
+								title: row.label,
+								"aria-label": row.label,
+								class: props.linkClass,
+							},
+							[
+								row.iconUrl
+									? h("img", {
+											src: row.iconUrl,
+											alt: row.label,
+											width: props.size,
+											height: props.size,
+											loading: "lazy",
+											class: props.iconClass,
+										})
+									: h(
+											"svg",
+											{
+												viewBox: SOCIAL_FALLBACK_GLYPH.viewBox,
+												width: props.size,
+												height: props.size,
+												fill: "none",
+												stroke: "currentColor",
+												"stroke-width": SOCIAL_FALLBACK_GLYPH.strokeWidth,
+												"aria-hidden": "true",
+												class: props.iconClass,
+											},
+											[
+												h("title", null, row.label),
+												h("circle", SOCIAL_FALLBACK_GLYPH.circle),
+												h("path", { d: SOCIAL_FALLBACK_GLYPH.path }),
+											],
+										),
+							],
+						),
+					]),
+				),
+			);
+		};
+	},
+});
+
+export { resolveSocialLinks } from "../social-core/index.js";

package/src/vue/index.ts

@@ -117,3 +117,6 @@ export type {
 	MissingField,
 	ResolvedFormSettings,
 } from "@businessdash/sdk/forms";
+
+// Headless storefront + chat — the native (non-iframe) surfaces.
+export * from "./headless.js";