> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wendung.app/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript types exported by the Wendung SDK reference

> Complete reference for every exported TypeScript type in the Wendung SDK, including configuration, identity, event, and ingest payload shapes.

The Wendung SDK is written in TypeScript and exports its public types from `@wendung/sdk`.

```ts theme={null}
import type {
  AggregatePageviewPayload,
  Config,
  ConsentState,
  EventContext,
  EventRequestPayload,
  Identity,
  InitConfig,
  Payload,
  StepEvent,
} from '@wendung/sdk'
```

## InitConfig

The configuration object accepted by [`Wendung.init()`](/api-reference/init). Only `apiKey` is required; the rest fall back to defaults.

```typescript theme={null}
export type InitConfig = Pick<Config, 'apiKey'> &
  Partial<
    Pick<Config, 'endpoint' | 'flushInterval' | 'maxBatchSize' | 'trackPageviews' | 'debug'>
  > & {
    consent?: ConsentState
  }
```

## ConsentState

The analytics consent states accepted by `init()` and [`setConsent()`](/api-reference/set-consent) and returned by [`getConsent()`](/api-reference/get-consent). See the [consent guide](/guides/consent) for what each state does.

```typescript theme={null}
export type ConsentState = 'pending' | 'granted' | 'denied'
```

## Config

The full resolved configuration after defaults are applied. Applications normally pass `InitConfig` instead.

```typescript theme={null}
export type Config = {
  apiKey: string
  endpoint: string
  flushInterval: number
  maxBatchSize: number
  trackPageviews: boolean | 'auto'
  debug?: boolean
}
```

<ResponseField name="apiKey" type="string" required>
  Your publishable API key. Sent with every request as the `X-API-Key` header; it does not appear in the request body.
</ResponseField>

<ResponseField name="endpoint" type="string" required>
  The resolved ingest endpoint. Defaults to `https://ingest.wendung.app/v1/events`. `http://` is only permitted for localhost addresses.
</ResponseField>

<ResponseField name="flushInterval" type="number" required>
  Milliseconds between automatic flushes. Defaults to `5000`.
</ResponseField>

<ResponseField name="maxBatchSize" type="number" required>
  Maximum events per outbound batch. Defaults to `50`; the effective value is clamped to 1–100.
</ResponseField>

<ResponseField name="trackPageviews" type="boolean | 'auto'" required>
  Defaults to `false`. `true` enables full pageviews with granted consent. `'auto'` also enables aggregate pageviews while pending. Denied consent stops both. See [options](/configuration/options).
</ResponseField>

<ResponseField name="debug" type="boolean">
  When `true`, verbose `[Wendung]` messages are written to the console. Defaults to `false`.
</ResponseField>

***

## Identity

The user context attached to events. Set by [`Wendung.identify()`](/api-reference/identify), cleared by [`Wendung.reset()`](/api-reference/reset).

```typescript theme={null}
export type Identity = {
  userId: string | null
  anonymousId?: string
  traits?: Record<string, unknown>
}
```

<ResponseField name="userId" type="string | null" required>
  The identifier of the current user, or `null` for an anonymous session.
</ResponseField>

<ResponseField name="anonymousId" type="string">
  The SDK's random visitor identifier for full analytics. Aggregate pageviews omit identity entirely.
</ResponseField>

<ResponseField name="traits" type="Record<string, unknown>">
  Key-value metadata about the user. Replaced wholesale by each `identify()` call.
</ResponseField>

***

## EventContext

Environment metadata captured when an event is tracked.

```typescript theme={null}
export type EventContext = {
  sdkName: '@wendung/sdk'
  sdkVersion: string
  pageUrl?: string
  referrer?: string
  pageTitle?: string
  screenWidth?: number
  screenHeight?: number
}
```

<ResponseField name="sdkName" type="'@wendung/sdk'" required>
  The literal package name.
</ResponseField>

<ResponseField name="sdkVersion" type="string" required>
  The SDK version, also sent as the `X-Wendung-SDK-Version` request header.
</ResponseField>

<ResponseField name="pageUrl" type="string">
  The full URL for consented events, or origin and pathname for aggregate pageviews. Absent outside the browser.
</ResponseField>

<ResponseField name="referrer" type="string">
  For the first pageview, `document.referrer`; for later pageviews, the previous pageview's URL. Aggregate pageviews restrict it to the origin. Absent when empty or outside the browser.
</ResponseField>

***

## StepEvent

A single tracked event, as queued and as sent in the `events` array of a payload. All snapshot fields are captured at the moment [`Wendung.step()`](/api-reference/step) is called.

```typescript theme={null}
export type StepEvent = {
  id: string
  name: string
  properties?: Record<string, unknown>
  timestamp: string
  sessionId?: string
  identity?: Identity
  context?: EventContext
}
```

<ResponseField name="id" type="string" required>
  Unique event ID, generated with `crypto.randomUUID()`.
</ResponseField>

<ResponseField name="name" type="string" required>
  The event name passed to `step()`, 1–100 characters.
</ResponseField>

<ResponseField name="properties" type="Record<string, unknown>">
  Deep-cloned copy of the properties passed to `step()`. Present only when supplied.
</ResponseField>

<ResponseField name="timestamp" type="string" required>
  ISO 8601 UTC timestamp (`new Date().toISOString()`) recorded at call time.
</ResponseField>

<ResponseField name="sessionId" type="string">
  The session ID active when the event was tracked.
</ResponseField>

<ResponseField name="identity" type="Identity">
  Snapshot of the identity at track time. Later `identify()` calls do not backfill earlier events.
</ResponseField>

<ResponseField name="context" type="EventContext">
  Snapshot of the [event context](#eventcontext) at track time.
</ResponseField>

***

## EventRequestPayload

The JSON body for full analytics requests. `Payload` is an alias for this type. Pending aggregate pageviews use [`AggregatePageviewPayload`](#aggregatepageviewpayload) instead. Requests carry the headers `Content-Type: application/json`, `X-API-Key`, and `X-Wendung-SDK-Version`.

```typescript theme={null}
export type EventRequestPayload = {
  type: 'identity' | 'event'
  batchId: string
  sessionId: string
  identity: Identity
  events: StepEvent[]
  sentAt: string
  context: EventContext
}

export type Payload = EventRequestPayload
```

<ResponseField name="type" type="'identity' | 'event'" required>
  Payload discriminant. The SDK currently always sends `'event'`.
</ResponseField>

<ResponseField name="batchId" type="string" required>
  Random UUID identifying the batch. Stable across retries of the same batch.
</ResponseField>

<ResponseField name="sessionId" type="string" required>
  The session ID of the first event in the batch, or the current session if the batch is empty.
</ResponseField>

<ResponseField name="identity" type="Identity" required>
  The identity snapshot of the first event in the batch, or the current identity.
</ResponseField>

<ResponseField name="events" type="StepEvent[]" required>
  The events being delivered, at most the effective batch size (1–100).
</ResponseField>

<ResponseField name="sentAt" type="string" required>
  ISO 8601 UTC timestamp taken when the payload is serialized, distinct from the per-event `timestamp` fields.
</ResponseField>

<ResponseField name="context" type="EventContext" required>
  The context snapshot of the first event in the batch, or the current context.
</ResponseField>

## AggregatePageviewPayload

The request body for pageviews collected with `trackPageviews: 'auto'` while consent is pending.

```typescript theme={null}
export type AggregatePageviewPayload = {
  type: 'event'
  collection: 'aggregate'
  batchId: string
  events: Pick<StepEvent, 'id' | 'name' | 'timestamp' | 'context'>[]
  sentAt: string
}
```

Every event has the name `$pageview`. The body and its events contain no visitor identity or session ID. Event and batch IDs support delivery deduplication. The [pageview field reference](/concepts/pageviews#aggregate-pageviews) describes the restricted context.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.