@businessdash/sdk 0.9.60 → 0.9.80

package/src/qwik.tsx

@@ -269,13 +269,16 @@ const BiabFieldInput = component$<{
 			) : null;
 
 		case "textarea":
+			// `autocomplete` and `accept` below are SPREAD rather than passed as
+			// `attr={maybeUndefined}`. Under `exactOptionalPropertyTypes` an
+			// optional attribute must be absent, not present-and-undefined.
 			return (
 				<textarea
 					class="biab-input biab-textarea"
 					value={asString(value)}
 					placeholder={field.placeholder || ""}
 					rows={4}
-					autocomplete={autoComplete as AutoFill | undefined}
+					{...(autoComplete ? { autocomplete: autoComplete as AutoFill } : {})}
 					onInput$={(_, el) => void set((el as HTMLTextAreaElement).value)}
 				/>
 			);
@@ -656,7 +659,7 @@ const BiabFieldInput = component$<{
 						class="biab-file__input"
 						type="file"
 						multiple={maxFiles > 1}
-						accept={accept}
+						{...(accept ? { accept } : {})}
 						disabled={uploading || remaining === 0}
 						onChange$={async (_, el) => {
 							const picked = (el as HTMLInputElement).files;
@@ -1232,3 +1235,600 @@ export const BiabForm = component$<BiabFormProps>((props) => {
 });
 
 export default BiabForm;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Native storefront + chat
+//
+// The controllers are NOT serializable, so they can never live in a `useStore`
+// or cross Qwik's resumability boundary. They are created inside
+// `useVisibleTask$` — client-side, after hydration — and their snapshots are
+// copied into a serializable signal that the template reads. That is the same
+// shape `<BiabForm>` already uses for its controller.
+// ─────────────────────────────────────────────────────────────────────────────
+
+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 {
+	createPortalController,
+	type PortalController,
+	type PortalSnapshot,
+} from "./portal-core/index.js";
+import {
+	createMarketingController,
+	type MarketingController,
+	type MarketingSnapshot,
+} from "./marketing-core/index.js";
+import {
+	type CreateVerifyControllerOptions,
+	createVerifyController,
+	type VerifyController,
+	type VerifySnapshot,
+} from "./verify-core/index.js";
+import { createBiabClient as createBiabClientForFollowers } from "./sdk.js";
+import {
+	type BlogController,
+	type BlogSnapshot,
+	createBlogController,
+} from "./blog-core/index.js";
+import {
+	type ChatController,
+	type ChatSnapshot,
+	createChatController,
+} from "./chat-core/index.js";
+import { BiabDevClient as BiabDevClientForSurfaces } from "./client.js";
+import {
+	createStoreController,
+	type StoreController,
+	type StoreSnapshot,
+} from "./store-core/index.js";
+
+export type UseStorefrontOptions = {
+	apiKey: string;
+	baseUrl: string;
+	pageSize?: number;
+	categoryId?: string | null;
+};
+
+/**
+ * Headless storefront + cart.
+ *
+ * Returns a signal of the snapshot plus QRL-safe actions. Actions are plain
+ * functions closed over the client-side controller, so call them from an
+ * event handler (`onClick$`) rather than during render.
+ *
+ * ```tsx
+ * const store = useStorefront({ apiKey, baseUrl });
+ * return <>{store.state.value.products.map((p) => <MyCard product={p} />)}</>;
+ * ```
+ */
+export function useStorefront(options: UseStorefrontOptions) {
+	const state = useSignal<StoreSnapshot | null>(null);
+	// `noSerialize` is mandatory, not stylistic: a controller holds a client, a
+	// subscriber set and timers. Qwik would try to serialise it into the HTML on
+	// pause and throw. Marked this way it simply becomes `undefined` after a
+	// resume, which is correct — the visible task recreates it client-side.
+	const actions = useStore<{ current: NoSerialize<StoreController> | undefined }>(
+		{ current: undefined },
+		{ deep: false },
+	);
+
+	useVisibleTask$(({ cleanup }) => {
+		const controller = createStoreController({
+			client: new BiabDevClientForSurfaces({
+				apiKey: options.apiKey,
+				baseUrl: options.baseUrl,
+			}),
+			...(options.pageSize ? { pageSize: options.pageSize } : {}),
+			...(options.categoryId ? { categoryId: options.categoryId } : {}),
+		});
+		actions.current = noSerialize(controller);
+		state.value = controller.snapshot();
+		const unsubscribe = controller.subscribe((next) => {
+			state.value = next;
+		});
+		void controller.load();
+		cleanup(() => {
+			unsubscribe();
+			controller.destroy();
+			actions.current = undefined;
+		});
+	});
+
+	return {
+		state,
+		loadMore: () => actions.current?.loadMore(),
+		filterByCategory: (id: string | null) =>
+			actions.current?.filterByCategory(id),
+		openProduct: (id: string) => actions.current?.openProduct(id),
+		closeProduct: () => actions.current?.closeProduct(),
+		// biome-ignore lint/suspicious/noExplicitAny: input mirrors CartAddItemInput
+		addToCart: (input: any) => actions.current?.addToCart(input),
+		updateQuantity: (itemId: string, quantity: number) =>
+			actions.current?.updateQuantity(itemId, quantity),
+		removeItem: (itemId: string) => actions.current?.removeItem(itemId),
+		applyCoupon: (code: string) => actions.current?.applyCoupon(code),
+		removeCoupon: () => actions.current?.removeCoupon(),
+		clearCart: () => actions.current?.clearCart(),
+		refreshCart: () => actions.current?.refreshCart(),
+	};
+}
+
+export type UseChatOptions = { apiKey: string; baseUrl: string };
+
+/** Headless Front Desk chat — the native alternative to the iframe widget. */
+export function useChat(options: UseChatOptions) {
+	const state = useSignal<ChatSnapshot | null>(null);
+	const actions = useStore<{ current: NoSerialize<ChatController> | undefined }>(
+		{ current: undefined },
+		{ deep: false },
+	);
+
+	useVisibleTask$(({ cleanup }) => {
+		const controller = createChatController({
+			client: new BiabDevClientForSurfaces({
+				apiKey: options.apiKey,
+				baseUrl: options.baseUrl,
+			}),
+		});
+		actions.current = noSerialize(controller);
+		state.value = controller.snapshot();
+		const unsubscribe = controller.subscribe((next) => {
+			state.value = next;
+		});
+		cleanup(() => {
+			unsubscribe();
+			controller.destroy();
+			actions.current = undefined;
+		});
+	});
+
+	return {
+		state,
+		send: (content: string) => actions.current?.send(content),
+		reset: () => actions.current?.reset(),
+		loadConfig: () => actions.current?.loadConfig(),
+		refreshAvailability: () => actions.current?.refreshAvailability(),
+		getForm: (slug: string) => actions.current?.getForm(slug),
+		// biome-ignore lint/suspicious/noExplicitAny: input mirrors ChatbotFormSubmitInput
+		submitForm: (slug: string, input: any) =>
+			actions.current?.submitForm(slug, input),
+		// biome-ignore lint/suspicious/noExplicitAny: input mirrors ChatbotRequestHumanInput
+		requestHuman: (input: any) => actions.current?.requestHuman(input),
+	};
+}
+
+export type UseBlogOptions = {
+	apiKey: string;
+	baseUrl: string;
+	pageSize?: number;
+	categoryId?: string | null;
+};
+
+/** Headless blog — the native alternative to the hosted `<Blog>` iframe. */
+export function useBlog(options: UseBlogOptions) {
+	const state = useSignal<BlogSnapshot | null>(null);
+	const actions = useStore<{ current: NoSerialize<BlogController> | undefined }>(
+		{ current: undefined },
+		{ deep: false },
+	);
+
+	useVisibleTask$(({ cleanup }) => {
+		const controller = createBlogController({
+			client: new BiabDevClientForSurfaces({
+				apiKey: options.apiKey,
+				baseUrl: options.baseUrl,
+			}),
+			...(options.pageSize ? { pageSize: options.pageSize } : {}),
+			...(options.categoryId ? { categoryId: options.categoryId } : {}),
+		});
+		actions.current = noSerialize(controller);
+		state.value = controller.snapshot();
+		const unsubscribe = controller.subscribe((next) => {
+			state.value = next;
+		});
+		void controller.load();
+		cleanup(() => {
+			unsubscribe();
+			controller.destroy();
+			actions.current = undefined;
+		});
+	});
+
+	return {
+		state,
+		loadMore: () => actions.current?.loadMore(),
+		filterByCategory: (id: string | null) =>
+			actions.current?.filterByCategory(id),
+		openPost: (slug: string) => actions.current?.openPost(slug),
+		closePost: () => actions.current?.closePost(),
+		loadComments: () => actions.current?.loadComments(),
+		loadMoreComments: () => actions.current?.loadMoreComments(),
+		// biome-ignore lint/suspicious/noExplicitAny: input mirrors BlogCommentPostInput
+		postComment: (input: any) => actions.current?.postComment(input),
+		toggleLike: () => actions.current?.toggleLike(),
+	};
+}
+
+/** Headless checkout. `start()` mints a session; `redirect()` navigates. */
+export function useCheckout(options: { apiKey: string; baseUrl: string }) {
+	const state = useSignal<CheckoutSnapshot | null>(null);
+	const actions = useStore<{
+		current: NoSerialize<CheckoutController> | undefined;
+	}>({ current: undefined }, { deep: false });
+
+	useVisibleTask$(({ cleanup }) => {
+		const controller = createCheckoutController({
+			client: new BiabDevClientForSurfaces({
+				apiKey: options.apiKey,
+				baseUrl: options.baseUrl,
+			}),
+		});
+		actions.current = noSerialize(controller);
+		state.value = controller.snapshot();
+		const unsubscribe = controller.subscribe((next) => {
+			state.value = next;
+		});
+		cleanup(() => {
+			unsubscribe();
+			controller.destroy();
+			actions.current = undefined;
+		});
+	});
+
+	return {
+		state,
+		// biome-ignore lint/suspicious/noExplicitAny: input mirrors CheckoutSessionInput
+		start: (input: any) => actions.current?.start(input),
+		redirect: () => actions.current?.redirect(),
+		resolve: (sessionId: string) => actions.current?.resolve(sessionId),
+		reset: () => actions.current?.reset(),
+	};
+}
+
+/** The signed-in customer, from the auth handler's `/me`. */
+export function useUser(options: { basePath?: string } = {}) {
+	const state = useSignal<UserSnapshot | null>(null);
+	const actions = useStore<{ current: NoSerialize<UserController> | undefined }>(
+		{ current: undefined },
+		{ deep: false },
+	);
+
+	useVisibleTask$(({ cleanup }) => {
+		const controller = createUserController(options);
+		actions.current = noSerialize(controller);
+		state.value = controller.snapshot();
+		const unsubscribe = controller.subscribe((next) => {
+			state.value = next;
+		});
+		controller.start();
+		cleanup(() => {
+			unsubscribe();
+			controller.destroy();
+			actions.current = undefined;
+		});
+	});
+
+	return { state, refresh: () => actions.current?.refresh() };
+}
+
+/** Newsletter / follower subscribe with the local already-subscribed hint. */
+export function useFollowers(options: {
+	token: string;
+	siteId: string;
+	baseUrl?: string;
+}) {
+	const state = useSignal<FollowersSnapshot | null>(null);
+	const actions = useStore<{
+		current: NoSerialize<FollowersController> | undefined;
+	}>({ current: undefined }, { deep: false });
+
+	useVisibleTask$(({ cleanup }) => {
+		const controller = createFollowersController({
+			client: createBiabClientForFollowers({
+				apiKey: options.token,
+				siteId: options.siteId,
+				...(options.baseUrl ? { baseUrl: options.baseUrl } : {}),
+			}),
+			siteId: options.siteId,
+		});
+		actions.current = noSerialize(controller);
+		state.value = controller.snapshot();
+		const unsubscribe = controller.subscribe((next) => {
+			state.value = next;
+		});
+		cleanup(() => {
+			unsubscribe();
+			controller.destroy();
+			actions.current = undefined;
+		});
+	});
+
+	return {
+		state,
+		join: (input: { email: string; name?: string; source?: string }) =>
+			actions.current?.join(input),
+		leave: (email: string) => actions.current?.leave(email),
+		me: (email: string) => actions.current?.me(email),
+		edit: (email: string, patch: { name?: string; source?: string }) =>
+			actions.current?.edit(email, patch),
+	};
+}
+
+export {
+	signIn,
+	signInHref,
+	signOut,
+	signOutHref,
+	signUp,
+	signUpHref,
+} from "./account-core/index.js";
+
+/** Headless marketing pages — the index, plus one page at a time. */
+export function useMarketing(options: {
+	token: string;
+	siteId: string;
+	baseUrl?: string;
+}) {
+	const state = useSignal<MarketingSnapshot | null>(null);
+	const actions = useStore<{
+		current: NoSerialize<MarketingController> | undefined;
+	}>({ current: undefined }, { deep: false });
+
+	useVisibleTask$(({ cleanup }) => {
+		const controller = createMarketingController({
+			client: createBiabClientForFollowers({
+				apiKey: options.token,
+				siteId: options.siteId,
+				...(options.baseUrl ? { baseUrl: options.baseUrl } : {}),
+			}),
+		});
+		actions.current = noSerialize(controller);
+		state.value = controller.snapshot();
+		const unsubscribe = controller.subscribe((next) => {
+			state.value = next;
+		});
+		void controller.load();
+		cleanup(() => {
+			unsubscribe();
+			controller.destroy();
+			actions.current = undefined;
+		});
+	});
+
+	return {
+		state,
+		open: (pageKey?: string, opts?: { skipCache?: boolean }) =>
+			actions.current?.open(pageKey, opts),
+		prefetch: (pageKey?: string) => actions.current?.prefetch(pageKey),
+		close: () => actions.current?.close(),
+	};
+}
+
+/** Headless email / phone verification. Read `state.value.flow` before rendering. */
+export function useVerify(
+	options: { apiKey: string; baseUrl: string } & Omit<
+		CreateVerifyControllerOptions,
+		"client"
+	>,
+) {
+	const state = useSignal<VerifySnapshot | null>(null);
+	const actions = useStore<{
+		current: NoSerialize<VerifyController> | undefined;
+	}>({ current: undefined }, { deep: false });
+
+	useVisibleTask$(({ cleanup }) => {
+		const { apiKey, baseUrl, ...rest } = options;
+		const controller = createVerifyController({
+			client: new BiabDevClientForSurfaces({ apiKey, baseUrl }),
+			...rest,
+		});
+		actions.current = noSerialize(controller);
+		state.value = controller.snapshot();
+		const unsubscribe = controller.subscribe((next) => {
+			state.value = next;
+		});
+		cleanup(() => {
+			unsubscribe();
+			controller.destroy();
+			actions.current = undefined;
+		});
+	});
+
+	return {
+		state,
+		start: (destination: string) => actions.current?.start(destination),
+		resend: () => actions.current?.resend(),
+		confirm: (token: string) => actions.current?.confirm(token),
+		canResend: (now?: number) => actions.current?.canResend(now) ?? false,
+		reset: () => actions.current?.reset(),
+	};
+}
+
+/**
+ * The signed-in customer's portal. `sessionToken` is required — every portal
+ * route is scoped to the customer.
+ *
+ * There are no list endpoints for invoices, quotes, contracts or shipments:
+ * `state.value.work` carries the counts and you open each by id. A submitted
+ * review is queued for staff approval and will not appear in `reviews`.
+ */
+export function usePortal(options: {
+	apiKey: string;
+	baseUrl: string;
+	sessionToken: string;
+}) {
+	const state = useSignal<PortalSnapshot | null>(null);
+	const actions = useStore<{
+		current: NoSerialize<PortalController> | undefined;
+	}>({ current: undefined }, { deep: false });
+
+	useVisibleTask$(({ cleanup }) => {
+		const controller = createPortalController({
+			client: new BiabDevClientForSurfaces({
+				apiKey: options.apiKey,
+				baseUrl: options.baseUrl,
+			}),
+			sessionToken: options.sessionToken,
+		});
+		actions.current = noSerialize(controller);
+		state.value = controller.snapshot();
+		const unsubscribe = controller.subscribe((next) => {
+			state.value = next;
+		});
+		void controller.load();
+		cleanup(() => {
+			unsubscribe();
+			controller.destroy();
+			actions.current = undefined;
+		});
+	});
+
+	return {
+		state,
+		loadOrders: (opts?: { limit?: number }) =>
+			actions.current?.loadOrders(opts),
+		loadInvoices: (opts?: {
+			limit?: number;
+			status?: string;
+			unpaid?: boolean;
+		}) => actions.current?.loadInvoices(opts),
+		loadQuotes: (opts?: { limit?: number; status?: string }) =>
+			actions.current?.loadQuotes(opts),
+		loadContracts: (opts?: { limit?: number; status?: string }) =>
+			actions.current?.loadContracts(opts),
+		loadShipments: (opts?: { limit?: number; active?: boolean }) =>
+			actions.current?.loadShipments(opts),
+		loadMessages: (opts?: { limit?: number; jobId?: string }) =>
+			actions.current?.loadMessages(opts),
+		// biome-ignore lint/suspicious/noExplicitAny: input mirrors the contract
+		postMessage: (input: any) => actions.current?.postMessage(input),
+		markMessagesRead: () => actions.current?.markMessagesRead(),
+		loadPayments: (opts?: { limit?: number }) =>
+			actions.current?.loadPayments(opts),
+		loadReviews: () => actions.current?.loadReviews(),
+		loadReferrals: () => actions.current?.loadReferrals(),
+		loadNotificationPreferences: () =>
+			actions.current?.loadNotificationPreferences(),
+		loadOtherOrgs: () => actions.current?.loadOtherOrgs(),
+		openJob: (id: string) => actions.current?.openJob(id),
+		openOrder: (id: string) => actions.current?.openOrder(id),
+		openInvoice: (id: string) => actions.current?.openInvoice(id),
+		openQuote: (id: string) => actions.current?.openQuote(id),
+		openContract: (id: string) => actions.current?.openContract(id),
+		trackShipment: (id: string) => actions.current?.trackShipment(id),
+		closeDetail: () => actions.current?.closeDetail(),
+		// biome-ignore lint/suspicious/noExplicitAny: inputs mirror the contracts
+		postJobComment: (jobId: string, input: any) =>
+			actions.current?.postJobComment(jobId, input),
+		acceptQuote: (id: string) => actions.current?.acceptQuote(id),
+		rejectQuote: (id: string) => actions.current?.rejectQuote(id),
+		signContract: (id: string) => actions.current?.signContract(id),
+		// biome-ignore lint/suspicious/noExplicitAny: inputs mirror the contracts
+		payInvoice: (id: string, opts?: any) =>
+			actions.current?.payInvoice(id, opts),
+		// biome-ignore lint/suspicious/noExplicitAny: inputs mirror the contracts
+		updateProfile: (input: any) => actions.current?.updateProfile(input),
+		// biome-ignore lint/suspicious/noExplicitAny: inputs mirror the contracts
+		updateNotificationPreferences: (input: any) =>
+			actions.current?.updateNotificationPreferences(input),
+		// biome-ignore lint/suspicious/noExplicitAny: inputs mirror the contracts
+		submitReview: (input: any) => actions.current?.submitReview(input),
+		// biome-ignore lint/suspicious/noExplicitAny: inputs mirror the contracts
+		submitReturnRequest: (orderId: string, input?: any) =>
+			actions.current?.submitReturnRequest(orderId, input),
+		// biome-ignore lint/suspicious/noExplicitAny: inputs mirror the contracts
+		contactCompany: (input: any) => actions.current?.contactCompany(input),
+	};
+}
+
+import {
+	resolveSocialLinks,
+	SOCIAL_FALLBACK_GLYPH,
+	SOCIAL_LIST_STYLE,
+} from "./social-core/index.js";
+
+export type SocialLinksProps = {
+	/** 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;
+};
+
+/**
+ * The company's social profiles as icon links.
+ *
+ * Pure render from serializable props, so it needs no `useVisibleTask$` and
+ * survives resumption untouched — unlike the controller-backed surfaces above.
+ */
+export const SocialLinks = component$<SocialLinksProps>((props) => {
+	const size = props.size ?? 20;
+	const rows = resolveSocialLinks(props.socials, {
+		...(props.color ? { color: props.color } : {}),
+	});
+	// Nothing at all rather than an empty <ul> in a footer.
+	if (rows.length === 0) return null;
+
+	return (
+		<ul style={SOCIAL_LIST_STYLE}>
+			{rows.map((row) => (
+				<li key={row.key}>
+					<a
+						aria-label={row.label}
+						class={props.linkClass}
+						href={row.url}
+						rel="noopener noreferrer"
+						target="_blank"
+						title={row.label}
+					>
+						{row.iconUrl ? (
+							<img
+								alt={row.label}
+								class={props.iconClass}
+								height={size}
+								loading="lazy"
+								src={row.iconUrl}
+								width={size}
+							/>
+						) : (
+							<svg
+								aria-hidden="true"
+								class={props.iconClass}
+								fill="none"
+								height={size}
+								stroke="currentColor"
+								stroke-width={SOCIAL_FALLBACK_GLYPH.strokeWidth}
+								viewBox={SOCIAL_FALLBACK_GLYPH.viewBox}
+								width={size}
+							>
+								<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>
+						)}
+					</a>
+				</li>
+			))}
+		</ul>
+	);
+});
+
+export { resolveSocialLinks } from "./social-core/index.js";

package/src/react-marketing.tsx

@@ -1,6 +1,11 @@
+"use client";
+
 /**
  * React hooks for the schema-driven marketing-page flow.
  *
+ * Marked client-side in its own right, not just via `react.tsx`, so a deep
+ * import lands on the same boundary as the barrel export.
+ *
  * The base SDK file (`react.tsx`) is already past the workspace's
  * "stop and ask before growing" file-size threshold, so these new hooks
  * live alongside it in their own module. Same import target for