## Installation

Install the Jam SDK into your project:

- npm
- yarn

```
npm install '@jam.dev/sdk'
```

```
yarn add '@jam.dev/sdk'
```

## Usage

Call `jam.metadata()` once at the root of your app, in the same place you initialize your stores and render your root element. The callback you pass is invoked each time a Jam is captured, so the data is always live and never stale.

```
import { jam } from "@jam.dev/sdk";

jam.metadata(() => {
  return {
    userId: 5492,
    workspaceId: 'd3b59ce8-95f1-410c-bb5e-9dc598599336',
    timeSincePageLoad: performance.now(),
    // and any other debug data you'd need
  };
});
```

Once configured, your metadata appears inside every Jam filed from your site.

## What data you can include

Beyond static values and local variables, you can pass in:

- **App store state**: user ID, workspace ID, the last 5 items in a checkout cart, which feature flags are enabled, and so on.
- **localStorage values**: any values stored locally in the browser.
- **Any serializable data**: whatever you need to reproduce or understand the bug.

## When is metadata captured?

Metadata is captured at the moment the bug reporter creates a Jam. Because the function you pass to `jam.metadata()` is called at capture time, the data reflects the live state of your app, not a stale snapshot from when the page loaded.

## Limits and constraints

When calling `jam.metadata()`, the returned object must meet all of the following requirements:

1. **Must be an `Object` instance**: for example, `{ a: 1, b: 2 }`. Passing `window` (a `Window` instance) will not work.
2. **Under 10 KB** when serialized.
3. **Serializable**: if `JSON.stringify` cannot stringify it, Jam cannot store it.

## Error handling

If your app throws an error, or any of the above constraints are not met, Jam will:

- Log the error in your browser’s live console.
- Display an error message when the Jam is captured.

If `jam.metadata()` throws or returns an invalid value, the Jam is still created, but without your custom metadata. Check your browser console if you expect metadata and don’t see it in a Jam.