@businessdash/sdk 0.9.70 → 0.9.80

package/openapi.json

@@ -4785,6 +4785,113 @@
         "additionalProperties": false,
         "nullable": true
       },
+      "customerPortalQuizResultsResponseSchema": {
+        "type": "object",
+        "properties": {
+          "items": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "invitationId": {
+                  "type": "string"
+                },
+                "quizName": {
+                  "type": "string"
+                },
+                "competency": {
+                  "type": "string",
+                  "nullable": true
+                },
+                "status": {
+                  "type": "string"
+                },
+                "completedAt": {
+                  "type": "string",
+                  "nullable": true
+                },
+                "scoreWithheld": {
+                  "type": "boolean"
+                },
+                "result": {
+                  "type": "object",
+                  "properties": {
+                    "status": {
+                      "type": "string"
+                    },
+                    "scorePercent": {
+                      "type": "number",
+                      "nullable": true
+                    },
+                    "provisionalScorePercent": {
+                      "type": "number",
+                      "nullable": true
+                    },
+                    "passed": {
+                      "type": "boolean",
+                      "nullable": true
+                    },
+                    "pointsEarned": {
+                      "type": "number",
+                      "nullable": true
+                    },
+                    "pointsPossible": {
+                      "type": "number",
+                      "nullable": true
+                    },
+                    "passingScore": {
+                      "type": "number"
+                    },
+                    "results": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "additionalProperties": {}
+                      }
+                    },
+                    "submittedAt": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "durationSeconds": {
+                      "type": "number",
+                      "nullable": true
+                    }
+                  },
+                  "required": [
+                    "status",
+                    "scorePercent",
+                    "provisionalScorePercent",
+                    "passed",
+                    "pointsEarned",
+                    "pointsPossible",
+                    "passingScore",
+                    "results",
+                    "submittedAt",
+                    "durationSeconds"
+                  ],
+                  "additionalProperties": false,
+                  "nullable": true
+                }
+              },
+              "required": [
+                "invitationId",
+                "quizName",
+                "competency",
+                "status",
+                "completedAt",
+                "scoreWithheld",
+                "result"
+              ],
+              "additionalProperties": false
+            }
+          }
+        },
+        "required": [
+          "items"
+        ],
+        "additionalProperties": false
+      },
       "customerPortalUpdateProfileInputSchema": {
         "type": "object",
         "properties": {
@@ -12506,6 +12613,66 @@
         ]
       }
     },
+    "/consent": {
+      "get": {
+        "operationId": "get_consent",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object"
+                }
+              }
+            }
+          },
+          "402": {
+            "description": "Access gate (plan/payment/suspension)"
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      },
+      "post": {
+        "operationId": "post_consent",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object"
+                }
+              }
+            }
+          },
+          "402": {
+            "description": "Access gate (plan/payment/suspension)"
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/blogCommentPostInputSchema"
+              }
+            }
+          }
+        }
+      }
+    },
     "/coupons": {
       "post": {
         "operationId": "post_coupons",
@@ -13824,6 +13991,41 @@
         }
       }
     },
+    "/customer-portal/quiz-results": {
+      "get": {
+        "operationId": "get_customer_portal_quiz_results",
+        "parameters": [
+          {
+            "name": "token",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/customerPortalQuizResultsResponseSchema"
+                }
+              }
+            }
+          },
+          "402": {
+            "description": "Access gate (plan/payment/suspension)"
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
     "/customer-portal/quotes": {
       "get": {
         "operationId": "get_customer_portal_quotes",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@businessdash/sdk",
-	"version": "0.9.70",
+	"version": "0.9.80",
 	"description": "BusinessDash developer SDK \u2014 the data layer that lets you build customer-facing surfaces on your own domain while BusinessDash handles the operations stack behind the scenes. 0.9.x ships a comprehensive programmatic surface: storefront (products, categories, cart, checkout via Stripe Connect with Link payment), customer portal (work feed, per-item detail, quote accept/reject, job activity, comment threads, reviews, notification preferences), blog (posts, categories, threaded comments, reactions, paywalls, Mux video), Front Desk chat (sessions, AI bot, live human handoff, queue + place-in-line), coupons (validation against synced Stripe Promotion Codes \u2014 BOGO/BXGY/free-shipping kinds), shipping (multi-carrier rates + tracking via Shippo), address validation (Google Places, platform-proxied), customer notification preferences across in-app/email/SMS/webhook, subscriptions admin + Stripe sync, and followers/subscribers. Also: tenant sign-in/up/out via the auth handler, schema-driven marketing pages with restore semantics, typed JSON-LD SEO builders (LocalBusiness/Service/FAQ/Article/Breadcrumb/Review), and a CLI (`biab-dev sync-schema`) for the schema flow. The consumer renders the UI in their own design system on their own domain; BusinessDash supplies the data, the business logic, and the Stripe/Mux/Google/Shippo plumbing.",
 	"type": "module",
 	"sideEffects": false,
@@ -14,8 +14,8 @@
 	"module": "./dist/index.js",
 	"types": "./dist/index.d.ts",
 	"bin": {
-		"biab-dev": "./dist/cli.js",
-		"businessdash": "./dist/cli.js"
+		"biab-dev": "dist/cli.js",
+		"businessdash": "dist/cli.js"
 	},
 	"exports": {
 		".": {
@@ -221,6 +221,11 @@
 			"import": "./dist/model3d-core/index.js",
 			"require": "./dist/model3d-core/index.cjs"
 		},
+		"./consent": {
+			"types": "./dist/consent-core/index.d.ts",
+			"import": "./dist/consent-core/index.js",
+			"require": "./dist/consent-core/index.cjs"
+		},
 		"./biab-sw.js": "./assets/biab-sw.js"
 	},
 	"scripts": {

package/src/client.ts

@@ -111,6 +111,7 @@ import {
 	type CustomerPortalMessagesMarkReadResponse,
 	type CustomerPortalOtherOrgsResponse,
 	type CustomerPortalProfile,
+	type CustomerPortalQuizResultsResponse,
 	type CustomerPortalUpdateProfileInput,
 	type CustomerPortalUpdateProfileResponse,
 	type CustomerProductReviewCreated,
@@ -204,6 +205,7 @@ import {
 	customerPortalMessagesMarkReadResponseSchema,
 	customerPortalOtherOrgsResponseSchema,
 	customerPortalProfileSchema,
+	customerPortalQuizResultsResponseSchema,
 	customerPortalUpdateProfileInputSchema,
 	customerPortalUpdateProfileResponseSchema,
 	customerProductReviewCreatedSchema,
@@ -593,6 +595,16 @@ export class BiabDevClient {
 		return new BiabDevReviewsClient(this);
 	}
 
+	/**
+	 * Tracking consent for this org's site.
+	 *
+	 * Pair with `@businessdash/sdk/consent`, which handles the visitor cookie
+	 * and gives you a gate to check before starting analytics.
+	 */
+	get consent() {
+		return new BiabDevConsentClient(this);
+	}
+
 	/** Public job postings — build a careers page on your own domain. */
 	get hiring() {
 		return new BiabDevHiringClient(this);
@@ -2827,6 +2839,73 @@ export class BiabDevLegalClient {
 	}
 }
 
+const consentStateSchema = z.object({
+	/** Categories this org uses at all — one banner row each. */
+	categories: z.array(z.string()),
+	noticeText: z.string().nullable(),
+	noticeVersion: z.number(),
+	/** What may be used right now. */
+	allowed: z.array(z.string()),
+	mustAsk: z.boolean(),
+	reason: z.string(),
+});
+
+/**
+ * Tracking consent, scoped to the calling org.
+ *
+ * Every call is answered for the org whose key made it. There is no shape here
+ * that could read or write another org's consent — consent is given to a
+ * controller, and one controller's record is not another's to act on.
+ *
+ * The visitor is identified by an `x-biab-visitor` header carrying an opaque id
+ * from the caller's own first-party cookie. `@businessdash/sdk/consent` manages
+ * that for you; these methods are the transport underneath it.
+ */
+export class BiabDevConsentClient {
+	constructor(private readonly client: BiabDevClient) {}
+
+	/** The notice to show, and what this visitor currently allows. */
+	async get(visitorKey?: string | null): Promise<{
+		categories: string[];
+		noticeText: string | null;
+		noticeVersion: number;
+		allowed: string[];
+		mustAsk: boolean;
+		reason: string;
+	}> {
+		return this.client.request({
+			path: "consent",
+			responseSchema: consentStateSchema,
+			...(visitorKey ? { headers: { "x-biab-visitor": visitorKey } } : {}),
+		});
+	}
+
+	/**
+	 * Record the visitor's answer.
+	 *
+	 * `granted: []` is a real answer — "asked, refused everything" — and is
+	 * stored as one, so the banner does not reappear on the next page.
+	 */
+	async record(input: {
+		visitorKey: string;
+		granted: string[];
+		noticeVersion: number;
+		source?: "banner" | "settings";
+	}): Promise<{ ok: boolean }> {
+		return this.client.request({
+			method: "POST",
+			path: "consent",
+			body: {
+				granted: input.granted,
+				noticeVersion: input.noticeVersion,
+				source: input.source ?? "banner",
+			},
+			headers: { "x-biab-visitor": input.visitorKey },
+			responseSchema: z.object({ ok: z.boolean() }),
+		});
+	}
+}
+
 export class BiabDevChatbotClient {
 	constructor(private readonly client: BiabDevClient) {}
 
@@ -3190,6 +3269,26 @@ export class BiabDevCustomerPortalClient {
 		});
 	}
 
+	/**
+	 * The signed-in customer's quiz results at this org — the SDK side of
+	 * the account-gated reveal: an invitation completed with "create an
+	 * account to see how you did" surfaces its result here (and only to
+	 * the invited email). Interview-mode quizzes come back with
+	 * `scoreWithheld: true` and no verdict, by the org's own setting.
+	 */
+	async myQuizResults(options?: {
+		token?: string;
+	}): Promise<CustomerPortalQuizResultsResponse> {
+		const params = new URLSearchParams();
+		if (options?.token) params.set("token", options.token);
+		const qs = params.toString();
+		return this.client.request({
+			path: `customer-portal/quiz-results${qs ? `?${qs}` : ""}`,
+			responseSchema: customerPortalQuizResultsResponseSchema,
+			headers: this.headers(),
+		});
+	}
+
 	async updateProfile(
 		input: CustomerPortalUpdateProfileInput,
 	): Promise<CustomerPortalUpdateProfileResponse> {

package/src/consent-core/index.ts

@@ -0,0 +1,213 @@
+/**
+ * `@businessdash/sdk/consent` — tracking consent, per org.
+ *
+ * ## The rule that shapes everything here
+ *
+ * Consent is given to a **controller**, and each org is a separate controller.
+ * It does not travel between them in either direction:
+ *
+ * - A visitor who refuses at org 2 has said nothing to org 1. Org 1 keeps
+ *   collecting.
+ * - A visitor who consents at org 1 has NOT consented at org 2. Org 2 may not
+ *   start collecting on the strength of it.
+ *
+ * The second half is the one that gets skipped, and it is the one with legal
+ * teeth: acting on another controller's consent is processing without a lawful
+ * basis.
+ *
+ * That is why the visitor key lives in a **first-party cookie on the org's own
+ * domain**, and why every call carries the org's own API key. Two sites cannot
+ * see each other's cookies, so the isolation is enforced by the browser rather
+ * than by us remembering to scope a query.
+ *
+ * ## Gate analytics on it
+ *
+ * ```ts
+ * const consent = await loadConsent({ client });
+ * if (consent.allows('analytics')) {
+ *   initBiabAnalytics({ siteId, baseUrl, apiKey });
+ * }
+ * if (consent.mustAsk) showYourBanner(consent);
+ * ```
+ *
+ * `initBiabAnalytics` is deliberately NOT made to call this itself. A gate that
+ * fires implicitly is one nobody can see in review, and the decision of what
+ * happens before consent — render nothing, render a placeholder, collect
+ * essential-only — belongs to the site, not to us.
+ *
+ * @module
+ */
+
+export type ConsentCategory = "analytics" | "marketing" | "personalisation";
+
+/** Why consent resolved the way it did. Useful in an org's audit view. */
+export type ConsentReason =
+	| "browser_signal"
+	| "explicit"
+	| "stale_notice"
+	| "default_allow"
+	| "default_deny";
+
+export type ConsentState = {
+	/** Categories this org uses at all. Render one banner row per entry. */
+	categories: ConsentCategory[];
+	noticeText: string | null;
+	noticeVersion: number;
+	/** What may be used right now. */
+	allowed: ConsentCategory[];
+	/** True when the visitor has not answered and a banner should show. */
+	mustAsk: boolean;
+	reason: ConsentReason;
+	/** `allowed.includes(category)`, spelled as a question. */
+	allows(category: ConsentCategory): boolean;
+};
+
+/** The subset of the SDK client this needs. */
+export type ConsentClientLike = {
+	request(input: {
+		method?: string;
+		path: string;
+		body?: unknown;
+		headers?: Record<string, string>;
+		responseSchema: unknown;
+	}): Promise<unknown>;
+};
+
+const VISITOR_COOKIE = "biab_visitor";
+const VISITOR_HEADER = "x-biab-visitor";
+
+/**
+ * The visitor's id for THIS site, minted on first need.
+ *
+ * A first-party cookie on the org's own domain, which is what makes the
+ * per-org isolation structural: the same person visiting two orgs gets two
+ * unrelated keys, because two domains cannot read each other's cookies. There
+ * is no cross-site identifier here and deliberately no way to add one.
+ *
+ * Returns null on the server, where there is no visitor to identify.
+ */
+export function visitorKey(): string | null {
+	if (typeof document === "undefined") return null;
+
+	const found = document.cookie
+		.split(";")
+		.map((part) => part.trim())
+		.find((part) => part.startsWith(`${VISITOR_COOKIE}=`));
+	if (found) return decodeURIComponent(found.slice(VISITOR_COOKIE.length + 1));
+
+	const key =
+		typeof crypto !== "undefined" && "randomUUID" in crypto
+			? crypto.randomUUID()
+			: `v${Date.now()}${Math.floor(Math.random() * 1e9)}`;
+
+	// SameSite=Lax and no Secure flag would leak on http; Secure is set unless
+	// we are plainly on localhost, where it would stop the cookie working at all.
+	const secure = location.protocol === "https:" ? "; Secure" : "";
+	// biome-ignore lint/suspicious/noDocumentCookie: the suggested CookieStore
+	// API has no Safari or Firefox support. A consent banner has to work in
+	// every browser a visitor might arrive in — that is the entire point of it —
+	// so the universally supported API is the correct one here.
+	document.cookie = `${VISITOR_COOKIE}=${encodeURIComponent(key)}; Path=/; Max-Age=31536000; SameSite=Lax${secure}`;
+	return key;
+}
+
+/** True when the browser is signalling a global opt-out (DNT or GPC). */
+export function browserOptOut(): boolean {
+	if (typeof navigator === "undefined") return false;
+	const nav = navigator as Navigator & {
+		doNotTrack?: string;
+		globalPrivacyControl?: boolean;
+	};
+	if (nav.globalPrivacyControl === true) return true;
+	const dnt =
+		nav.doNotTrack ??
+		(typeof window === "undefined"
+			? undefined
+			: (window as Window & { doNotTrack?: string }).doNotTrack);
+	return dnt === "1" || dnt === "yes";
+}
+
+function toState(raw: {
+	categories?: string[];
+	noticeText?: string | null;
+	noticeVersion?: number;
+	allowed?: string[];
+	mustAsk?: boolean;
+	reason?: string;
+}): ConsentState {
+	const categories = (raw.categories ?? []) as ConsentCategory[];
+	const allowed = (raw.allowed ?? []) as ConsentCategory[];
+	return {
+		categories,
+		noticeText: raw.noticeText ?? null,
+		noticeVersion: raw.noticeVersion ?? 1,
+		allowed,
+		mustAsk: raw.mustAsk ?? true,
+		reason: (raw.reason ?? "default_deny") as ConsentReason,
+		allows: (category) => allowed.includes(category),
+	};
+}
+
+/**
+ * What this visitor currently allows, at this org.
+ *
+ * On any failure this returns a **deny-everything** state rather than throwing.
+ * A consent gate that fails open collects data nobody agreed to; one that fails
+ * closed loses some analytics. Only one of those is a compliance incident.
+ */
+export async function loadConsent(options: {
+	client: ConsentClientLike;
+}): Promise<ConsentState> {
+	const key = visitorKey();
+	try {
+		const raw = (await options.client.request({
+			path: "consent",
+			...(key ? { headers: { [VISITOR_HEADER]: key } } : {}),
+			responseSchema: { parse: (v: unknown) => v },
+		})) as Parameters<typeof toState>[0];
+		return toState(raw);
+	} catch {
+		return {
+			categories: [],
+			noticeText: null,
+			noticeVersion: 1,
+			allowed: [],
+			mustAsk: false,
+			reason: "default_deny",
+			allows: () => false,
+		};
+	}
+}
+
+/**
+ * Record the visitor's answer.
+ *
+ * `granted: []` is a real answer — "asked, refused everything" — and is stored
+ * as one, so the banner does not reappear on the next page.
+ */
+export async function recordConsent(options: {
+	client: ConsentClientLike;
+	granted: ConsentCategory[];
+	noticeVersion: number;
+	source?: "banner" | "settings";
+}): Promise<{ ok: boolean }> {
+	const key = visitorKey();
+	if (!key) return { ok: false };
+
+	try {
+		await options.client.request({
+			method: "POST",
+			path: "consent",
+			body: {
+				granted: options.granted,
+				noticeVersion: options.noticeVersion,
+				source: options.source ?? "banner",
+			},
+			headers: { [VISITOR_HEADER]: key },
+			responseSchema: { parse: (v: unknown) => v },
+		});
+		return { ok: true };
+	} catch {
+		return { ok: false };
+	}
+}

package/src/contracts.ts

@@ -995,6 +995,44 @@ export const customerPortalProfileSchema = z
 	})
 	.nullable();
 
+/**
+ * One quiz outcome for the signed-in customer. `scoreWithheld` marks an
+ * interview-mode quiz: the attempt exists, the verdict is staff-only —
+ * render "completed" and nothing else.
+ */
+export const customerPortalQuizResultSchema = z.object({
+	invitationId: z.string(),
+	quizName: z.string(),
+	competency: z.string().nullable(),
+	status: z.string(),
+	completedAt: z.string().nullable(),
+	scoreWithheld: z.boolean(),
+	result: z
+		.object({
+			status: z.string(),
+			scorePercent: z.number().nullable(),
+			provisionalScorePercent: z.number().nullable(),
+			passed: z.boolean().nullable(),
+			pointsEarned: z.number().nullable(),
+			pointsPossible: z.number().nullable(),
+			passingScore: z.number(),
+			results: z.array(z.record(z.unknown())),
+			submittedAt: z.string().nullable(),
+			durationSeconds: z.number().nullable(),
+		})
+		.nullable(),
+});
+export type CustomerPortalQuizResult = z.infer<
+	typeof customerPortalQuizResultSchema
+>;
+
+export const customerPortalQuizResultsResponseSchema = z.object({
+	items: z.array(customerPortalQuizResultSchema),
+});
+export type CustomerPortalQuizResultsResponse = z.infer<
+	typeof customerPortalQuizResultsResponseSchema
+>;
+
 export const customerPortalUpdateProfileInputSchema = z.object({
 	displayName: z.string().min(1).max(120).optional(),
 	profile: z.record(z.unknown()).optional(),