SDK API reference

export declare const APP_EVENTS_CONTRACT: "aniviewz.app-events.v1";

export interface QueueStorage {
  load(): Promise<string | null>;
  save(v: string): Promise<void>;
  clear(): Promise<void>;
}

export interface AppEvent {
  type: "placement_rendered" | "placement_click";
  placementId: string;
  idempotencyKey: string;
  createdAt: number;
}

export type Send = (
  e: AppEvent,
  signal: AbortSignal,
) => Promise<"ACCEPTED" | "DUPLICATE" | "RETRY" | "DROP">;

export declare function createAppQueue(o: {
  storage: QueueStorage;
  send: Send;
  max?: number;
  maxAgeMs?: number;
  now?: () => number;
}): {
  setConsent(v: boolean): Promise<void>;
  enqueue(e: Omit<AppEvent, "createdAt">): Promise<boolean>;
  /** Called when online / app foregrounded or backgrounded. Stops on RETRY, keeps order. */
  flush(): Promise<{
    sent: number;
    remaining: number;
  }>;
  cancel(): void;
  teardown(): Promise<void>;
};
/** Strict validator for one app event (debugger + native parity). Returns a list of problems. */

export declare function validateAppEvent(raw: unknown): string[];

export declare const EVENT_TYPES: readonly [
  "placement_rendered",
  "placement_click",
  "page_view",
  "declared_outcome",
];

export type EventType = (typeof EVENT_TYPES)[number];

export type EventClassName = "EXPOSURE" | "INTERACTION" | "PAGE_VIEW" | "DECLARED_OUTCOME";

export declare const EVENT_CLASS: Record<EventType, EventClassName>;

export declare const OUTCOME_TYPES: readonly [
  "lead_submitted",
  "signup",
  "add_to_cart",
  "purchase_declared",
  "download",
  "contact_request",
];
/** Developer namespace: x.<namespace>.<name>, lower-case. */

export declare const CUSTOM_OUTCOME: RegExp;
/** Value/currency allowed only for these outcome kinds (and custom ones). */

export declare const VALUE_OUTCOMES: Set<string>;

export declare const isOutcomeType: (t: string) => boolean;

export declare const valueAllowed: (t: string) => boolean;

export declare const SAFE_ID: RegExp;

export declare const PAGE_REF: RegExp;

export declare const MAX_PAGE_REF = 120;
/**
 * Normalises a caller-declared page path/template: strips query and hash, rejects full URLs,
 * PII-like characters and long digit runs. Returns null when it cannot be made safe.
 */

export declare function cleanPageRef(input: string): string | null;

export declare const SDK_VERSION: "0.1.0-local";

export declare const CONTRACT: "aniviewz.sdk.v1";

export type Scope = "READ_ONLY" | "EVENT_INGEST";

export type Environment = "TEST_ONLY" | "PRODUCTION";

export type ErrorCode =
  | "INVALID_CONFIG"
  | "SECRET_IN_PUBLIC_CONFIG"
  | "NOT_INITIALIZED"
  | "TORN_DOWN"
  | "CONSENT_REQUIRED"
  | "SCOPE_DENIED"
  | "PRODUCTION_INGEST_NOT_ACTIVATED"
  | "CAPABILITY_UNSUPPORTED"
  | "CONTRACT_MISMATCH"
  | "ABORTED"
  | "NETWORK"
  | "HTTP_4XX"
  | "HTTP_5XX"
  | "RETRIES_EXHAUSTED"
  | "SERVICE_NOT_ISSUED";

export declare class AniViewzError extends Error {
  readonly code: ErrorCode;
  readonly requestId: string | null;
  readonly status: number | null;
  /** Server error code, when the server sent one (e.g. ORIGIN_NOT_ALLOWED). */
  readonly detail: string | null;
  constructor(
    code: ErrorCode,
    requestId?: string | null,
    status?: number | null,
    /** Server error code, when the server sent one (e.g. ORIGIN_NOT_ALLOWED). */
    detail?: string | null,
  );
}

export interface Config {
  publicId: string;
  environment: Environment;
  scopes: Scope[];
  baseUrl: string;
  capabilities?: string[];
  consent?: {
    measurement: boolean;
    purpose: string;
    policyVersion: string;
  } | null;
  retry?: {
    attempts: number;
    baseDelayMs: number;
    maxDelayMs: number;
  };
  fetch?: typeof fetch;
  sleep?: (ms: number) => Promise<void>;
  newId?: () => string;
}

export declare function validateConfig(c: Config): ErrorCode | null;

export interface Placement {
  placementId: string;
  revision: number;
  testOnly: boolean;
}

export interface PlacementEvent {
  type: "placement_rendered" | "placement_click";
  placementId: string;
  idempotencyKey?: string;
}
/** Opt-in page view: caller-declared path/template only (query/hash stripped). */

export interface PageViewEvent {
  type: "page_view";
  page: string;
  optIn: true;
  idempotencyKey?: string;
}
/** Self-reported outcome declared by the site. Never a verified conversion. */

export interface DeclaredOutcomeEvent {
  type: "declared_outcome";
  outcomeType: string;
  value?: {
    amount: number;
    currency: string;
  };
  placementId?: string;
  idempotencyKey?: string;
}

export type SdkEvent = PlacementEvent | PageViewEvent | DeclaredOutcomeEvent;

export interface Client {
  readonly requestLog: readonly string[];
  negotiate(signal?: AbortSignal): Promise<{
    contract: string;
    capabilities: string[];
    status: string;
  }>;
  getPlacement(placementId: string, signal?: AbortSignal): Promise<Placement>;
  track(
    e: SdkEvent,
    signal?: AbortSignal,
  ): Promise<{
    accepted: boolean;
    idempotencyKey: string;
  }>;
  /** Ask the server to delete this client's already-sent TEST_ONLY events (consent withdrawal). */
  withdraw(
    idempotencyKeys: string[],
    requestKey?: string,
    signal?: AbortSignal,
  ): Promise<{
    deleted: number;
    replay: boolean;
  }>;
  setConsent(c: Config["consent"]): void;
  teardown(): void;
}

export declare function init(config: Config): Client;
import { type Client } from "./index";

export interface PixelOptions {
  client: Client;
  maxQueue?: number;
  newKey?: () => string;
}

export declare function createPixel(o: PixelOptions): {
  readonly debugLog: readonly string[];
  readonly queued: number;
  readonly pageViewsEnabled: boolean;
  grantConsent(policyVersion: string): void;
  /** Withdrawal: stop immediately, disable page views and discard anything not yet sent. */
  revokeConsent(): void;
  /** Explicit opt-in for page_view (still requires consent). Off by default. */
  enablePageViews(): void;
  disablePageViews(): void;
  /** Keys of events the server accepted (needed for a withdrawal deletion request). */
  readonly sentKeys: readonly string[];
  /** Withdrawal + server deletion: purge the local queue, then delete already-sent TEST_ONLY events. */
  withdrawAndDelete(
    requestKey?: string | undefined,
    signal?: AbortSignal | undefined,
  ): Promise<{
    deleted: number;
    replay: boolean;
  }>;
  placementRendered: (id: string) => boolean;
  placementClick: (id: string) => boolean;
  /** Opt-in page view of a caller-declared path/template (e.g. "/listing/:id"). Query/hash stripped. */
  pageView(page: string): boolean;
  /** Self-reported outcome. Classified DECLARED_OUTCOME — never a verified conversion. */
  declareOutcome(
    outcomeType: string,
    opts?: {
      value?:
        | {
            amount: number;
            currency: string;
          }
        | undefined;
      placementId?: string | undefined;
    },
  ): boolean;
  flush(signal?: AbortSignal | undefined): Promise<
    {
      key: string;
      accepted: boolean;
      error?: string | undefined;
    }[]
  >;
};
import { type ReactNode } from "react";
import { type Client, type Config, type ErrorCode, type Placement } from "./index";

export declare function AniViewzProvider(props: {
  config: Config;
  children?: ReactNode;
}): import("react").FunctionComponentElement<import("react").ProviderProps<Client | null>> | null;

export declare function useAniViewzClient(): Client;

export type PlacementState =
  | {
      status: "loading";
    }
  | {
      status: "ready";
      placement: Placement;
    }
  | {
      status: "error";
      code: ErrorCode;
      httpStatus: number | null;
      serverCode: string | null;
    };

export declare function usePlacement(placementId: string): PlacementState;

export interface ServerVerifierOptions {
  publicId: string;
  /** Origin registered on the public ID allowlist (e.g. https://partner.example). */
  origin: string;
  baseUrl: string;
  fetch?: typeof fetch;
  newId?: () => string;
  timeoutMs?: number;
}

export interface VerifiedPlacement {
  placementId: string;
  title: string;
  revision: number;
  testOnly: boolean;
  requestId: string;
}

export declare function createServerVerifier(o: ServerVerifierOptions): {
  verifyPlacement(
    placementId: string,
    signal?: AbortSignal | undefined,
  ): Promise<VerifiedPlacement>;
};