@webority/analytics 0.36.1 → 0.38.0

package/dist/types/catalogue/check.d.ts

@@ -0,0 +1,32 @@
+import type { MergedPlan } from "./plan.ts";
+export type SourceProblem = {
+    file: string | null;
+    line: number | null;
+    message: string;
+};
+export type CheckSummary = {
+    constants: number;
+    callSites: number;
+    files: number;
+};
+export declare function fleetConstantsOf(plan: MergedPlan): Map<string, string>;
+/**
+ * Checks a product's source against its merged plan. For each source in the plan:
+ * - every event constant in its constant files must be an event in the plan;
+ * - every use of those constants in the scanned folders must name a known constant, the plan must
+ *   list the source's sender for that event, and each property written inline must be declared on
+ *   the event or as a common property;
+ * - every event name written in a call of the source's `calls` (and, in JavaScript, of
+ *   trackSiteEvent) must be in the plan, held to the same sender and property rules.
+ * Returns { problems: [{ file, line, message }], summary }.
+ */
+export declare function checkSources(plan: MergedPlan, root: string): {
+    problems: SourceProblem[];
+    summary: CheckSummary;
+};
+/**
+ * The folder a plan's source paths are relative to: the repo root when the plan sits in `.webority/`,
+ * otherwise the plan's own folder.
+ */
+export declare function defaultRootOf(planFile: string): string;
+export declare function toPascalCase(name: string): string;

package/dist/types/catalogue/generate-events.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/types/catalogue/generate.d.ts

@@ -0,0 +1,28 @@
+import type { CatalogueEvent, MergedPlan } from "./plan.ts";
+/**
+ * The events a generated file carries, in plan order: fleet events first, then the product's own.
+ * sender limits them to one sender's events; productOnly drops the ones the base plan defines.
+ */
+export declare function selectEvents(plan: MergedPlan, { sender, productOnly }?: {
+    sender?: string | null;
+    productOnly?: boolean;
+}): CatalogueEvent[];
+/**
+ * A JavaScript module exporting one frozen object of event names. keys "constant" gives
+ * SIGNUP_STARTED (the package's own `events` style), "pascal" gives SignupStarted.
+ */
+export declare function renderJavaScript(events: CatalogueEvent[], { exportName, keys, planLabel, }?: {
+    exportName?: string;
+    keys?: "constant" | "pascal";
+    planLabel?: string;
+}): string;
+/**
+ * A C# file holding one static class of event-name constants, file-scoped namespace, marked
+ * auto-generated so analyzers leave it alone.
+ */
+export declare function renderCSharp(events: CatalogueEvent[], { namespace, className, accessibility, planLabel, }: {
+    namespace: string;
+    className: string;
+    accessibility?: "public" | "internal";
+    planLabel?: string;
+}): string;

package/dist/types/catalogue/plan.d.ts

@@ -0,0 +1,97 @@
+export declare const FLEET_PLAN_ID = "@webority/analytics/fleet";
+export declare const FUNNEL_STAGES: readonly ["acquisition", "activation", "engagement", "retention", "revenue", "referral", "support", "quality"];
+export type FunnelStage = (typeof FUNNEL_STAGES)[number];
+export declare const PERSONAL_DATA_CLASSES: readonly ["none", "pseudonymous", "personal"];
+export type PersonalDataClass = (typeof PERSONAL_DATA_CLASSES)[number];
+export declare const PROPERTY_TYPES: readonly ["string", "integer", "number", "boolean", "array", "object"];
+export type PropertyType = (typeof PROPERTY_TYPES)[number];
+export declare const PROPERTY_NAME_PATTERN: RegExp;
+declare const LANGUAGES: readonly ["csharp", "javascript"];
+export type SourceLanguage = (typeof LANGUAGES)[number];
+export type PropertyDefinition = {
+    type: PropertyType;
+    description?: string;
+    values?: unknown[];
+    nullable?: boolean;
+    personalData?: PersonalDataClass;
+};
+export type EventDefinition = {
+    description?: string;
+    stage?: FunnelStage;
+    owner?: string;
+    personalData?: PersonalDataClass;
+    senders?: string[];
+    properties?: Record<string, PropertyDefinition>;
+};
+export type SourceDefinition = {
+    sender: string;
+    language: SourceLanguage;
+    constants?: string[];
+    references?: string[];
+    calls?: string[];
+    ignoreConstants?: string[];
+    scan?: string[];
+    exclude?: string[];
+};
+export type TrackingPlan = {
+    $schema?: string;
+    product: string;
+    extends?: string;
+    description?: string;
+    commonProperties?: Record<string, PropertyDefinition>;
+    events: Record<string, EventDefinition>;
+    sources?: SourceDefinition[];
+};
+export type CatalogueEvent = {
+    name: string;
+    description: string | undefined;
+    stage: FunnelStage | undefined;
+    owner: string | undefined;
+    personalData: PersonalDataClass | undefined;
+    senders: string[];
+    properties: Map<string, PropertyDefinition>;
+    origin: string;
+};
+export type CommonProperty = PropertyDefinition & {
+    origin: string;
+};
+export type MergedPlan = {
+    product: string;
+    events: Map<string, CatalogueEvent>;
+    commonProperties: Map<string, CommonProperty>;
+    sources: SourceDefinition[];
+    file: string;
+};
+export type PlanLoad = {
+    plan: MergedPlan | null;
+    problems: string[];
+};
+/**
+ * Reads a tracking plan and everything it extends, merged into one catalogue. Never throws on a bad
+ * plan: every problem is returned, so a check can list them all at once.
+ * Returns { plan, problems } where plan is { product, events: Map, commonProperties: Map, sources, file }.
+ */
+export declare function loadPlan(file: string): PlanLoad;
+export declare function loadFleetPlan(): PlanLoad;
+/**
+ * Merges a plan's own declarations over its base. A product may list a base event again only to add
+ * properties or senders; anything else on it, or a property redeclared with another type, is a problem.
+ */
+export declare function mergePlan(base: MergedPlan | null, raw: TrackingPlan, label?: string): {
+    plan: MergedPlan;
+    problems: string[];
+};
+/**
+ * The structural rules of tracking-plan.schema.json, checked without a schema library so the check
+ * has no runtime dependency. The schema is what an editor validates against; this is what the build
+ * enforces, and the catalogue test keeps their enums the same.
+ */
+export declare function validatePlanShape(raw: unknown, label?: string): string[];
+/**
+ * Checks one event as it would be sent: a name the catalogue does not hold, a property declared
+ * neither on the event nor as a common property, or a value of the wrong type. PostHog's own `$`
+ * events and properties are not the product's vocabulary and are skipped.
+ * Returns a list of problem strings, empty when the event is valid.
+ */
+export declare function validateEvent(plan: MergedPlan, name: unknown, properties?: unknown): string[];
+export {};

package/dist/types/catalogue/scan.d.ts

@@ -0,0 +1,42 @@
+import type { SourceLanguage } from "./plan.ts";
+export type ConstantEntry = {
+    name: string;
+    value: string | null;
+    line: number;
+};
+export type EventReference = {
+    constant: string;
+    line: number;
+    properties: string[] | null;
+};
+export type EventCall = {
+    call: string;
+    name: string;
+    line: number;
+    properties: string[] | null;
+};
+/**
+ * Event constants declared in a C# file: `const string Name = "value";`, or `= AnalyticsEvents.X;`
+ * resolved through fleetConstants (PascalCase name to event name). Nested classes are flattened to
+ * the constant's own name. Returns [{ name, value, line }]; value is null for a reference that
+ * cannot be resolved.
+ */
+export declare function readCSharpConstants(text: string, fleetConstants?: ReadonlyMap<string, string>): ConstantEntry[];
+/**
+ * Event constants declared in a JavaScript file as string values of object literals,
+ * `Key: "value"` or `KEY: 'value'`. Returns [{ name, value, line }].
+ */
+export declare function readJavaScriptConstants(text: string): ConstantEntry[];
+/**
+ * Every use of `<reference>.<Constant>` (or `<reference>.<Nested>.<Constant>`) in a source file, with
+ * the property names written inline beside it. Returns [{ constant, line, properties }], where
+ * properties is an array of names, or null when no inline properties were found.
+ */
+export declare function findEventReferences(text: string, references: readonly string[], language: SourceLanguage): EventReference[];
+/**
+ * Every call of one of the named functions (`trackSiteEvent("x", ...)`, `window.lumexTrack("x", ...)`)
+ * whose first argument writes its event name, with the property names written inline beside it.
+ * Returns [{ call, name, line, properties }], one entry per name, so both arms of a ternary count.
+ */
+export declare function findEventCalls(text: string, calls: readonly string[], language: SourceLanguage): EventCall[];
+export declare function maskComments(text: string, language: SourceLanguage): string;

package/dist/types/channels.d.ts

@@ -0,0 +1,24 @@
+import type { AttributionTouch } from "./attribution.ts";
+declare const AI_ASSISTANTS: readonly [readonly ["chatgpt", readonly ["chatgpt.com", "chat.openai.com"]], readonly ["perplexity", readonly ["perplexity.ai"]], readonly ["gemini", readonly ["gemini.google.com"]], readonly ["copilot", readonly ["copilot.microsoft.com"]], readonly ["claude", readonly ["claude.ai"]], readonly ["you", readonly ["you.com"]], readonly ["phind", readonly ["phind.com"]], readonly ["deepseek", readonly ["deepseek.com"]], readonly ["grok", readonly ["grok.com"]], readonly ["meta_ai", readonly ["meta.ai"]], readonly ["poe", readonly ["poe.com"]]];
+type AiAssistant = (typeof AI_ASSISTANTS)[number][0];
+export declare const channels: Readonly<{
+    readonly DIRECT: "direct";
+    readonly GOOGLE: "google";
+    readonly META: "meta";
+    readonly LINKEDIN: "linkedin";
+    readonly MICROSOFT: "microsoft";
+    readonly OTHER: "other";
+    readonly AI_ASSISTANT: "ai_assistant";
+    readonly ORGANIC_SEARCH: "organic_search";
+    readonly ORGANIC_SOCIAL: "organic_social";
+    readonly REFERRAL: "referral";
+}>;
+type Channel = (typeof channels)[keyof typeof channels];
+/**
+ * The channel of a touch, as captureAttribution stores it. utm_source wins, then click ids; an
+ * untagged visit is classified by its referrer's host.
+ */
+export declare function resolveChannel(touch: Partial<AttributionTouch> | null | undefined): Channel;
+/** The AI assistant ("chatgpt", "perplexity", "gemini", "copilot", "claude"...) behind a touch, or "". */
+export declare function resolveAiSource(touch: Partial<AttributionTouch> | null | undefined): AiAssistant | "";
+export {};

package/dist/types/consent-regions.d.ts

@@ -0,0 +1,2 @@
+export declare const OPT_IN_COUNTRIES: readonly ["AT", "BE", "BG", "HR", "CY", "CZ", "DK", "EE", "FI", "FR", "DE", "GR", "HU", "IE", "IT", "LV", "LT", "LU", "MT", "NL", "PL", "PT", "RO", "SK", "SI", "ES", "SE", "IS", "LI", "NO", "GB", "CH"];
+export declare function requiresOptIn(countryCode: string | null | undefined): boolean;

package/dist/types/consent.d.ts

@@ -0,0 +1,83 @@
+export declare const CONSENT_COOKIE_NAME = "webority_cookie_consent";
+export declare const CONSENT_CHANGE_EVENT = "webority-consent-change";
+declare global {
+    interface Window {
+        dataLayer?: unknown[];
+    }
+}
+/** The categories a visitor chooses between. Essential cookies are always on, so they are not a choice. */
+export type ConsentCategory = "analytics" | "functional" | "marketing";
+/**
+ * The saved choice, shaped as the webority_cookie_consent cookie holds it. timestamp is an ISO
+ * string when this package wrote the cookie. A cookie edited by hand can hold any JSON value there,
+ * so it stays unknown and is only read after a type check.
+ */
+export type ConsentState = Record<ConsentCategory, boolean> & {
+    essential: true;
+    timestamp: unknown;
+};
+type SharedConsentOptions = {
+    cookieDomain?: string;
+    cookieDays?: number;
+    adStorage?: boolean;
+    regionCookie?: string;
+};
+/**
+ * The initConsent options. requiresOptIn comes from the host's country lookup and is required, except
+ * under strictOptIn, which asks every region and so may leave it out. requiresOptIn: false beside
+ * strictOptIn throws at run time, and the type rules it out too.
+ */
+export type ConsentOptions = SharedConsentOptions & ({
+    requiresOptIn: boolean;
+    strictOptIn?: false | undefined;
+} | {
+    requiresOptIn?: true | undefined;
+    strictOptIn: true;
+});
+type Region = "eea" | "other";
+type ConsentView = Omit<ConsentState, "timestamp"> & {
+    decided: boolean;
+};
+type ConsentListener = (consent: ConsentView) => void;
+/**
+ * Sets Google Consent Mode's defaults and applies the visitor's saved choice. Call once, first,
+ * before initAnalytics, loadTags or captureAttribution. requiresOptIn comes from the host, which
+ * knows the visitor's country (requiresOptIn(countryCode)); guessing it in the browser misplaces
+ * VPN users. cookieDomain (".capnix.ai") shares one choice between the website and every portal
+ * subdomain; without it the choice stays on the current host.
+ *
+ * strictOptIn asks every visitor in every region: Consent Mode is denied everywhere until they
+ * choose, loadTags holds Tag Manager and Ahrefs until consent, and requiresOptIn may be left out.
+ * adStorage says whether marketing consent also grants Google's ad_* signals: true by default,
+ * false under strictOptIn. cookieDays is the saved choice's lifetime, 365 by default.
+ *
+ * regionCookie names a cookie the host sets to "eea" or "other" (see setConsentRegion), read
+ * once, synchronously, here. With no saved choice, "other" lifts the opt-in default: analytics and
+ * functional start on, marketing stays off until chosen, and Google's ad signals follow adStorage.
+ * "eea", a missing cookie or any other value keeps the opt-in default. strictOptIn ignores it, and
+ * a saved choice always wins.
+ */
+export declare function initConsent(options: ConsentOptions): void;
+/**
+ * Applies the visitor's region when the host learns it after initConsent (a country check that
+ * answered later than the page). "other" lifts the opt-in default and "eea" restores it, with the
+ * same rule initConsent's regionCookie applies. onConsentChange listeners fire when the effective
+ * consent changes; a saved choice is untouched and nothing fires.
+ */
+export declare function setConsentRegion(region: Region): void;
+export declare function isConsentInitialized(): boolean;
+export declare function isStrictOptIn(): boolean;
+export declare function isAdStorageEnabled(): boolean;
+/**
+ * The visitor's current consent. Before they choose (decided: false) every optional category
+ * follows the region default: denied where opt-in is required, granted everywhere else. A region
+ * of "other" (regionCookie, setConsentRegion) grants analytics and functional where opt-in would
+ * otherwise be required; marketing stays off until the visitor chooses it.
+ */
+export declare function getConsent(): ConsentView;
+/** Records the visitor's choice, tells Google, and notifies every listener. */
+export declare function saveConsent(preferences?: Partial<Record<ConsentCategory, boolean>>): void;
+/** Calls listener with the new consent after every saveConsent. Returns an unsubscribe function. */
+export declare function onConsentChange(listener: ConsentListener): () => boolean;
+export declare function resetConsentForTests(): void;
+export {};

package/dist/types/errors.d.ts

@@ -0,0 +1,35 @@
+import type { PostHog } from "posthog-js";
+type ErrorState = {
+    started: boolean;
+    posthog: PostHog | null;
+    pending: [unknown, Record<string, unknown> | undefined][];
+    loadPosthog: () => Promise<{
+        default: PostHog;
+    }>;
+};
+/** PostHog options for error tracking only: exceptions are sent, nothing else is. Pure, so the test can lock the mapping. */
+export declare function buildErrorTrackingInitOptions({ host }: {
+    host: string;
+}): Parameters<PostHog["init"]>[1];
+/**
+ * Starts exception tracking in the browser, once per page. No initConsent is needed: nothing is
+ * stored on the device (memory persistence), no person is profiled and only exceptions are sent.
+ * Call it in the browser, once per page; in Next.js that is inside a useEffect in _app.
+ * Nothing starts when disabled, in Local, or when a host, client key, product or environment is missing.
+ */
+export declare function initErrorTracking({ host, clientKey, product, surface, environment, release, enabled, }?: {
+    host?: string;
+    clientKey?: string;
+    product?: string;
+    surface?: string | undefined;
+    environment?: string;
+    release?: string | undefined;
+    enabled?: boolean;
+}): void;
+/**
+ * Reports an exception the page caught itself, such as one stopped by a React error boundary,
+ * which never reaches the global handlers. Does nothing unless initErrorTracking has started.
+ */
+export declare function captureBrowserException(error: unknown, properties?: Record<string, unknown>): void;
+export declare function resetErrorTrackingForTests(loadPosthog?: ErrorState["loadPosthog"]): void;
+export {};

package/dist/types/event-registry.d.ts

@@ -0,0 +1,19 @@
+import type { FleetEventName } from "./vocabulary.ts";
+/** A value PostHog can store and a JSON event body can carry. */
+export type EventPropertyValue = string | number | boolean | null | EventPropertyValue[] | {
+    [key: string]: EventPropertyValue;
+};
+/** The properties an event, identify or group call carries. */
+export type EventProperties = {
+    [key: string]: EventPropertyValue;
+};
+export type EventName = FleetEventName | (string & Record<never, never>);
+/**
+ * The event names an entry may send: the fleet vocabulary plus every name the product registers.
+ * Each entry owns one, kept outside its session state, because an event name belongs to the
+ * product's vocabulary rather than to one analytics session.
+ */
+export declare function createEventRegistry(): {
+    register(names: Iterable<string>): void;
+    assertRegistered(name: EventName): void;
+};

package/dist/types/feature-flags.d.ts

@@ -0,0 +1,26 @@
+import type { PostHog } from "posthog-js";
+/**
+ * Whether a PostHog feature flag is on for this person. False whenever the answer cannot be
+ * trusted: flags not turned on in initAnalytics, analytics off or Local, no analytics consent
+ * (a revoke included), or PostHog still loading. A PostHog failure also reads as false, the default
+ * for the current render, but is never silent: it is sent to the logger passed to initAnalytics and
+ * rethrown on its own turn so the page's error reporting sees it. PostHog's own call records the
+ * exposure as $feature_flag_called. Never throws into the caller's own turn.
+ */
+export declare function isFeatureEnabled(key: string): boolean;
+/**
+ * The flag's value: the variant key for a multivariate flag (an experiment), true or false for a
+ * plain one. Null under the same conditions as isFeatureEnabled returns false, and for an unknown
+ * flag. A PostHog failure reads as null for the current render, is sent to the logger and rethrown
+ * on its own turn, as isFeatureEnabled does; records the exposure like isFeatureEnabled.
+ */
+export declare function getFeatureFlag(key: string): string | boolean | null;
+/**
+ * Calls listener whenever flags become readable: when PostHog loads or reloads them (after
+ * consent, identify, group). When they cannot load now (flags off, analytics off, no consent) it
+ * is called once on the next turn, so a screen waiting on it renders its default instead of
+ * waiting forever. Read the values inside it with isFeatureEnabled or getFeatureFlag. Returns an
+ * unsubscribe function that works at any time, before initAnalytics included.
+ */
+export declare function onFeatureFlags(listener: () => void): () => boolean;
+export declare function followFeatureFlags(posthog: PostHog): void;

package/dist/types/index.d.ts

@@ -0,0 +1,5 @@
+export { group, identify, initAnalytics, resetIdentity, trackEvent, WORKSPACE_GROUP_TYPE } from "./analytics.ts";
+export { getFeatureFlag, isFeatureEnabled, onFeatureFlags } from "./feature-flags.ts";
+export { CONSENT_CHANGE_EVENT, CONSENT_COOKIE_NAME, captureAttribution, channels, events, getAttribution, getConsent, initConsent, loadTags, onConsentChange, registerEvents, requiresOptIn, resolveAiSource, resolveChannel, saveConsent, setConsentRegion, trackSiteEvent, } from "./site.ts";
+export { trackTours } from "./tours.ts";
+export { track } from "./track-helpers.ts";

package/dist/types/node/errors.d.ts

@@ -0,0 +1,38 @@
+import { PostHog } from "posthog-node";
+type NodeErrorState = {
+    client: PostHog | null;
+    base: Record<string, unknown>;
+    createClient: (key: string, options: NonNullable<ConstructorParameters<typeof PostHog>[1]>) => PostHog;
+};
+/**
+ * Starts exception tracking on the server, once per process. Nothing starts when disabled, in Local,
+ * when already started, or when a host, client key, product or environment is missing.
+ * captureUncaught also reports uncaught exceptions and unhandled rejections.
+ */
+export declare function initServerErrorTracking({ host, clientKey, product, surface, environment, release, enabled, captureUncaught, }?: {
+    host?: string;
+    clientKey?: string;
+    product?: string;
+    surface?: string | undefined;
+    environment?: string;
+    release?: string | undefined;
+    enabled?: boolean;
+    captureUncaught?: boolean;
+}): void;
+/** Sends an exception with the request it came from. Does nothing until initServerErrorTracking has run. */
+export declare function captureServerException(error: unknown, { distinctId, path, method, statusCode, properties, }?: {
+    distinctId?: string;
+    path?: string;
+    method?: string;
+    statusCode?: unknown;
+    properties?: Record<string, unknown>;
+}): void;
+/** Express error middleware: records the error, then passes it on so Express answers as it would without tracking. */
+export declare function expressErrorHandler(): (err: unknown, req: {
+    originalUrl: string;
+    method: string;
+}, _res: unknown, next: (err: unknown) => void) => void;
+/** Sends what is queued and stops the client, within timeoutMs. Call it on shutdown, before the process exits. */
+export declare function flushServerErrorTracking(timeoutMs?: number): Promise<void>;
+export declare function resetServerErrorTrackingForTests(createClient?: NodeErrorState["createClient"]): void;
+export {};

package/dist/types/node/index.d.ts

@@ -0,0 +1 @@
+export { captureServerException, expressErrorHandler, flushServerErrorTracking, initServerErrorTracking, resetServerErrorTrackingForTests, } from "./errors.ts";

package/dist/types/posthog-bridge.d.ts

@@ -0,0 +1,22 @@
+import type { PostHog, PostHogConfig } from "posthog-js";
+import { type ResolvedAnalyticsConfig } from "./state.ts";
+export type PosthogInitOptions = Partial<PostHogConfig> & Record<string, unknown>;
+/** What buildInitOptions reads from a config: initAnalytics passes its resolved config, initSiteAnalytics only these. */
+export type PosthogInitConfig = Pick<ResolvedAnalyticsConfig, "host" | "heatmaps" | "captureExceptions"> & {
+    sessionRecording?: ResolvedAnalyticsConfig["sessionRecording"] | undefined;
+    featureFlags?: boolean | undefined;
+};
+export declare function ensurePosthogInitialized(): Promise<PostHog>;
+/**
+ * Copies init options and, when consent is absent, sets the flag that keeps init itself
+ * from capturing. Pure so the smoke test can lock the consent decision without a browser.
+ * With the product's flags on it also holds the first flags request: opting out does not stop
+ * posthog-js asking for flags, and that request names the visitor. The grant reloads them.
+ */
+export declare function applyConsentToInitOptions(options: PosthogInitOptions, consentGranted: boolean, featureFlags?: boolean): PosthogInitOptions;
+/**
+ * The posthog-js init options for a config. Pure, so the smoke test can assert the mapping
+ * without a browser: replay stays off unless the product enabled it, and the masking choices
+ * ride through only when it is on.
+ */
+export declare function buildInitOptions(config: PosthogInitConfig): PosthogInitOptions;

package/dist/types/react-native/index.d.ts

@@ -0,0 +1,90 @@
+import type { AnalyticsLogger } from "../analytics.ts";
+import type { EventName, EventProperties } from "../event-registry.ts";
+import { events } from "../vocabulary.ts";
+export { __setNativeModulesForTests } from "./native-modules.ts";
+export { events };
+export declare const CONSENT_STORAGE_KEY = "webority_analytics_consent";
+declare const REGIONS: readonly ["eea", "other"];
+type ConsentRegion = (typeof REGIONS)[number];
+export declare const WORKSPACE_GROUP_TYPE = "workspace";
+type KeyValueStorage = {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+};
+type MobileInit = {
+    host?: string;
+    clientKey?: string;
+    product?: string;
+    surface?: string;
+    environment?: string;
+    enabled?: boolean;
+    logger?: AnalyticsLogger;
+    storage?: KeyValueStorage;
+    featureFlags?: boolean;
+    requiresOptIn?: boolean;
+};
+type MobileConsent = {
+    analytics: boolean;
+    decided: boolean;
+};
+/**
+ * Reads the stored choice and, when the config is complete and not Local, starts PostHog opted
+ * out. It opts in only while analytics consent holds. requiresOptIn comes from the person's
+ * country, as on the web; with no stored choice and opt-in required, nothing is sent until
+ * setConsentRegion("other") or setAnalyticsConsent(true). Resolves once PostHog is ready, never rejects.
+ */
+export declare function initMobileAnalytics(config?: MobileInit): Promise<void>;
+/**
+ * Applies the person's region when the app learns it. "other" grants analytics by default when
+ * no choice is stored; "eea" keeps opt-in. Listeners fire only when the effective consent changes.
+ */
+export declare function setConsentRegion(region: ConsentRegion): void;
+/** Stores the person's choice, opts PostHog in or out, and notifies every listener. Never rejects. */
+export declare function setAnalyticsConsent(granted: boolean): Promise<void>;
+/**
+ * The current consent. Before a choice (decided: false) analytics follows the region default,
+ * except after a stored choice that could not be read: that is no consent, whatever the region.
+ */
+export declare function getAnalyticsConsent(): MobileConsent;
+/** Calls listener with the new consent whenever it changes. Returns an unsubscribe function. */
+export declare function onAnalyticsConsentChange(listener: (consent: MobileConsent) => void): () => boolean;
+/**
+ * Names the person by their PublicId, never an internal id or an email. Made before consent, it
+ * is kept and applied when analytics is allowed; only the last one is kept.
+ */
+export declare function identify(publicId: string, props?: EventProperties): void;
+/**
+ * Ties the person's later events to a PostHog group and sets the group's properties (plan,
+ * seats): group(WORKSPACE_GROUP_TYPE, workspacePublicId, props). PublicId strings only; a number
+ * throws, because an internal id never reaches analytics. Held like identify, one per type, and
+ * forgotten by resetIdentity.
+ */
+export declare function group(type: string, key: string, props?: EventProperties): void;
+/**
+ * Whether a PostHog feature flag is on for this person. False whenever the answer cannot be
+ * trusted: flags not turned on in initMobileAnalytics, analytics off or Local, no consent, or
+ * PostHog still starting. A PostHog failure also reads as false for this render: it is sent to the
+ * logger passed to initMobileAnalytics and rethrown on its own turn.
+ * PostHog's own call records the exposure as $feature_flag_called.
+ */
+export declare function isFeatureEnabled(key: string): boolean;
+/**
+ * The flag's value: the variant key for a multivariate flag (an experiment), true or false for a
+ * plain one. Null when isFeatureEnabled would return false for the same reason, and for an
+ * unknown flag. A PostHog failure reads as null for this render, is sent to the logger and rethrown
+ * on its own turn, as isFeatureEnabled does; records the exposure like isFeatureEnabled.
+ */
+export declare function getFeatureFlag(key: string): string | boolean | null;
+/**
+ * Calls listener whenever flags become readable (after consent, identify, group). When they
+ * cannot load now (flags off, analytics off, no consent) it is called once on the next turn, so a
+ * screen waiting on it renders its default. Returns an unsubscribe function.
+ */
+export declare function onFeatureFlags(listener: () => void): () => boolean;
+export declare function resetIdentity(): void;
+export declare function registerEvents(names: readonly string[]): void;
+export declare function trackEvent(name: EventName, props?: EventProperties): void;
+/** Sends a PostHog $screen view. Screen names are not event names, so they need no registration. */
+export declare function trackScreen(screenName: string, props?: EventProperties): void;
+/** Puts the module back to its first-load state for the smoke test. Not part of the public API. */
+export declare function __resetForTests(): void;

package/dist/types/react-native/native-modules.d.ts

@@ -0,0 +1,41 @@
+type PostHogClient = {
+    ready?(): unknown;
+    register(props: Record<string, unknown>): unknown;
+    identify(publicId: string, props: Record<string, unknown>): unknown;
+    group(type: string, key: string, props: Record<string, unknown>): unknown;
+    capture(name: string, props: Record<string, unknown>): unknown;
+    screen(name: string, props: Record<string, unknown>): unknown;
+    optIn(): unknown;
+    optOut(): unknown;
+    reset(): unknown;
+    isFeatureEnabled(key: string): boolean | undefined;
+    getFeatureFlag(key: string): string | boolean | undefined;
+    onFeatureFlags?(listener: () => void): unknown;
+    reloadFeatureFlagsAsync?(): unknown;
+};
+type PostHogConstructor = new (apiKey: string, options: ReturnType<typeof buildNativeOptions>) => PostHogClient;
+/**
+ * Replaces posthog-react-native for the smoke test, which runs under plain node.
+ * Not part of the public API. Pass null to go back to the real modules.
+ */
+export declare function __setNativeModulesForTests(modules: unknown): void;
+export declare function loadPostHogClass(): Promise<PostHogConstructor | null>;
+export declare function isMissingModule(error: unknown): boolean;
+/**
+ * The posthog-react-native constructor options for a config. Pure, so the smoke test can lock
+ * the privacy choices without a device.
+ */
+export declare function buildNativeOptions(config: {
+    host: string;
+    featureFlags: boolean;
+}): {
+    host: string;
+    defaultOptIn: boolean;
+    personProfiles: string;
+    captureAppLifecycleEvents: boolean;
+    enableSessionReplay: boolean;
+    preloadFeatureFlags: boolean;
+    disableRemoteFeatureFlags: boolean;
+    disableSurveys: boolean;
+};
+export {};

package/dist/types/site-events.d.ts

@@ -0,0 +1,16 @@
+import type { EventName, EventProperties } from "./event-registry.ts";
+declare global {
+    interface Window {
+        dataLayer?: unknown[];
+    }
+}
+/**
+ * Pushes a catalogue event (lead_submitted, whatsapp_click, calculator_use, phone_click...) to
+ * dataLayer for a Tag Manager trigger, carrying the visitor's first and last acquisition channel
+ * and ai_source. Nothing is pushed until the visitor has granted analytics consent; a name that is
+ * neither in the catalogue nor passed to registerEvents throws. When initSiteAnalytics has run, the
+ * event goes to PostHog too, held until PostHog starts, cookieless and anonymous without consent,
+ * as on the portal. Returns whether it was pushed to dataLayer.
+ */
+export declare function trackSiteEvent(name: EventName, props?: EventProperties): boolean;
+export declare function registerEvents(names: Iterable<EventName>): void;

package/dist/types/site-posthog-snippet.d.ts

@@ -0,0 +1,27 @@
+declare const QUEUED_METHODS: readonly ["capture", "register", "opt_in_capturing", "opt_out_capturing"];
+type QueuedMethod = (typeof QUEUED_METHODS)[number];
+type SnippetOptions = {
+    api_host: string;
+};
+type SnippetMethods = {
+    [method in QueuedMethod]: (...args: unknown[]) => void;
+};
+type SnippetParts = SnippetMethods & {
+    _i: unknown[];
+    __SV: number;
+    people: unknown[];
+    init: (token: string, options: SnippetOptions) => void;
+};
+type SnippetQueue = unknown[] & SnippetParts;
+type SnippetApi = {
+    init: (token: string, options: SnippetOptions) => void;
+} & {
+    [method in QueuedMethod]?: (...args: unknown[]) => void;
+};
+declare global {
+    interface Window {
+        posthog?: SnippetQueue;
+    }
+}
+declare const posthog: SnippetApi;
+export default posthog;