From 5f397fd4a6fb445ca9e161d86d7538c666a132ad Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 6 Sep 2026 02:45:13 +0000 Subject: [PATCH] docs(client): the SDK examples read the resolved payload MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `analytics.query` / `analytics.meta` / `analytics.explain` and `automation.trigger` resolve to the payload rather than the dispatcher's `{ success, data }` envelope, but the three places a reader first meets the SDK showed the calls with nothing reading the resolved value: the page was neither wrong nor instructive about the shape. One payload read per example, on all three sites together — the docs site's Client SDK page, the Data API page's `GET /analytics/meta` prose, and the `@objectstack/client` README — using the members the contracts declare (`AnalyticsResult.rows` / `.fields[].name`, the bare `CubeMeta[]`, `{ sql, params }`, `AutomationResult.status`). Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01AhooRxUmvwYwcnQ5LATTB7 --- ...lient-readme-analytics-automation-payload-reads.md | 9 +++++++++ content/docs/api/client-sdk.mdx | 6 +++++- content/docs/api/data-api.mdx | 5 ++++- packages/client/README.md | 11 +++++++---- 4 files changed, 25 insertions(+), 6 deletions(-) create mode 100644 .changeset/client-readme-analytics-automation-payload-reads.md diff --git a/.changeset/client-readme-analytics-automation-payload-reads.md b/.changeset/client-readme-analytics-automation-payload-reads.md new file mode 100644 index 0000000000..8afd188304 --- /dev/null +++ b/.changeset/client-readme-analytics-automation-payload-reads.md @@ -0,0 +1,9 @@ +--- +"@objectstack/client": patch +--- + +The README's analytics and automation examples read the resolved payload. + +`client.analytics.query` / `analytics.meta` and `client.automation.trigger` stopped handing back the dispatcher's `{ success, data }` envelope in 17.0.0: each resolves to the payload itself. The README's namespace tour still showed all three as bare `await` calls with nothing reading the resolved value, so the package's own front page taught nothing about which shape comes back — neither wrong nor useful. Each of the three now assigns its result and reads one member of it: `report.rows` / `report.fields[0].name` (`AnalyticsResult`), `cubes[0].name` (the bare `CubeMeta[]`), `run.status` (`AutomationResult`) — the members those contracts actually declare, read off the payload rather than off a `data` wrapper. + +No behaviour changes; this is the README that ships inside the package. The docs site's Client SDK and Data API pages take the same treatment in the same PR. diff --git a/content/docs/api/client-sdk.mdx b/content/docs/api/client-sdk.mdx index 360a274949..c784b024c5 100644 --- a/content/docs/api/client-sdk.mdx +++ b/content/docs/api/client-sdk.mdx @@ -316,15 +316,18 @@ const result = await client.analytics.query({ where: { status: 'active' }, limit: 100, }); +console.log(result.rows.length, result.fields[0].name); // AnalyticsResult, unwrapped // Get cube metadata — all cubes, or one with meta('account') const meta = await client.analytics.meta('account'); +console.log(meta[0].name, meta[0].measures.length); // the bare cube list // Dry-run a query to its generated SQL (POST /analytics/sql) const explained = await client.analytics.explain({ cube: 'account', measures: ['revenue_sum'], }); +console.log(explained.sql, explained.params); // { sql, params } ``` ### `client.packages` — Package Management @@ -430,7 +433,8 @@ await client.i18n.getTranslations('zh-CN'); await client.i18n.getFieldLabels('account', 'zh-CN'); // Automation — Trigger workflows and automations -await client.automation.trigger('send_welcome_email', { userId }); +const welcome = await client.automation.trigger('send_welcome_email', { userId }); +console.log(welcome.status); // AutomationResult — the run's own outcome, unwrapped // A flow that does not run REJECTS — it does not resolve with an inner // `{ success: false }`. Branch on the thrown error's `code`, not on the diff --git a/content/docs/api/data-api.mdx b/content/docs/api/data-api.mdx index 4e76c19bf8..33fb566a00 100644 --- a/content/docs/api/data-api.mdx +++ b/content/docs/api/data-api.mdx @@ -444,7 +444,10 @@ Pass `?cube=` to filter the listing to a single cube (this is what **Response**: `{ success: true, data: [...] }` where `data` is an array of cube definitions with measures and dimensions (time-based dimensions are `dimensions` -entries with `type: "time"`). +entries with `type: "time"`). That envelope is the wire shape only — the SDK +unwraps it, so `client.analytics.meta(cube)` resolves to the cube array itself +and a caller reads `cubes[0].name`. The same holds for the other analytics and +automation calls; see the [Client SDK](/docs/api/client-sdk) page. ### `POST /analytics/sql` diff --git a/packages/client/README.md b/packages/client/README.md index 4646204164..742acff797 100644 --- a/packages/client/README.md +++ b/packages/client/README.md @@ -269,12 +269,15 @@ await client.i18n.getLocales(); await client.i18n.getTranslations('zh-CN'); await client.i18n.getFieldLabels('contact', 'zh-CN'); -// Analytics -await client.analytics.query({ object: 'sales', aggregations: ['sum:amount'] }); -await client.analytics.meta('sales'); +// Analytics — every method resolves to the payload itself +const report = await client.analytics.query({ object: 'sales', aggregations: ['sum:amount'] }); +console.log(report.rows.length, report.fields[0].name); +const cubes = await client.analytics.meta('sales'); +console.log(cubes[0].name); // Automation -await client.automation.trigger('send_welcome_email', { userId }); +const run = await client.automation.trigger('send_welcome_email', { userId }); +console.log(run.status); // File Storage await client.storage.upload(fileData, 'user');