@farthershore/client 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/CHANGELOG.md +34 -0
  2. package/README.md +251 -2
  3. package/dist/index.js +6997 -0
  4. package/dist/types/api.generated.d.ts +1356 -0
  5. package/dist/types/credentials.d.ts +78 -0
  6. package/dist/types/envelope.d.ts +48 -0
  7. package/dist/types/errors.d.ts +86 -0
  8. package/dist/types/helpers/abort.d.ts +7 -0
  9. package/dist/types/helpers/paginate.d.ts +32 -0
  10. package/dist/types/helpers/poll.d.ts +26 -0
  11. package/dist/types/helpers/refs.d.ts +84 -0
  12. package/dist/types/helpers/wait-for-frontend-build.d.ts +43 -0
  13. package/dist/types/index.d.ts +24 -0
  14. package/dist/types/operations/agents.d.ts +48 -0
  15. package/dist/types/operations/agreements.d.ts +44 -0
  16. package/dist/types/operations/analytics.d.ts +25 -0
  17. package/dist/types/operations/audit-notifications.d.ts +33 -0
  18. package/dist/types/operations/auth.d.ts +16 -0
  19. package/dist/types/operations/backends.d.ts +53 -0
  20. package/dist/types/operations/billing.d.ts +15 -0
  21. package/dist/types/operations/businesses.d.ts +92 -0
  22. package/dist/types/operations/change-sets.d.ts +43 -0
  23. package/dist/types/operations/consumers.d.ts +49 -0
  24. package/dist/types/operations/define.d.ts +91 -0
  25. package/dist/types/operations/environments.d.ts +19 -0
  26. package/dist/types/operations/frontend.d.ts +13 -0
  27. package/dist/types/operations/index.d.ts +1036 -0
  28. package/dist/types/operations/maker-tokens.d.ts +30 -0
  29. package/dist/types/operations/organizations.d.ts +71 -0
  30. package/dist/types/operations/personas.d.ts +46 -0
  31. package/dist/types/operations/plans-usage.d.ts +18 -0
  32. package/dist/types/operations/platform.d.ts +47 -0
  33. package/dist/types/operations/portal.d.ts +49 -0
  34. package/dist/types/operations/promo-codes.d.ts +19 -0
  35. package/dist/types/operations/variables.d.ts +25 -0
  36. package/dist/types/operations/webhooks.d.ts +67 -0
  37. package/dist/types/surface-types.d.ts +54 -0
  38. package/dist/types/surface.d.ts +35 -0
  39. package/dist/types/transport.d.ts +119 -0
  40. package/dist/types/types.d.ts +469 -0
  41. package/dist/types/version.d.ts +8 -0
  42. package/package.json +53 -3
package/CHANGELOG.md ADDED
@@ -0,0 +1,34 @@
1
+ # Changelog — @farthershore/client
2
+
3
+ All notable changes to the API client are documented here. This package
4
+ versions independently from the CLI and the other SDKs. Pre-1.0: minor versions
5
+ may include breaking changes.
6
+
7
+ ## [0.1.0] - 2026-10-12
8
+
9
+ ### Added
10
+
11
+ - `createFartherShore({ transport })`: the namespaced operation surface
12
+ (`fs.<namespace>.<method>(input, { signal, dryRun, retry })`), one method
13
+ per operation key at its derived namespace path, each with static `meta`
14
+ (summary, description, side effect, destructive, one-time secret, preview,
15
+ reconcile read, pagination, permission). `fs.call(opKey, …)` and
16
+ `listOperations()` for discovery. `dryRun` is refused locally on operations
17
+ without a preview; an `OUTCOME_UNKNOWN` error carries
18
+ `details.reconcile = { op }`.
19
+ - Helpers: `paginate` / `collect` (offset and cursor), `createRefs` (business
20
+ and environment references), `poll`, `waitForFrontendBuild`.
21
+ - `createTransport`: the authenticated transport extracted from the
22
+ `farthershore` CLI, with its retry rules (reads retry on transient failures;
23
+ writes only on a server-proven refusal), `OUTCOME_UNKNOWN` reporting,
24
+ per-attempt deadlines that cover the body read, single-flight token exchange,
25
+ one re-exchange after a 401, `dryRun`, and an `AbortSignal` on every request.
26
+ - `x-fs-client: @farthershore/client/<version>` on every request, followed by
27
+ the caller's `clientInfo`.
28
+ - Credential sources: `cliExchangeCredentials`, `bearerCredentials`,
29
+ `consumerCredentials`.
30
+ - `FartherShoreError` / `FartherShoreTransportError` with `toJSON()`, and a
31
+ single error-envelope reader (`errorEnvelopeOf`, `diagnosticsOf`).
32
+ - `transport.raw()` for untyped requests to any path. It never follows a
33
+ redirect: any 3xx is `REDIRECT_NOT_FOLLOWED` with `details.location`,
34
+ never retried, and reported as an unknown outcome for a write.
package/README.md CHANGED
@@ -1,3 +1,252 @@
1
- # Temporary Holding Version
1
+ # @farthershore/client
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The Farther Shore API client that the `farthershore` CLI and its MCP server
4
+ run on: a namespaced, typed operation surface (`fs.runtimeTokens.revoke(…)`)
5
+ over an authenticated `fetch` transport with exact retry and outcome
6
+ semantics, pluggable credential sources, and typed errors.
7
+
8
+ > **Status: `0.1.0`.** Pre-1.0: minor releases may include breaking changes.
9
+ > Responses keep today's hand-written types; where none exists yet a method
10
+ > returns `unknown`. Runtime schemas follow domain by domain.
11
+
12
+ ```sh
13
+ npm install @farthershore/client
14
+ ```
15
+
16
+ Works anywhere with a standard `fetch` (Node 22+, browsers, workers): the
17
+ package uses Web APIs only.
18
+
19
+ > Writing an agent or script against the client? See [`AGENTS.md`](./AGENTS.md)
20
+ > for the working summary: setup, metadata checks, retry rules, and code mode.
21
+
22
+ ## Quick start
23
+
24
+ ```ts
25
+ import {
26
+ createFartherShore,
27
+ createTransport,
28
+ cliExchangeCredentials,
29
+ } from "@farthershore/client";
30
+
31
+ const fs = createFartherShore({
32
+ transport: createTransport({
33
+ baseUrl: "https://api.example.com",
34
+ credentials: cliExchangeCredentials(process.env.FARTHERSHORE_TOKEN!),
35
+ surface: "my-tool",
36
+ }),
37
+ });
38
+
39
+ const businesses = await fs.businesses.list();
40
+ const revoked = await fs.runtimeTokens.revoke({ businessId, tokenId });
41
+ ```
42
+
43
+ ## The namespaced API
44
+
45
+ Every operation is a method `fs.<namespace>.<method>(input, options?)`:
46
+
47
+ - **input** is one object. Path parameters are named fields
48
+ (`{ businessId, tokenId }`); typed body fields sit next to them; endpoints
49
+ whose body is an open record take it as `body`.
50
+ - **options** are `{ signal?, dryRun?, retry? }`. `signal` cancels the request
51
+ and any retry wait. `dryRun: true` asks for a preview and is accepted only
52
+ where `method.meta.preview` is true; anywhere else the method throws
53
+ `DRY_RUN_NOT_SUPPORTED` before sending anything. `retry: "none"` makes a
54
+ single attempt.
55
+
56
+ The namespace path comes from the operation key (`runtime_token.revoke` →
57
+ `fs.runtimeTokens.revoke`). The namespaces:
58
+
59
+ | Namespace | Covers |
60
+ | -------------------- | --------------------------------------------------------------------------------------- |
61
+ | `fs.agents` | Operating agents: list, status, runs, enable, disable |
62
+ | `fs.agreements` | Economic agreements: read, preview, create, amend, subject pins |
63
+ | `fs.analytics` | Event analytics: `timeseries`, `latency`, `top`, `log`, `query` |
64
+ | `fs.auditLogs` | Organization and business audit logs, CSV export |
65
+ | `fs.auth` | `context.read` (who am I), `context.issue`, `listOrganizations`, `selectedOrganization` |
66
+ | `fs.automationRules` | Automation rules |
67
+ | `fs.backends` | Backends: read, create, bind, delete |
68
+ | `fs.billing` | `stripe` (status, disconnect) and `taxSettings` |
69
+ | `fs.bulletin` | Business bulletin: list, read, ack, resolve |
70
+ | `fs.businesses` | Businesses, publish/rollback/status, `brand`, `docs`, `previewEnv`, `cors`, `rbac`, … |
71
+ | `fs.changeSets` | Governed ChangeSet proposals and the apply `timeline` |
72
+ | `fs.consumers` | Subscribers: read, block, remove, migrate, roles, RBAC, API keys |
73
+ | `fs.environments` | Preview environments: read, create, delete |
74
+ | `fs.frontend` | Hosted frontend: status, rollback |
75
+ | `fs.knowledge` | Knowledge index (guide, business) |
76
+ | `fs.makerTokens` | Organization maker tokens and their approvals |
77
+ | `fs.notifications` | Notification preferences |
78
+ | `fs.organizations` | Organizations, roles, members, invitations, ownership, overview |
79
+ | `fs.personas` | Test personas and local-preview sign-in |
80
+ | `fs.plans` | Compiled plans (read) |
81
+ | `fs.platform` | Denial explanations, dependents, resource counts, workflow replay/rollback previews |
82
+ | `fs.portal` | Subscriber plane (consumer credentials): service accounts, usage limits |
83
+ | `fs.promoCodes` | Promo codes |
84
+ | `fs.runtimeTokens` | Runtime tokens: read, mint, rotate, revoke |
85
+ | `fs.usage` | Usage |
86
+ | `fs.variables` | Write-only business variables and their asynchronous operations |
87
+ | `fs.webhooks` | Webhook endpoints, test/trigger, secret rotation, event types, deliveries |
88
+
89
+ Each method carries static metadata as `method.meta`:
90
+
91
+ ```ts
92
+ fs.runtimeTokens.revoke.meta;
93
+ // { path: "runtimeTokens.revoke", op: "runtime_token.revoke",
94
+ // summary, description, sideEffect: "write", destructive: true,
95
+ // oneTimeSecret: false, preview: false,
96
+ // reconcile: { op: "runtime_token.read" }, pagination: null,
97
+ // maxPageSize: null, permission: "runtime_token:revoke" }
98
+ ```
99
+
100
+ Portal-plane methods have no opKey; they declare the same safety and paging
101
+ flags themselves (`fs.portal.serviceAccounts.rotate.meta.oneTimeSecret` is
102
+ `true`). `paginate` clamps a requested `limit` to `meta.maxPageSize`, so a
103
+ server-capped page is never mistaken for the last one.
104
+
105
+ `fs.listOperations()` (also exported as `listOperations()`) returns that
106
+ metadata for every method, for discovery. `fs.call(opKey, input, options)`
107
+ runs an operation by its key.
108
+
109
+ A write that may have run without an answer proving it (`OUTCOME_UNKNOWN`)
110
+ carries the read that reconciles it: `error.details.reconcile = { op }`
111
+ (merged into the server's object `details`; a non-object `details` is left
112
+ as the server sent it). Run
113
+ that read before deciding whether to send the write again.
114
+
115
+ The surface never exposes the transport, the credential source, or a token.
116
+
117
+ ## Helpers
118
+
119
+ ```ts
120
+ import {
121
+ createRefs,
122
+ paginate,
123
+ poll,
124
+ waitForFrontendBuild,
125
+ } from "@farthershore/client";
126
+
127
+ // Every item of a paginated method (offset or cursor, from `meta.pagination`).
128
+ for await (const env of paginate(
129
+ fs.environments.read,
130
+ { businessId },
131
+ {
132
+ maxItems: 500,
133
+ signal,
134
+ },
135
+ )) {
136
+ console.log(env.name);
137
+ }
138
+
139
+ // Resolve references (pure lookups; no working directory or env vars).
140
+ const refs = createRefs(fs);
141
+ const businessId = await refs.business("acme");
142
+ const preview = await refs.environment(businessId, "preview");
143
+
144
+ // Wait for a condition.
145
+ const { value, timedOut } = await poll({
146
+ check: (signal) => fs.businesses.status({ businessId }, { signal }),
147
+ until: (status) => status.live,
148
+ intervalMs: 2_000,
149
+ deadlineMs: 120_000,
150
+ });
151
+
152
+ // Wait for a git-triggered frontend build to be built and served.
153
+ const build = await waitForFrontendBuild(fs, {
154
+ businessId,
155
+ ref: commitSha,
156
+ timeoutMs: 600_000,
157
+ });
158
+ ```
159
+
160
+ `paginate` fails with `PAGINATION_NOT_ADVANCING` rather than looping when a
161
+ page does not advance. A starting `offset` or `limit` may be a number or a
162
+ numeric string (`"50"`); anything else fails with `INVALID_PAGE_PARAMETER`
163
+ before a page is fetched. `collect(method, input, options)` gathers the items
164
+ into an array.
165
+
166
+ ## `createTransport`
167
+
168
+ ```ts
169
+ import { createTransport, cliExchangeCredentials } from "@farthershore/client";
170
+
171
+ const transport = createTransport({
172
+ baseUrl: "https://api.example.com",
173
+ credentials: cliExchangeCredentials(process.env.FARTHERSHORE_TOKEN!),
174
+ surface: "my-tool",
175
+ clientInfo: "my-tool/1.0.0",
176
+ });
177
+
178
+ const businesses = await transport.request("GET", "/businesses");
179
+ ```
180
+
181
+ Options: `baseUrl`, `credentials`, `surface` (sent as `x-fs-surface`), and
182
+ optionally `fetch` (defaults to `globalThis.fetch`), `organizationId` (id or
183
+ slug), `requiredOrganizationId` (refuses a credential acting in any other
184
+ organization), `clientInfo` (appended to the `x-fs-client`
185
+ header after `@farthershore/client/<version>`), and `retry`
186
+ (`{ attempts, sleep }`; `attempts` must be a whole number).
187
+
188
+ | Method | What it does |
189
+ | -------------------------------------------------------- | ------------------------------------------------------------- |
190
+ | `request(method, path, body?, options?)` | JSON request; resolves the parsed body (`undefined` for 204). |
191
+ | `requestRaw(method, path, bytes, contentType, options?)` | Binary body, JSON answer. |
192
+ | `requestText(method, path, options?)` | Text answer (CSV exports). |
193
+ | `raw(method, path, { query, body, headers, ... })` | Any path; resolves `{ status, headers, data }`. |
194
+ | `selectedOrganizationId()` | The organization the credential acts in. |
195
+ | `listOrganizations()` | Organizations a user login can act in. |
196
+
197
+ `raw` never follows a redirect, so caller headers never reach another
198
+ location: a 3xx answer fails with `REDIRECT_NOT_FOLLOWED` (the 3xx `status`,
199
+ `details.location`; `outcomeUnknown: true` for a write, which may have run).
200
+
201
+ Per-request `options`: `signal` (an `AbortSignal`), `headers`, `dryRun`
202
+ (appends `dry_run=true`), and `retry`:
203
+
204
+ - omitted: `GET`/`HEAD` are reads, everything else is a write;
205
+ - `"read"`: a read-only `POST` (queries, previews);
206
+ - `"write"`: force write handling;
207
+ - `"none"`: one attempt, same classification.
208
+
209
+ One exception applies to every mode: a refreshable credential
210
+ (`cliExchangeCredentials`) that the server rejects with 401 is re-minted and the
211
+ request is resent once, even with `"none"` or `attempts: 1`. A 401 means the
212
+ request did not run, so that resend cannot apply a write twice.
213
+
214
+ Reads are retried on network errors, timeouts, 429 and 5xx. Writes are retried
215
+ only when the server proves nothing ran (429, or an error marked `retryable`
216
+ with `retryDisposition: "safe_to_repeat"`). A write that may have run fails with
217
+ `outcomeUnknown: true`: read current state before sending it again. Key on
218
+ `outcomeUnknown`, not on `code`: when the server answered with an error
219
+ envelope the error keeps the server's own `code` (a 5xx write can be
220
+ `TEARDOWN_FAILED` with `outcomeUnknown: true`); `code: "OUTCOME_UNKNOWN"` is
221
+ used only when no server code arrived. Each attempt has a 30-second deadline that also covers
222
+ reading the response body.
223
+
224
+ ## Credential sources
225
+
226
+ | Source | Use |
227
+ | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
228
+ | `cliExchangeCredentials(token)` | A CLI login or maker token, exchanged for a short-lived access token and refreshed as needed. |
229
+ | `bearerCredentials(token)` | A static bearer token, sent as is. |
230
+ | `consumerCredentials({ token, environmentId, organizationId })` | A subscriber session acting in one environment and subscribing organization. |
231
+
232
+ A `CredentialSource` is `{ kind, getAccessToken({ signal, forceRefresh }) }`.
233
+ The transport keeps the source private: no transport method returns a token.
234
+ Give each transport its own source.
235
+
236
+ ## Errors
237
+
238
+ Request failures are `FartherShoreError`s with `status` (0 when no HTTP answer
239
+ arrived), `code`, `message`, `details`, `param`, `retryable`,
240
+ `retryDisposition`, `outcomeUnknown` and `cause`; an error from an HTTP answer
241
+ also carries that answer's `headers` (`Retry-After`, request ids). `toJSON()`
242
+ returns the plain data, without `headers`. Requests that got no answer throw `FartherShoreTransportError`
243
+ (`NETWORK_ERROR`, `TIMEOUT`, `REQUEST_ABORTED` or `OUTCOME_UNKNOWN`). A
244
+ custom `fetch` that resolves to something other than a response fails with
245
+ `INVALID_RESPONSE` (status 0; counted against the attempt limit for a read,
246
+ `outcomeUnknown: true` for a write). No outcome retries past `retry.attempts`.
247
+
248
+ Two deterministic failures stay native, because repeating them cannot help:
249
+ a successful read whose JSON body is malformed rejects with the parser's
250
+ `SyntaxError` (it is not retried), and a request `body` that `JSON.stringify`
251
+ cannot serialize (a `BigInt`, a cycle) throws its `TypeError` before anything
252
+ is sent.