@businessdash/sdk 0.9.60 → 0.9.80

package/src/svelte/headless.ts

@@ -0,0 +1,435 @@
+/**
+ * `@businessdash/sdk/svelte` — 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
+ * a Svelte store.
+ *
+ * Stores rather than runes on purpose: runes are a compiler feature that only
+ * exists inside `.svelte` / `.svelte.ts` files, and these have to be callable
+ * from a plain `.ts` module too. `$store` auto-subscription in a component
+ * reads identically either way.
+ *
+ * @module
+ */
+
+import { type Readable, readable } from "svelte/store";
+
+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;
+};
+
+/**
+ * Wrap a controller as a readable store.
+ *
+ * `readable`'s start function runs on the FIRST subscriber and its return value
+ * runs when the LAST one goes away, which is exactly the controller's lifetime:
+ * a component that mounts, renders and unmounts destroys it, and one that never
+ * subscribes never opens a request.
+ *
+ * The initial value comes from `snapshot()` because the cores do not replay on
+ * subscribe.
+ */
+function toStore<TSnapshot>(
+	controller: Observable<TSnapshot>,
+	start?: () => void,
+): Readable<TSnapshot> {
+	return readable(controller.snapshot(), (set) => {
+		const unsubscribe = controller.subscribe(set);
+		start?.();
+		return () => {
+			unsubscribe();
+			controller.destroy();
+		};
+	});
+}
+
+export type CreateStorefrontOptions = {
+	apiKey: string;
+	baseUrl: string;
+	pageSize?: number;
+	categoryId?: string | null;
+};
+
+export type StorefrontHandle = {
+	state: Readable<StoreSnapshot>;
+} & Omit<StoreController, "snapshot" | "subscribe" | "destroy" | "load">;
+
+/**
+ * Headless storefront + cart.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   const { state, addToCart } = createStorefront({ apiKey, baseUrl });
+ * </script>
+ * {#each $state.products as product}
+ *   <MyCard {product} />
+ * {/each}
+ * ```
+ */
+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 } : {}),
+	});
+
+	return {
+		state: toStore(controller, () => void controller.load()),
+		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: Readable<ChatSnapshot>;
+} & Omit<ChatController, "snapshot" | "subscribe" | "destroy">;
+
+/**
+ * Headless Front Desk chat — the native alternative to `<Chatbot>`.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   const { state, send } = createChat({ apiKey, baseUrl });
+ * </script>
+ * {#each $state.messages as message}
+ *   <Bubble {message} />
+ * {/each}
+ * ```
+ */
+export function createChat(options: CreateChatOptions): ChatHandle {
+	const controller = createChatController({
+		client: new BiabDevClient({
+			apiKey: options.apiKey,
+			baseUrl: options.baseUrl,
+		}),
+	});
+
+	return {
+		state: toStore(controller),
+		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: Readable<BlogSnapshot>;
+} & 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 } : {}),
+	});
+
+	return {
+		state: toStore(controller, () => void controller.load()),
+		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 CreateCheckoutResult = {
+	state: Readable<CheckoutSnapshot>;
+} & Omit<CheckoutController, "snapshot" | "subscribe" | "destroy">;
+
+/** Headless checkout. `start()` mints a session; `redirect()` navigates. */
+export function createCheckout(options: CreateCheckoutOptions): CreateCheckoutResult {
+	const controller = createCheckoutController({
+		client: new BiabDevClient({
+			apiKey: options.apiKey,
+			baseUrl: options.baseUrl,
+		}),
+	});
+	const state = toStore(controller);
+	return {
+		state,
+		start: (input) => controller.start(input),
+		redirect: () => controller.redirect(),
+		resolve: (sessionId: string) => controller.resolve(sessionId),
+		reset: () => controller.reset(),
+	};
+}
+
+export type CreateUserResult = {
+	state: Readable<UserSnapshot>;
+	refresh: () => Promise<UserSnapshot>;
+};
+
+/** The signed-in customer, from the auth handler's `/me`. */
+export function createUser(options: { basePath?: string } = {}): CreateUserResult {
+	const controller = createUserController(options);
+	const state = toStore(controller, () => controller.start());
+	return { state, refresh: () => controller.refresh() };
+}
+
+export type CreateFollowersOptions = {
+	token: string;
+	siteId: string;
+	baseUrl?: string;
+};
+export type CreateFollowersResult = {
+	state: Readable<FollowersSnapshot>;
+} & Omit<FollowersController, "snapshot" | "subscribe" | "destroy">;
+
+/** Newsletter / follower subscribe with the local already-subscribed hint. */
+export function createFollowers(
+	options: CreateFollowersOptions,
+): CreateFollowersResult {
+	const controller = createFollowersController({
+		client: createBiabClient({
+			apiKey: options.token,
+			siteId: options.siteId,
+			...(options.baseUrl ? { baseUrl: options.baseUrl } : {}),
+		}),
+		siteId: options.siteId,
+	});
+	const state = toStore(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 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 = toStore(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 CreateVerifyOptions = {
+	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 createVerify(options: CreateVerifyOptions) {
+	const { apiKey, baseUrl, ...rest } = options;
+	const controller = createVerifyController({
+		client: new BiabDevClient({ apiKey, baseUrl }),
+		...rest,
+	});
+	const state = toStore(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 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: Readable<PortalSnapshot> = toStore(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,
+	};
+}

package/src/svelte/index.ts

@@ -77,3 +77,12 @@ export type {
 	FormsResource,
 } from "../forms-core/index.js";
 export type { BiabClient } from "../sdk.js";
+
+// Headless storefront + chat — the native (non-iframe) surfaces.
+export * from "./headless.js";
+
+// The social-links block. Markup lives in an SFC because Svelte has no
+// render-function escape hatch; everything that could drift is in `social-core`.
+export { default as SocialLinks } from "./SocialLinks.svelte";
+export { resolveSocialLinks } from "../social-core/index.js";
+export type { SocialLinkRow } from "../social-core/index.js";