@farthershore/client 0.7.0 → 0.9.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 +35 -0
- package/README.md +10 -10
- package/dist/index.js +158 -61
- package/dist/types/api.generated.d.ts +61 -25
- package/dist/types/generated/schemas.d.ts +129 -37
- package/dist/types/operations/auth.d.ts +26 -8
- package/dist/types/operations/backends.d.ts +76 -21
- package/dist/types/operations/businesses.d.ts +199 -91
- package/dist/types/operations/consumers.d.ts +2 -2
- package/dist/types/operations/define.d.ts +1 -1
- package/dist/types/operations/index.d.ts +355 -126
- package/dist/types/operations/platform.d.ts +6 -6
- package/dist/types/operations/webhooks.d.ts +64 -2
- package/dist/types/surface-types.d.ts +1 -1
- package/dist/types/surface.d.ts +1 -1
- package/dist/types/types.d.ts +20 -6
- package/dist/types/version.d.ts +2 -2
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,14 @@
|
|
|
1
1
|
# Changelog — @farthershore/client
|
|
2
2
|
|
|
3
|
+
## [0.9.0] - 2026-11-21
|
|
4
|
+
|
|
5
|
+
- `businesses.release` (cut the next release of a live business) and `businesses.releaseTag.set` (choose the release tag prefix). `Business.releaseTagPrefix` on reads. `businesses.release` takes `expectedCommit` to refuse a release on any other commit, and its dry run is retried like a read.
|
|
6
|
+
|
|
7
|
+
## [0.8.0] - 2026-11-21
|
|
8
|
+
|
|
9
|
+
- **Breaking:** runtime tokens are now secret keys. `runtimeTokens.read`, `.mint`, `.rotate` and `.revoke` are replaced by the same operations under `secretKeys`, on the `/secret-keys` routes, with no old-name aliases.
|
|
10
|
+
- Backend, key and webhook operations accept and return an explicit scope (all, production, non-production or one environment).
|
|
11
|
+
|
|
3
12
|
## [0.7.0] - 2026-11-20
|
|
4
13
|
|
|
5
14
|
- Add `organizations.sellerDetails.read`: the seller details (legal name, support email, postal address and optional support URL) every business in the organization shows its customers, read from the organization's Stripe account, and where they stand (`not_connected`, `incomplete` or `complete`).
|
|
@@ -15,6 +24,32 @@
|
|
|
15
24
|
|
|
16
25
|
- Stop frontend build waits on supersession and keep the awaited build identity fixed, including when it is missing from a status response.
|
|
17
26
|
|
|
27
|
+
## [0.6.0] - 2026-11-10
|
|
28
|
+
|
|
29
|
+
- **Breaking:** Rename `runtimeTokens` to `secretKeys`, operation keys and permissions to `secret_key`, REST routes to `/secret-keys`, and exported `RuntimeToken*` types to `SecretKey*`. No old-name aliases or old-server fallback remain.
|
|
30
|
+
|
|
31
|
+
### Added — scoped backend connections
|
|
32
|
+
|
|
33
|
+
- Backend deployment and runtime key requests accept explicit environment
|
|
34
|
+
scopes. Bind responses include the managed receiver and one-time default key;
|
|
35
|
+
bootstrap contracts describe the key's accepted environments.
|
|
36
|
+
- Webhook operations accept event subscription patterns and expose delivery
|
|
37
|
+
diagnostics through the updated typed responses.
|
|
38
|
+
|
|
39
|
+
### Added
|
|
40
|
+
|
|
41
|
+
- `webhooks.delivery.redeliver({ businessId, webhookId, deliveryId })` sends
|
|
42
|
+
one delivery again with the same `webhook-id`.
|
|
43
|
+
- `webhooks.redeliver({ businessId, webhookId, since, until? })` sends every
|
|
44
|
+
failed or dead delivery created in `[since, until)` again and returns
|
|
45
|
+
`{ data: { redelivered } }`.
|
|
46
|
+
|
|
47
|
+
### Changed
|
|
48
|
+
|
|
49
|
+
- `WebhookEndpoint.disabledAt` is replaced by **`pausedAt`**: endpoints are no
|
|
50
|
+
longer disabled after repeated failures; they pause after a day of failed
|
|
51
|
+
deliveries and resume on their own. Requires the matching platform release.
|
|
52
|
+
|
|
18
53
|
## [0.5.0] - 2026-11-09
|
|
19
54
|
|
|
20
55
|
- **Breaking:** `businesses.rollback` takes `publishId` and returns
|
package/README.md
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
# @farthershore/client
|
|
2
2
|
|
|
3
3
|
The Farther Shore API client that the `farthershore` CLI runs on: a
|
|
4
|
-
namespaced, typed operation surface (`fs.
|
|
4
|
+
namespaced, typed operation surface (`fs.secretKeys.revoke(…)`) over an
|
|
5
5
|
authenticated `fetch` transport with exact retry and outcome semantics,
|
|
6
6
|
pluggable credential sources, and typed errors.
|
|
7
7
|
|
|
8
|
-
> **Status: `0.
|
|
8
|
+
> **Status: `0.9.0`.** Pre-1.0: minor releases may include breaking changes.
|
|
9
9
|
> Every response is typed. Responses are generated
|
|
10
10
|
> from the platform's zod schemas (through the API's OpenAPI components), so a
|
|
11
11
|
> field exists in a type exactly when the server sends it.
|
|
@@ -38,7 +38,7 @@ const fs = createFartherShore({
|
|
|
38
38
|
});
|
|
39
39
|
|
|
40
40
|
const businesses = await fs.businesses.list();
|
|
41
|
-
const revoked = await fs.
|
|
41
|
+
const revoked = await fs.secretKeys.revoke({ businessId, tokenId });
|
|
42
42
|
```
|
|
43
43
|
|
|
44
44
|
## The namespaced API
|
|
@@ -60,8 +60,8 @@ On preview-capable methods, literal `{ dryRun: true }` resolves to
|
|
|
60
60
|
resolves to the union, so check `"dryRun" in result` before using the result.
|
|
61
61
|
`W` is the preview payload, which can differ from the write result.
|
|
62
62
|
|
|
63
|
-
The namespace path comes from the operation key (`
|
|
64
|
-
`fs.
|
|
63
|
+
The namespace path comes from the operation key (`secret_key.revoke` →
|
|
64
|
+
`fs.secretKeys.revoke`). The namespaces:
|
|
65
65
|
|
|
66
66
|
| Namespace | Covers |
|
|
67
67
|
| -------------------- | --------------------------------------------------------------------------------------- |
|
|
@@ -87,7 +87,7 @@ The namespace path comes from the operation key (`runtime_token.revoke` →
|
|
|
87
87
|
| `fs.platform` | Denial explanations, dependents, resource counts, workflow replay/rollback previews |
|
|
88
88
|
| `fs.portal` | Subscriber plane (consumer credentials): service accounts, usage limits |
|
|
89
89
|
| `fs.promoCodes` | Promo codes |
|
|
90
|
-
| `fs.
|
|
90
|
+
| `fs.secretKeys` | Secret keys: read, mint, rotate, revoke |
|
|
91
91
|
| `fs.usage` | Usage |
|
|
92
92
|
| `fs.variables` | Write-only business variables and their asynchronous operations |
|
|
93
93
|
| `fs.webhooks` | Webhook endpoints, test/trigger, secret rotation, event types, deliveries |
|
|
@@ -95,12 +95,12 @@ The namespace path comes from the operation key (`runtime_token.revoke` →
|
|
|
95
95
|
Each method carries static metadata as `method.meta`:
|
|
96
96
|
|
|
97
97
|
```ts
|
|
98
|
-
fs.
|
|
99
|
-
// { path: "
|
|
98
|
+
fs.secretKeys.revoke.meta;
|
|
99
|
+
// { path: "secretKeys.revoke", op: "secret_key.revoke",
|
|
100
100
|
// summary, description, sideEffect: "write", destructive: true,
|
|
101
101
|
// oneTimeSecret: false, preview: false,
|
|
102
|
-
// reconcile: { op: "
|
|
103
|
-
// maxPageSize: null, permission: "
|
|
102
|
+
// reconcile: { op: "secret_key.read" }, pagination: null,
|
|
103
|
+
// maxPageSize: null, permission: "secret_key:revoke" }
|
|
104
104
|
```
|
|
105
105
|
|
|
106
106
|
Portal-plane methods have no opKey; they declare the same safety and paging
|
package/dist/index.js
CHANGED
|
@@ -219,6 +219,9 @@ var PLATFORM_PERMISSION_CATALOG = {
|
|
|
219
219
|
allowedTargetKinds: SELF,
|
|
220
220
|
defaultRoles: BUILDER_ROLES_AND_SUBSCRIBER,
|
|
221
221
|
humanOnly: true,
|
|
222
|
+
// Agreeing to the documents is the person's own act in their own
|
|
223
|
+
// session; asking for an emailed code first protects nothing.
|
|
224
|
+
humanOnlyFreshSession: false,
|
|
222
225
|
delegation: "browser_only"
|
|
223
226
|
}),
|
|
224
227
|
"business:create": permission("business:create", {
|
|
@@ -672,25 +675,25 @@ var PLATFORM_PERMISSION_CATALOG = {
|
|
|
672
675
|
defaultRoles: OWNER_ADMIN,
|
|
673
676
|
delegation: "maker_token"
|
|
674
677
|
}),
|
|
675
|
-
"
|
|
678
|
+
"secret_key:mint": permission("secret_key:mint", {
|
|
676
679
|
effect: "write",
|
|
677
680
|
allowedTargetKinds: BUSINESS,
|
|
678
681
|
defaultRoles: OWNER_ADMIN,
|
|
679
682
|
delegation: "maker_token"
|
|
680
683
|
}),
|
|
681
|
-
"
|
|
684
|
+
"secret_key:read": permission("secret_key:read", {
|
|
682
685
|
effect: "read",
|
|
683
686
|
allowedTargetKinds: BUSINESS,
|
|
684
687
|
defaultRoles: BUILDER_ROLES,
|
|
685
688
|
delegation: "maker_token"
|
|
686
689
|
}),
|
|
687
|
-
"
|
|
690
|
+
"secret_key:revoke": permission("secret_key:revoke", {
|
|
688
691
|
effect: "write",
|
|
689
692
|
allowedTargetKinds: BUSINESS,
|
|
690
693
|
defaultRoles: OWNER_ADMIN,
|
|
691
694
|
delegation: "maker_token"
|
|
692
695
|
}),
|
|
693
|
-
"
|
|
696
|
+
"secret_key:rotate": permission("secret_key:rotate", {
|
|
694
697
|
effect: "write",
|
|
695
698
|
allowedTargetKinds: BUSINESS,
|
|
696
699
|
defaultRoles: OWNER_ADMIN,
|
|
@@ -1104,6 +1107,14 @@ var PLATFORM_OPERATION_DEFINITIONS = [
|
|
|
1104
1107
|
{ key: "webhook.listen", class: "operate", domain: WEBHOOKS_DOMAIN },
|
|
1105
1108
|
// Wire v1: issue a replacement signing secret (24 h dual-signing grace).
|
|
1106
1109
|
{ key: "webhook.rotate_secret", class: "operate", domain: WEBHOOKS_DOMAIN },
|
|
1110
|
+
// Send one delivery again (same webhook-id), or every failed / dead
|
|
1111
|
+
// delivery of an endpoint in a time range.
|
|
1112
|
+
{
|
|
1113
|
+
key: "webhook.delivery.redeliver",
|
|
1114
|
+
class: "operate",
|
|
1115
|
+
domain: WEBHOOKS_DOMAIN
|
|
1116
|
+
},
|
|
1117
|
+
{ key: "webhook.redeliver", class: "operate", domain: WEBHOOKS_DOMAIN },
|
|
1107
1118
|
// The subscribable event catalog, served so clients validate without an
|
|
1108
1119
|
// SDK bump.
|
|
1109
1120
|
{ key: "webhook.event_type.read", class: "operate", domain: WEBHOOKS_DOMAIN },
|
|
@@ -1223,17 +1234,17 @@ var PLATFORM_OPERATION_DEFINITIONS = [
|
|
|
1223
1234
|
class: "operate",
|
|
1224
1235
|
domain: VARIABLES_DOMAIN
|
|
1225
1236
|
},
|
|
1226
|
-
{ key: "
|
|
1227
|
-
{ key: "
|
|
1228
|
-
{ key: "
|
|
1229
|
-
{ key: "
|
|
1237
|
+
{ key: "secret_key.mint", class: "operate", domain: "secret-keys" },
|
|
1238
|
+
{ key: "secret_key.rotate", class: "operate", domain: "secret-keys" },
|
|
1239
|
+
{ key: "secret_key.revoke", class: "operate", domain: "secret-keys" },
|
|
1240
|
+
{ key: "secret_key.read", class: "operate", domain: "secret-keys" },
|
|
1230
1241
|
{
|
|
1231
1242
|
key: "metering_token.mint",
|
|
1232
1243
|
class: "operate",
|
|
1233
1244
|
domain: "metering",
|
|
1234
1245
|
unavailable: {
|
|
1235
1246
|
reason: "runtime_surface",
|
|
1236
|
-
detail: "The metering credential is DERIVED from the
|
|
1247
|
+
detail: "The metering credential is DERIVED from the secret key at backend bootstrap (/runtime/*), not minted separately. Issue the secret key with `farthershore backend tokens create --operations metering`."
|
|
1237
1248
|
}
|
|
1238
1249
|
},
|
|
1239
1250
|
{
|
|
@@ -1482,6 +1493,7 @@ var PLATFORM_OPERATION_DEFINITIONS = [
|
|
|
1482
1493
|
// API verb is the read — mutations happen through the manifest contract.
|
|
1483
1494
|
{ key: "rbac.subjects.read", class: "operate", domain: "businesses" },
|
|
1484
1495
|
{ key: "business.preview_env.set", class: "operate", domain: "businesses" },
|
|
1496
|
+
{ key: "business.release_tag.set", class: "operate", domain: "businesses" },
|
|
1485
1497
|
// FAR-797 — `workflows.replay` was REMOVED from this catalog, not just from
|
|
1486
1498
|
// the CLI. The command was a stub that always threw, so leaving the key here
|
|
1487
1499
|
// advertised a live control-plane operation that no surface implements —
|
|
@@ -1519,6 +1531,7 @@ var PLATFORM_OPERATION_DEFINITIONS = [
|
|
|
1519
1531
|
{ key: "business.routes.read", class: "contract", domain: "businesses" },
|
|
1520
1532
|
{ key: "business.contract.read", class: "contract", domain: "businesses" },
|
|
1521
1533
|
{ key: "business.publish", class: "operate", domain: "lifecycle" },
|
|
1534
|
+
{ key: "business.release", class: "operate", domain: "lifecycle" },
|
|
1522
1535
|
{
|
|
1523
1536
|
key: "manifest.apply",
|
|
1524
1537
|
class: "contract",
|
|
@@ -1854,6 +1867,14 @@ var AGENT_OPERATION_AUTHORIZATIONS = {
|
|
|
1854
1867
|
permission: "business:publish",
|
|
1855
1868
|
targetKind: "business"
|
|
1856
1869
|
},
|
|
1870
|
+
"business.release": {
|
|
1871
|
+
permission: "business:publish",
|
|
1872
|
+
targetKind: "business"
|
|
1873
|
+
},
|
|
1874
|
+
"business.release_tag.set": {
|
|
1875
|
+
permission: "business:publish",
|
|
1876
|
+
targetKind: "business"
|
|
1877
|
+
},
|
|
1857
1878
|
"business.read": {
|
|
1858
1879
|
permission: BUSINESS_READ_PERMISSION,
|
|
1859
1880
|
targetKind: "business"
|
|
@@ -2143,20 +2164,20 @@ var AGENT_OPERATION_AUTHORIZATIONS = {
|
|
|
2143
2164
|
// bound to this key serves the accepted business config, so reading either
|
|
2144
2165
|
// is a business read (`rbac:read` stays the subject/role catalog authority).
|
|
2145
2166
|
"rbac.read": { permission: BUSINESS_READ_PERMISSION, targetKind: "business" },
|
|
2146
|
-
"
|
|
2147
|
-
permission: "
|
|
2167
|
+
"secret_key.mint": {
|
|
2168
|
+
permission: "secret_key:mint",
|
|
2148
2169
|
targetKind: "business"
|
|
2149
2170
|
},
|
|
2150
|
-
"
|
|
2151
|
-
permission: "
|
|
2171
|
+
"secret_key.read": {
|
|
2172
|
+
permission: "secret_key:read",
|
|
2152
2173
|
targetKind: "business"
|
|
2153
2174
|
},
|
|
2154
|
-
"
|
|
2155
|
-
permission: "
|
|
2175
|
+
"secret_key.revoke": {
|
|
2176
|
+
permission: "secret_key:revoke",
|
|
2156
2177
|
targetKind: "business"
|
|
2157
2178
|
},
|
|
2158
|
-
"
|
|
2159
|
-
permission: "
|
|
2179
|
+
"secret_key.rotate": {
|
|
2180
|
+
permission: "secret_key:rotate",
|
|
2160
2181
|
targetKind: "business"
|
|
2161
2182
|
},
|
|
2162
2183
|
"resource_count.report": {
|
|
@@ -2199,6 +2220,14 @@ var AGENT_OPERATION_AUTHORIZATIONS = {
|
|
|
2199
2220
|
permission: "webhook:update",
|
|
2200
2221
|
targetKind: "business"
|
|
2201
2222
|
},
|
|
2223
|
+
"webhook.delivery.redeliver": {
|
|
2224
|
+
permission: "webhook:update",
|
|
2225
|
+
targetKind: "business"
|
|
2226
|
+
},
|
|
2227
|
+
"webhook.redeliver": {
|
|
2228
|
+
permission: "webhook:update",
|
|
2229
|
+
targetKind: "business"
|
|
2230
|
+
},
|
|
2202
2231
|
"webhook.event_type.read": {
|
|
2203
2232
|
permission: "webhook:read",
|
|
2204
2233
|
targetKind: "business"
|
|
@@ -2541,9 +2570,9 @@ var SPECS = {
|
|
|
2541
2570
|
},
|
|
2542
2571
|
"business.create": {
|
|
2543
2572
|
summary: "Create a new business and provision its managed GitHub repo",
|
|
2544
|
-
description: "Create a new business and provision its managed GitHub repo",
|
|
2573
|
+
description: "Create a new business and provision its managed GitHub repo. Also issues the business's default key (every environment, every runtime operation) and returns it ONCE as defaultKey \u2014 set it as FS_SECRET_KEY in your backend.",
|
|
2545
2574
|
destructive: false,
|
|
2546
|
-
oneTimeSecret:
|
|
2575
|
+
oneTimeSecret: true,
|
|
2547
2576
|
preview: false,
|
|
2548
2577
|
reconcile: { op: "business.list" }
|
|
2549
2578
|
},
|
|
@@ -2564,6 +2593,14 @@ var SPECS = {
|
|
|
2564
2593
|
preview: true,
|
|
2565
2594
|
reconcile: { op: "business.status" }
|
|
2566
2595
|
},
|
|
2596
|
+
"business.release": {
|
|
2597
|
+
summary: "Release what is on the default branch of a live business, with the version picked from what changed",
|
|
2598
|
+
description: "Cut the next release of a live business from its default branch. Compares that commit with the last release, picks a major, minor or patch version from what changed (removals and tightened access are major, additions and price changes minor, everything else patch), runs the go-live checks and creates the release, which then deploys. Use a dry run first to see the plan, and business status to prove it is live. A draft business goes live with business publish instead.",
|
|
2599
|
+
destructive: false,
|
|
2600
|
+
oneTimeSecret: false,
|
|
2601
|
+
preview: true,
|
|
2602
|
+
reconcile: { op: "business.status" }
|
|
2603
|
+
},
|
|
2567
2604
|
"business.delete": {
|
|
2568
2605
|
summary: "Permanently delete a business (stage only)",
|
|
2569
2606
|
description: "(stage only) Permanently delete a business. Requires --yes. Registered only in the stage channel (`make cli-stage`); production businesses are deleted from the dashboard.",
|
|
@@ -2580,6 +2617,14 @@ var SPECS = {
|
|
|
2580
2617
|
preview: false,
|
|
2581
2618
|
reconcile: { op: "environment.read" }
|
|
2582
2619
|
},
|
|
2620
|
+
"business.release_tag.set": {
|
|
2621
|
+
summary: "Choose the prefix of a business's release tags",
|
|
2622
|
+
description: "Choose the prefix of a business's release tags. Releases are tagged `<prefix>X.Y.Z`: `v` by default, or for example `release-`, `prod/` or an empty prefix for bare numbers. Changing the prefix continues the version numbers and never renames existing tags.",
|
|
2623
|
+
destructive: false,
|
|
2624
|
+
oneTimeSecret: false,
|
|
2625
|
+
preview: false,
|
|
2626
|
+
reconcile: { op: "business.read" }
|
|
2627
|
+
},
|
|
2583
2628
|
"business.docs.enable": {
|
|
2584
2629
|
summary: "Enable docs for a business (publish/serve docs scaffold)",
|
|
2585
2630
|
description: "Enable docs for a business \u2014 published docs become available in the portal. Safe to repeat: enabling them when already enabled changes nothing.",
|
|
@@ -2676,7 +2721,7 @@ var SPECS = {
|
|
|
2676
2721
|
},
|
|
2677
2722
|
"backend.read": {
|
|
2678
2723
|
summary: "List backends for a business (id, scope, name, transport, status)",
|
|
2679
|
-
description: "List a business's
|
|
2724
|
+
description: "List a business's backend deployments \u2014 id, scope (all | production | non-production | kind:<kind> | env:<environment>), name, slug, transport (direct|tunnel), default flag, and derived status. A backend has one deployment per scope; each environment is served by the most specific one. Read-only.",
|
|
2680
2725
|
destructive: false,
|
|
2681
2726
|
oneTimeSecret: false,
|
|
2682
2727
|
preview: false,
|
|
@@ -2684,60 +2729,60 @@ var SPECS = {
|
|
|
2684
2729
|
},
|
|
2685
2730
|
"backend.create": {
|
|
2686
2731
|
summary: "Create a backend (default transport: direct)",
|
|
2687
|
-
description: "Create a backend
|
|
2732
|
+
description: "Create a backend deployment for a business. Pick a transport mode: direct (public HTTPS URL, secured by request signing) or tunnel (private outbound-only connection). Mark it default to route traffic to it. With an origin, the default backend gets its webhook receiver at <origin>/_fs/webhooks automatically, and a business without a default key gets one, returned ONCE as defaultKey.",
|
|
2688
2733
|
destructive: false,
|
|
2689
|
-
oneTimeSecret:
|
|
2734
|
+
oneTimeSecret: true,
|
|
2690
2735
|
preview: true,
|
|
2691
2736
|
reconcile: { op: "backend.read" }
|
|
2692
2737
|
},
|
|
2693
2738
|
"backend.bind": {
|
|
2694
|
-
summary: "
|
|
2695
|
-
description: "
|
|
2739
|
+
summary: "Set a backend's origin (every environment unless overridden)",
|
|
2740
|
+
description: "Set the origin of a backend declared in business/. Without a scope it sets the `all` deployment, which serves every environment; with scope env:<environment> (or non-production / kind:<kind>, or an origin template with {env}) it creates or updates that override. Farther Shore keeps the default backend's webhook receiver at <origin>/_fs/webhooks, and a business without a default key gets one, returned ONCE as defaultKey.",
|
|
2696
2741
|
destructive: false,
|
|
2697
|
-
oneTimeSecret:
|
|
2742
|
+
oneTimeSecret: true,
|
|
2698
2743
|
preview: true,
|
|
2699
2744
|
reconcile: { op: "backend.read" }
|
|
2700
2745
|
},
|
|
2701
2746
|
"backend.delete": {
|
|
2702
|
-
summary: "Delete a backend (revokes its
|
|
2747
|
+
summary: "Delete a backend (revokes its secret keys)",
|
|
2703
2748
|
description: "Delete a backend (origin). Traffic routed to it stops; re-create to restore.",
|
|
2704
2749
|
destructive: true,
|
|
2705
2750
|
oneTimeSecret: false,
|
|
2706
2751
|
preview: false,
|
|
2707
2752
|
reconcile: { op: "backend.read" }
|
|
2708
2753
|
},
|
|
2709
|
-
"
|
|
2710
|
-
summary: "List
|
|
2711
|
-
description: "List a business's
|
|
2754
|
+
"secret_key.read": {
|
|
2755
|
+
summary: "List secret keys for a business",
|
|
2756
|
+
description: "List a business's secret keys (fsrt_) \u2014 id, last-four, operations, status, and env scope. Read-only; secrets are never shown.",
|
|
2712
2757
|
destructive: false,
|
|
2713
2758
|
oneTimeSecret: false,
|
|
2714
2759
|
preview: false,
|
|
2715
2760
|
pagination: "offset"
|
|
2716
2761
|
},
|
|
2717
|
-
"
|
|
2718
|
-
summary: "Create a
|
|
2719
|
-
description: "Mint
|
|
2762
|
+
"secret_key.mint": {
|
|
2763
|
+
summary: "Create a secret key (returns it once)",
|
|
2764
|
+
description: "Mint an additional secret key (fsrt_), e.g. a dedicated key for one environment (scope env:<environment>) that can act for no other. The business's default key already covers every environment. Returns the plaintext ONCE. Operations default to gateway_verification, metering, health and webhook_secrets.",
|
|
2720
2765
|
destructive: false,
|
|
2721
2766
|
oneTimeSecret: true,
|
|
2722
2767
|
preview: false,
|
|
2723
|
-
reconcile: { op: "
|
|
2768
|
+
reconcile: { op: "secret_key.read" }
|
|
2724
2769
|
},
|
|
2725
|
-
// DECISION: NEITHER side → destructive (+ oneTimeSecret, already declared). Rotation revokes the previous
|
|
2726
|
-
"
|
|
2727
|
-
summary: "Rotate a
|
|
2728
|
-
description: "Rotate a
|
|
2770
|
+
// DECISION: NEITHER side → destructive (+ oneTimeSecret, already declared). Rotation revokes the previous FS_SECRET_KEY immediately; a backend still using it starts failing.
|
|
2771
|
+
"secret_key.rotate": {
|
|
2772
|
+
summary: "Rotate a secret key (returns a fresh FS_SECRET_KEY once)",
|
|
2773
|
+
description: "Rotate a secret key: mint a fresh secret carrying the same scope and revoke the old one. Returns the new plaintext token ONCE.",
|
|
2729
2774
|
destructive: true,
|
|
2730
2775
|
oneTimeSecret: true,
|
|
2731
2776
|
preview: false,
|
|
2732
|
-
reconcile: { op: "
|
|
2777
|
+
reconcile: { op: "secret_key.read" }
|
|
2733
2778
|
},
|
|
2734
|
-
"
|
|
2735
|
-
summary: "Revoke a
|
|
2736
|
-
description: "Revoke a
|
|
2779
|
+
"secret_key.revoke": {
|
|
2780
|
+
summary: "Revoke a secret key",
|
|
2781
|
+
description: "Revoke a secret key. The backend using it stops verifying.",
|
|
2737
2782
|
destructive: true,
|
|
2738
2783
|
oneTimeSecret: false,
|
|
2739
2784
|
preview: false,
|
|
2740
|
-
reconcile: { op: "
|
|
2785
|
+
reconcile: { op: "secret_key.read" }
|
|
2741
2786
|
},
|
|
2742
2787
|
"frontend.status": {
|
|
2743
2788
|
summary: "Show the current frontend release, recent releases, and recent builds (incl. failure reasons)",
|
|
@@ -2828,6 +2873,25 @@ var SPECS = {
|
|
|
2828
2873
|
preview: false,
|
|
2829
2874
|
reconcile: { op: "webhook.read" }
|
|
2830
2875
|
},
|
|
2876
|
+
// Redelivery queues the SAME delivery again (same webhook-id), so a
|
|
2877
|
+
// receiver that already processed it can dedupe. Each call sends again;
|
|
2878
|
+
// read the delivery log before repeating an ambiguous one.
|
|
2879
|
+
"webhook.delivery.redeliver": {
|
|
2880
|
+
summary: "Send one webhook delivery again",
|
|
2881
|
+
description: "Queue one delivery to be sent again right away, with the same webhook-id and payload. Works for a delivered, failed or dead delivery; one still being sent is refused. It gets a fresh 72-hour retry window.",
|
|
2882
|
+
destructive: false,
|
|
2883
|
+
oneTimeSecret: false,
|
|
2884
|
+
preview: false,
|
|
2885
|
+
reconcile: { op: "webhook.delivery.read" }
|
|
2886
|
+
},
|
|
2887
|
+
"webhook.redeliver": {
|
|
2888
|
+
summary: "Send every failed or dead delivery of a webhook endpoint in a time range again",
|
|
2889
|
+
description: "Queue every failed or dead delivery of one webhook endpoint created in [since, until) to be sent again right away, each with its own webhook-id and a fresh 72-hour retry window. Returns how many were queued.",
|
|
2890
|
+
destructive: false,
|
|
2891
|
+
oneTimeSecret: false,
|
|
2892
|
+
preview: false,
|
|
2893
|
+
reconcile: { op: "webhook.delivery.read" }
|
|
2894
|
+
},
|
|
2831
2895
|
"webhook.event_type.read": {
|
|
2832
2896
|
summary: "List the event names a webhook endpoint can subscribe to",
|
|
2833
2897
|
description: "List the event names a webhook endpoint can subscribe to, with descriptions.",
|
|
@@ -3783,14 +3847,14 @@ function namespacePathFor(key) {
|
|
|
3783
3847
|
}
|
|
3784
3848
|
|
|
3785
3849
|
// ../contracts/dist/runtime.js
|
|
3786
|
-
var
|
|
3850
|
+
var FS_SECRET_KEY_ENV = "FS_SECRET_KEY";
|
|
3787
3851
|
var RESPONSE_METERING_HEADER_NAMES = {
|
|
3788
3852
|
payload: "x-fs-metering",
|
|
3789
3853
|
signature: "x-fs-metering-sig",
|
|
3790
3854
|
token: "x-fs-metering-token"
|
|
3791
3855
|
};
|
|
3792
3856
|
var RESPONSE_METERING_TOKEN_CONTRACT = {
|
|
3793
|
-
environmentVariable:
|
|
3857
|
+
environmentVariable: FS_SECRET_KEY_ENV,
|
|
3794
3858
|
presentation: RESPONSE_METERING_HEADER_NAMES.token,
|
|
3795
3859
|
storage: "sha256-hash-only"
|
|
3796
3860
|
};
|
|
@@ -3807,6 +3871,7 @@ var RUNTIME_ERROR_CODES = {
|
|
|
3807
3871
|
replayedNonce: "replayed_nonce",
|
|
3808
3872
|
bodyTooLarge: "body_too_large",
|
|
3809
3873
|
environmentMismatch: "environment_mismatch",
|
|
3874
|
+
environmentUnknown: "environment_unknown",
|
|
3810
3875
|
missingToken: "missing_token",
|
|
3811
3876
|
invalidToken: "invalid_token",
|
|
3812
3877
|
/** UA-6 — `contextVerification: "required"` and the signed X-Fs-Context
|
|
@@ -3840,8 +3905,10 @@ var ERROR_CODES = {
|
|
|
3840
3905
|
ACCOUNT_ERASURE_PUBLISHED_BUSINESS: "ACCOUNT_ERASURE_PUBLISHED_BUSINESS",
|
|
3841
3906
|
ACCOUNT_ERASURE_UNSETTLED_MONEY: "ACCOUNT_ERASURE_UNSETTLED_MONEY",
|
|
3842
3907
|
ACCOUNT_ERASURE_CONFIRMATION_MISMATCH: "ACCOUNT_ERASURE_CONFIRMATION_MISMATCH",
|
|
3843
|
-
|
|
3844
|
-
|
|
3908
|
+
/** A legal obligation stands in front of the action; `details.unmet` names each fix. */
|
|
3909
|
+
LEGAL_OBLIGATION_UNMET: "LEGAL_OBLIGATION_UNMET",
|
|
3910
|
+
/** The agreement versions submitted for acceptance are no longer the ones required. */
|
|
3911
|
+
LEGAL_DOCUMENT_VERSION_CHANGED: "LEGAL_DOCUMENT_VERSION_CHANGED",
|
|
3845
3912
|
MAINTENANCE_JOB_RETIRED: "MAINTENANCE_JOB_RETIRED",
|
|
3846
3913
|
INVALID_USAGE_UNIT_LABEL: "INVALID_USAGE_UNIT_LABEL",
|
|
3847
3914
|
HUMAN_ONLY_ACTION: "HUMAN_ONLY_ACTION",
|
|
@@ -3854,6 +3921,10 @@ var ERROR_CODES = {
|
|
|
3854
3921
|
/** A release cut by an earlier publish is still being applied. Wait for it
|
|
3855
3922
|
* to be accepted (or fail) before cutting another release. */
|
|
3856
3923
|
RELEASE_PENDING_ACCEPTANCE: "RELEASE_PENDING_ACCEPTANCE",
|
|
3924
|
+
/** The default branch holds nothing that the last release did not ship. */
|
|
3925
|
+
NOTHING_TO_RELEASE: "NOTHING_TO_RELEASE",
|
|
3926
|
+
/** The latest push is still being checked; retry the release shortly. */
|
|
3927
|
+
RELEASE_SOURCE_NOT_READY: "RELEASE_SOURCE_NOT_READY",
|
|
3857
3928
|
/** A RollbackWorkflow for this source execution is already running. */
|
|
3858
3929
|
ROLLBACK_IN_FLIGHT: "ROLLBACK_IN_FLIGHT",
|
|
3859
3930
|
INTERNAL_ERROR: "INTERNAL_ERROR",
|
|
@@ -4173,6 +4244,7 @@ var RUNTIME_ERROR_CODE_TO_ERROR_CODE = {
|
|
|
4173
4244
|
body_hash_mismatch: ERROR_CODES.UNAUTHORIZED,
|
|
4174
4245
|
route_mismatch: ERROR_CODES.UNAUTHORIZED,
|
|
4175
4246
|
environment_mismatch: ERROR_CODES.UNAUTHORIZED,
|
|
4247
|
+
environment_unknown: ERROR_CODES.UNAUTHORIZED,
|
|
4176
4248
|
// JWKS fetch unavailable — a dependency fault, but the backend still
|
|
4177
4249
|
// fail-closes the request as 401 (statusForCode), so the canonical code is
|
|
4178
4250
|
// SERVICE_UNAVAILABLE to preserve the "dependency down" semantic for callers.
|
|
@@ -4564,7 +4636,7 @@ var authOperations = {
|
|
|
4564
4636
|
|
|
4565
4637
|
// src/operations/backends.ts
|
|
4566
4638
|
var backends = (businessId) => `/businesses/${seg(businessId)}/backends`;
|
|
4567
|
-
var
|
|
4639
|
+
var secretKeys = (businessId) => `/businesses/${seg(businessId)}/secret-keys`;
|
|
4568
4640
|
var backendOperations = {
|
|
4569
4641
|
"backends.read": operation({
|
|
4570
4642
|
op: "backend.read",
|
|
@@ -4590,29 +4662,29 @@ var backendOperations = {
|
|
|
4590
4662
|
op: "backend.delete",
|
|
4591
4663
|
run: (ctx, { businessId, backendId }) => send(ctx, "DELETE", `${backends(businessId)}/${seg(backendId)}`)
|
|
4592
4664
|
}),
|
|
4593
|
-
"
|
|
4594
|
-
op: "
|
|
4665
|
+
"secretKeys.read": operation({
|
|
4666
|
+
op: "secret_key.read",
|
|
4595
4667
|
run: (ctx, { businessId, environmentId, limit, offset }) => send(
|
|
4596
4668
|
ctx,
|
|
4597
4669
|
"GET",
|
|
4598
|
-
withQuery(
|
|
4670
|
+
withQuery(secretKeys(businessId), {
|
|
4599
4671
|
environmentId,
|
|
4600
4672
|
limit: num(limit),
|
|
4601
4673
|
offset: num(offset)
|
|
4602
4674
|
})
|
|
4603
4675
|
)
|
|
4604
4676
|
}),
|
|
4605
|
-
"
|
|
4606
|
-
op: "
|
|
4607
|
-
run: (ctx, { businessId, ...data }) => send(ctx, "POST",
|
|
4677
|
+
"secretKeys.mint": operation({
|
|
4678
|
+
op: "secret_key.mint",
|
|
4679
|
+
run: (ctx, { businessId, ...data }) => send(ctx, "POST", secretKeys(businessId), data)
|
|
4608
4680
|
}),
|
|
4609
|
-
"
|
|
4610
|
-
op: "
|
|
4611
|
-
run: (ctx, { businessId, tokenId }) => send(ctx, "POST", `${
|
|
4681
|
+
"secretKeys.rotate": operation({
|
|
4682
|
+
op: "secret_key.rotate",
|
|
4683
|
+
run: (ctx, { businessId, tokenId }) => send(ctx, "POST", `${secretKeys(businessId)}/${seg(tokenId)}/rotate`)
|
|
4612
4684
|
}),
|
|
4613
|
-
"
|
|
4614
|
-
op: "
|
|
4615
|
-
run: (ctx, { businessId, tokenId }) => send(ctx, "DELETE", `${
|
|
4685
|
+
"secretKeys.revoke": operation({
|
|
4686
|
+
op: "secret_key.revoke",
|
|
4687
|
+
run: (ctx, { businessId, tokenId }) => send(ctx, "DELETE", `${secretKeys(businessId)}/${seg(tokenId)}`)
|
|
4616
4688
|
})
|
|
4617
4689
|
};
|
|
4618
4690
|
|
|
@@ -4733,6 +4805,15 @@ var businessOperations = {
|
|
|
4733
4805
|
Object.keys(body).length > 0 ? body : void 0
|
|
4734
4806
|
)
|
|
4735
4807
|
}),
|
|
4808
|
+
"businesses.release": previewOperation({
|
|
4809
|
+
op: "business.release",
|
|
4810
|
+
run: (ctx, { businessId, ...body }) => send(
|
|
4811
|
+
ctx,
|
|
4812
|
+
"POST",
|
|
4813
|
+
`${business(businessId)}/release`,
|
|
4814
|
+
Object.keys(body).length > 0 ? body : void 0
|
|
4815
|
+
)
|
|
4816
|
+
}),
|
|
4736
4817
|
// A retry may append another diagnostic compilation record; it never
|
|
4737
4818
|
// applies or publishes the contract.
|
|
4738
4819
|
"businesses.compile": operation({
|
|
@@ -4776,6 +4857,7 @@ var businessOperations = {
|
|
|
4776
4857
|
run: (ctx, { businessId, kind }) => send(ctx, "DELETE", `${business(businessId)}/${seg(kind)}`)
|
|
4777
4858
|
}),
|
|
4778
4859
|
"businesses.previewEnv.set": patchBusiness("business.preview_env.set"),
|
|
4860
|
+
"businesses.releaseTag.set": patchBusiness("business.release_tag.set"),
|
|
4779
4861
|
"businesses.docs.enable": setDocs("business.docs.enable", true),
|
|
4780
4862
|
"businesses.docs.disable": setDocs("business.docs.disable", false),
|
|
4781
4863
|
"businesses.cors.update": patchBusiness("business.cors.update"),
|
|
@@ -5683,6 +5765,13 @@ var webhookOperations = {
|
|
|
5683
5765
|
op: "webhook.rotate_secret",
|
|
5684
5766
|
run: (ctx, { businessId, webhookId }) => send(ctx, "POST", `${webhook(businessId, webhookId)}/rotate-secret`)
|
|
5685
5767
|
}),
|
|
5768
|
+
"webhooks.redeliver": operation({
|
|
5769
|
+
op: "webhook.redeliver",
|
|
5770
|
+
run: (ctx, { businessId, webhookId, since, until }) => send(ctx, "POST", `${webhook(businessId, webhookId)}/redeliver`, {
|
|
5771
|
+
since,
|
|
5772
|
+
...until !== void 0 ? { until } : {}
|
|
5773
|
+
})
|
|
5774
|
+
}),
|
|
5686
5775
|
"webhooks.eventType.read": operation({
|
|
5687
5776
|
op: "webhook.event_type.read",
|
|
5688
5777
|
run: (ctx, { businessId }) => send(
|
|
@@ -5712,6 +5801,14 @@ var webhookOperations = {
|
|
|
5712
5801
|
`${webhook(businessId, webhookId)}/deliveries/${seg(deliveryId)}`
|
|
5713
5802
|
)
|
|
5714
5803
|
}),
|
|
5804
|
+
"webhooks.delivery.redeliver": operation({
|
|
5805
|
+
op: "webhook.delivery.redeliver",
|
|
5806
|
+
run: (ctx, { businessId, webhookId, deliveryId }) => send(
|
|
5807
|
+
ctx,
|
|
5808
|
+
"POST",
|
|
5809
|
+
`${webhook(businessId, webhookId)}/deliveries/${seg(deliveryId)}/redeliver`
|
|
5810
|
+
)
|
|
5811
|
+
}),
|
|
5715
5812
|
"webhooks.delivery.payload.read": operation({
|
|
5716
5813
|
op: "webhook.delivery.payload.read",
|
|
5717
5814
|
run: (ctx, { businessId, webhookId, deliveryId }) => send(
|
|
@@ -6298,7 +6395,7 @@ function diagnosticsOf(parsed) {
|
|
|
6298
6395
|
}
|
|
6299
6396
|
|
|
6300
6397
|
// src/version.ts
|
|
6301
|
-
var CLIENT_VERSION = "0.
|
|
6398
|
+
var CLIENT_VERSION = "0.9.0";
|
|
6302
6399
|
var CLIENT_PRODUCT = `@farthershore/client/${CLIENT_VERSION}`;
|
|
6303
6400
|
|
|
6304
6401
|
// src/transport.ts
|
|
@@ -6352,7 +6449,7 @@ function supportsReadOnlyDryRun(method, path) {
|
|
|
6352
6449
|
if (method.toUpperCase() !== "POST") return false;
|
|
6353
6450
|
return /^\/(?:businesses|agent\/v1\/businesses)\/[^/]+\/backends\/?$/.test(
|
|
6354
6451
|
pathname
|
|
6355
|
-
) || /^\/businesses\/[^/]+\/publish\/?$/.test(pathname) || /^\/businesses\/[^/]+\/frontend\/rollback\/?$/.test(pathname) || /^\/businesses\/[^/]+\/consumers\/[^/]+\/change-sets\/?$/.test(pathname) || /^\/agent\/v1\/(?:replay|rollback-to-config)\/?$/.test(pathname);
|
|
6452
|
+
) || /^\/businesses\/[^/]+\/publish\/?$/.test(pathname) || /^\/businesses\/[^/]+\/release\/?$/.test(pathname) || /^\/businesses\/[^/]+\/frontend\/rollback\/?$/.test(pathname) || /^\/businesses\/[^/]+\/consumers\/[^/]+\/change-sets\/?$/.test(pathname) || /^\/agent\/v1\/(?:replay|rollback-to-config)\/?$/.test(pathname);
|
|
6356
6453
|
}
|
|
6357
6454
|
function retryPolicyFor(method, path, options) {
|
|
6358
6455
|
if (options?.retry === "write") return "write";
|