feat: [CHA-2563] add retention policy endpoints (#1713)

## Ticket
-
https://linear.app/stream/issue/CHA-2563/retention-policy-for-existing-customers

## Summary
Adds server-side SDK methods for the retention policy CRUD endpoints:

- **`setRetentionPolicy(policy, maxAgeHours)`** — creates or updates a
retention policy (`old-messages` or `inactive-channels`) with a max age
between 24–43800 hours
- **`deleteRetentionPolicy(policy)`** — removes a retention policy
- **`getRetentionPolicy()`** — lists all retention policies configured
for the app
- **`getRetentionPolicyRuns(options?)`** — queries retention cleanup run
history with support for `filter_conditions`, `sort`, and cursor-based
pagination

All endpoints are server-side only and require initializing the client
with a secret.

New types added: `RetentionPolicy`, `RetentionPolicyConfig`,
`RetentionRunStats`, `RetentionRunResponse`, and request/response types
for each endpoint.

## Checklist
- [x] Types added to `src/types.ts`
- [x] Methods added to `src/client.ts`
- [x] TypeScript compilation passes
- [x] Prettier formatting passes
- [ ] The changed code has been covered with unit tests
- [ ] API endpoints are covered with client tests

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: hifaizsk

src/client.ts

@@ -83,6 +83,7 @@ import type {
   DeleteChannelsResponse,
   DeleteCommandResponse,
   DeleteMessageOptions,
+  DeleteRetentionPolicyResponse,
   DeleteUserOptions,
   Device,
   DeviceIdentifier,
@@ -118,6 +119,9 @@ import type {
   GetPollAPIResponse,
   GetPollOptionAPIResponse,
   GetRateLimitsResponse,
+  GetRetentionPolicyResponse,
+  GetRetentionPolicyRunsOptions,
+  GetRetentionPolicyRunsResponse,
   GetThreadAPIResponse,
   GetThreadOptions,
   GetUnreadCountAPIResponse,
@@ -205,6 +209,7 @@ import type {
   SegmentTargetsResponse,
   SegmentType,
   SendFileAPIResponse,
+  SetRetentionPolicyResponse,
   SharedLocationResponse,
   SortParam,
   StreamChatOptions,
@@ -4986,4 +4991,62 @@ export class StreamChat {
       },
     );
   }
+
+  /**
+   * setRetentionPolicy - Creates or updates a retention policy for the app.
+   * Server-side only.
+   *
+   * @param {string} policy The policy type ('old-messages' or 'inactive-channels')
+   * @param {number} maxAgeHours Max age in hours (24-43800)
+   * @returns {Promise<SetRetentionPolicyResponse>}
+   */
+  async setRetentionPolicy(policy: string, maxAgeHours: number) {
+    this.validateServerSideAuth();
+    return await this.post<SetRetentionPolicyResponse>(
+      this.baseURL + '/retention_policy',
+      { policy, max_age_hours: maxAgeHours },
+    );
+  }
+
+  /**
+   * deleteRetentionPolicy - Deletes a retention policy for the app.
+   * Server-side only.
+   *
+   * @param {string} policy The policy type ('old-messages' or 'inactive-channels')
+   * @returns {Promise<DeleteRetentionPolicyResponse>}
+   */
+  async deleteRetentionPolicy(policy: string) {
+    this.validateServerSideAuth();
+    return await this.post<DeleteRetentionPolicyResponse>(
+      this.baseURL + '/retention_policy/delete',
+      { policy },
+    );
+  }
+
+  /**
+   * getRetentionPolicy - Returns all retention policies configured for the app.
+   * Server-side only.
+   *
+   * @returns {Promise<GetRetentionPolicyResponse>}
+   */
+  async getRetentionPolicy() {
+    this.validateServerSideAuth();
+    return await this.get<GetRetentionPolicyResponse>(this.baseURL + '/retention_policy');
+  }
+
+  /**
+   * getRetentionPolicyRuns - Returns filtered and sorted retention cleanup run history.
+   * Supports filter_conditions on 'policy' and 'date' fields.
+   * Server-side only.
+   *
+   * @param {GetRetentionPolicyRunsOptions} options Filter, sort, and pagination options
+   * @returns {Promise<GetRetentionPolicyRunsResponse>}
+   */
+  async getRetentionPolicyRuns(options: GetRetentionPolicyRunsOptions = {}) {
+    this.validateServerSideAuth();
+    return await this.post<GetRetentionPolicyRunsResponse>(
+      this.baseURL + '/retention_policy/runs',
+      options,
+    );
+  }
 }

src/types.ts

@@ -4891,3 +4891,50 @@ export type QueryTeamUsageStatsResponse = APIResponse & {
   /** Cursor for pagination to fetch next page */
   next?: string;
 };
+
+export type RetentionPolicyConfig = {
+  max_age_hours: number;
+};
+
+export type RetentionPolicy = {
+  app_pk: number;
+  policy: string;
+  config: RetentionPolicyConfig;
+  enabled_at: string;
+};
+
+export type SetRetentionPolicyResponse = APIResponse & {
+  policy: RetentionPolicy;
+};
+
+export type DeleteRetentionPolicyResponse = APIResponse;
+
+export type GetRetentionPolicyResponse = APIResponse & {
+  policies: RetentionPolicy[];
+};
+
+export type RetentionRunStats = {
+  channels_deleted?: number;
+  messages_deleted?: number;
+};
+
+export type RetentionRunResponse = {
+  app_pk: number;
+  policy: string;
+  date: string;
+  stats: RetentionRunStats;
+};
+
+export type GetRetentionPolicyRunsOptions = {
+  filter_conditions?: Record<string, unknown>;
+  sort?: Array<{ field: string; direction: 1 | -1 }>;
+  next?: string;
+  prev?: string;
+  limit?: number;
+};
+
+export type GetRetentionPolicyRunsResponse = APIResponse & {
+  runs: RetentionRunResponse[];
+  next?: string;
+  prev?: string;
+};