You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 6f50412
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: .claude/skills/docs-sync/SKILL.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -67,7 +67,7 @@ Work one docs page at a time.
67
67
68
68
### Mislabelled fence
69
69
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.
71
71
72
72
### Region differs from its fence (docs changed)
73
73
@@ -94,7 +94,7 @@ Write a test for it in the page's test file (create the file if the page is new)
94
94
- Comment-only fences (e.g. "This is a server-side only feature...") need no region.
95
95
- 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`.
96
96
- 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.
98
98
- 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.
Copy file name to clipboardExpand all lines: test/docs-snippets/AGENTS.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -131,7 +131,7 @@ New entries are added only after the user approves them (agents propose them in
131
131
132
132
### Client-side vs server-side
133
133
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`.
135
135
- 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.
136
136
- 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).
137
137
-`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.
Copy file name to clipboardExpand all lines: test/docs-snippets/README.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@ Typed tests that run the client-side JavaScript snippets of the chat and platfor
4
4
sidebars `getstream.io/content/docs/_sidebars/[chat][javascript].json` and `[platform][default].json`) against a
5
5
real Stream app. Only fences labelled `JavaScript` are in scope (docs fences must always have a label): they are fixed
6
6
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
8
8
neither tested nor changed.
9
9
Platform pages also cover other products: their Feeds fences (`@stream-io/feeds-client` and its React / React Native
10
10
hooks) are excluded with `EXCLUDED_SECTIONS` (see below).
@@ -69,8 +69,8 @@ const message = await client
69
69
-`index` is 1-based among fences with the same heading text and tab (default 1).
70
70
-**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.
71
71
-**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.
74
74
-**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.
75
75
-**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`).
76
76
-**`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.
`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)`,
0 commit comments