@intenque/network-sdk 0.0.0-stage → 2.2.0-beta.2

package/dist/react/index.d.cts

@@ -0,0 +1,421 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { S as SiteChannel } from '../constants-C_6Zxu_k.cjs';
+export { D as DEFAULT_CDN_BASE, M as MANIFEST_SCHEMA_MAJOR, a as SDK_VERSION } from '../constants-C_6Zxu_k.cjs';
+
+/**
+ * Trusted root public keys — spec §4.5 (`rootPublicKeys`, "an array to allow overlap").
+ *
+ * The root private key is generated offline by the owner (`npm run keys -- root:new`) and never reaches the hub; the
+ * public JWK printed by that command is what goes here. The hub holds the same list in `MANIFEST_ROOT_PUBLIC_KEYS`
+ * and refuses to certify or sign with a key the SDK would reject.
+ *
+ * HOW PRODUCTION ROOTS ARE ADDED (release step, see docs/install-guide.md "Adding a production root"):
+ *   1. `npm run keys -- root:new --kid root-<year> --out <file>` on the owner's machine; store the private file in
+ *      the password manager (+ printed backup).
+ *   2. Append `{ kid: 'root-<year>', jwk: { kty: 'EC', crv: 'P-256', x, y } }` to `rootPublicKeys` below.
+ *   3. Release an SDK **minor** (`npm version minor` / changeset); every site picks it up as an ordinary dependency
+ *      bump. Removing an old root is a **major** (§4.5 "Root rotation").
+ *   4. Add the same entry to `MANIFEST_ROOT_PUBLIC_KEYS` on the hub, certify the manifest key under the new root.
+ *
+ * `rootPublicKeys` is EMPTY up to 2.2.0-beta.1: no production root exists yet (nothing is published in production). A
+ * site that does not pass `manifestRootKeys` therefore trusts no manifest and renders nothing — the correct result
+ * for an environment that has no signed content. The development root below is exported separately and is only ever
+ * referenced explicitly (`network-sdk init --root-keys …` writes it into `manifestRootKeys` of the site's
+ * `network.config.js`); it must never be merged into `rootPublicKeys`, because its private key lives on a developer
+ * machine and the dev bucket (`network-dev/v1`) is not production content.
+ */
+type RootPublicKey = {
+    kid: string;
+    jwk: {
+        kty: 'EC';
+        crv: 'P-256';
+        x: string;
+        y: string;
+    };
+};
+/** Production roots (none yet; see the file comment). */
+declare const rootPublicKeys: readonly RootPublicKey[];
+/**
+ * The DEVELOPMENT root (hub `.env` `MANIFEST_ROOT_PUBLIC_KEYS`, dev bucket `network-dev/v1`, kid `root-dev-a01e0d`).
+ * Public key, not a secret. Used by the test suite and by `init --root-keys` for the JCM pilot; never trusted by
+ * default.
+ */
+declare const DEV_ROOT_PUBLIC_KEYS: readonly RootPublicKey[];
+
+/**
+ * `defineNetworkConfig` — spec §6.2 (the only per-site file is `src/network.config.js`) and §4.2 / §6.3 URL precedence:
+ * `config.manifestUrl ?? (config.cdnBase ?? fallback.cdnBase ?? DEFAULT_CDN_BASE) + '/' + (preview?) + 'sites/<siteKey>/manifest.json'`.
+ * It also derives `capture = { siteKey, endpoint: fallback.analytics.endpoint, consent, consentMode }` for `main.jsx`
+ * (§5.3) so nothing is assembled by hand. Release 2b review round 2: the endpoint is the fallback's whatever its
+ * `analytics.landings` says — the bundled copy is refreshed only by a site build, while §2.2 makes the switch a publish;
+ * the hub refuses a landing for a destination whose live `landings` is off (`disabled`, 0 operations). It is `null`
+ * only for a DEV build of a production-channel site whose endpoint is not a local hub (the v2.2 changelog's "SDK
+ * silent on localhost / DEV"). Pure: no DOM, no network.
+ */
+
+type ConsentState = 'granted' | 'denied' | null;
+/** §6.2: the consent adapter contract, stated once. */
+type ConsentAdapter = {
+    get: () => ConsentState;
+};
+type ConsentMode = 'session-default' | 'require-consent';
+declare const THEME_SLOTS: readonly ["section", "container", "heading", "accentWord", "subheading", "grid", "card", "imageBox", "image", "placeholder", "body", "name", "meta", "description", "button", "buttonIcon"];
+type ThemeSlot = (typeof THEME_SLOTS)[number];
+/** §6.1 headless className slots: the site's own Tailwind classes live in the site's source. */
+type NetworkTheme = Partial<Record<ThemeSlot, string>>;
+type NetworkEvent = {
+    type: 'directory';
+    payload: {
+        source: string;
+        revision: number | null;
+        flags: string[];
+    };
+} | {
+    type: 'impression';
+    payload: {
+        ids: string[];
+        revision: number | null;
+    };
+}
+/** `href` is the at-rest link (UTMs only): the click id never reaches the site's own tracker (§5.3). */
+ | {
+    type: 'click';
+    payload: {
+        id: string;
+        href: string;
+        via: string;
+    };
+}
+/** §5.1: a beacon was handed to the browser (`sent`) or could not be; `why` is the impression's send reason. */
+ | {
+    type: 'signal';
+    payload: {
+        kind: 'impression' | 'click';
+        sent: boolean;
+        why?: string;
+    };
+};
+type NetworkConfigInput = {
+    /** 1) per site. When omitted the SDK uses `fallback.site` and flags `sitekey_from_fallback` (§5.1). */
+    siteKey?: string | undefined;
+    /** `'preview'` → `/network/v1/preview/sites/…` on the production CDN. Default `'production'`. */
+    channel?: SiteChannel | string | undefined;
+    /** Optional override of `DEFAULT_CDN_BASE` (normally the manifest's `cdnBase` wins once loaded). */
+    cdnBase?: string | undefined;
+    /** Full override: the separate staging hub only, together with `manifestRootKeys`. */
+    manifestUrl?: string | undefined;
+    /** `src/data/network.fallback.json`, written by `network-sdk sync-fallback`; also the rollback floor. */
+    fallback?: unknown;
+    /** Staging / dev override of the compiled `rootPublicKeys` (§4.5). */
+    manifestRootKeys?: readonly RootPublicKey[] | undefined;
+    /** 2) per site adapter; omitted → treated as `null`. */
+    consent?: ConsentAdapter | undefined;
+    consentMode?: ConsentMode | undefined;
+    /** 3) per site brand classes. */
+    theme?: NetworkTheme | undefined;
+    /** Drop the `inr-*` default class names (Tailwind-only sites). */
+    unstyled?: boolean | undefined;
+    /** Defaults to true (§4.5). `false` skips the signature (schema + identity still run); development only. */
+    verifySignature?: boolean | undefined;
+    /** §4.6 insecure contexts: render the fallback unverified when `crypto.subtle` is missing in production. */
+    allowInsecureFallback?: boolean | undefined;
+    /** The site's `import.meta.env.DEV`: enables the single `console.warn` per failure and the insecure-context skip. */
+    dev?: boolean | undefined;
+    /** Mirror events into the site's own tracker (§6.3). */
+    onEvent?: ((event: NetworkEvent) => void) | undefined;
+};
+type CaptureConfig = {
+    siteKey: string;
+    endpoint: string | null;
+    consent: ConsentAdapter | undefined;
+    consentMode: ConsentMode;
+};
+type NetworkConfig = {
+    siteKey: string;
+    siteKeyFromFallback: boolean;
+    channel: SiteChannel;
+    manifestUrl: string;
+    fallback: unknown;
+    roots: readonly RootPublicKey[];
+    consent: ConsentAdapter | undefined;
+    consentMode: ConsentMode;
+    theme: NetworkTheme;
+    unstyled: boolean;
+    verifySignature: boolean;
+    allowInsecureFallback: boolean;
+    dev: boolean;
+    onEvent: ((event: NetworkEvent) => void) | undefined;
+    /** For `captureReferral(networkConfig.capture)` in `main.jsx` (§5.3). */
+    capture: CaptureConfig;
+};
+declare function defineNetworkConfig(input: NetworkConfigInput): NetworkConfig;
+
+type PublicJwk$1 = {
+    kty: 'EC';
+    crv: 'P-256';
+    x: string;
+    y: string;
+};
+type ManifestImage = {
+    src: string;
+    src2x: string;
+    alt: string;
+    width: 640;
+    height: 360;
+};
+type Instrumentation = 'none' | 'landings' | 'conversions';
+type ManifestBusiness = {
+    id: string;
+    idx: number;
+    name: string;
+    description: string;
+    url: string;
+    domain: string;
+    image: ManifestImage;
+    category: string | null;
+    location: string | null;
+    region: string | null;
+    tags: string[];
+    pinned: boolean;
+    position: number;
+    instrumentation: Instrumentation;
+};
+type ManifestSigner = {
+    kid: string;
+    jwk: PublicJwk$1;
+    notBefore: string;
+    notAfter: string;
+    rootKid: string;
+    rootSig: string;
+    revokedKids: string[];
+};
+type ManifestSig = {
+    alg: 'ES256';
+    kid: string;
+    value: string;
+};
+type ManifestAnalytics = {
+    enabled: boolean;
+    endpoint: string;
+    impressions: boolean;
+    clicks: boolean;
+    landings: boolean;
+    samplePermille: number;
+    token: string;
+};
+type ManifestLinks = {
+    utmMedium: string;
+    utmCampaign: string;
+    utmSource: string;
+    refParam: string;
+    nofollow: boolean;
+};
+type Manifest = {
+    schema: 2;
+    revision: number;
+    publishedAt: string;
+    site: string;
+    siteIndex: number;
+    channel: 'production' | 'preview';
+    cdnBase: string;
+    minSdkVersion: string;
+    analytics: ManifestAnalytics;
+    links: ManifestLinks;
+    section: {
+        title: string;
+        subtitle: string | null;
+    };
+    businesses: ManifestBusiness[];
+    signer: ManifestSigner;
+    sig: ManifestSig;
+};
+/** Returns the typed manifest, or `null` when the input is not a valid schema-2 manifest. Never throws. */
+declare function parseManifest(input: unknown): Manifest | null;
+
+type SendReason = 'timer' | 'click' | 'hidden' | 'pagehide';
+type SignalKind = 'impression' | 'click';
+/** One page view (§2.4 `pv`): the impression tracker plus the fields every click of the page view carries. */
+type PageView = {
+    readonly pv: string;
+    /** Mount epoch ms (§2.4 `m`): the same value on the impression and every click of this `pv`. */
+    readonly m: number;
+    /** §5.1 sampling, rolled once: `1` = impressions measured for this page view. Clicks always go, with `smp: 0`. */
+    readonly smp: 0 | 1;
+    readonly hd: number;
+    /** An impression for this `pv` has been sent (survives bfcache with the heap): the click's `ip`. */
+    readonly sent: boolean;
+    /** Rendered slugs in order: `pos` on the impression items and on the click signal is the index here. */
+    setOrder(ids: readonly string[]): void;
+    /** The clicked card's position: its rendered index (the hub requires `pos < itemCount`). */
+    pos(b: ManifestBusiness): number;
+    /** Registers (or, with `null`, forgets) a card element; works before and after `start()`. Dwell is kept per slug. */
+    observe(slug: string, el: Element | null): void;
+    /** From the component's effect with the `<section>` element; honours the §5.1 prerender guard. */
+    start(section: Element | null): void;
+    /** Unmount (SPA route change): a due impression is sent first (`hidden`), then everything is detached. */
+    stop(): void;
+    /** §5.1 common payload fields, shared with the click signal (every ms / epoch value an integer). */
+    common(now: number): Record<string, unknown>;
+    post(kind: SignalKind, body: Record<string, unknown>, why?: SendReason | null): boolean;
+    /** The synchronous flush before a click signal; returns `ip` (an impression exists for this page view). */
+    flushForClick(): boolean;
+    /**
+     * Sends the impression when it is due: never when sampled out or unmeasured; the first send needs something to
+     * have been on screen; a re-send only from `hidden` / `pagehide` and only when a `seen` / `ms` / `fv` changed.
+     */
+    flush(why: SendReason): boolean;
+};
+
+type DirectorySource = 'live' | 'fallback' | 'empty';
+/** §5.1 flag vocabulary (the subset the directory path sets) plus the SDK-local `fetch_fail` / `insecure_context`. */
+type DirectoryFlag = 'sig_fail' | 'sig_revoked' | 'rev_rollback' | 'stale_cache' | 'fallback_invalid' | 'fallback_key_expired' | 'sitekey_from_fallback' | 'sdk_outdated' | 'fetch_fail' | 'insecure_context';
+type DirectoryState = {
+    businesses: ManifestBusiness[];
+    loading: boolean;
+    source: DirectorySource;
+    revision: number | null;
+    manifest: Manifest | null;
+    flags: DirectoryFlag[];
+    /**
+     * The revision of the live manifest rejected below the floor (`rev_rollback`) or first received stale and resolved
+     * by the reload (`stale_cache`); sent as `rr` with those flags so the hub can judge the `manifest_replay` tolerance
+     * (§4.6). `null` otherwise.
+     */
+    rr: number | null;
+};
+type LoaderDeps = {
+    fetch?: typeof fetch | undefined;
+    now?: () => Date;
+    hostname?: string;
+    warn?: (message: string) => void;
+};
+declare function loadDirectory(config: NetworkConfig, deps?: LoaderDeps): Promise<DirectoryState>;
+
+type ClickVia = 'click' | 'auxclick' | 'contextmenu' | 'drag';
+type ClickButton = 0 | 1 | 2;
+type SignalHooks = {
+    /** The section rendered these cards (the Phase 1 `impression` `onEvent` mirror, kept as is). */
+    rendered: (ids: string[]) => void;
+    /** `pointerdown`: mints the card's click id; returns the rewritten href, or `null` when clicks are off. */
+    pointerDown: (business: ManifestBusiness, href: string) => string | null;
+    /**
+     * `click` / `auxclick` / `contextmenu` / `dragstart` (or a custom card's `trackClick`): flushes the impression, sends
+     * the click signal with the id minted at pointerdown (minted now for a keyboard activation) and returns the href to
+     * navigate with (`href` itself when clicks are off).
+     */
+    click: (business: ManifestBusiness, href: string, via: ClickVia, button: ClickButton) => string;
+    /** Card element registration for per-card viewability (ref callbacks). */
+    observe: (slug: string, el: Element | null) => void;
+    /** Rendered order: `pos` on the impression items and on the click signal. */
+    setOrder: (ids: readonly string[]) => void;
+    /** From the component's effect with the `<section>` element; the cleanup calls `stop()`. */
+    start: (section: Element | null) => void;
+    stop: () => void;
+    /** `null` when analytics is off in the manifest, nothing is loaded, or the runtime has no CSPRNG. */
+    readonly page: PageView | null;
+};
+
+declare function NetworkProvider(props: {
+    config: NetworkConfig;
+    children?: ReactNode;
+}): react.JSX.Element;
+
+/** Structural event type: React synthetic events and native DOM events both fit. */
+type LinkEvent = {
+    currentTarget: unknown;
+    button?: number;
+};
+type NetworkLinkProps = {
+    href: string;
+    target: '_blank';
+    rel: string;
+    'aria-label': string;
+    onPointerDown: (e: LinkEvent) => void;
+    onClick: (e: LinkEvent) => void;
+    onAuxClick: (e: LinkEvent) => void;
+    onContextMenu: (e: LinkEvent) => void;
+    onDragStart: (e: LinkEvent) => void;
+    /** Release 2b review round 2: the end of the gesture starts the restore of the at-rest href. */
+    onPointerUp: (e: LinkEvent) => void;
+    onPointerCancel: (e: LinkEvent) => void;
+    onBlur: (e: LinkEvent) => void;
+};
+type NetworkLink = {
+    href: string;
+    linkProps: NetworkLinkProps;
+    /**
+     * For a custom control that is not an `<a {...linkProps}>`: sends the click signal (flushing the impression first)
+     * and returns the href to navigate with (`…&inr=<clickId>` when the manifest enables clicks).
+     */
+    trackClick: (via?: ClickVia, button?: ClickButton) => string;
+    /** Ref callback for the card element: per-card viewability (`seen` / `ms` / `fv`, §5.1). Stable per card. */
+    observe: (el: Element | null) => void;
+};
+declare function buildHref(url: string, links: ManifestLinks, slug: string): string;
+/** 2.0.0's second argument (`trackClick` returned its result); kept as a deprecated mirror in 2.x. */
+type LegacyOnClick = (business: ManifestBusiness, href: string, via: string) => string;
+declare function useNetworkLink(business: ManifestBusiness, hooks?: SignalHooks | LegacyOnClick | null): NetworkLink;
+
+declare const HEADING_ID = "discover-businesses-heading";
+/** `href`, `linkProps` (spread onto the card's `<a>`), `trackClick(via)` and `observe` (the card's `ref`). */
+type RenderCardArgs = NetworkLink;
+type DiscoverBusinessesProps = {
+    title?: string | undefined;
+    subtitle?: string | null | undefined;
+    maxItems?: number | undefined;
+    renderCard?: ((business: ManifestBusiness, args: RenderCardArgs) => ReactNode) | undefined;
+    theme?: NetworkTheme | undefined;
+    unstyled?: boolean | undefined;
+    onEvent?: ((event: NetworkEvent) => void) | undefined;
+    /** Use without `<NetworkProvider>`: pass the config directly. */
+    config?: NetworkConfig | undefined;
+};
+declare function DiscoverBusinesses(props: DiscoverBusinessesProps): react.JSX.Element | null;
+
+declare function useNetworkDirectory(override?: NetworkConfig | null): DirectoryState;
+
+declare function canonicalJson(value: unknown): string;
+
+type PublicJwk = {
+    kty: 'EC';
+    crv: 'P-256';
+    x: string;
+    y: string;
+};
+
+type RootKey = {
+    kid: string;
+    jwk: PublicJwk;
+};
+type ManifestVerifyReason = 'malformed' | 'identity' | 'root_unknown' | 'root_sig' | 'window' | 'kid_mismatch' | 'sig' | 'revoked';
+type ManifestVerifyResult = {
+    ok: true;
+    manifest: Manifest;
+} | {
+    ok: false;
+    reason: ManifestVerifyReason;
+};
+type VerifyManifestOptions = {
+    /** Trusted root public keys (`rootPublicKeys` or `manifestRootKeys`); empty → `root_unknown`. */
+    roots: readonly RootKey[];
+    /** Must be a finite date. */
+    now: Date;
+    /** `site`, `channel` and `links.utmSource` must match. */
+    expect: {
+        site: string;
+        channel: 'production' | 'preview';
+    };
+    /** `live`: window applies and the trusted `revokedKids` is required. `fallback`: only the window is skipped. */
+    source: 'live' | 'fallback';
+    revokedKids?: readonly string[];
+};
+declare function verifyManifest(input: unknown, opts: VerifyManifestOptions): Promise<ManifestVerifyResult>;
+/**
+ * The bytes entry point for a fetched manifest: refuses input over 24 KB before decoding or parsing, decodes fatal
+ * UTF-8 **keeping** a leading BOM (which then fails to parse), requires `canonicalJson(JSON.parse(raw)) === raw`
+ * (no whitespace, sorted keys, no duplicate keys, no alternative escapes), then `verifyManifest`.
+ */
+declare function verifyManifestBytes(raw: string | Uint8Array, opts: VerifyManifestOptions): Promise<ManifestVerifyResult>;
+
+export { type CaptureConfig, type ClickButton, type ClickVia, type ConsentAdapter, type ConsentMode, type ConsentState, DEV_ROOT_PUBLIC_KEYS, type DirectoryFlag, type DirectorySource, type DirectoryState, DiscoverBusinesses, type DiscoverBusinessesProps, HEADING_ID, type LinkEvent, type Manifest, type ManifestBusiness, type ManifestVerifyReason, type ManifestVerifyResult, type NetworkConfig, type NetworkConfigInput, type NetworkEvent, type NetworkLink, type NetworkLinkProps, NetworkProvider, type NetworkTheme, type RenderCardArgs, type RootKey, type RootPublicKey, THEME_SLOTS, type ThemeSlot, buildHref, canonicalJson, defineNetworkConfig, loadDirectory, parseManifest, rootPublicKeys, useNetworkDirectory, useNetworkLink, verifyManifest, verifyManifestBytes };