Skip to content

Commit 5b66958

Browse files
committed
docs(sdk): resync the corrected reference; contain its tables and endpoint paths at phone width
Review findings on #1106 (nik13). The pages are resynced from futureagi-sdk 3269d58, where the generator was fixed: ref-aware example values (dashboards query shows an object for time_range), error imports from @future-agi/sdk/platform, no TypeScript strictResponses claim. Nothing was edited by hand here. Phone width: every generated table now sits in <div class="sdk-ref-table">, styled in global.css as a bounded horizontal scroller (max-width 100%, overflow-x auto), so a long identifier scrolls inside the table instead of widening the page; h3/h4 may break inside a single long identifier; and the ApiEndpoint badge lets a long path wrap (min-w-0, overflow-wrap: anywhere), which was the other source of document overflow. Nothing is clipped. scripts/sdk-reference-mobile.cjs (part of test:integrations:browser, so it runs in pr-checks after the preview starts) loads every page of the reference group at a 390 px viewport and fails if the document scrolls horizontally, if a table is outside .sdk-ref-table, or if any heading, cell or code block starts left of the viewport. Locally: 34 pages fit 390 px (annotation-queues was 536 px, prompts 402 px, prompt models 425 px before).
1 parent 30cd2eb commit 5b66958

38 files changed

Lines changed: 381 additions & 18 deletions

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
"new-doc": "node scripts/new-doc.mjs",
1313
"audit-links": "node scripts/audit-links.mjs",
1414
"test:integrations": "node --test scripts/integrations.test.mjs scripts/new-doc.test.mjs scripts/sdk-reference-release.test.mjs",
15-
"test:integrations:browser": "node scripts/integrations.browser.cjs && node scripts/integrations.regression.cjs && node scripts/widget-regression.cjs",
15+
"test:integrations:browser": "node scripts/integrations.browser.cjs && node scripts/integrations.regression.cjs && node scripts/widget-regression.cjs && node scripts/sdk-reference-mobile.cjs",
1616
"check:integrations": "tsc --allowJs --checkJs --noEmit --strict --types node --target ES2022 --module nodenext src/lib/integrations.mjs"
1717
},
1818
"dependencies": {

‎scripts/sdk-reference-mobile.cjs‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
// Phone-width regression for the generated platform SDK reference: every page in the
2+
// sidebar group must fit a 390 px viewport with no horizontal page scroll, and every
3+
// reference table must sit in a bounded scroller (.sdk-ref-table) so wide identifiers
4+
// scroll inside the table instead of widening the document. Runs against the preview
5+
// on 127.0.0.1:4321 (npm run build && npm run preview), like integrations.browser.cjs.
6+
const { chromium } = require('playwright');
7+
const assert = require('node:assert/strict');
8+
const path = require('node:path');
9+
10+
const BASE = 'http://127.0.0.1:4321';
11+
const WIDTH = 390;
12+
13+
async function routes() {
14+
const { sdkReferenceNavigation } = await import(path.join(__dirname, '..', 'src', 'lib', 'sdk-reference.mjs'));
15+
const out = [];
16+
const walk = (items) => {
17+
for (const item of items) {
18+
if (item.href) out.push(item.href);
19+
if (item.items) walk(item.items);
20+
}
21+
};
22+
walk(sdkReferenceNavigation.items);
23+
return out;
24+
}
25+
26+
(async () => {
27+
let ready = false;
28+
for (let i = 0; i < 30 && !ready; i++) {
29+
try { if ((await fetch(BASE + '/docs/sdk/reference')).ok) ready = true; else await new Promise((r) => setTimeout(r, 1000)); } catch { await new Promise((r) => setTimeout(r, 1000)); }
30+
}
31+
assert.ok(ready, 'Start the docs preview on 127.0.0.1:4321 before running browser checks');
32+
const hrefs = await routes();
33+
assert.ok(hrefs.length >= 30, `expected the full reference in the sidebar, found ${hrefs.length} routes`);
34+
const browser = await chromium.launch({ headless: true });
35+
const ctx = await browser.newContext({ viewport: { width: WIDTH, height: 844 }, colorScheme: 'dark' });
36+
const page = await ctx.newPage();
37+
const failures = [];
38+
for (const href of hrefs) {
39+
await page.goto(BASE + href + '/', { waitUntil: 'networkidle' });
40+
const m = await page.evaluate(() => ({
41+
scrollWidth: document.documentElement.scrollWidth,
42+
clientWidth: document.documentElement.clientWidth,
43+
tables: document.querySelectorAll('.docs-content table').length,
44+
unwrapped: [...document.querySelectorAll('.docs-content table')].filter((t) => !t.closest('.sdk-ref-table')).length,
45+
offscreen: [...document.querySelectorAll('.docs-content h2, .docs-content h3, .docs-content td, .docs-content pre')]
46+
.filter((el) => el.getBoundingClientRect().left < 0).length,
47+
}));
48+
if (m.scrollWidth > m.clientWidth) failures.push(`${href}: document scrolls to ${m.scrollWidth}px at a ${m.clientWidth}px viewport`);
49+
if (m.unwrapped) failures.push(`${href}: ${m.unwrapped} table(s) not inside .sdk-ref-table`);
50+
if (m.offscreen) failures.push(`${href}: ${m.offscreen} element(s) start left of the viewport (clipped content)`);
51+
console.log(`${href}: ${m.scrollWidth}px wide, ${m.tables} table(s)`);
52+
}
53+
await browser.close();
54+
assert.deepEqual(failures, [], failures.join('\n'));
55+
console.log(`sdk reference mobile: ${hrefs.length} pages fit ${WIDTH}px with bounded tables`);
56+
})().catch((error) => {
57+
console.error(error.message || error);
58+
process.exit(1);
59+
});

‎src/components/docs/ApiEndpoint.astro‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,5 +27,6 @@ const methodColors = {
2727
]}>
2828
{method}
2929
</span>
30-
<code class="text-sm font-mono text-[var(--color-text-primary)]">{path}</code>
30+
<!-- min-w-0 + overflow-wrap: a long path wraps inside the badge instead of widening a phone page -->
31+
<code class="text-sm font-mono text-[var(--color-text-primary)] min-w-0 [overflow-wrap:anywhere]">{path}</code>
3132
</div>

‎src/pages/docs/sdk/reference/account-models.mdx‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,21 @@ title: "Account response models"
33
description: "The 8 response models returned by the account resources of the Future AGI Python and TypeScript SDKs, with every field and its type."
44
---
55

6-
The models returned by `client.account`, `client.workspaces`, `client.usage`, importable from `fi.platform.models` (Python) and `@future-agi/sdk/platform/models` (TypeScript). Types are language-neutral: `string[]` is a Python `list[str]` and a TypeScript `string[]`, and a type named after another model links to that model. Parsing is tolerant by default: a response that leaves a field out or adds one never breaks a call, and `strict_responses=True` (Python) or `strictResponses: true` (TypeScript) rejects a response that misses a field the contract requires (see the [overview](/docs/sdk/reference#strict-mode)).
6+
The models returned by `client.account`, `client.workspaces`, `client.usage`, importable from `fi.platform.models` (Python) and `@future-agi/sdk/platform/models` (TypeScript). Types are language-neutral: `string[]` is a Python `list[str]` and a TypeScript `string[]`, and a type named after another model links to that model. Parsing is tolerant by default: a response that leaves a field out or adds one never breaks a call. In Python, `Client(strict_responses=True)` rejects a response that misses a field the contract requires (see the [overview](/docs/sdk/reference#strict-mode)); TypeScript has no strict mode.
77

88
## Models
99

10+
<div class="sdk-ref-table">
11+
1012
| Model | Fields |
1113
|---|---|
1214
| <span id="usageoverviewdimension">`UsageOverviewDimension`</span> | `key: string`, `display_name: string`, `display_unit: string`, `current_usage: number`, `current_usage_raw: number`, `free_allowance: number`, `projected_usage: number`, `estimated_cost: number`, `tier_breakdown:` [`UsageTierBreakdown`](#usagetierbreakdown)[], `usage_pct: number` |
1315
| <span id="usageoverviewresult">`UsageOverviewResult`</span> | `plan: string`, `plan_display_name: string`, `platform_fee: number`, `period: string`, `billing_period_start: string`, `billing_period_end: string`, `total_estimated_cost: number`, `total_with_platform: number`, `dimensions:` [`UsageOverviewDimension`](#usageoverviewdimension)[], `pending_cancel: boolean`, `cancel_at: string` |
1416
| <span id="usagetierbreakdown">`UsageTierBreakdown`</span> | `tier_start: number`, `tier_end: number`, `quantity: number`, `rate: number`, `cost: number` |
1517
| <span id="userinfoorganization">`UserInfoOrganization`</span> | `id: string`, `name: string`, `display_name: string`, `ws_enabled: boolean` |
16-
| <span id="userinforesponse">`UserInfoResponse`</span> | `id: string`, `email: string`, `name: string`, `organization_role: string`, `organization:` [`UserInfoOrganization`](#userinfoorganization), `created_at: string`, `status: string`, `role: string`, `goals: string[]`, `remember_me: boolean`, `get_started_completed: boolean`, `onboarding_completed: boolean`, `ws_enabled: boolean`, `requires_org_setup: boolean`, `default_workspace_id: string`, `default_workspace_name: string`, `default_workspace_display_name: string`, `default_workspace_role: string`, `org_level: integer`, `ws_level: integer`, `effective_level: integer`, `has_2fa_enabled: boolean`, `two_factor_methods:` [`UserInfoTwoFactorMethods`](#userinfotwofactormethods), `org_2fa_required: boolean`, `org_2fa_grace_ends_at: string` |
18+
| <span id="userinforesponse">`UserInfoResponse`</span> | `id: string`, `email: string`, `name: string`, `organization_role: string`, `organization:` [`UserInfoOrganization`](#userinfoorganization), `created_at: string`, `status: string`, `role: string`, `goals: string[]`, `remember_me: boolean`, `get_started_completed: boolean`, `onboarding_completed: boolean`, `ws_enabled: boolean`, `requires_org_setup: boolean`, `default_workspace_id: string`, `default_workspace_name: string`, `default_workspace_display_name: string`, `default_workspace_role: string`, `org_level: integer`, `ws_level: integer`, `effective_level: integer`, `has_2fa_enabled: boolean`, `two_factor_methods:` [`UserInfoTwoFactorMethods`](#userinfotwofactormethods), `org_2fa_required: boolean`, `org_2fa_grace_ends_at: string`, `restrict_simulate_to_environments: boolean` |
1719
| <span id="userinfotwofactormethods">`UserInfoTwoFactorMethods`</span> | `totp: boolean`, `passkey: boolean` |
1820
| <span id="workspacemanagementitem">`WorkspaceManagementItem`</span> | `id: string`, `name: string`, `display_name: string`, `description: string`, `is_default: boolean`, `member_count: integer`, `created_at: string`, `created_by: string` |
1921
| <span id="workspacemanagementlistresult">`WorkspaceManagementListResult`</span> | `organization: string`, `workspaces:` [`WorkspaceManagementItem`](#workspacemanagementitem)[], `total: integer` |
22+
23+
</div>

‎src/pages/docs/sdk/reference/account.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,14 @@ description: "Reference for client.account in the Future AGI Python and TypeScri
77

88
## Methods
99

10+
<div class="sdk-ref-table">
11+
1012
| Method | Description |
1113
|---|---|
1214
| [`account.whoami`](#accountwhoami) | Return the authenticated user, organization, and workspace context. |
1315

16+
</div>
17+
1418
## client.account
1519

1620
### account.whoami

‎src/pages/docs/sdk/reference/agents.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ description: "Reference for client.agents in the Future AGI Python and TypeScrip
77

88
## Methods
99

10+
<div class="sdk-ref-table">
11+
1012
| Method | Description |
1113
|---|---|
1214
| [`agents.create`](#agentscreate) | Create a text or voice agent definition and its first active version. |
@@ -15,6 +17,8 @@ description: "Reference for client.agents in the Future AGI Python and TypeScrip
1517
| [`agents.update`](#agentsupdate) | Edit an agent definition. |
1618
| [`agents.versions.create`](#agentsversionscreate) | Snapshot agent configuration into a new version and activate it. |
1719

20+
</div>
21+
1822
## client.agents
1923

2024
### agents.create

‎src/pages/docs/sdk/reference/alerts.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,15 @@ description: "Reference for client.alerts in the Future AGI Python and TypeScrip
77

88
## Methods
99

10+
<div class="sdk-ref-table">
11+
1012
| Method | Description |
1113
|---|---|
1214
| [`alerts.logs.list`](#alertslogslist) | List alerts that have fired in numbered pages. |
1315
| [`alerts.rules.list`](#alertsruleslist) | List the configured alert monitors - what each one watches, its threshold and its project. |
1416

17+
</div>
18+
1519
## client.alerts
1620

1721
## client.alerts.logs

‎src/pages/docs/sdk/reference/annotation-models.mdx‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,12 @@ title: "Annotation response models"
33
description: "The 30 response models returned by the annotation resources of the Future AGI Python and TypeScript SDKs, with every field and its type."
44
---
55

6-
The models returned by `client.annotation_queues`, `client.annotations`, `client.scores`, importable from `fi.platform.models` (Python) and `@future-agi/sdk/platform/models` (TypeScript). Types are language-neutral: `string[]` is a Python `list[str]` and a TypeScript `string[]`, and a type named after another model links to that model. Parsing is tolerant by default: a response that leaves a field out or adds one never breaks a call, and `strict_responses=True` (Python) or `strictResponses: true` (TypeScript) rejects a response that misses a field the contract requires (see the [overview](/docs/sdk/reference#strict-mode)).
6+
The models returned by `client.annotation_queues`, `client.annotations`, `client.scores`, importable from `fi.platform.models` (Python) and `@future-agi/sdk/platform/models` (TypeScript). Types are language-neutral: `string[]` is a Python `list[str]` and a TypeScript `string[]`, and a type named after another model links to that model. Parsing is tolerant by default: a response that leaves a field out or adds one never breaks a call. In Python, `Client(strict_responses=True)` rejects a response that misses a field the contract requires (see the [overview](/docs/sdk/reference#strict-mode)); TypeScript has no strict mode.
77

88
## Models
99

10+
<div class="sdk-ref-table">
11+
1012
| Model | Fields |
1113
|---|---|
1214
| <span id="annotationqueue">`AnnotationQueue`</span> | `id: string`, `name: string`, `description: string`, `instructions: string`, `status: string`, `assignment_strategy: string`, `annotations_required: integer`, `reservation_timeout_minutes: integer`, `requires_review: boolean`, `auto_assign: boolean`, `organization: string`, `project: string`, `dataset: string`, `agent_definition: string`, `is_default: boolean`, `labels:` [`QueueLabelNested`](#queuelabelnested)[], `annotators:` [`QueueAnnotatorNested`](#queueannotatornested)[], `label_ids: string[]`, `annotator_ids: string[]`, `annotator_roles: any`, `label_count: integer`, `annotator_count: integer`, `item_count: integer`, `completed_count: integer`, `created_by: string`, `created_by_name: string`, `viewer_role: string`, `viewer_roles: string[]`, `deleted: boolean`, `created_at: string` |
@@ -39,3 +41,5 @@ The models returned by `client.annotation_queues`, `client.annotations`, `client
3941
| <span id="queueremovelabelresult">`QueueRemoveLabelResult`</span> | `removed: boolean` |
4042
| <span id="queuesubmitannotationsresult">`QueueSubmitAnnotationsResult`</span> | `submitted: integer` |
4143
| <span id="score">`Score`</span> | `id: string`, `source_type: string`, `source_id: any`, `label_id: string`, `label_name: string`, `label_type: string`, `label_settings: any`, `label_allow_notes: boolean`, `value: any`, `value_history: any`, `score_source: string`, `notes: string`, `annotator: string`, `annotator_name: string`, `annotator_email: string`, `queue_item: string`, `queue_id: any`, `created_at: string`, `updated_at: string` |
44+
45+
</div>

‎src/pages/docs/sdk/reference/annotation-queues.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ description: "Reference for client.annotation_queues in the Future AGI Python an
77

88
## Methods
99

10+
<div class="sdk-ref-table">
11+
1012
| Method | Description |
1113
|---|---|
1214
| [`annotation_queues.add_label`](#annotation_queuesadd_label) | Add an annotation label to a queue. |
@@ -33,6 +35,8 @@ description: "Reference for client.annotation_queues in the Future AGI Python an
3335
| [`annotation_queues.items.skip`](#annotation_queuesitemsskip) | Skip a queue item and return the next one to work on. |
3436
| [`annotation_queues.items.submit`](#annotation_queuesitemssubmit) | Submit annotation values for an item in an annotation queue. |
3537

38+
</div>
39+
3640
## client.annotation_queues
3741

3842
### annotation_queues.add_label

‎src/pages/docs/sdk/reference/annotations.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ description: "Reference for client.annotations in the Future AGI Python and Type
77

88
## Methods
99

10+
<div class="sdk-ref-table">
11+
1012
| Method | Description |
1113
|---|---|
1214
| [`annotations.bulk_create`](#annotationsbulk_create) | Create or update annotations and notes on spans in bulk. |
@@ -15,6 +17,8 @@ description: "Reference for client.annotations in the Future AGI Python and Type
1517
| [`annotations.labels.get`](#annotationslabelsget) | Return an annotation label by id. |
1618
| [`annotations.labels.list`](#annotationslabelslist) | List annotation labels, optionally filtered by project, type or search text. |
1719

20+
</div>
21+
1822
## client.annotations
1923

2024
### annotations.bulk_create

0 commit comments

Comments
 (0)