# realtime.pim

Subscribe to live calendar and contacts change events over WebSocket.

Upgrades to a WebSocket that streams `pim.changed` frames for this identity's calendars, tasks and contacts: `{ v, type, ts, data }` where `data` is the current state token per type (`{ Calendar, CalendarEvent, Task, AddressBook, ContactCard }`), the same tokens the per-collection `/changes` feeds and JMAP accept. A `ready` frame with the session deadline is sent on connect. Signals are not a journal: there is no replay, so on every (re)connect re-sync, and treat each frame as 'this changed, re-fetch it'. The vocabulary is additive: treat an unrecognized `type` as a generic nudge.

Owner-only: a calendar or address book shared with you is not streamed here. Before the first calendar or contact use, the connection waits without creating a store. Its first authorized PIM use creates the default collections and sends one `pim.changed` frame. The session is closed with 4401 (session_expired: reconnect with a fresh bearer) after 12h, 4403 (credential_revoked: the credential was revoked or its owner suspended; do not reconnect with it) or 4410 (mailbox_gone: the identity is being deleted; stop reconnecting). Keepalive: send a `ping` text frame, receive `pong`.

```ts
openemail.realtime.pim(
  identityId: string,
  options?: CallOptions,
): RealtimeConnection
```

It calls `GET /identities/{identityId}/pim/events`: [Subscribe to live calendar and contacts change events over WebSocket](/docs/api/pim/get_PimEvents) in the API reference.

## Example

```ts
const live = openemail.realtime.pim(identityId)

live.on('frame', (frame) => {
  // every frame the API sends, the ready frame of each connect first
})
```

## Arguments

| Argument | Type | Description |
| --- | --- | --- |
| `identityId` | `string` | Identity ULID. The path's `{identityId}`. |

## Options

It takes no options of its own. Every call also takes `signal`, `timeout`, `retry` and `headers`, which say how that one call is sent ([call options](/docs/sdks/typescript/calling-methods#call-options)).

## Answer

It opens a live channel, a [`RealtimeConnection`](/docs/sdks/typescript/live-events), which holds itself open, replaces a socket it loses, and tells each frame to its `frame` listeners until it is closed.

## Errors

| Status | What it means |
| --- | --- |
| `401` | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge |
| `403` | forbidden: the identity's owner is suspended and this connection would act for them (an account or system key acting for nobody may still connect) |
| `404` | not_found (the identity does not exist or is not this principal's to stream) |
| `410` | mailbox_gone: the identity is being deleted; stop reconnecting |
| `426` | upgrade_required: the request was not a WebSocket upgrade |
| `429` | too_many_subscribers: the store's subscriber cap is reached |
| `503` | temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description) |

A live channel rejects nothing: a refused upgrade reaches its WebSocket only as a lost connection, so the channel reconnects (it tells `reconnecting`), without end unless its `retry` bounds it. The API's close codes `4403` and `4410` end it: see [Live events](/docs/sdks/typescript/live-events).
