@trackstall/sdk 0.1.0

package/index.d.ts

@@ -0,0 +1,843 @@
+// Generated by dts-bundle-generator v9.5.1
+
+/**
+ * Canonical attribution schema shared between the TrackStall SDK (clients that
+ * integrate into any app) and the Node/Lambda server. All types here are
+ * runtime-agnostic: no Hermes-only APIs, no Node-only APIs.
+ *
+ * A single `AttributionEvent` fans out to:
+ *   - Meta SDK (in-app `logEvent`)
+ *   - TikTok Business SDK (in-app `trackEvent`)
+ *   - Meta Conversions API (server)
+ *   - TikTok Events API (server)
+ *   - TrackStall's own Mongo store (reporting / dashboard)
+ *
+ * Cross-channel deduplication relies on `eventId` being identical across all
+ * destinations — see `eventId.ts`.
+ *
+ * Multi-tenancy: every event carries an `appId`. The server scopes every read
+ * and write by it, and resolves the per-app provider credentials (Meta CAPI
+ * token + pixel, TikTok EAPI token + pixel) from it.
+ */
+/** ISO 4217 currency code (e.g. "USD", "BRL"). Always upper-case. */
+export type Currency = string;
+/** Runtime platform the event was emitted from. */
+export type Platform = "ios" | "android" | "web";
+/** Origin store of a paid transaction. */
+export type StorePlatform = "apple" | "google" | "stripe" | "web" | "unknown";
+/** Snapshot of App Tracking Transparency status at event time. */
+export type AttStatus = "authorized" | "denied" | "restricted" | "undetermined" | "unavailable";
+/**
+ * Canonical event names recognized by TrackStall. These are vendor-neutral;
+ * adapters map them to vendor-specific names at the edge (e.g. `subscribe` →
+ * `fb_mobile_subscribe` on Meta SDK, `Subscribe` on Meta CAPI, `subscribe` on
+ * TikTok Events API).
+ *
+ * Because TrackStall is multi-tenant and serves arbitrary apps, the event
+ * `name` accepts any string too — apps can emit custom events while still
+ * getting autocomplete on the canonical set. Custom names pass through to
+ * vendor `custom_data` / `properties` and to the dashboard as-is.
+ */
+export type CanonicalEventName = "install" | "app_open" | "onboarding_started" | "onboarding_step" | "onboarding_completed" | "paywall_shown" | "paywall_dismissed" | "start_checkout" | "trial_started" | "subscribe" | "purchase" | "renewal" | "cancellation" | "expiration" | "refund" | "add_to_cart" | "level_complete" | "tutorial_complete" | "content_view";
+/**
+ * Event name as accepted on the wire: a canonical name (autocompleted) OR any
+ * custom string the integrating app chooses. `(string & {})` keeps the union
+ * literals in IntelliSense while still allowing arbitrary strings.
+ */
+export type AttributionEventName = CanonicalEventName | (string & {});
+/**
+ * Identifiers and PII for the acting user. All PII fields (`email`, `phone`)
+ * are sent as raw values through the pipeline and hashed at the adapter layer
+ * right before being shipped to Meta CAPI / TikTok Events API — never logged
+ * raw, never persisted raw.
+ */
+export interface AttributionUser {
+	/** Stable internal user id supplied by the integrating app. */
+	userId?: string;
+	/** iOS Identifier for Vendor (always available, no ATT required). */
+	idfv?: string;
+	/** iOS Advertising Identifier (only available when ATT === 'authorized'). */
+	idfa?: string;
+	/** Google Advertising ID (Android only). */
+	gaid?: string;
+	/** PII — hashed at adapter boundary (Meta `em`, TikTok `email`). */
+	email?: string;
+	/** PII — hashed at adapter boundary (Meta `ph`, TikTok `phone_number`). */
+	phone?: string;
+	/** ISO 3166-1 alpha-2, lower-case (e.g. "br", "us"). */
+	country?: string;
+	/** BCP-47 locale (e.g. "pt-BR", "en-US"). */
+	locale?: string;
+	/** ATT snapshot at event time. */
+	attStatus?: AttStatus;
+	/**
+	 * Client IP as observed by the server at request time. Populated SERVER-side
+	 * from the request socket — never trust a wire value. Boosts Event Match
+	 * Quality (Meta `client_ip_address`, TikTok `ip`). Never logged/persisted raw
+	 * (PII redaction strips it before Mongo).
+	 */
+	ipAddress?: string;
+	/** User agent from the same request as `ipAddress`. Server-side capture only. */
+	userAgent?: string;
+	/** Meta browser cookie (`_fbp`). Sent to Meta CAPI as `user_data.fbp`. */
+	fbp?: string;
+	/** Meta click cookie (`_fbc`). Highest-impact field for paid Meta traffic. */
+	fbc?: string;
+	/** TikTok click id (`ttclid`). Deterministic match key for paid TikTok. */
+	ttclid?: string;
+	/** TikTok pixel cookie (`_ttp`). */
+	ttp?: string;
+}
+/**
+ * Monetary information for revenue-bearing events. The server uses `netValue`
+ * to teach the ad algorithm; do not use `grossValue` for optimization (it
+ * inflates LTV by the store's commission).
+ */
+export interface RevenueData {
+	/** What the user paid, before any commission. Used for accounting / BI. */
+	grossValue: number;
+	/** What the app actually receives after store fee. Used for optimization. */
+	netValue: number;
+	/** ISO 4217, upper-case. */
+	currency: Currency;
+	/** Where the money came from. Determines the default fee rate. */
+	store: StorePlatform;
+	/** Store-issued transaction id (App Store original_transaction_id, etc.). */
+	transactionId?: string;
+}
+/**
+ * Optional marketing attribution context. Populated by the server when a
+ * webhook/event arrives (joining `userId` → first-touch campaign captured at
+ * install) or by deep-link adapters on the client.
+ */
+export interface AttributionContext {
+	campaignId?: string;
+	adsetId?: string;
+	adId?: string;
+	creativeId?: string;
+	source?: "meta" | "tiktok" | "google" | "organic" | "referral" | "unknown";
+	/** Stable token returned by `POST /v1/click`. Joins user → click. */
+	clickToken?: string;
+	utmSource?: string;
+	utmMedium?: string;
+	utmCampaign?: string;
+	utmContent?: string;
+	utmTerm?: string;
+	/** 1.0 = deterministic (Universal Link); <1.0 = probabilistic fingerprint. */
+	matchConfidence?: number;
+	matchMethod?: "universal_link" | "fingerprint" | "manual" | "none";
+}
+/**
+ * The single canonical event shape that flows through every layer. Adapters at
+ * the edge translate it to vendor formats; the Mongo collection stores it as-is
+ * for reporting / dashboard.
+ */
+export interface AttributionEvent {
+	/**
+	 * Tenant scope. Every read/write on the server is filtered by this, and the
+	 * per-app provider credentials are resolved from it.
+	 */
+	appId: string;
+	/**
+	 * Deterministic event id (UUID v5) — see `eventId.ts`. Identical across the
+	 * in-app SDK, Meta CAPI and TikTok Events API for a given underlying action.
+	 * Powers the dedup that lets us double-send for resilience without
+	 * double-counting.
+	 */
+	eventId: string;
+	name: AttributionEventName;
+	/** Unix epoch in **seconds** (Meta CAPI / TikTok EAPI convention). */
+	timestamp: number;
+	platform: Platform;
+	user: AttributionUser;
+	/** Present on monetization events. */
+	revenue?: RevenueData;
+	/** Store product id (e.g. "pro_weekly"). */
+	productId?: string;
+	/** Marketing attribution joined on the server side. */
+	attribution?: AttributionContext;
+	/** Free-form extras flattened into vendor `custom_data` / `properties`. */
+	properties?: Record<string, string | number | boolean | null>;
+}
+/**
+ * Subset of `AttributionEvent` callers supply when emitting an event; the
+ * orchestrator fills in `eventId`, `timestamp`, and `platform`. `appId` is
+ * resolved from the authenticated API key on the server, so the SDK does not
+ * need to send it explicitly (though it may).
+ */
+export type AttributionEventInput = Omit<AttributionEvent, "eventId" | "timestamp" | "platform" | "appId"> & {
+	appId?: string;
+	eventId?: string;
+	timestamp?: number;
+	platform?: Platform;
+};
+/** Allowed value types inside `properties` (JSON scalars only). */
+export type ProductPropertyValue = string | number | boolean | null;
+/** Lightweight device/app context captured automatically by the SDK. */
+export interface ProductEventContext {
+	appVersion?: string;
+	osVersion?: string;
+	deviceModel?: string;
+	/** BCP-47 locale (e.g. "pt-BR"). */
+	locale?: string;
+	/** ISO 3166-1 alpha-2 (e.g. "br"). */
+	country?: string;
+	/** SDK name/version that produced the event (e.g. "trackstall-js/0.1"). */
+	sdk?: string;
+}
+/**
+ * The canonical product-analytics event. One row per occurrence in the
+ * `product_events` collection; `(appId, eventId)` is the dedup key.
+ */
+export interface ProductEvent {
+	/** Tenant scope — stamped server-side from the authenticated API key. */
+	appId: string;
+	/** Unique id for dedup across SDK retries. UUID, client-generated. */
+	eventId: string;
+	/** Free-form event name chosen by the app (e.g. "screen_view"). */
+	name: string;
+	/** Unix epoch in **seconds** (same convention as attribution events). */
+	timestamp: number;
+	platform: Platform;
+	/**
+	 * Who did it: the app's stable `userId` when identified, otherwise the
+	 * SDK-generated anonymous id. Powers unique-user counts.
+	 */
+	distinctId: string;
+	/** Set when the user is identified (mirrors `distinctId` in that case). */
+	userId?: string;
+	/** Device-generated anonymous id (kept after identify for stitching). */
+	anonymousId?: string;
+	/** Optional client-managed session id for session analytics. */
+	sessionId?: string;
+	/** Free-form event payload. JSON scalars only; no PII. */
+	properties?: Record<string, ProductPropertyValue>;
+	context?: ProductEventContext;
+}
+/**
+ * Wire input accepted by `POST /v1/track`. The server stamps `appId` from the
+ * API key and fills `eventId`/`timestamp` when omitted. `distinctId` may be
+ * derived from `userId`/`anonymousId` when not set explicitly.
+ */
+export type ProductEventInput = Omit<ProductEvent, "appId" | "eventId" | "timestamp" | "distinctId"> & {
+	appId?: string;
+	eventId?: string;
+	timestamp?: number;
+	distinctId?: string;
+};
+export interface DeterministicEventIdInput {
+	/**
+	 * Tenant scope. Included in the dedup key so the same logical action in two
+	 * different apps never collides on a shared `userId`/`transactionId`.
+	 */
+	appId: string;
+	/** Stable user identifier supplied by the integrating app. */
+	userId: string;
+	eventName: AttributionEventName;
+	/**
+	 * Strongest dedup key when present — App Store `original_transaction_id`,
+	 * Play Store `purchaseToken`, Stripe `payment_intent`, etc. For non-purchase
+	 * events, prefer a stable client-generated id (persisted) so offline retries
+	 * collapse to the same `eventId`.
+	 */
+	transactionId?: string;
+	/**
+	 * Unix epoch in seconds. Including it scopes dedup to a single "occurrence"
+	 * of an otherwise idempotent action (e.g. two renewals on the same
+	 * transactionId still produce different ids). Omit for interchangeable
+	 * actions (e.g. the first `install` for a user).
+	 */
+	timestamp?: number;
+}
+/**
+ * Deterministic event id used as the dedup key across every channel (in-app
+ * SDK → ad platform pixel/SDK; backend webhook → Meta CAPI / TikTok EAPI).
+ * Same inputs always produce the same UUID.
+ */
+export declare function deterministicEventId(input: DeterministicEventIdInput): string;
+/**
+ * Non-deterministic event id for one-off events with no stable dedup key.
+ * Avoid for monetization.
+ */
+export declare function randomEventId(): string;
+export interface BuildRevenueInput {
+	/** Gross amount the user paid (default) or net amount if `netOfStoreFee`. */
+	value: number;
+	/** ISO 4217 — will be upper-cased. */
+	currency: string;
+	store: StorePlatform;
+	transactionId?: string;
+	/** Custom fee rate (0..1). Overrides `STORE_FEE_DEFAULTS[store]`. */
+	feeRateOverride?: number;
+	/** `true` if `value` is already net of the store commission. */
+	netOfStoreFee?: boolean;
+}
+/**
+ * Build a normalized `RevenueData` block.
+ *
+ * Why both `grossValue` and `netValue`:
+ *   - `grossValue` → revenue reports / BI ("the user paid R$299").
+ *   - `netValue`   → the `value` sent to Meta CAPI / TikTok EAPI, so the
+ *     optimization algorithm learns from money actually received, not the
+ *     store's cut. The single most impactful tweak after dedup.
+ */
+export declare function buildRevenue(input: BuildRevenueInput): RevenueData;
+export interface AdapterDeliveryResult {
+	ok: boolean;
+	/** Short machine code (`unmapped`, `sdk_threw`, `sdk_not_initialized`, ...). */
+	code?: string;
+	message?: string;
+	/** Whether the host could retry. Native adapters are fire-and-forget today. */
+	retriable?: boolean;
+}
+export interface NativeAdapter {
+	readonly name: string;
+	/** Boot the underlying native SDK. Called once from `client.initialize()`. */
+	initialize(): Promise<void>;
+	/** Propagate (or clear) user identity to the SDK. */
+	setUser(identity: UserIdentity | null): void;
+	/** Fire one canonical event into the SDK. */
+	deliver(event: AttributionEvent): Promise<AdapterDeliveryResult>;
+	/** Flush the SDK's internal buffer, if it has one. */
+	flush?(): Promise<void>;
+	/** Update ATT/advertiser-tracking consent (Meta). */
+	setAdvertiserTracking?(enabled: boolean): Promise<void>;
+}
+export interface MetaAdapterOptions {
+	/** Meta App ID (developers.facebook.com). */
+	appId: string;
+	/** Meta Client Token (Settings → Advanced → Client Token). */
+	clientToken: string;
+	/**
+	 * Send `AdvertiserTrackingEnabled` based on ATT status. Default true —
+	 * required on iOS 14.5+ to reach Meta's algorithms (not just SKAdNetwork).
+	 */
+	honorAtt?: boolean;
+	/** Override the adapter name (default `'meta'`). */
+	name?: string;
+	/** Injectable Meta SDK module — for tests. Default: lazy `require`. */
+	sdkLoader?: () => MetaSdkModule;
+}
+/** Minimal slice of `react-native-fbsdk-next` the adapter uses. */
+export interface MetaSdkModule {
+	Settings: {
+		setAppID(appId: string): void;
+		setClientToken(token: string): void;
+		initializeSDK(): void;
+		setAdvertiserTrackingEnabled?(enabled: boolean): Promise<void> | void;
+		setAdvertiserIDCollectionEnabled?(enabled: boolean): Promise<void> | void;
+		setAutoLogAppEventsEnabled?(enabled: boolean): Promise<void> | void;
+	};
+	AppEventsLogger: {
+		logEvent(eventName: string, parameters?: Record<string, unknown>): void;
+		logEvent(eventName: string, valueToSum: number, parameters?: Record<string, unknown>): void;
+		logPurchase(amount: number, currency: string, parameters?: Record<string, unknown>): void;
+		setUserID(userId: string): void;
+		clearUserID(): void;
+		setUserData(userData: Record<string, string | null | undefined>): void;
+		flush(): void;
+		clearUserData?(): void;
+	};
+}
+export declare class MetaAdapter implements NativeAdapter {
+	private readonly options;
+	readonly name: string;
+	private sdk;
+	private readonly honorAtt;
+	constructor(options: MetaAdapterOptions);
+	initialize(): Promise<void>;
+	setUser(identity: UserIdentity | null): void;
+	deliver(event: AttributionEvent): Promise<AdapterDeliveryResult>;
+	flush(): Promise<void>;
+	setAdvertiserTracking(enabled: boolean): Promise<void>;
+	private loadSdk;
+}
+export interface MetaMappedEvent {
+	name: string;
+	kind: "purchase" | "standard" | "custom";
+	amount?: number;
+	currency?: string;
+	valueToSum?: number;
+	parameters: Record<string, unknown>;
+}
+/** Map TrackStall canonical names → Meta `AppEvents`. `null` = skip silently. */
+export declare function mapToMetaEvent(event: AttributionEvent): MetaMappedEvent | null;
+export interface TikTokAdapterOptions {
+	/** App bundle id (iOS) / package name (Android). */
+	appId: string;
+	/** TikTok App ID (Business Center → App → Settings). */
+	tiktokAppId: string;
+	/** Access token the TikTok SDK needs at `initialize()`. */
+	accessToken: string;
+	/** Default false. True while validating in TikTok Events Manager. */
+	debugMode?: boolean;
+	/** Override adapter name (default `'tiktok'`). */
+	name?: string;
+	/** Injectable SDK module — for tests. */
+	sdkLoader?: () => TikTokSdkModule;
+}
+/** Minimal surface of `@layers/expo-tiktok-business`. */
+export interface TikTokSdkModule {
+	default: {
+		initialize(appId: string, tiktokAppId: string, options: {
+			accessToken: string;
+			debugMode?: boolean;
+			autoTrackAppLifecycle?: boolean;
+			autoTrackRouteChanges?: boolean;
+		}): Promise<boolean>;
+		trackEvent(name: string, params?: Record<string, unknown>): Promise<boolean>;
+		trackCompletePurchase(value: number, currency: string, contents: Array<{
+			content_id: string;
+			content_type?: string;
+			content_name?: string;
+			quantity?: number;
+			price?: number;
+		}>, additionalParams?: Record<string, unknown>): Promise<boolean>;
+	};
+}
+export declare class TikTokAdapter implements NativeAdapter {
+	private readonly options;
+	readonly name: string;
+	private sdk;
+	private currentUserId;
+	constructor(options: TikTokAdapterOptions);
+	initialize(): Promise<void>;
+	setUser(identity: UserIdentity | null): void;
+	deliver(event: AttributionEvent): Promise<AdapterDeliveryResult>;
+	private loadSdk;
+}
+export interface TikTokMappedEvent {
+	name: string;
+	kind: "purchase" | "standard" | "custom";
+	value?: number;
+	currency?: string;
+	contents?: Array<{
+		content_id: string;
+		content_type?: string;
+		content_name?: string;
+		quantity?: number;
+		price?: number;
+	}>;
+	params: Record<string, unknown>;
+}
+/** Map TrackStall canonical names → TikTok standard events. `null` = skip. */
+export declare function mapToTikTokEvent(event: AttributionEvent, userId: string | null): TikTokMappedEvent | null;
+/**
+ * Minimal slice of the tracking-transparency packages. Either pair works:
+ * Expo (`requestTrackingPermissionsAsync`) or bare RN
+ * (`requestTrackingPermission`).
+ */
+export interface AttSdkModule {
+	requestTrackingPermissionsAsync?(): Promise<{
+		status: string;
+	}>;
+	getTrackingPermissionsAsync?(): Promise<{
+		status: string;
+	}>;
+	/** expo-tracking-transparency: returns the IDFA once tracking is authorized. */
+	getAdvertisingId?(): string | null;
+	requestTrackingPermission?(): Promise<string>;
+	getTrackingStatus?(): Promise<string>;
+}
+export declare function loadAttModule(injected?: AttSdkModule): AttSdkModule | null;
+/** Show the native ATT prompt and return the normalized status. */
+export declare function requestAttStatus(mod: AttSdkModule): Promise<AttStatus>;
+/**
+ * Read the device advertising id (IDFA) when tracking is authorized. Returns
+ * `undefined` when the module can't provide it or tracking isn't authorized
+ * (the vendor returns a zeroed UUID in that case, which we filter out).
+ */
+export declare function readAdvertisingId(mod: AttSdkModule): string | undefined;
+/** Read the current ATT status without prompting. */
+export declare function getAttStatus(mod: AttSdkModule): Promise<AttStatus>;
+/** Map vendor status strings onto TrackStall's canonical `AttStatus`. */
+export declare function normalizeAttStatus(raw: string | undefined): AttStatus;
+/**
+ * Exponential-backoff retry calculator for backend deliveries. Pure functions —
+ * no timers, no `Date.now()`. The queue stores `nextRetryAt` (epoch ms) and the
+ * flush loop pulls ready rows on each tick.
+ *
+ *   delay(attempt) = clamp(initialDelay * 2^(attempt-1), 0, maxDelay) ± jitter
+ */
+export interface RetryConfig {
+	/** Max attempts (including the first). Default 6. */
+	maxAttempts?: number;
+	/** First retry delay in ms. Default 1000ms. */
+	initialDelayMs?: number;
+	/** Cap on individual delays. Default 5 minutes. */
+	maxDelayMs?: number;
+	/** Jitter factor [0, 1). Default 0.2 → ±20%. */
+	jitter?: number;
+}
+export declare const DEFAULT_RETRY: Required<RetryConfig>;
+export declare function resolveRetryConfig(input?: RetryConfig): Required<RetryConfig>;
+export declare function computeRetryDelayMs(attempt: number, config: Required<RetryConfig>, random?: () => number): number;
+export declare function shouldRetry(attemptsSoFar: number, retriable: boolean | undefined, config: Required<RetryConfig>): boolean;
+/**
+ * Minimal async key-value contract the SDK persists against. Deliberately a
+ * subset of `@react-native-async-storage/async-storage` so that package drops
+ * in directly; `localStorage` and an in-memory fallback are adapted to it too.
+ */
+export interface KeyValueStorage {
+	getItem(key: string): Promise<string | null>;
+	setItem(key: string, value: string): Promise<void>;
+	removeItem(key: string): Promise<void>;
+}
+/**
+ * Client-safe runtime config served by `GET /v1/config`. Mirrors the server's
+ * `ClientRuntimeConfig`. Holds ONLY values the device may hold (App IDs, client
+ * token, device access token) — never the CAPI/EAPI server tokens.
+ */
+export interface RemoteConfig {
+	appId: string;
+	sandbox: boolean;
+	meta: {
+		appId: string;
+		clientToken: string;
+	} | null;
+	tiktok: {
+		appId: string;
+		ttAppId: string;
+		accessToken: string;
+	} | null;
+}
+export interface ClientLogger {
+	debug(message: string, context?: Record<string, unknown>): void;
+	info(message: string, context?: Record<string, unknown>): void;
+	warn(message: string, context?: Record<string, unknown>): void;
+	error(message: string, error?: unknown, context?: Record<string, unknown>): void;
+}
+export interface DeviceContext {
+	bundleId?: string;
+	appVersion?: string;
+	/** Two-letter country (e.g. `BR`). Improves match quality. */
+	country?: string;
+	/** IETF language tag (e.g. `pt-BR`). */
+	locale?: string;
+	timezone?: string;
+	/** Device advertising identifiers, when available + permitted. */
+	idfa?: string;
+	idfv?: string;
+	gaid?: string;
+	attStatus?: AttStatus;
+	/**
+	 * Probabilistic-match fingerprint signals. Feeding these lifts install
+	 * matching from the weak IP+locale tier (0.60–0.85) to the strong
+	 * device-fingerprint tiers (0.82–0.90). Without them, click→install
+	 * matching on iOS (no deterministic id from Safari) is effectively blind.
+	 * Populate from React Native `Dimensions`/`Platform`/`expo-device`.
+	 */
+	screenW?: number;
+	screenH?: number;
+	pixelRatio?: number;
+	osVersion?: string;
+	deviceModel?: string;
+}
+export interface UserIdentity {
+	/** Stable internal id — matches the server's `user.userId`. Required. */
+	userId: string;
+	email?: string;
+	phone?: string;
+	country?: string;
+	locale?: string;
+}
+export interface TrackEventInput {
+	name: AttributionEventName;
+	revenue?: RevenueData;
+	productId?: string;
+	/** Free-form extras → server `properties`. No PII here. */
+	properties?: Record<string, string | number | boolean | null>;
+	/** Override the deterministic event id. */
+	eventId?: string;
+	/** Override event timestamp (epoch ms). Defaults to now. */
+	timestampMs?: number;
+	/** Per-event user override (log an event for a different user). */
+	user?: UserIdentity;
+	/** Mark this event as sandbox/test traffic. */
+	sandbox?: boolean;
+}
+/**
+ * Optional knobs for `logEvent()` — the product-analytics lane (Mixpanel
+ * style). Most apps never need this: `ts.logEvent('screen_view', { screen:
+ * 'home' })` is the whole integration.
+ */
+export interface LogEventOptions {
+	/** Override the random event id (dedup key on the server). */
+	eventId?: string;
+	/** Override event timestamp (epoch ms). Defaults to now. */
+	timestampMs?: number;
+	/** Client-managed session id for session analytics. */
+	sessionId?: string;
+}
+/** Free-form product-analytics payload. JSON scalars only; no PII. */
+export type LogEventProperties = Record<string, ProductPropertyValue>;
+/** Click capture input — fields mirror `POST /v1/click`. */
+export interface RecordClickInput {
+	fbclid?: string;
+	ttclid?: string;
+	gclid?: string;
+	fbp?: string;
+	fbc?: string;
+	ttp?: string;
+	utmSource?: string;
+	utmMedium?: string;
+	utmCampaign?: string;
+	utmContent?: string;
+	utmTerm?: string;
+	campaignId?: string;
+	adsetId?: string;
+	adId?: string;
+	creativeId?: string;
+	landingUrl?: string;
+	referrer?: string;
+	locale?: string;
+	timezone?: string;
+	country?: string;
+	screenW?: number;
+	screenH?: number;
+	pixelRatio?: number;
+	osVersion?: string;
+	deviceModel?: string;
+}
+export interface RecordClickResult {
+	clickToken: string;
+	expiresAt: string;
+}
+/** Install-match input — fields mirror `POST /v1/match`. */
+export interface MatchInstallInput {
+	userId?: string;
+	clickToken?: string;
+	locale?: string;
+	timezone?: string;
+	screenW?: number;
+	screenH?: number;
+	pixelRatio?: number;
+	osVersion?: string;
+	deviceModel?: string;
+}
+export interface MatchInstallResult {
+	matched: boolean;
+	matchMethod: string;
+	matchConfidence: number;
+	source: string | null;
+	campaignId: string | null;
+}
+/**
+ * Install-referrer input (Android) — fields mirror `POST /v1/referrer`. Pass the
+ * raw referrer string read from the Play Install Referrer API
+ * (`com.android.installreferrer` / `react-native-play-install-referrer`).
+ */
+export interface InstallReferrerInput {
+	userId?: string;
+	referrer: string;
+	locale?: string;
+	timezone?: string;
+	country?: string;
+	screenW?: number;
+	screenH?: number;
+	pixelRatio?: number;
+	osVersion?: string;
+	deviceModel?: string;
+}
+/** Mirrors `MatchInstallResult` — the referrer match is deterministic (conf 1.0). */
+export type InstallReferrerResult = MatchInstallResult;
+export interface TrackStallConfig {
+	/** Tenant id assigned by TrackStall. */
+	appId: string;
+	/** Public API key (`tsk_pub_...`). Authenticates the SDK. */
+	publicKey: string;
+	/** Base URL of the TrackStall API (no trailing slash), e.g. `https://api.trackstall.io`. */
+	endpoint: string;
+	/** Runtime platform. Defaults to `'ios'` if unset and not inferable. */
+	platform?: Platform;
+	device?: DeviceContext;
+	storage?: KeyValueStorage;
+	logger?: ClientLogger;
+	/** Master kill-switch. When `false`, every call silently no-ops. */
+	enabled?: boolean;
+	/** Inject a fetch implementation (default: global `fetch`). */
+	fetchImpl?: typeof fetch;
+	/** Per-request timeout in ms. Default 8000. */
+	requestTimeoutMs?: number;
+	/** Offline buffer capacity (FIFO drop when full). Default 500. */
+	bufferCapacity?: number;
+	/** Flush batch size for `/v1/events`. Default 20. */
+	batchSize?: number;
+	retry?: RetryConfig;
+	now?: () => number;
+	/**
+	 * Disable best-effort device auto-collection on `initialize()` (screen/OS/model
+	 * fingerprint signals from React Native / `expo-device`). Host-supplied
+	 * `config.device` values always take precedence regardless. Default false.
+	 */
+	disableAutoDeviceContext?: boolean;
+	/**
+	 * Inject the native SDK modules. By default each adapter lazy-`require()`s
+	 * its package (`react-native-fbsdk-next`, `@layers/expo-tiktok-business`,
+	 * `expo-tracking-transparency` / `react-native-tracking-transparency`).
+	 * Pass these to inject explicitly (tests, or non-standard resolution).
+	 */
+	native?: {
+		meta?: MetaSdkModule;
+		tiktok?: TikTokSdkModule;
+		att?: AttSdkModule;
+	};
+	/**
+	 * Disable the `GET /v1/config` fetch and native dual-send entirely — only the
+	 * backend (HTTP → CAPI/EAPI) lane runs. Use on web/server. Default false.
+	 */
+	disableNativeDualSend?: boolean;
+	/**
+	 * Override the remote config (skip the `/v1/config` fetch). Tests / advanced
+	 * setups that already hold the client-safe config.
+	 */
+	remoteConfig?: RemoteConfig;
+}
+export interface FlushResult {
+	attempted: number;
+	delivered: number;
+	retryScheduled: number;
+	dropped: number;
+}
+export interface ClientDiagnostics {
+	initialized: boolean;
+	enabled: boolean;
+	appId: string;
+	userId: string | null;
+	anonymousId: string | null;
+	queueSize: number;
+	analyticsQueueSize: number;
+}
+export interface TrackStallClient {
+	initialize(): Promise<void>;
+	setUser(identity: UserIdentity | null): void;
+	recordClick(input: RecordClickInput): Promise<RecordClickResult>;
+	matchInstall(input?: MatchInstallInput): Promise<MatchInstallResult>;
+	/**
+	 * ANDROID deterministic attribution: report the Google Play Install Referrer
+	 * string (read once on first launch via the Play Install Referrer API). The
+	 * backend parses the ad-network click id out of it and enriches future events
+	 * at confidence 1.0 — the Android equivalent of a Universal Link `clickToken`.
+	 */
+	reportInstallReferrer(input: InstallReferrerInput): Promise<InstallReferrerResult>;
+	/**
+	 * ATTRIBUTION lane: enqueue a marketing event for durable delivery to the
+	 * ad networks (Meta CAPI / TikTok EAPI). Returns the canonical `eventId`.
+	 */
+	track(input: TrackEventInput): Promise<string>;
+	/**
+	 * PRODUCT ANALYTICS lane (Mixpanel-style): log an in-app event to the
+	 * TrackStall dashboard only — never forwarded to ad networks.
+	 *
+	 *   ts.logEvent('screen_view', { screen: 'home' });
+	 *
+	 * Identity is automatic: the current user's `userId` when set, otherwise a
+	 * persistent device-generated anonymous id. Returns the `eventId`.
+	 */
+	logEvent(name: string, properties?: LogEventProperties, options?: LogEventOptions): Promise<string>;
+	/**
+	 * Show the native ATT prompt (iOS) and report the resulting status to the
+	 * TrackStall backend automatically — no extra code needed in the app.
+	 * Resolves the tracking-transparency module lazily (`expo-tracking-transparency`
+	 * or `react-native-tracking-transparency`); returns `'unavailable'` when the
+	 * platform isn't iOS or no module is installed.
+	 */
+	requestAttPermission(): Promise<AttStatus>;
+	/**
+	 * Report an ATT status obtained by the app itself (when the host app manages
+	 * the prompt). Also stamps `attStatus` on subsequent attribution events.
+	 */
+	setAttStatus(status: AttStatus): Promise<void>;
+	flush(): Promise<FlushResult>;
+	getDiagnostics(): ClientDiagnostics;
+}
+export declare function createTrackStallClient(config: TrackStallConfig): TrackStallClient;
+/**
+ * HTTP transport for the TrackStall API. Adds the public-key auth header,
+ * enforces a per-request timeout, and classifies the response so the queue
+ * knows whether to retry (5xx / 408 / 429 / network) or drop (4xx schema/auth).
+ */
+export interface TransportResponse {
+	ok: boolean;
+	status: number;
+	body: unknown;
+	retriable: boolean;
+	errorMessage?: string;
+}
+export interface TransportOptions {
+	endpoint: string;
+	publicKey: string;
+	fetchImpl?: typeof fetch;
+	timeoutMs?: number;
+}
+export declare class Transport {
+	private readonly endpoint;
+	private readonly publicKey;
+	private readonly fetchImpl;
+	private readonly timeoutMs;
+	constructor(options: TransportOptions);
+	get(path: string): Promise<TransportResponse>;
+	post(path: string, body: unknown): Promise<TransportResponse>;
+	private send;
+}
+export declare function isRetriableStatus(status: number): boolean;
+export interface QueuedEvent {
+	/** Local queue id (not the attribution eventId). */
+	id: string;
+	/** Server dedup id — also used to match per-event results on flush. */
+	eventId: string;
+	/** The wire body posted inside `{ events: [...] }`. */
+	body: Record<string, unknown>;
+	attempts: number;
+	nextRetryAt: number;
+	createdAt: number;
+}
+export interface EventQueueOptions {
+	storage: KeyValueStorage;
+	logger: ClientLogger;
+	capacity?: number;
+	storageKey?: string;
+	now?: () => number;
+}
+export declare class EventQueue {
+	private readonly storage;
+	private readonly logger;
+	private readonly capacity;
+	private readonly storageKey;
+	private readonly now;
+	private entries;
+	private hydrated;
+	private counter;
+	private chain;
+	constructor(options: EventQueueOptions);
+	hydrate(): Promise<void>;
+	size(): number;
+	enqueue(eventId: string, body: Record<string, unknown>): Promise<void>;
+	/** Snapshot of entries eligible to send now (does not mutate). */
+	pullReady(limit: number): QueuedEvent[];
+	markDelivered(ids: string[]): Promise<void>;
+	markFailed(ids: string[], nextRetryAt: number): Promise<void>;
+	clear(): Promise<void>;
+	private persist;
+	private serialize;
+}
+/** In-memory storage. Default when no persistence is provided — the offline
+ * buffer is then lost across app launches (fine for web sessions / tests). */
+export declare class MemoryStorage implements KeyValueStorage {
+	private readonly map;
+	getItem(key: string): Promise<string | null>;
+	setItem(key: string, value: string): Promise<void>;
+	removeItem(key: string): Promise<void>;
+}
+/**
+ * Adapts a synchronous Web Storage (`localStorage`) to the async contract.
+ * Returns a `MemoryStorage` when no Web Storage is available (RN, SSR, Node).
+ */
+export declare function defaultStorage(): KeyValueStorage;
+/**
+ * Collect whatever device signals are available without any user permission.
+ * Returns a partial `DeviceContext`; missing fields are simply omitted.
+ */
+export declare function collectDeviceContext(): Partial<DeviceContext>;
+
+export {};