# Changelog

Read the environment's public product changelog as posts, or filter individual changes by category, audience, surface, and time.

`client.changelog` reads the product changelog published for the environment the client calls. It is public and read-only: no credentials are needed, requests are cacheable GETs, and they are rate-limited per client address. Enum values the SDK does not know decode as `"unspecified"`.

A post groups changes into sections. Read posts with `listPosts` and `getPost`, or query changes across posts with `listChanges`. Timestamps are epoch milliseconds.

## Methods

| Method        | Summary                                                        |
| ------------- | -------------------------------------------------------------- |
| `listPosts`   | List post summaries, newest first, with change counts by kind. |
| `getPost`     | Fetch one post with every section and change.                  |
| `listChanges` | List individual changes across posts, with filters.            |

### `listPosts(input?, options?)`

Returns `{ posts, nextPageToken }` with post summaries, newest first. `limit` is 0 through 100; 0 or omitted uses the server default of 20. Pass the previous `nextPageToken` as `pageToken` to continue; an empty `nextPageToken` means no more posts. Use `limit: 1` to poll for the latest post.

```ts
const { posts } = await client.changelog.listPosts({ limit: 1 });
const latest = posts[0];
console.log(latest?.slug, latest?.title, latest?.breakingChangeCount);
```

```ts
interface ChangelogPostSummary {
	slug: string;
	title: string;
	introduction: string;
	publishedAt: number;
	coverageCutoff?: number; // exclusive end of the covered period
	changeCount: number;
	breakingChangeCount: number;
	actionRequiredCount: number;
	newFeatureCount: number;
	improvementCount: number;
	bugFixCount: number;
}
```

### `getPost(input, options?)`

Returns one `ChangelogPost`: the summary fields plus `sections`. A slug is the post's coverage cutoff date, `YYYY-MM-DD`, with `-2`, `-3`, and so on for later posts on the same day. An unknown slug throws `ResourceNotFoundError`. A large post can hold hundreds of changes; page through them with `listChanges` and `postSlug` instead.

```ts
const post = await client.changelog.getPost({ slug: latest.slug });
for (const section of post.sections) {
	console.log(section.heading, section.surface, section.changes.length);
}
```

```ts
interface ChangelogPost extends ChangelogPostSummary {
	sections: ChangelogSection[];
}

interface ChangelogSection {
	heading: string;
	summary?: string;
	surface: ChangelogSurface | "unspecified"; // "unspecified" when it spans several areas
	changes: ChangelogChange[];
}

interface ChangelogChange {
	id: string; // public base58 id, stable across environments
	title: string;
	summary: string;
	details?: string;
	category: "breaking_change" | "new_feature" | "improvement" | "bug_fix" | "unspecified";
	actionRequired: boolean;
	migrationGuidance?: string;
	audiences: ("all_users" | "traders" | "market_makers" | "developers" | "unspecified")[];
	surfaces: (ChangelogSurface | "unspecified")[];
}
```

A section's `surface` is the product area it covers, or `"unspecified"` when it covers more than one.

### `listChanges(input?, options?)`

Returns `{ changes, nextPageToken }`. Posts come newest first unless `sort` is `"asc"`; changes keep their publication order inside each post. Each entry is a `ChangelogChange` plus the `postSlug`, `publishedAt`, and `sectionHeading` of the post that announced it.

```ts
const { changes } = await client.changelog.listChanges({
	categories: ["breaking_change"],
	audiences: ["developers"],
	surfaces: ["api", "trading"],
	startTime: Date.now() - 30 * 24 * 60 * 60 * 1000,
});
for (const change of changes) {
	console.log(change.postSlug, change.title, change.actionRequired);
}
```

Filters on different fields combine with AND; values within one field combine with OR. Changes addressed to `all_users` match every `audiences` filter. Reuse a `pageToken` only with the same filters, time bounds, and sort.

| Field            | Type                                                                   | Notes                                                                 |
| ---------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `categories`     | `("breaking_change" \| "new_feature" \| "improvement" \| "bug_fix")[]` | Default `[]` (all).                                                   |
| `actionRequired` | `boolean`                                                              | Only changes that do, or do not, require action.                      |
| `surfaces`       | `ChangelogSurface[]`                                                   | Default `[]` (all).                                                   |
| `audiences`      | `("all_users" \| "traders" \| "market_makers" \| "developers")[]`      | Default `[]` (all).                                                   |
| `startTime`      | `number`                                                               | Epoch ms on post publication time, inclusive.                         |
| `endTime`        | `number`                                                               | Epoch ms, exclusive. Must be after `startTime`, or `ValidationError`. |
| `postSlug`       | `string`                                                               | Only changes from one post.                                           |
| `sort`           | `"asc" \| "desc"`                                                      | Post order. Default newest first.                                     |
| `limit`          | `number`                                                               | 0 through 500; 0 or omitted uses the server default of 100.           |
| `pageToken`      | `string`                                                               | `nextPageToken` from the previous page.                               |

`ChangelogSurface` is one of `"trading"`, `"funding"`, `"accounts"`, `"api"`, `"explorer"`, `"documentation"`, `"platform"`, `"market_data"`, `"quickswap"`, or `"rewards"`.

## Related

- [Client configuration](https://testnet.polyester.com/docs/sdk/typescript/reference/client-configuration) for choosing the environment the changelog is read from.
- [Errors](https://testnet.polyester.com/docs/sdk/typescript/reference/errors) for the error type reference.