# Statum Model

## Statum Frames

A statum frame consists of a JSON object with three keys:
- `content`: a string containing the literal content of the frame.
- `signer`: a string containing a signer ID.
- `signature`: a base64 encoded signature verifying the content authored by the signer.

## Statum Slot

- `key`: a server issued ID for the slot.
- `scope`: a string value that can be one of:
    - `"device"`: persists between browser sessions.
    - `"session"`: persists within the browser session (e.g. between tabs).
    - `"flow"`: persists only within the current tab, while the tab remains on the site (e.g. persits on between navigation)
    - `"page"`: persists only while the current page is loaded (e.g. clears on navigate).
    - `"transient"`: does not persist, will never get sent back to the server - random or `null` key each time.
- `type`: an application defined type name.

## Statum Snapshot

A statum snapshot captures an aspect of the application state at a particular point-in-time. It is usually wrapped in a frame, which must be retained if it is to be sent back to the server after the `transmit_after` time. It contains:

- `as_at`: an ISO 8601 string representing the time the snapshot was authored.
- `slot`: a slot object (above)
- `transmit_after`: an ISO 8601 string representing the time the slot will no longer be cached by the server and the application will need to send the snapshot. `undefined` if this is a unidirectional snapshot that never needs to be sent to the server. If it equals `as_at`, then the snapshot must always be sent.
- `invalid_after`: an IOS 8601 string representing the time this snapshot should be considered invalid and not used.
- `private`: a base64 encoded string of data only readable by the application server.
- `public`: a JSON object with application-defines key/values.

## Statum Action

- `uri`: The URI to request.
- `method`: the HTTP verb to use.
- `private`: a base64 encoded string of data only readable by the application server (can be `undefined`)

## Statum Directive

- `type`: One of
    - `"navigate"`: Used to redirect the frontend to a new URI.
    - `"post"`: Used to cause the frontend to POST some data to a URI.
    - `"set"`: Used to set a slot to a new snapshot.
    - `"clear"`: Used to clear a slot.

Depending on the type, it will have other properties.

### Navigate Directive

- `uri`: The URI to navigate to.

### Post Directive

- `uri`: The URI to perform a form post to.
- `data`: Key/value pairs for form data.

### Set Directive

- `snapshot_frame`: A frame containing a snapshot.

### Clear Directive

- `slot_id`: The ID of the slot to clear.

# Statum HTTP API


## Entrypoint Endpoint

`GET /_statum/entrypoint`: Get initial diretives based on the URL. has query param `uri` set to the browsers current `window.location`.
Returns a JSON array of Statum Directives.

## Slot Post Endpoint

`POST /_statum/slots`: Send a saved state snapshots frame to the server once it has reached its `transmit_after` time window. Sent as a JSON array of Statum Frames. Returns a JSON array of Statum Directives.

## Action Endpoints

The URLs of action endpoints are entirely defined by the action iteself (in the `uri` property). An additional `X-Statum-Private` header should contain the `private` data of the action if present. Returns a JSON array of Statum Directives.

## Request Headers

All HTTP API requests must have a `X-Statum-Slot` header for each relevant slot snapshot in scope.

There are two variations of this header:

- For slots that have a snapshot that are within the `transmit_after` time window, an `as_at` timestamp is sent, e.g. `X-Statum-Slot: key=d3cceb88-c211-41ee-a0b1-6a93f3b6331b; as_at=2026-07-06T07:33:02.332Z`.
- For slots that have a snapshot which has a `transmit_after` timestamp equal to its `as_at` timestamp, the frame is sent in base64, e.g. `X-Statum-Slot: eyAiY29udGVudCI6ICIuLi4uIiwgInNpZ25lciI6ICJzMSIsICJzaWduYXR1cmUiOiAiZXlBaVkyOXVkR1Z1ZENJNklDSXVMaTR1SWl3Z0luTnBaMjVsY2lJNklDSnpNU0lzSUNKemFXZHVZWFIxY21VaU9pQWlJbjA9In0=`

Before an HTTP request is sent, if one or more slot snapshots's `transmit_after` timestamp is in the past, and it is not equal to its `as_at` timestamp, a pre-flight request should be made to the slot post endpoint, which will in turn provide updated snapshots and a new `as_at` timestamp.