Skip to content

Commit 6f50412

Browse files
authored
1 parent b515849 commit 6f50412

5 files changed

Lines changed: 10 additions & 10 deletions

File tree

‎.claude/skills/docs-sync/SKILL.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ Work one docs page at a time.
6767

6868
### Mislabelled fence
6969

70-
Label it `JavaScript` for client code, `Node.js` for server-side code (with or without `@stream-io/node-sdk`). `Node.js` fences are out of scope: never test, add or change them otherwise. The same goes for the stream-chat-js@9 versions next to them, `JavaScript (stream-chat-js@9)` and `Node.js (stream-chat-js@9)`: valid labels, never tested, added or changed.
70+
Label it `JavaScript` for client code, `Node.js` for server-side code (with or without `@stream-io/node-sdk`). `Node.js` fences are out of scope: never test, add or change them otherwise. The same goes for the stream-chat@9 versions next to them, `JavaScript (stream-chat@9)` and `Node.js (stream-chat@9)`: valid labels, never tested, added or changed.
7171

7272
### Region differs from its fence (docs changed)
7373

@@ -94,7 +94,7 @@ Write a test for it in the page's test file (create the file if the page is new)
9494
- Comment-only fences (e.g. "This is a server-side only feature...") need no region.
9595
- A fence that isn't code (e.g. a bare data shape) is a docs bug: rewrite it as code that runs (e.g. reading and logging the fields), and report it. Never remove a `JavaScript` fence just because it is a fragment or can't be tested: wrap it, or put it in `it.skip`.
9696
- A snippet the test app can't run goes in `it.skip('BLOCKED: <reason>', ...)` so it is still typechecked; report the exact API error.
97-
- **Server-only code in a `JavaScript` fence** (fails with a user token, e.g. 403 code 17 or "only allowed when using server side auth"): remove that fence, or just the server-only part, from the docs. Don't add a `Node.js` tab for it. When you remove the whole fence, remove its `JavaScript (stream-chat-js@9)` partner in the same tab group too: a v9 tab never stands without its v10 one. When you remove only part of it, leave the v9 fence as it is. To decide whether an endpoint or an acting-user field (`user_id`, `created_by_id`, ...) is client-side, check the client-side OpenAPI spec (`chat-clientside-api.json` in https://github.com/GetStream/protocol/tree/main/openapi/v2): an endpoint or field missing from it is server-only. Report every removal with the error.
97+
- **Server-only code in a `JavaScript` fence** (fails with a user token, e.g. 403 code 17 or "only allowed when using server side auth"): remove that fence, or just the server-only part, from the docs. Don't add a `Node.js` tab for it. When you remove the whole fence, remove its `JavaScript (stream-chat@9)` partner in the same tab group too: a v9 tab never stands without its v10 one. When you remove only part of it, leave the v9 fence as it is. To decide whether an endpoint or an acting-user field (`user_id`, `created_by_id`, ...) is client-side, check the client-side OpenAPI spec (`chat-clientside-api.json` in https://github.com/GetStream/protocol/tree/main/openapi/v2): an endpoint or field missing from it is server-only. Report every removal with the error.
9898
- A fence from another product (Feeds, `@stream-io/feeds-client`, React / React Native tabs on platform pages) isn't tested: report the page and heading so it can be added to `EXCLUDED_SECTIONS` in `test/docs-snippets/sync/parse.ts`. Don't edit `parse.ts` without asking the user.
9999

100100
### Broken docs snippet

‎test/docs-snippets/AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -131,7 +131,7 @@ New entries are added only after the user approves them (agents propose them in
131131

132132
### Client-side vs server-side
133133

134-
- Server-only `JavaScript` snippets (they fail with a user token) are removed from the page. Don't add a `Node.js` tab for them (`Node.js` fences are out of scope). If only part of a snippet is server-only (e.g. setting `channel_role` in `updateMemberPartial`), remove just that part from the `JavaScript` tab and keep the rest. Removing a whole `JavaScript` fence also removes its `JavaScript (stream-chat-js@9)` partner in the same tab group (a v9 tab never stands without its v10 one); a partial removal leaves the v9 fence unchanged. stream-chat-js@9 fences are otherwise out of scope, like `Node.js`.
134+
- Server-only `JavaScript` snippets (they fail with a user token) are removed from the page. Don't add a `Node.js` tab for them (`Node.js` fences are out of scope). If only part of a snippet is server-only (e.g. setting `channel_role` in `updateMemberPartial`), remove just that part from the `JavaScript` tab and keep the rest. Removing a whole `JavaScript` fence also removes its `JavaScript (stream-chat@9)` partner in the same tab group (a v9 tab never stands without its v10 one); a partial removal leaves the v9 fence unchanged. stream-chat@9 fences are otherwise out of scope, like `Node.js`.
135135
- If every `JavaScript` fence of a page turns out to be server-only (all removed), don't write a client test file: a test that only asserts the user-token rejection covers no docs snippet. Record the error in the report instead.
136136
- Acting-user fields (`user_id`, `user: { id }`, `created_by_id`, a `userId` option saying who performs the action): remove one from a `JavaScript` snippet only if the client-side OpenAPI spec doesn't list it on that endpoint's request. Check `chat-clientside-api.json` (`gh api -H 'Accept: application/vnd.github.raw' repos/GetStream/protocol/contents/openapi/v2/chat-clientside-api.json`): find the operation, follow the `requestBody` `$ref`s, and cite the operation id + schema in the report. If the client spec has the field, keep it and test it. Example: `SendMessage`'s client `MessageRequest` has no `user`/`user_id` (the server one does), so `user: systemUser` is removed from `sendMessage` snippets. Don't decide by probing: some endpoints silently ignore the field and act on the connected user (e.g. `channel.mute({ user_id })`). `user_id` as data is fine (filter values, member lists like `addMembers([{ user_id }])`, sort keys).
137137
- `getUnreadCount(userId)`, `channel.markRead({ user_id })` and `channel.markUnread({ user_id })` silently act on the connected user with a user token (no error), and the client spec has no `user_id` on `UnreadCounts`/`MarkReadRequest`/`MarkUnreadRequest`: remove it from `JavaScript` tabs. `getUnreadCountBatch` is server-only (403 code 17). Likewise `sendMessage(msg, { pending: true, pending_message_metadata })` is ignored client-side (sent as a regular message): create pending messages server-side (`sendServerMessage(serverClient, cid, { text, user_id }, { pending: true })`, any `messaging` channel), and check the effect, not just the 200.

‎test/docs-snippets/README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ Typed tests that run the client-side JavaScript snippets of the chat and platfor
44
sidebars `getstream.io/content/docs/_sidebars/[chat][javascript].json` and `[platform][default].json`) against a
55
real Stream app. Only fences labelled `JavaScript` are in scope (docs fences must always have a label): they are fixed
66
when they are wrong or contain server-side code. `Node.js` fences (server-side, with or without `@stream-io/node-sdk`) and the
7-
stream-chat-js@9 versions next to them (`JavaScript (stream-chat-js@9)`, `Node.js (stream-chat-js@9)`) are out of scope and are
7+
stream-chat@9 versions next to them (`JavaScript (stream-chat@9)`, `Node.js (stream-chat@9)`) are out of scope and are
88
neither tested nor changed.
99
Platform pages also cover other products: their Feeds fences (`@stream-io/feeds-client` and its React / React Native
1010
hooks) are excluded with `EXCLUDED_SECTIONS` (see below).
@@ -69,8 +69,8 @@ const message = await client
6969
- `index` is 1-based among fences with the same heading text and tab (default 1).
7070
- **COPY**: `name="literal"` pairs, applied to the region before comparing (identifier `name` becomes the docs literal). Don't use COPY variables as object keys or shorthand properties.
7171
- **Comparison**: both sides are formatted with the same prettier options, so quote style and line wrapping don't matter, but any code or comment change does.
72-
- **Coverage** (checked first): every JS fence (`js`/`javascript`/`ts`/`typescript`) on the pages of the tested sidebars (`SIDEBARS` in `sync/parse.ts`: `[chat][javascript].json`, `[platform][default].json`), whether or not the page has tests yet, must have a region (inside `it.skip` if it can't run). `Node.js` and stream-chat-js@9 fences (`OUT_OF_SCOPE_TABS`) and comment-only fences (e.g. the "server-side only" placeholders) are ignored.
73-
- **Labels**: every JS fence on those pages must be labelled `JavaScript`, `Node.js`, `JavaScript (stream-chat-js@9)` or `Node.js (stream-chat-js@9)` (`ALLOWED_JS_LABELS`); unlabelled or otherwise labelled JS fences fail.
72+
- **Coverage** (checked first): every JS fence (`js`/`javascript`/`ts`/`typescript`) on the pages of the tested sidebars (`SIDEBARS` in `sync/parse.ts`: `[chat][javascript].json`, `[platform][default].json`), whether or not the page has tests yet, must have a region (inside `it.skip` if it can't run). `Node.js` and stream-chat@9 fences (`OUT_OF_SCOPE_TABS`) and comment-only fences (e.g. the "server-side only" placeholders) are ignored.
73+
- **Labels**: every JS fence on those pages must be labelled `JavaScript`, `Node.js`, `JavaScript (stream-chat@9)` or `Node.js (stream-chat@9)` (`ALLOWED_JS_LABELS`); unlabelled or otherwise labelled JS fences fail.
7474
- **Excluded pages**: `EXCLUDED_PAGES` in `sync/parse.ts` lists sidebar pages that are deliberately not validated, with a reason (e.g. the v9 upgrade guide's TSX type examples). Both checks skip them.
7575
- **Excluded sections**: `EXCLUDED_SECTIONS` in `sync/parse.ts` lists headings per page, with a reason. Every fence nested under one of them (at any heading level) is skipped by both checks. Used for the Feeds fences on platform pages (e.g. `Feeds Push Preferences`, whose `JavaScript`, `React` and `React Native` tabs use `@stream-io/feeds-client`).
7676
- **`DOCS_SYNC_WRITE=<page path, e.g. chat/_default/04-messages/01-send_message.md> yarn test-docs-sync`** writes the regions of that page into the docs fences (docs prettier style). Use it to apply a fix to the docs. `DOCS_SYNC_WRITE=1` writes all pages.

‎test/docs-snippets/sync/docs-sync.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ import type { DocsFence, TestRegion } from './parse';
2121

2222
// `yarn test-docs-sync`, in this order:
2323
// 1. Every JS fence (except `OUT_OF_SCOPE_TABS` fences: `Node.js` and the
24-
// stream-chat-js@9 versions, and comment-only fences, like the "server-side only"
24+
// stream-chat@9 versions, and comment-only fences, like the "server-side only"
2525
// placeholders) on the pages of the tested sidebars (chat JavaScript, platform) has a
2626
// test region.
2727
// 2. Every JS fence on those pages is labelled with one of `ALLOWED_JS_LABELS`.
@@ -93,7 +93,7 @@ describe.skipIf(!hasDocs)(`docs sync (${DOCS_DIR})`, () => {
9393
);
9494
expect(
9595
mislabelled,
96-
`JS fences need label="${ALLOWED_JS_LABELS.join('" or label="')}" (client-side code, server-side Node.js code with or without @stream-io/node-sdk, or their stream-chat-js@9 versions)`,
96+
`JS fences need label="${ALLOWED_JS_LABELS.join('" or label="')}" (client-side code, server-side Node.js code with or without @stream-io/node-sdk, or their stream-chat@9 versions)`,
9797
).toEqual([]);
9898
});
9999

‎test/docs-snippets/sync/parse.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -58,10 +58,10 @@ export const JS_TAB = 'JavaScript';
5858
*/
5959
export const NODE_TAB = 'Node.js';
6060
/**
61-
* Out of scope too: the stream-chat-js@9 versions shown next to `JavaScript` (client-side)
61+
* Out of scope too: the stream-chat@9 versions shown next to `JavaScript` (client-side)
6262
* and `Node.js` (server-side). Neither tested nor changed.
6363
*/
64-
export const V9_TABS = ['JavaScript (stream-chat-js@9)', 'Node.js (stream-chat-js@9)'];
64+
export const V9_TABS = ['JavaScript (stream-chat@9)', 'Node.js (stream-chat@9)'];
6565
/** Fences with these labels are never tested. */
6666
export const OUT_OF_SCOPE_TABS = [NODE_TAB, ...V9_TABS];
6767
/** Every JS fence must carry one of these labels. */

0 commit comments

Comments
 (0)