@zoowork-ai/sdk 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -3,6 +3,46 @@
 All notable changes to `@zoowork-ai/sdk` (formerly `@zooclaw-agents/sdk`). Dates are the
 day the behaviour was verified, not the day it was written.
 
+## 0.4.2 — 2026-08-25
+
+### Documentation
+
+- **`addChannel` is idempotent, not an upsert — 0.3.4 said the opposite.** Re-posting an
+  identical body for the same `platform` + `account` replays the binding you already have and
+  answers `201` again; that same pair with a **different** `config` answers
+  `409 channel.conflict`. Rotating credentials therefore means `removeChannel` and then a
+  fresh `addChannel` — a plain re-add fails. The earlier note came from re-posting the same
+  body, where a replay cannot be told apart from an overwrite; the conflict path was measured
+  on staging 2026-08-25. No signature or behaviour change.
+
+## 0.4.1 — 2026-08-25
+
+### Internal
+
+- **Trailing slashes are stripped from the base URL by a scan rather than `/\/+$/`.** Same
+  output for every input; the regex retried at every start position on a long run of
+  slashes, which CodeQL flags as polynomial. Nothing hostile reaches it — the input is the
+  caller's own base URL — so this closes an alert rather than a vulnerability.
+
+### Documentation
+
+- **`account` on `addChannel` / `startFeishuSetup` now documents what it actually is.** It
+  names a binding and is part of its identity — `updateChannel` and `removeChannel` look a
+  binding up by `platform` + `account`, and nothing renames one. The four constraints, all
+  staging-verified 2026-08-25:
+  - the name is unique per USER across every agent, not per agent;
+  - `'default'` is usually taken already by a binding the app made, which this API will not
+    adopt — it answers `409 channel.conflict`;
+  - the format is `^[a-z0-9][a-z0-9_-]{0,63}$` plus three reserved words, and nothing is
+    normalized for you;
+  - this SDK cannot pre-check a name, because `listChannels` is scoped to one agent while the
+    constraint spans the whole account.
+- **`startFeishuSetup` warns that a name clash surfaces after the scan.** Approving the QR
+  registers a new app in the Feishu workspace before the binding is written, so a clash costs
+  a scan and leaves that app behind; retrying under the same name repeats both.
+
+No runtime change — comments only.
+
 ## 0.4.0 — 2026-08-25
 
 ### Changed (breaking)

package/dist/client.d.ts

@@ -275,7 +275,29 @@ export type ChannelPlatform = 'feishu' | 'slack' | 'wecom';
 export interface AddChannelInput {
     /** See {@link ChannelPlatform}. Typed loosely so a newly supported platform needs no SDK release. */
     platform: ChannelPlatform | (string & {});
-    /** Server default: `'default'`. */
+    /**
+     * Names this binding. It is part of the record's identity, not a setting: `updateChannel`
+     * and `removeChannel` find a binding by `platform` + `account`, and nothing renames one
+     * afterwards — you would remove it and bind again.
+     *
+     * Four things to know before you pick a value, all staging-verified 2026-08-25:
+     *
+     * - **The name is unique per USER, across every agent** — one active row per
+     *   (owner, platform, account). Binding `feishu`/`default` on one agent takes that name away
+     *   from all your other agents.
+     * - **`'default'` is very likely taken already** if the same login ever bound this platform in
+     *   the app. That binding was not made through this API, so the server refuses to adopt it and
+     *   answers `409 channel.conflict`.
+     * - **Format is `^[a-z0-9][a-z0-9_-]{0,63}$`**, plus three reserved words (`__proto__`,
+     *   `prototype`, `constructor`). Anything else is `400`. Nothing is normalized for you, so a
+     *   display name with capitals, spaces or non-ASCII characters is rejected rather than fixed.
+     * - **This SDK cannot pre-check the name for you.** {@link ZooworkClient.listChannels} is scoped
+     *   to one agent while the constraint spans your whole account, so a name another agent holds is
+     *   invisible here. Track your own names.
+     *
+     * Use whatever naming scheme your system already has. With no scheme of your own, the agent id
+     * works as-is: it matches the pattern and is unique per agent by construction.
+     */
     account?: string;
     display_name?: string;
     /** Server default: `'open'`. `'pairing'` is rejected with `400 channel.pairing_unsupported`. */
@@ -296,7 +318,7 @@ export interface AddChannelInput {
     config?: Record<string, unknown>;
 }
 export interface UpdateChannelInput {
-    /** Which platform account to touch. Server default: `'default'`. */
+    /** Which binding to touch — see {@link AddChannelInput.account}. Server default: `'default'`. */
     account?: string;
     dm_policy?: string;
     group_policy?: string;
@@ -305,7 +327,29 @@ export interface UpdateChannelInput {
 export interface FeishuSetupInput {
     /** `'feishu'` (default) or `'lark'` — the international brand of the same platform. */
     brand?: 'feishu' | 'lark';
-    /** Server default: `'default'`. */
+    /**
+     * Names this binding. It is part of the record's identity, not a setting: `updateChannel`
+     * and `removeChannel` find a binding by `platform` + `account`, and nothing renames one
+     * afterwards — you would remove it and bind again.
+     *
+     * Four things to know before you pick a value, all staging-verified 2026-08-25:
+     *
+     * - **The name is unique per USER, across every agent** — one active row per
+     *   (owner, platform, account). Binding `feishu`/`default` on one agent takes that name away
+     *   from all your other agents.
+     * - **`'default'` is very likely taken already** if the same login ever bound this platform in
+     *   the app. That binding was not made through this API, so the server refuses to adopt it and
+     *   answers `409 channel.conflict`.
+     * - **Format is `^[a-z0-9][a-z0-9_-]{0,63}$`**, plus three reserved words (`__proto__`,
+     *   `prototype`, `constructor`). Anything else is `400`. Nothing is normalized for you, so a
+     *   display name with capitals, spaces or non-ASCII characters is rejected rather than fixed.
+     * - **This SDK cannot pre-check the name for you.** {@link ZooworkClient.listChannels} is scoped
+     *   to one agent while the constraint spans your whole account, so a name another agent holds is
+     *   invisible here. Track your own names.
+     *
+     * Use whatever naming scheme your system already has. With no scheme of your own, the agent id
+     * works as-is: it matches the pattern and is unique per agent by construction.
+     */
     account?: string;
     /** Server default: `'open'`. */
     dm_policy?: string;
@@ -1012,8 +1056,12 @@ export interface ZooworkClient {
      * path for Slack and WeCom; Feishu also has the QR flow. See {@link ChannelPlatform} for what
      * binds and what does not.
      *
-     * **It is an upsert, not a create.** Binding the same `platform` + `account` twice answers
-     * `201` again and overwrites the first binding rather than conflicting.
+     * **It is idempotent, not an upsert.** Re-posting an identical body for the same
+     * `platform` + `account` answers `201` again and replays the binding you already have — it
+     * neither creates a second channel nor overwrites the first. That same pair with a DIFFERENT
+     * `config` answers `409 channel.conflict`, so rotating credentials means
+     * {@link removeChannel} and then a fresh `addChannel`; a plain re-add fails
+     * (staging-verified 2026-08-25).
      *
      * ⚠️ **201 means STORED, not WORKING.** Credentials are not validated at bind time: a channel
      * created from deliberately bogus credentials still answered 201 with `health: 'unknown'`,
@@ -1049,6 +1097,12 @@ export interface ZooworkClient {
      * Observed defaults: `expires_in: 600`, `poll_interval: 5`. `brand` picks the real host —
      * `'feishu'` answers an `open.feishu.cn` URI, `'lark'` an `open.larksuite.com` one, so the
      * brand has to match the workspace the person will approve it in.
+     *
+     * Pick `account` before you show the QR. Approving the scan registers a NEW app in that
+     * Feishu workspace, and only then does the binding get written — so a name clash surfaces as
+     * `409 channel.conflict` AFTER someone has scanned, with the freshly registered app left
+     * behind in their workspace. Retrying under the same name repeats both. See
+     * {@link AddChannelInput.account} for how names are scoped.
      */
     startFeishuSetup(agentId: string, input?: FeishuSetupInput): Promise<FeishuSetupSession>;
     /**

package/dist/client.js

@@ -27,6 +27,18 @@ function readEnv(name) {
     const value = proc?.env?.[name];
     return value === undefined || value === '' ? undefined : value;
 }
+/**
+ * Trailing `/` removed by scanning, not by `/\/+$/`. That regex retries at every start
+ * position on a long run of slashes, which is quadratic and which CodeQL flags. Nothing
+ * hostile can reach it — the input is the caller's own base URL — but one pass is simpler
+ * than arguing with the scanner about it.
+ */
+function stripTrailingSlashes(url) {
+    let end = url.length;
+    while (end > 0 && url.charCodeAt(end - 1) === 47 /* '/' */)
+        end--;
+    return end === url.length ? url : url.slice(0, end);
+}
 export class ZooworkError extends Error {
     status;
     /**
@@ -64,7 +76,7 @@ export class ZooworkError extends Error {
  */
 export function createZooworkClient(cfg = {}) {
     const doFetch = cfg.fetch ?? ((input, init) => fetch(input, init));
-    const base = (cfg.baseUrl ?? readEnv('ZOOWORK_BASE_URL') ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+    const base = stripTrailingSlashes(cfg.baseUrl ?? readEnv('ZOOWORK_BASE_URL') ?? DEFAULT_BASE_URL);
     const auth = cfg.auth ??
         (cfg.apiKey !== undefined
             ? { apiKey: cfg.apiKey }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zoowork-ai/sdk",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "TypeScript SDK for the ZooWork Managed Agents API (Developer Preview)",
   "keywords": [
     "zoowork",