# TypeScript types

URL: https://supapulse.app/docs/api/types

Every TypeScript interface exported by @supapulse/core, @supapulse/revenue and @supapulse/react, as shipped in their current releases.

## @supapulse/core [#supapulsecore]

```ts
import type {
  SupapulseConfig,
  PageviewOptions,
  EventData,
  SupapulseExtension,
  SupapulseCore,
  TrackingData,
  QueuedEvent,
} from '@supapulse/core';
```

```ts
interface SupapulseConfig {
  apiToken: string;
  endpoint?: string; // default 'https://supapulse.app/api/ingest'
  fingerprintEndpoint?: string; // default: endpoint with /ingest replaced by /fingerprint
  autoPageviews?: boolean; // default true
  debug?: boolean; // default false
  maxRetries?: number; // default 10
  retryBackoff?: number; // default 1000 (ms)
}

interface PageviewOptions {
  url?: string;
  referrer?: string;
  title?: string;
}

interface EventData {
  [key: string]: any;
}

interface SupapulseExtension {
  name: string;
  init(core: SupapulseCore): void;
}

interface SupapulseCore {
  init(config: SupapulseConfig): void;
  pageview(options?: PageviewOptions): void;
  event(eventName: string, eventData?: EventData): void;
  identify(customerId: string): Promise<void>;
  getVisitorFingerprint(): Promise<string | null>;
  getSessionId(): string;
  use(extension: SupapulseExtension): void;
}

/** The `data` the tracker sends. */
interface TrackingData {
  type: 'pageview' | 'event' | 'identify';
  visitor_fingerprint?: string | null;
  customer_id?: string;
  session_id: string;
  url?: string;
  path?: string;
  referrer?: string;
  referrer_source?: string;
  title?: string;
  locale?: string;
  event_name?: string;
  event_data?: EventData;
  utm_source?: string;
  utm_medium?: string;
  utm_campaign?: string;
  utm_term?: string;
  utm_content?: string;
  timestamp: number; // not sent; stripped before the request
}

/** An entry in the in-memory retry queue. */
interface QueuedEvent {
  id: string;
  timestamp: number;
  attempts: number;
  data: TrackingData;
}
```

The `Supapulse` class implements `SupapulseCore`. Its `pageview()` and `event()` return `Promise<void>`.

## @supapulse/revenue [#supapulserevenue]

```ts
import type { RevenueConfig, RevenueData, RevenueTrackingData } from '@supapulse/revenue';
```

```ts
interface RevenueConfig {
  apiToken: string;
  endpoint?: string; // default 'https://supapulse.app/api/ingest'
  debug?: boolean; // default false
  maxRetries?: number; // default 3
  retryBackoff?: number; // default 1000 (ms)
}

interface RevenueData {
  visitor_fingerprint?: string;
  session_id?: string;
  customer_id: string;
  amount: number;
  currency?: string; // default 'USD'
  transaction_id: string;
  payment_processor?: string;
  event_type?: 'purchase' | 'subscription' | 'renewal' | 'upgrade' | 'downgrade' | 'churn' | 'refund';
  occurred_at?: Date | string;
  subscription_id?: string;
  /** @deprecated Use `subscription_id`. */
  customer_subscription_id?: string;
  mrr_impact?: number;
  is_recurring?: boolean;
  metadata?: Record<string, any>;
}

interface RevenueTrackingData {
  type: 'revenue';
  visitor_fingerprint?: string;
  session_id?: string;
  customer_id: string;
  amount: number;
  currency: string;
  transaction_id: string;
  payment_processor?: string;
  event_type?: string;
  subscription_id?: string;
  mrr_impact?: number;
  is_recurring?: boolean;
  metadata?: Record<string, any>;
  occurred_at?: string;
}
```

The ingest API validates and stores every field here. See the [Revenue API reference](https://supapulse.app/docs/revenue/api-reference).

## @supapulse/react [#supapulsereact]

```ts
import type {
  SupapulseProviderProps,
  SupapulseContextValue,
  UsePageviewOptions,
  TrackEventFunction,
  SupapulseConfig,
  SupapulseCore,
  EventData,
} from '@supapulse/react';
```

```ts
interface SupapulseProviderProps {
  config: SupapulseConfig;
  children: ReactNode;
}

interface SupapulseContextValue {
  supapulse: SupapulseCore; // available from the first render
  isReady: boolean;
  autoPageviews: boolean; // true unless config.autoPageviews is false
  error: Error | null;
}

interface UsePageviewOptions {
  trigger?: any; // a pageview is sent whenever this changes
  disabled?: boolean;
}

type TrackEventFunction = (eventName: string, eventData?: EventData) => Promise<void>;
```

`SupapulseConfig`, `SupapulseCore` and `EventData` are re-exported from `@supapulse/core`.

## Hook signatures [#hook-signatures]

```ts
function useSupapulse(): SupapulseCore;
function useIdentify(): (customerId: string) => Promise<void>;
function useEvent(): TrackEventFunction;
function usePageview(options?: UsePageviewOptions): void;
```