From 3909a11333603cdb7fc82100c5af6ae4ff05b618 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 6 Sep 2026 05:22:25 +0000 Subject: [PATCH 1/2] docs(client): the README's AI example shows the surface that exists MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `client.ai.nlq` / `.suggest` / `.insights` were removed in v17 (#3718), and no server in any repo ever mounted `/api/v1/ai/{nlq,suggest,insights}` — every call 404ed for the whole life of the namespace. The `@objectstack/client` README's namespace tour still showed all three, and `files` ships `README.md` inside the tarball, so that example is the package's npm front page: a TypeScript reader copying it gets TS2339 and a JavaScript reader a runtime `TypeError`. Replaced with the live `ai` surface — `chat` (reading `answer.content` / `answer.usage`), `complete`, `models`, `conversations.list`, `agents.chat`, `pendingActions.list` — each call type-checked against this package's own published `dist/index.d.ts`, with the removed three kept as a control that still fails with TS2339 there. The comment also names the condition a reader would otherwise hit unexplained: `/ai` is served by `service-ai` (Cloud/EE), and an environment without it answers 501, not 404, carrying the remedy discovery reports under `services.ai`. The docs site's Client SDK page already carried this correction; it is untouched here. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01D47qPfEWVPmhguWgBZCi5N --- .changeset/client-readme-retired-ai-methods.md | 11 +++++++++++ packages/client/README.md | 14 ++++++++++---- 2 files changed, 21 insertions(+), 4 deletions(-) create mode 100644 .changeset/client-readme-retired-ai-methods.md diff --git a/.changeset/client-readme-retired-ai-methods.md b/.changeset/client-readme-retired-ai-methods.md new file mode 100644 index 0000000000..0013cadf5e --- /dev/null +++ b/.changeset/client-readme-retired-ai-methods.md @@ -0,0 +1,11 @@ +--- +"@objectstack/client": patch +--- + +The README's namespace tour documents the `ai` surface that exists, not the three methods v17 removed. + +`client.ai.nlq` / `.suggest` / `.insights` were deleted in 17.0.0 (#3718) — and no server in any repo ever mounted `/api/v1/ai/{nlq,suggest,insights}`, so they 404ed for the whole life of the namespace. The README's "AI Services" example still showed all three. Because `files` ships `README.md` inside the tarball, that example is the package's npm front page: a TypeScript reader copying it gets TS2339 on three properties that are not on `client.ai`, and a JavaScript reader gets a runtime `TypeError`. + +The block now shows the surface the client really exposes — `ai.chat` (with a read of `answer.content` / `answer.usage`), `ai.complete`, `ai.models`, `ai.conversations.list`, `ai.agents.chat`, `ai.pendingActions.list` — every call type-checked against the package's own published `dist/index.d.ts`. It also names the condition a reader will otherwise hit unexplained: the AI routes are served by `service-ai` (a Cloud/EE package), and an environment without it answers 501 rather than 404, with the remedy discovery reports under `services.ai`. + +No behaviour changes. `patch` rather than no changeset because the README is a published file of this package, so correcting it changes what `@objectstack/client` ships; the docs site's Client SDK page already carried this correction and is untouched here. diff --git a/packages/client/README.md b/packages/client/README.md index 742acff797..891c27e3c0 100644 --- a/packages/client/README.md +++ b/packages/client/README.md @@ -259,10 +259,16 @@ await client.approvals.reject(requestId, 'Incomplete'); await client.notifications.list({ read: false }); // unread only await client.notifications.markRead(['notif-1', 'notif-2']); -// AI Services -await client.ai.nlq({ query: 'Show me all active contacts' }); -await client.ai.suggest({ object: 'contact', field: 'industry' }); -await client.ai.insights({ object: 'sales', recordId: dealId }); +// AI Services — served by an AI service plugin (`service-ai`, a Cloud/EE +// package). The `/ai` routes are mounted either way, so an environment without +// it answers 501, not 404; discovery carries the same remedy under `services.ai`. +const answer = await client.ai.chat({ messages: [{ role: 'user', content: 'How many open orders this quarter?' }] }); +console.log(answer.content, answer.usage?.totalTokens); +await client.ai.complete({ prompt: 'Summarise this account in one line:' }); +await client.ai.models(); // plan-filtered picker list (ADR-0028) +await client.ai.conversations.list({ limit: 20 }); +await client.ai.agents.chat('build', { messages: [{ role: 'user', content: 'Draft a follow-up' }] }); +await client.ai.pendingActions.list({ status: 'pending' }); // human-in-the-loop queue // Internationalization await client.i18n.getLocales(); From 4731e998a68c06e607b4a0d561e43fbf87a4fbba Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 6 Sep 2026 06:27:59 +0000 Subject: [PATCH 2/2] docs(client): drop the ADR-0028 citation from the models example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ADR-0028 in this repository is Metadata Naming & Namespace Isolation (Deferred) — it says nothing about a model allowlist or plan tiers, and no ADR in docs/adr/ covers one. The citation was inherited verbatim from the docblock chain rather than checked, which is the same failure this card exists to correct. "plan-filtered" went with it: `AiModelsResponseSchema` declares `models` as a union of bare id strings and `{ id, label, default }` objects, and states that both shapes are live — objects when the service exposes the allowlist, bare ids when it falls back to the adapter's `listModels()`. Both are pinned accepted in `protocol.test.ts`. The comment now says only what the schema asserts unconditionally. Comment text only; no code, no other line, no changeset change. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01D47qPfEWVPmhguWgBZCi5N --- packages/client/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/client/README.md b/packages/client/README.md index 891c27e3c0..63c0e95c14 100644 --- a/packages/client/README.md +++ b/packages/client/README.md @@ -265,7 +265,7 @@ await client.notifications.markRead(['notif-1', 'notif-2']); const answer = await client.ai.chat({ messages: [{ role: 'user', content: 'How many open orders this quarter?' }] }); console.log(answer.content, answer.usage?.totalTokens); await client.ai.complete({ prompt: 'Summarise this account in one line:' }); -await client.ai.models(); // plan-filtered picker list (ADR-0028) +await client.ai.models(); // picker list — allowlist objects or bare ids, both live await client.ai.conversations.list({ limit: 20 }); await client.ai.agents.chat('build', { messages: [{ role: 'user', content: 'Draft a follow-up' }] }); await client.ai.pendingActions.list({ status: 'pending' }); // human-in-the-loop queue