@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.
- package/CHANGELOG.md +34 -0
- package/README.md +251 -2
- package/dist/index.js +6997 -0
- package/dist/types/api.generated.d.ts +1356 -0
- package/dist/types/credentials.d.ts +78 -0
- package/dist/types/envelope.d.ts +48 -0
- package/dist/types/errors.d.ts +86 -0
- package/dist/types/helpers/abort.d.ts +7 -0
- package/dist/types/helpers/paginate.d.ts +32 -0
- package/dist/types/helpers/poll.d.ts +26 -0
- package/dist/types/helpers/refs.d.ts +84 -0
- package/dist/types/helpers/wait-for-frontend-build.d.ts +43 -0
- package/dist/types/index.d.ts +24 -0
- package/dist/types/operations/agents.d.ts +48 -0
- package/dist/types/operations/agreements.d.ts +44 -0
- package/dist/types/operations/analytics.d.ts +25 -0
- package/dist/types/operations/audit-notifications.d.ts +33 -0
- package/dist/types/operations/auth.d.ts +16 -0
- package/dist/types/operations/backends.d.ts +53 -0
- package/dist/types/operations/billing.d.ts +15 -0
- package/dist/types/operations/businesses.d.ts +92 -0
- package/dist/types/operations/change-sets.d.ts +43 -0
- package/dist/types/operations/consumers.d.ts +49 -0
- package/dist/types/operations/define.d.ts +91 -0
- package/dist/types/operations/environments.d.ts +19 -0
- package/dist/types/operations/frontend.d.ts +13 -0
- package/dist/types/operations/index.d.ts +1036 -0
- package/dist/types/operations/maker-tokens.d.ts +30 -0
- package/dist/types/operations/organizations.d.ts +71 -0
- package/dist/types/operations/personas.d.ts +46 -0
- package/dist/types/operations/plans-usage.d.ts +18 -0
- package/dist/types/operations/platform.d.ts +47 -0
- package/dist/types/operations/portal.d.ts +49 -0
- package/dist/types/operations/promo-codes.d.ts +19 -0
- package/dist/types/operations/variables.d.ts +25 -0
- package/dist/types/operations/webhooks.d.ts +67 -0
- package/dist/types/surface-types.d.ts +54 -0
- package/dist/types/surface.d.ts +35 -0
- package/dist/types/transport.d.ts +119 -0
- package/dist/types/types.d.ts +469 -0
- package/dist/types/version.d.ts +8 -0
- 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
|
-
#
|
|
1
|
+
# @farthershore/client
|
|
2
2
|
|
|
3
|
-
|
|
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.
|