@kharon-labs/browser 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,271 @@
+type SignalSource = "campaign_link" | "form_email" | "known_visitor" | "reverse_ip" | "referrer";
+type AttributeKey = "company.domain" | "company.name" | "company.legalName" | "company.industry"
+/** NAICS sector id ("finance", "health-care"), rolled up from `company.naics` by `naicsSector`. */
+ | "company.sector" | "company.naics" | "company.sic" | "company.employeeCount" | "company.employeeBand" | "company.revenueBand" | "company.country" | "company.region" | "company.city" | "company.founded" | "company.ownership" | "company.ticker" | "crm.lists" | "crm.stage" | "crm.owner" | "crm.isCustomer" | "visitor.role" | "visitor.networkType" | "visitor.identified" | "visitor.country" | "intent.campaign" | "intent.utmSource" | "intent.utmMedium" | "intent.utmTerm" | "intent.referrerHost";
+type AttributeValue = string | number | boolean;
+type ListAttributeKey = "crm.lists";
+type ScalarAttributeKey = Exclude<AttributeKey, ListAttributeKey>;
+type IdentityContext = Partial<Record<ScalarAttributeKey, AttributeValue>> & Partial<Record<ListAttributeKey, string[]>>;
+type Condition = ({
+	attr: ScalarAttributeKey;
+	op: "eq";
+	value: AttributeValue;
+} | {
+	attr: ScalarAttributeKey;
+	op: "in";
+	value: AttributeValue[];
+}
+/** `startsWith` is a prefix match, for hierarchical codes: NAICS "51" covers "5112". */
+ | {
+	attr: ScalarAttributeKey;
+	op: "contains" | "startsWith";
+	value: string;
+} | {
+	attr: ScalarAttributeKey;
+	op: "gte" | "lte";
+	value: number;
+}
+/** The list attribute holds this id, e.g. the account is on CRM list "hs-123". */
+ | {
+	attr: ListAttributeKey;
+	op: "has";
+	value: string;
+} | {
+	attr: AttributeKey;
+	op: "exists";
+}) & {
+	/**
+	 * For near matching: a visitor who fails this condition never gets a near match. Exact matching
+	 * ignores it. Conditions under `not` are always required.
+	 */
+	required?: boolean;
+};
+type SlotContent = Record<string, string>;
+type VariantStatus = "draft" | "live" | "paused" | "retired";
+type DecisionReason = "matched" | "default" | "holdout";
+type DecisionRung = "exact" | "near" | "segment" | "default";
+interface Decision {
+	slotId: string;
+	/** The variant or segment row (`seg:…`) shown, or null when default content was shown. */
+	variantId: string | null;
+	/**
+	 * For holdout visitors: the variant they *would* have seen. This is the control group for that
+	 * variant's lift. Null for visitors no variant matched.
+	 */
+	counterfactualVariantId: string | null;
+	reason: DecisionReason;
+	rung: DecisionRung;
+	/** Content with all tokens rendered. */
+	content: SlotContent;
+}
+type ConsentChoice = "granted" | "denied" | "unknown";
+type CandidateOutcome = "wins" | "outranked" | "skipped" | "held-out";
+type ExplainOutcome = Exclude<CandidateOutcome, "held-out"> | "no-match" | "not-live";
+interface ConditionExplanation {
+	attr: AttributeKey;
+	op: Condition["op"];
+	/** The rule's value; absent for `exists`. */
+	value?: Extract<Condition, {
+		value: unknown;
+	}>["value"];
+	/** The visitor's value for `attr`, or null when they have none. */
+	actual: AttributeValue | string[] | null;
+	/** Whether this condition alone holds. Null when the attribute can't be known here (see `unavailable`). */
+	matched: boolean | null;
+}
+interface AudienceExplanation {
+	id: string;
+	name: string;
+	matched: boolean;
+	/** Some condition reads an attribute this explanation can't see, so `matched` may be wrong for real visitors. */
+	unknown: boolean;
+	/** Every leaf condition of the rule, in order. `not`, `any` and `all` are folded into `matched`. */
+	conditions: ConditionExplanation[];
+}
+interface VariantExplanation {
+	variantId: string;
+	audienceId: string;
+	status: VariantStatus;
+	/** Whether the variant's audience matches this visitor, whatever its status. */
+	audienceMatched: boolean;
+	outcome: ExplainOutcome;
+	/** For `skipped`: the attributes with no value and no fallback that stopped it rendering. */
+	missing?: string[];
+}
+interface SlotExplanation {
+	/** The variant or segment row (`seg:…`) shown, or null for default content. */
+	variantId: string | null;
+	reason: DecisionReason;
+	/** The step of the fallback ladder that chose the content. */
+	rung: DecisionRung;
+	/** The text each field shows. */
+	content: Record<string, string>;
+	variants: VariantExplanation[];
+}
+interface SiteExplanation {
+	company: {
+		domain: string;
+		source: SignalSource;
+		confidence: number;
+	} | null;
+	/** The flat attributes audiences and templates see. */
+	context: IdentityContext;
+	audiences: AudienceExplanation[];
+	slots: Record<string, SlotExplanation>;
+}
+declare const RESOLVE_API_VERSION = 1;
+interface DeclaredSlot {
+	id: string;
+	h: string;
+}
+/** `POST /api/v1/resolve`. Browsers send it as `text/plain` so no CORS preflight is needed. */
+export interface ResolveRequest {
+	v: typeof RESOLVE_API_VERSION;
+	/** Publishable key. A server call sends its secret key as `Authorization: Bearer` instead. */
+	key?: string;
+	/** The visitor id the package stored after an earlier `persist: true`. */
+	vid?: string;
+	/** Page URL; campaign links and UTM parameters are read from it. */
+	url: string;
+	referrer?: string | null;
+	slots: DeclaredSlot[];
+	/** What the customer's CMP reported through `setConsent`. */
+	consent?: ConsentChoice;
+	/** Global Privacy Control as the page or the customer's server saw it. */
+	gpc?: boolean;
+	/** Secret-key calls only: the visitor's IP and country from the customer's own edge. Ignored otherwise. */
+	ip?: string;
+	country?: string;
+	/** The session's config pin from an earlier response (`"<version>.<epoch>"`), to keep its copy stable. */
+	pin?: string;
+}
+/**
+ * What one slot shows. The same fields `<Slot>` writes as `data-ge-*` attributes. `rung` is absent in
+ * answers from servers that predate the fallback ladder.
+ */
+export type ResolvedSlot = Pick<Decision, "variantId" | "counterfactualVariantId" | "reason" | "content"> & Partial<Pick<Decision, "rung">>;
+export interface ResolveResponse {
+	v: typeof RESOLVE_API_VERSION;
+	/** Published config version the decisions came from; 0 when the site has never published. */
+	configVersion: number;
+	/** Whether consent lets the package store `vid` and start the tracker. */
+	persist: boolean;
+	/** The visitor id to store, present only when `persist` is true. */
+	vid?: string;
+	/**
+	 * The pin to keep for the rest of the session and send back as `pin`, present only when `persist`
+	 * is true. The session then sees `configVersion` until a rollback breaks the pin.
+	 */
+	pin?: string;
+	/** Requested slots that exist in the live config. Any other slot keeps its code defaults. */
+	decisions: Record<string, ResolvedSlot>;
+	/** Match token for the tracker to echo in beacon v2 (`m`), present only when `persist` is true. Opaque. */
+	m?: string;
+	/**
+	 * A live-page preview from the console (the page URL carried a valid `ge_preview` token): drafts
+	 * for a synthetic visitor. The package stores nothing, forgets nothing and doesn't measure.
+	 */
+	preview?: true;
+	/**
+	 * A debug link (docs/design/resolve-debug): why each requested slot shows what it does to this
+	 * request, resolved from what our CDN saw. Only with `preview`; the browser SDK logs it to the console.
+	 */
+	explain?: SiteExplanation;
+}
+/**
+ * A short, stable fingerprint of a slot's defaults, so resolve can tell when the code and the
+ * console disagree. FNV-1a over the fields sorted by name; 8 hex characters.
+ */
+export declare function hashSlotDefaults(content: SlotContent): string;
+/** What the visitor chose in the site's consent tool. `unknown` fails closed where opt-in applies. */
+export type Consent = ConsentChoice;
+/**
+ * Validates a resolve response. Returns null when the envelope is unusable, so the page keeps its
+ * defaults; a single malformed decision is dropped and its slot keeps its defaults.
+ */
+export declare function parseResolveResponse(body: unknown): ResolveResponse | null;
+export declare const DEFAULT_API_BASE = "https://kharonlabs.com";
+/** After this, a response is dropped and the page keeps its defaults (design: hard 500 ms timeout). */
+export declare const DEFAULT_TIMEOUT_MS = 500;
+export declare const VISITOR_COOKIE = "ge_vid";
+export interface KharonOptions {
+	/** Publishable key (`ge_pk_…`). Bound to the site's allowed origins. */
+	key: string;
+	/** Where the API lives. Defaults to Kharon Labs production. */
+	apiBase?: string;
+	/** The visitor's consent, if the page already knows it. Update later with `setConsent`. */
+	consent?: Consent;
+	/** Hard limit for the first resolve; a later answer is dropped. Default 500 ms. */
+	timeoutMs?: number;
+	/** Page id for page views. Defaults to one derived from the URL path. */
+	pageId?: string;
+	/** Cookie domain for the visitor id, e.g. `example.com` to share it across subdomains. */
+	cookieDomain?: string;
+	/** The document to work in. Tests pass their own. */
+	root?: Document;
+}
+export interface SlotDeclaration {
+	id: string;
+	defaults: Record<string, string>;
+}
+export interface KharonClient {
+	/**
+	 * Asks the server what to show. Resolves to null on any failure or after `deadline` (epoch ms),
+	 * meaning: keep the defaults. Never rejects.
+	 */
+	resolve(slots: SlotDeclaration[], deadline?: number): Promise<ResolveResponse | null>;
+	/** Adopts a decision made elsewhere (server mode): keeps or drops the visitor id it carries. */
+	adopt(response: ResolveResponse): void;
+	/** Starts measuring the page's slots, only if the last response allowed storing the visitor. */
+	track(configVersion: number): void;
+	setConsent(consent: Consent): void;
+	/** Called after a consent change; a grant needs a fresh resolve to get an id. */
+	onConsentChange(listener: (consent: Consent) => void): () => void;
+	conversion(goal: string, value?: number): void;
+	stop(): void;
+	readonly consent: Consent;
+}
+export declare function createClient(options: KharonOptions): KharonClient;
+/** `/pricing/team` → `pricing.team`; `/` → `home`. Page ids allow `[A-Za-z0-9_.:-]`. */
+export declare function pageIdFor(pathname: string): string;
+/**
+ * Paste into `<head>` before any stylesheet to hide slots (never the page) until the swap. It
+ * reveals them after 500 ms on its own, so a slow or missing script can't keep them hidden.
+ */
+export declare const ANTI_FLICKER_SNIPPET: string;
+/** Every slot on the page with its code defaults, read from the markup. A repeated id is one slot. */
+export declare function scanSlots(root: Document): SlotDeclaration[];
+export declare function applyDecision(el: Element, decision: ResolvedSlot, baseURI: string): void;
+/** Removes the anti-flicker style, if the page has one. */
+export declare function reveal(root: Document): void;
+/** When the anti-flicker snippet started hiding slots, so the swap shares its deadline. */
+export declare function antiFlickerStart(root: Document): number | undefined;
+export declare function isWritable(attr: string, value: string, baseURI: string): boolean;
+export interface Kharon {
+	/** Forward your consent tool's answer. A grant re-resolves and starts measuring; a denial stops it. */
+	setConsent(consent: Consent): void;
+	/** Records a goal. Not recorded for visitors we may not store. */
+	conversion(goal: string, value?: number): void;
+	/** Re-scans and re-resolves the page, e.g. after a client-side route change. */
+	refresh(): Promise<void>;
+	stop(): void;
+	/** Settles once the latest resolve has been applied, or given up on. */
+	readonly ready: Promise<void>;
+	readonly client: KharonClient;
+}
+/**
+ * Personalizes the slots in the page's HTML. The page shows its own defaults until the decision
+ * arrives; after `timeoutMs` (500 ms) the answer is dropped and the defaults stay.
+ */
+export declare function init(options: KharonOptions): Kharon;
+/** Same as `instance.setConsent`. Safe to call before `init`; the choice is used by the first resolve. */
+export declare function setConsent(consent: Consent): void;
+export declare function conversion(goal: string, value?: number): void;
+/**
+ * Records a signup from the page. Prefer `recordSignup` in `@kharon-labs/server` from your signup
+ * handler: it counts only signups that succeeded, and ones whose browser blocks scripts.
+ */
+export declare function signup(): void;
+export declare function refresh(): Promise<void>;
+
+export {};