@farthershore/client 0.7.0 → 0.8.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 +31 -0
- package/README.md +10 -10
- package/dist/index.js +117 -60
- package/dist/types/api.generated.d.ts +43 -25
- package/dist/types/generated/schemas.d.ts +117 -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 +48 -90
- 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 +201 -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 +12 -6
- package/dist/types/version.d.ts +2 -2
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,10 @@
|
|
|
1
1
|
# Changelog — @farthershore/client
|
|
2
2
|
|
|
3
|
+
## [0.8.0] - 2026-11-21
|
|
4
|
+
|
|
5
|
+
- **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.
|
|
6
|
+
- Backend, key and webhook operations accept and return an explicit scope (all, production, non-production or one environment).
|
|
7
|
+
|
|
3
8
|
## [0.7.0] - 2026-11-20
|
|
4
9
|
|
|
5
10
|
- 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 +20,32 @@
|
|
|
15
20
|
|
|
16
21
|
- Stop frontend build waits on supersession and keep the awaited build identity fixed, including when it is missing from a status response.
|
|
17
22
|
|
|
23
|
+
## [0.6.0] - 2026-11-10
|
|
24
|
+
|
|
25
|
+
- **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.
|
|
26
|
+
|
|
27
|
+
### Added — scoped backend connections
|
|
28
|
+
|
|
29
|
+
- Backend deployment and runtime key requests accept explicit environment
|
|
30
|
+
scopes. Bind responses include the managed receiver and one-time default key;
|
|
31
|
+
bootstrap contracts describe the key's accepted environments.
|
|
32
|
+
- Webhook operations accept event subscription patterns and expose delivery
|
|
33
|
+
diagnostics through the updated typed responses.
|
|
34
|
+
|
|
35
|
+
### Added
|
|
36
|
+
|
|
37
|
+
- `webhooks.delivery.redeliver({ businessId, webhookId, deliveryId })` sends
|
|
38
|
+
one delivery again with the same `webhook-id`.
|
|
39
|
+
- `webhooks.redeliver({ businessId, webhookId, since, until? })` sends every
|
|
40
|
+
failed or dead delivery created in `[since, until)` again and returns
|
|
41
|
+
`{ data: { redelivered } }`.
|
|
42
|
+
|
|
43
|
+
### Changed
|
|
44
|
+
|
|
45
|
+
- `WebhookEndpoint.disabledAt` is replaced by **`pausedAt`**: endpoints are no
|
|
46
|
+
longer disabled after repeated failures; they pause after a day of failed
|
|
47
|
+
deliveries and resume on their own. Requires the matching platform release.
|
|
48
|
+
|
|
18
49
|
## [0.5.0] - 2026-11-09
|
|
19
50
|
|
|
20
51
|
- **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.8.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
|
{
|
|
@@ -2143,20 +2154,20 @@ var AGENT_OPERATION_AUTHORIZATIONS = {
|
|
|
2143
2154
|
// bound to this key serves the accepted business config, so reading either
|
|
2144
2155
|
// is a business read (`rbac:read` stays the subject/role catalog authority).
|
|
2145
2156
|
"rbac.read": { permission: BUSINESS_READ_PERMISSION, targetKind: "business" },
|
|
2146
|
-
"
|
|
2147
|
-
permission: "
|
|
2157
|
+
"secret_key.mint": {
|
|
2158
|
+
permission: "secret_key:mint",
|
|
2148
2159
|
targetKind: "business"
|
|
2149
2160
|
},
|
|
2150
|
-
"
|
|
2151
|
-
permission: "
|
|
2161
|
+
"secret_key.read": {
|
|
2162
|
+
permission: "secret_key:read",
|
|
2152
2163
|
targetKind: "business"
|
|
2153
2164
|
},
|
|
2154
|
-
"
|
|
2155
|
-
permission: "
|
|
2165
|
+
"secret_key.revoke": {
|
|
2166
|
+
permission: "secret_key:revoke",
|
|
2156
2167
|
targetKind: "business"
|
|
2157
2168
|
},
|
|
2158
|
-
"
|
|
2159
|
-
permission: "
|
|
2169
|
+
"secret_key.rotate": {
|
|
2170
|
+
permission: "secret_key:rotate",
|
|
2160
2171
|
targetKind: "business"
|
|
2161
2172
|
},
|
|
2162
2173
|
"resource_count.report": {
|
|
@@ -2199,6 +2210,14 @@ var AGENT_OPERATION_AUTHORIZATIONS = {
|
|
|
2199
2210
|
permission: "webhook:update",
|
|
2200
2211
|
targetKind: "business"
|
|
2201
2212
|
},
|
|
2213
|
+
"webhook.delivery.redeliver": {
|
|
2214
|
+
permission: "webhook:update",
|
|
2215
|
+
targetKind: "business"
|
|
2216
|
+
},
|
|
2217
|
+
"webhook.redeliver": {
|
|
2218
|
+
permission: "webhook:update",
|
|
2219
|
+
targetKind: "business"
|
|
2220
|
+
},
|
|
2202
2221
|
"webhook.event_type.read": {
|
|
2203
2222
|
permission: "webhook:read",
|
|
2204
2223
|
targetKind: "business"
|
|
@@ -2541,9 +2560,9 @@ var SPECS = {
|
|
|
2541
2560
|
},
|
|
2542
2561
|
"business.create": {
|
|
2543
2562
|
summary: "Create a new business and provision its managed GitHub repo",
|
|
2544
|
-
description: "Create a new business and provision its managed GitHub repo",
|
|
2563
|
+
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
2564
|
destructive: false,
|
|
2546
|
-
oneTimeSecret:
|
|
2565
|
+
oneTimeSecret: true,
|
|
2547
2566
|
preview: false,
|
|
2548
2567
|
reconcile: { op: "business.list" }
|
|
2549
2568
|
},
|
|
@@ -2676,7 +2695,7 @@ var SPECS = {
|
|
|
2676
2695
|
},
|
|
2677
2696
|
"backend.read": {
|
|
2678
2697
|
summary: "List backends for a business (id, scope, name, transport, status)",
|
|
2679
|
-
description: "List a business's
|
|
2698
|
+
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
2699
|
destructive: false,
|
|
2681
2700
|
oneTimeSecret: false,
|
|
2682
2701
|
preview: false,
|
|
@@ -2684,60 +2703,60 @@ var SPECS = {
|
|
|
2684
2703
|
},
|
|
2685
2704
|
"backend.create": {
|
|
2686
2705
|
summary: "Create a backend (default transport: direct)",
|
|
2687
|
-
description: "Create a backend
|
|
2706
|
+
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
2707
|
destructive: false,
|
|
2689
|
-
oneTimeSecret:
|
|
2708
|
+
oneTimeSecret: true,
|
|
2690
2709
|
preview: true,
|
|
2691
2710
|
reconcile: { op: "backend.read" }
|
|
2692
2711
|
},
|
|
2693
2712
|
"backend.bind": {
|
|
2694
|
-
summary: "
|
|
2695
|
-
description: "
|
|
2713
|
+
summary: "Set a backend's origin (every environment unless overridden)",
|
|
2714
|
+
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
2715
|
destructive: false,
|
|
2697
|
-
oneTimeSecret:
|
|
2716
|
+
oneTimeSecret: true,
|
|
2698
2717
|
preview: true,
|
|
2699
2718
|
reconcile: { op: "backend.read" }
|
|
2700
2719
|
},
|
|
2701
2720
|
"backend.delete": {
|
|
2702
|
-
summary: "Delete a backend (revokes its
|
|
2721
|
+
summary: "Delete a backend (revokes its secret keys)",
|
|
2703
2722
|
description: "Delete a backend (origin). Traffic routed to it stops; re-create to restore.",
|
|
2704
2723
|
destructive: true,
|
|
2705
2724
|
oneTimeSecret: false,
|
|
2706
2725
|
preview: false,
|
|
2707
2726
|
reconcile: { op: "backend.read" }
|
|
2708
2727
|
},
|
|
2709
|
-
"
|
|
2710
|
-
summary: "List
|
|
2711
|
-
description: "List a business's
|
|
2728
|
+
"secret_key.read": {
|
|
2729
|
+
summary: "List secret keys for a business",
|
|
2730
|
+
description: "List a business's secret keys (fsrt_) \u2014 id, last-four, operations, status, and env scope. Read-only; secrets are never shown.",
|
|
2712
2731
|
destructive: false,
|
|
2713
2732
|
oneTimeSecret: false,
|
|
2714
2733
|
preview: false,
|
|
2715
2734
|
pagination: "offset"
|
|
2716
2735
|
},
|
|
2717
|
-
"
|
|
2718
|
-
summary: "Create a
|
|
2719
|
-
description: "Mint
|
|
2736
|
+
"secret_key.mint": {
|
|
2737
|
+
summary: "Create a secret key (returns it once)",
|
|
2738
|
+
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
2739
|
destructive: false,
|
|
2721
2740
|
oneTimeSecret: true,
|
|
2722
2741
|
preview: false,
|
|
2723
|
-
reconcile: { op: "
|
|
2742
|
+
reconcile: { op: "secret_key.read" }
|
|
2724
2743
|
},
|
|
2725
|
-
// DECISION: NEITHER side → destructive (+ oneTimeSecret, already declared). Rotation revokes the previous
|
|
2726
|
-
"
|
|
2727
|
-
summary: "Rotate a
|
|
2728
|
-
description: "Rotate a
|
|
2744
|
+
// DECISION: NEITHER side → destructive (+ oneTimeSecret, already declared). Rotation revokes the previous FS_SECRET_KEY immediately; a backend still using it starts failing.
|
|
2745
|
+
"secret_key.rotate": {
|
|
2746
|
+
summary: "Rotate a secret key (returns a fresh FS_SECRET_KEY once)",
|
|
2747
|
+
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
2748
|
destructive: true,
|
|
2730
2749
|
oneTimeSecret: true,
|
|
2731
2750
|
preview: false,
|
|
2732
|
-
reconcile: { op: "
|
|
2751
|
+
reconcile: { op: "secret_key.read" }
|
|
2733
2752
|
},
|
|
2734
|
-
"
|
|
2735
|
-
summary: "Revoke a
|
|
2736
|
-
description: "Revoke a
|
|
2753
|
+
"secret_key.revoke": {
|
|
2754
|
+
summary: "Revoke a secret key",
|
|
2755
|
+
description: "Revoke a secret key. The backend using it stops verifying.",
|
|
2737
2756
|
destructive: true,
|
|
2738
2757
|
oneTimeSecret: false,
|
|
2739
2758
|
preview: false,
|
|
2740
|
-
reconcile: { op: "
|
|
2759
|
+
reconcile: { op: "secret_key.read" }
|
|
2741
2760
|
},
|
|
2742
2761
|
"frontend.status": {
|
|
2743
2762
|
summary: "Show the current frontend release, recent releases, and recent builds (incl. failure reasons)",
|
|
@@ -2828,6 +2847,25 @@ var SPECS = {
|
|
|
2828
2847
|
preview: false,
|
|
2829
2848
|
reconcile: { op: "webhook.read" }
|
|
2830
2849
|
},
|
|
2850
|
+
// Redelivery queues the SAME delivery again (same webhook-id), so a
|
|
2851
|
+
// receiver that already processed it can dedupe. Each call sends again;
|
|
2852
|
+
// read the delivery log before repeating an ambiguous one.
|
|
2853
|
+
"webhook.delivery.redeliver": {
|
|
2854
|
+
summary: "Send one webhook delivery again",
|
|
2855
|
+
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.",
|
|
2856
|
+
destructive: false,
|
|
2857
|
+
oneTimeSecret: false,
|
|
2858
|
+
preview: false,
|
|
2859
|
+
reconcile: { op: "webhook.delivery.read" }
|
|
2860
|
+
},
|
|
2861
|
+
"webhook.redeliver": {
|
|
2862
|
+
summary: "Send every failed or dead delivery of a webhook endpoint in a time range again",
|
|
2863
|
+
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.",
|
|
2864
|
+
destructive: false,
|
|
2865
|
+
oneTimeSecret: false,
|
|
2866
|
+
preview: false,
|
|
2867
|
+
reconcile: { op: "webhook.delivery.read" }
|
|
2868
|
+
},
|
|
2831
2869
|
"webhook.event_type.read": {
|
|
2832
2870
|
summary: "List the event names a webhook endpoint can subscribe to",
|
|
2833
2871
|
description: "List the event names a webhook endpoint can subscribe to, with descriptions.",
|
|
@@ -3783,14 +3821,14 @@ function namespacePathFor(key) {
|
|
|
3783
3821
|
}
|
|
3784
3822
|
|
|
3785
3823
|
// ../contracts/dist/runtime.js
|
|
3786
|
-
var
|
|
3824
|
+
var FS_SECRET_KEY_ENV = "FS_SECRET_KEY";
|
|
3787
3825
|
var RESPONSE_METERING_HEADER_NAMES = {
|
|
3788
3826
|
payload: "x-fs-metering",
|
|
3789
3827
|
signature: "x-fs-metering-sig",
|
|
3790
3828
|
token: "x-fs-metering-token"
|
|
3791
3829
|
};
|
|
3792
3830
|
var RESPONSE_METERING_TOKEN_CONTRACT = {
|
|
3793
|
-
environmentVariable:
|
|
3831
|
+
environmentVariable: FS_SECRET_KEY_ENV,
|
|
3794
3832
|
presentation: RESPONSE_METERING_HEADER_NAMES.token,
|
|
3795
3833
|
storage: "sha256-hash-only"
|
|
3796
3834
|
};
|
|
@@ -3807,6 +3845,7 @@ var RUNTIME_ERROR_CODES = {
|
|
|
3807
3845
|
replayedNonce: "replayed_nonce",
|
|
3808
3846
|
bodyTooLarge: "body_too_large",
|
|
3809
3847
|
environmentMismatch: "environment_mismatch",
|
|
3848
|
+
environmentUnknown: "environment_unknown",
|
|
3810
3849
|
missingToken: "missing_token",
|
|
3811
3850
|
invalidToken: "invalid_token",
|
|
3812
3851
|
/** UA-6 — `contextVerification: "required"` and the signed X-Fs-Context
|
|
@@ -3840,8 +3879,10 @@ var ERROR_CODES = {
|
|
|
3840
3879
|
ACCOUNT_ERASURE_PUBLISHED_BUSINESS: "ACCOUNT_ERASURE_PUBLISHED_BUSINESS",
|
|
3841
3880
|
ACCOUNT_ERASURE_UNSETTLED_MONEY: "ACCOUNT_ERASURE_UNSETTLED_MONEY",
|
|
3842
3881
|
ACCOUNT_ERASURE_CONFIRMATION_MISMATCH: "ACCOUNT_ERASURE_CONFIRMATION_MISMATCH",
|
|
3843
|
-
|
|
3844
|
-
|
|
3882
|
+
/** A legal obligation stands in front of the action; `details.unmet` names each fix. */
|
|
3883
|
+
LEGAL_OBLIGATION_UNMET: "LEGAL_OBLIGATION_UNMET",
|
|
3884
|
+
/** The agreement versions submitted for acceptance are no longer the ones required. */
|
|
3885
|
+
LEGAL_DOCUMENT_VERSION_CHANGED: "LEGAL_DOCUMENT_VERSION_CHANGED",
|
|
3845
3886
|
MAINTENANCE_JOB_RETIRED: "MAINTENANCE_JOB_RETIRED",
|
|
3846
3887
|
INVALID_USAGE_UNIT_LABEL: "INVALID_USAGE_UNIT_LABEL",
|
|
3847
3888
|
HUMAN_ONLY_ACTION: "HUMAN_ONLY_ACTION",
|
|
@@ -4173,6 +4214,7 @@ var RUNTIME_ERROR_CODE_TO_ERROR_CODE = {
|
|
|
4173
4214
|
body_hash_mismatch: ERROR_CODES.UNAUTHORIZED,
|
|
4174
4215
|
route_mismatch: ERROR_CODES.UNAUTHORIZED,
|
|
4175
4216
|
environment_mismatch: ERROR_CODES.UNAUTHORIZED,
|
|
4217
|
+
environment_unknown: ERROR_CODES.UNAUTHORIZED,
|
|
4176
4218
|
// JWKS fetch unavailable — a dependency fault, but the backend still
|
|
4177
4219
|
// fail-closes the request as 401 (statusForCode), so the canonical code is
|
|
4178
4220
|
// SERVICE_UNAVAILABLE to preserve the "dependency down" semantic for callers.
|
|
@@ -4564,7 +4606,7 @@ var authOperations = {
|
|
|
4564
4606
|
|
|
4565
4607
|
// src/operations/backends.ts
|
|
4566
4608
|
var backends = (businessId) => `/businesses/${seg(businessId)}/backends`;
|
|
4567
|
-
var
|
|
4609
|
+
var secretKeys = (businessId) => `/businesses/${seg(businessId)}/secret-keys`;
|
|
4568
4610
|
var backendOperations = {
|
|
4569
4611
|
"backends.read": operation({
|
|
4570
4612
|
op: "backend.read",
|
|
@@ -4590,29 +4632,29 @@ var backendOperations = {
|
|
|
4590
4632
|
op: "backend.delete",
|
|
4591
4633
|
run: (ctx, { businessId, backendId }) => send(ctx, "DELETE", `${backends(businessId)}/${seg(backendId)}`)
|
|
4592
4634
|
}),
|
|
4593
|
-
"
|
|
4594
|
-
op: "
|
|
4635
|
+
"secretKeys.read": operation({
|
|
4636
|
+
op: "secret_key.read",
|
|
4595
4637
|
run: (ctx, { businessId, environmentId, limit, offset }) => send(
|
|
4596
4638
|
ctx,
|
|
4597
4639
|
"GET",
|
|
4598
|
-
withQuery(
|
|
4640
|
+
withQuery(secretKeys(businessId), {
|
|
4599
4641
|
environmentId,
|
|
4600
4642
|
limit: num(limit),
|
|
4601
4643
|
offset: num(offset)
|
|
4602
4644
|
})
|
|
4603
4645
|
)
|
|
4604
4646
|
}),
|
|
4605
|
-
"
|
|
4606
|
-
op: "
|
|
4607
|
-
run: (ctx, { businessId, ...data }) => send(ctx, "POST",
|
|
4647
|
+
"secretKeys.mint": operation({
|
|
4648
|
+
op: "secret_key.mint",
|
|
4649
|
+
run: (ctx, { businessId, ...data }) => send(ctx, "POST", secretKeys(businessId), data)
|
|
4608
4650
|
}),
|
|
4609
|
-
"
|
|
4610
|
-
op: "
|
|
4611
|
-
run: (ctx, { businessId, tokenId }) => send(ctx, "POST", `${
|
|
4651
|
+
"secretKeys.rotate": operation({
|
|
4652
|
+
op: "secret_key.rotate",
|
|
4653
|
+
run: (ctx, { businessId, tokenId }) => send(ctx, "POST", `${secretKeys(businessId)}/${seg(tokenId)}/rotate`)
|
|
4612
4654
|
}),
|
|
4613
|
-
"
|
|
4614
|
-
op: "
|
|
4615
|
-
run: (ctx, { businessId, tokenId }) => send(ctx, "DELETE", `${
|
|
4655
|
+
"secretKeys.revoke": operation({
|
|
4656
|
+
op: "secret_key.revoke",
|
|
4657
|
+
run: (ctx, { businessId, tokenId }) => send(ctx, "DELETE", `${secretKeys(businessId)}/${seg(tokenId)}`)
|
|
4616
4658
|
})
|
|
4617
4659
|
};
|
|
4618
4660
|
|
|
@@ -5683,6 +5725,13 @@ var webhookOperations = {
|
|
|
5683
5725
|
op: "webhook.rotate_secret",
|
|
5684
5726
|
run: (ctx, { businessId, webhookId }) => send(ctx, "POST", `${webhook(businessId, webhookId)}/rotate-secret`)
|
|
5685
5727
|
}),
|
|
5728
|
+
"webhooks.redeliver": operation({
|
|
5729
|
+
op: "webhook.redeliver",
|
|
5730
|
+
run: (ctx, { businessId, webhookId, since, until }) => send(ctx, "POST", `${webhook(businessId, webhookId)}/redeliver`, {
|
|
5731
|
+
since,
|
|
5732
|
+
...until !== void 0 ? { until } : {}
|
|
5733
|
+
})
|
|
5734
|
+
}),
|
|
5686
5735
|
"webhooks.eventType.read": operation({
|
|
5687
5736
|
op: "webhook.event_type.read",
|
|
5688
5737
|
run: (ctx, { businessId }) => send(
|
|
@@ -5712,6 +5761,14 @@ var webhookOperations = {
|
|
|
5712
5761
|
`${webhook(businessId, webhookId)}/deliveries/${seg(deliveryId)}`
|
|
5713
5762
|
)
|
|
5714
5763
|
}),
|
|
5764
|
+
"webhooks.delivery.redeliver": operation({
|
|
5765
|
+
op: "webhook.delivery.redeliver",
|
|
5766
|
+
run: (ctx, { businessId, webhookId, deliveryId }) => send(
|
|
5767
|
+
ctx,
|
|
5768
|
+
"POST",
|
|
5769
|
+
`${webhook(businessId, webhookId)}/deliveries/${seg(deliveryId)}/redeliver`
|
|
5770
|
+
)
|
|
5771
|
+
}),
|
|
5715
5772
|
"webhooks.delivery.payload.read": operation({
|
|
5716
5773
|
op: "webhook.delivery.payload.read",
|
|
5717
5774
|
run: (ctx, { businessId, webhookId, deliveryId }) => send(
|
|
@@ -6298,7 +6355,7 @@ function diagnosticsOf(parsed) {
|
|
|
6298
6355
|
}
|
|
6299
6356
|
|
|
6300
6357
|
// src/version.ts
|
|
6301
|
-
var CLIENT_VERSION = "0.
|
|
6358
|
+
var CLIENT_VERSION = "0.8.0";
|
|
6302
6359
|
var CLIENT_PRODUCT = `@farthershore/client/${CLIENT_VERSION}`;
|
|
6303
6360
|
|
|
6304
6361
|
// src/transport.ts
|
|
@@ -189,23 +189,23 @@ export interface FartherShoreApi {
|
|
|
189
189
|
};
|
|
190
190
|
readonly backends: {
|
|
191
191
|
/**
|
|
192
|
-
*
|
|
192
|
+
* Set a backend's origin (every environment unless overridden)
|
|
193
193
|
*
|
|
194
|
-
*
|
|
194
|
+
* 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.
|
|
195
195
|
*
|
|
196
|
-
* Operation `backend.bind` · write · requires `backend:bind` · supports `dryRun` · reconcile an unknown outcome with `backend.read`.
|
|
196
|
+
* Operation `backend.bind` · write · requires `backend:bind` · returns a one-time secret · supports `dryRun` · reconcile an unknown outcome with `backend.read`.
|
|
197
197
|
*/
|
|
198
198
|
readonly bind: Method<"backends.bind">;
|
|
199
199
|
/**
|
|
200
200
|
* Create a backend (default transport: direct)
|
|
201
201
|
*
|
|
202
|
-
* Create a backend
|
|
202
|
+
* 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.
|
|
203
203
|
*
|
|
204
|
-
* Operation `backend.create` · write · requires `backend:create` · supports `dryRun` · reconcile an unknown outcome with `backend.read`.
|
|
204
|
+
* Operation `backend.create` · write · requires `backend:create` · returns a one-time secret · supports `dryRun` · reconcile an unknown outcome with `backend.read`.
|
|
205
205
|
*/
|
|
206
206
|
readonly create: Method<"backends.create">;
|
|
207
207
|
/**
|
|
208
|
-
* Delete a backend (revokes its
|
|
208
|
+
* Delete a backend (revokes its secret keys)
|
|
209
209
|
*
|
|
210
210
|
* Delete a backend (origin). Traffic routed to it stops; re-create to restore.
|
|
211
211
|
*
|
|
@@ -215,7 +215,7 @@ export interface FartherShoreApi {
|
|
|
215
215
|
/**
|
|
216
216
|
* List backends for a business (id, scope, name, transport, status)
|
|
217
217
|
*
|
|
218
|
-
* List a business's
|
|
218
|
+
* List a business's backend deployments — 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.
|
|
219
219
|
*
|
|
220
220
|
* Operation `backend.read` · read · requires `backend:read` · offset pagination.
|
|
221
221
|
*/
|
|
@@ -347,7 +347,9 @@ export interface FartherShoreApi {
|
|
|
347
347
|
/**
|
|
348
348
|
* Create a new business and provision its managed GitHub repo
|
|
349
349
|
*
|
|
350
|
-
*
|
|
350
|
+
* 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 — set it as FS_SECRET_KEY in your backend.
|
|
351
|
+
*
|
|
352
|
+
* Operation `business.create` · write · requires `business:create` · returns a one-time secret · reconcile an unknown outcome with `business.list`.
|
|
351
353
|
*/
|
|
352
354
|
readonly create: Method<"businesses.create">;
|
|
353
355
|
readonly docs: {
|
|
@@ -1173,39 +1175,39 @@ export interface FartherShoreApi {
|
|
|
1173
1175
|
*/
|
|
1174
1176
|
readonly update: Method<"promoCodes.update">;
|
|
1175
1177
|
};
|
|
1176
|
-
readonly
|
|
1178
|
+
readonly secretKeys: {
|
|
1177
1179
|
/**
|
|
1178
|
-
* Create a
|
|
1180
|
+
* Create a secret key (returns it once)
|
|
1179
1181
|
*
|
|
1180
|
-
* Mint
|
|
1182
|
+
* 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.
|
|
1181
1183
|
*
|
|
1182
|
-
* Operation `
|
|
1184
|
+
* Operation `secret_key.mint` · write · requires `secret_key:mint` · returns a one-time secret · reconcile an unknown outcome with `secret_key.read`.
|
|
1183
1185
|
*/
|
|
1184
|
-
readonly mint: Method<"
|
|
1186
|
+
readonly mint: Method<"secretKeys.mint">;
|
|
1185
1187
|
/**
|
|
1186
|
-
* List
|
|
1188
|
+
* List secret keys for a business
|
|
1187
1189
|
*
|
|
1188
|
-
* List a business's
|
|
1190
|
+
* List a business's secret keys (fsrt_) — id, last-four, operations, status, and env scope. Read-only; secrets are never shown.
|
|
1189
1191
|
*
|
|
1190
|
-
* Operation `
|
|
1192
|
+
* Operation `secret_key.read` · read · requires `secret_key:read` · offset pagination.
|
|
1191
1193
|
*/
|
|
1192
|
-
readonly read: Method<"
|
|
1194
|
+
readonly read: Method<"secretKeys.read">;
|
|
1193
1195
|
/**
|
|
1194
|
-
* Revoke a
|
|
1196
|
+
* Revoke a secret key
|
|
1195
1197
|
*
|
|
1196
|
-
* Revoke a
|
|
1198
|
+
* Revoke a secret key. The backend using it stops verifying.
|
|
1197
1199
|
*
|
|
1198
|
-
* Operation `
|
|
1200
|
+
* Operation `secret_key.revoke` · write · requires `secret_key:revoke` · destructive · reconcile an unknown outcome with `secret_key.read`.
|
|
1199
1201
|
*/
|
|
1200
|
-
readonly revoke: Method<"
|
|
1202
|
+
readonly revoke: Method<"secretKeys.revoke">;
|
|
1201
1203
|
/**
|
|
1202
|
-
* Rotate a
|
|
1204
|
+
* Rotate a secret key (returns a fresh FS_SECRET_KEY once)
|
|
1203
1205
|
*
|
|
1204
|
-
* Rotate a
|
|
1206
|
+
* Rotate a secret key: mint a fresh secret carrying the same scope and revoke the old one. Returns the new plaintext token ONCE.
|
|
1205
1207
|
*
|
|
1206
|
-
* Operation `
|
|
1208
|
+
* Operation `secret_key.rotate` · write · requires `secret_key:rotate` · destructive · returns a one-time secret · reconcile an unknown outcome with `secret_key.read`.
|
|
1207
1209
|
*/
|
|
1208
|
-
readonly rotate: Method<"
|
|
1210
|
+
readonly rotate: Method<"secretKeys.rotate">;
|
|
1209
1211
|
};
|
|
1210
1212
|
readonly usage: {
|
|
1211
1213
|
/**
|
|
@@ -1317,6 +1319,14 @@ export interface FartherShoreApi {
|
|
|
1317
1319
|
* Operation `webhook.delivery.read` · read · requires `webhook:delivery_read` · offset pagination.
|
|
1318
1320
|
*/
|
|
1319
1321
|
readonly read: Method<"webhooks.delivery.read">;
|
|
1322
|
+
/**
|
|
1323
|
+
* Send one webhook delivery again
|
|
1324
|
+
*
|
|
1325
|
+
* 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.
|
|
1326
|
+
*
|
|
1327
|
+
* Operation `webhook.delivery.redeliver` · write · requires `webhook:update` · reconcile an unknown outcome with `webhook.delivery.read`.
|
|
1328
|
+
*/
|
|
1329
|
+
readonly redeliver: Method<"webhooks.delivery.redeliver">;
|
|
1320
1330
|
};
|
|
1321
1331
|
readonly eventType: {
|
|
1322
1332
|
/**
|
|
@@ -1336,6 +1346,14 @@ export interface FartherShoreApi {
|
|
|
1336
1346
|
* Operation `webhook.read` · read · requires `webhook:read` · offset pagination.
|
|
1337
1347
|
*/
|
|
1338
1348
|
readonly read: Method<"webhooks.read">;
|
|
1349
|
+
/**
|
|
1350
|
+
* Send every failed or dead delivery of a webhook endpoint in a time range again
|
|
1351
|
+
*
|
|
1352
|
+
* 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.
|
|
1353
|
+
*
|
|
1354
|
+
* Operation `webhook.redeliver` · write · requires `webhook:update` · reconcile an unknown outcome with `webhook.delivery.read`.
|
|
1355
|
+
*/
|
|
1356
|
+
readonly redeliver: Method<"webhooks.redeliver">;
|
|
1339
1357
|
/**
|
|
1340
1358
|
* Issue a new signing secret (returned once); readable old secrets verify for 24h
|
|
1341
1359
|
*
|