@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 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.runtimeTokens.revoke(…)`) over an
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.7.0`.** Pre-1.0: minor releases may include breaking changes.
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.runtimeTokens.revoke({ businessId, tokenId });
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 (`runtime_token.revoke` →
64
- `fs.runtimeTokens.revoke`). The namespaces:
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.runtimeTokens` | Runtime tokens: read, mint, rotate, revoke |
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.runtimeTokens.revoke.meta;
99
- // { path: "runtimeTokens.revoke", op: "runtime_token.revoke",
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: "runtime_token.read" }, pagination: null,
103
- // maxPageSize: null, permission: "runtime_token:revoke" }
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
- "runtime_token:mint": permission("runtime_token:mint", {
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
- "runtime_token:read": permission("runtime_token:read", {
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
- "runtime_token:revoke": permission("runtime_token:revoke", {
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
- "runtime_token:rotate": permission("runtime_token:rotate", {
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: "runtime_token.mint", class: "operate", domain: "runtime-tokens" },
1227
- { key: "runtime_token.rotate", class: "operate", domain: "runtime-tokens" },
1228
- { key: "runtime_token.revoke", class: "operate", domain: "runtime-tokens" },
1229
- { key: "runtime_token.read", class: "operate", domain: "runtime-tokens" },
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 runtime token at backend bootstrap (/runtime/*), not minted separately. Issue the runtime token with `farthershore backend tokens create --operations metering`."
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
- "runtime_token.mint": {
2147
- permission: "runtime_token:mint",
2157
+ "secret_key.mint": {
2158
+ permission: "secret_key:mint",
2148
2159
  targetKind: "business"
2149
2160
  },
2150
- "runtime_token.read": {
2151
- permission: "runtime_token:read",
2161
+ "secret_key.read": {
2162
+ permission: "secret_key:read",
2152
2163
  targetKind: "business"
2153
2164
  },
2154
- "runtime_token.revoke": {
2155
- permission: "runtime_token:revoke",
2165
+ "secret_key.revoke": {
2166
+ permission: "secret_key:revoke",
2156
2167
  targetKind: "business"
2157
2168
  },
2158
- "runtime_token.rotate": {
2159
- permission: "runtime_token:rotate",
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: false,
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 backends (origins) \u2014 id, scope (production|environment), environmentId, name, slug, transport (direct|tunnel), default flag, and derived status. Backends are per-(business, environment) rows, so the same declared backend can legitimately appear once per scope and be default in each. Read-only.",
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 (origin) for a business. Pick a transport mode: direct (public HTTPS URL, secured by Ed25519 request signing) or tunnel (private outbound-only cloudflared, secure bring-your-own-backend). Mark it default to route traffic to it.",
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: false,
2708
+ oneTimeSecret: true,
2690
2709
  preview: true,
2691
2710
  reconcile: { op: "backend.read" }
2692
2711
  },
2693
2712
  "backend.bind": {
2694
- summary: "Bind a logical backend to a direct upstream in one environment",
2695
- description: "Bind a logical backend id to a concrete direct upstream URL in one environment. Previews inherit the production backend until a concrete override is bound. Omit environmentId for production.",
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: false,
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 runtime tokens)",
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
- "runtime_token.read": {
2710
- summary: "List runtime tokens for a business",
2711
- description: "List a business's runtime tokens (fsrt_) \u2014 id, last-four, operations, status, and env scope. Read-only; secrets are never shown.",
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
- "runtime_token.mint": {
2718
- summary: "Create a runtime token (returns FS_RUNTIME_TOKEN once)",
2719
- description: "Mint a new runtime token (fsrt_) for a backend. Returns the plaintext token ONCE \u2014 store it now (e.g. as FS_RUNTIME_TOKEN). Operations default to the backend's needs (gateway_verification, metering, health).",
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: "runtime_token.read" }
2742
+ reconcile: { op: "secret_key.read" }
2724
2743
  },
2725
- // DECISION: NEITHER side → destructive (+ oneTimeSecret, already declared). Rotation revokes the previous FS_RUNTIME_TOKEN immediately; a backend still using it starts failing.
2726
- "runtime_token.rotate": {
2727
- summary: "Rotate a runtime token (returns a fresh FS_RUNTIME_TOKEN once)",
2728
- description: "Rotate a runtime token: mint a fresh secret carrying the same scope and revoke the old one. Returns the new plaintext token ONCE.",
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: "runtime_token.read" }
2751
+ reconcile: { op: "secret_key.read" }
2733
2752
  },
2734
- "runtime_token.revoke": {
2735
- summary: "Revoke a runtime token",
2736
- description: "Revoke a runtime token. The backend using it stops verifying.",
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: "runtime_token.read" }
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 FS_RUNTIME_TOKEN_ENV = "FS_RUNTIME_TOKEN";
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: FS_RUNTIME_TOKEN_ENV,
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
- SELLER_LAUNCH_REQUIREMENTS_MISSING: "SELLER_LAUNCH_REQUIREMENTS_MISSING",
3844
- LEGAL_ACCEPTANCE_REQUIRED: "LEGAL_ACCEPTANCE_REQUIRED",
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 runtimeTokens = (businessId) => `/businesses/${seg(businessId)}/runtime-tokens`;
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
- "runtimeTokens.read": operation({
4594
- op: "runtime_token.read",
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(runtimeTokens(businessId), {
4640
+ withQuery(secretKeys(businessId), {
4599
4641
  environmentId,
4600
4642
  limit: num(limit),
4601
4643
  offset: num(offset)
4602
4644
  })
4603
4645
  )
4604
4646
  }),
4605
- "runtimeTokens.mint": operation({
4606
- op: "runtime_token.mint",
4607
- run: (ctx, { businessId, ...data }) => send(ctx, "POST", runtimeTokens(businessId), data)
4647
+ "secretKeys.mint": operation({
4648
+ op: "secret_key.mint",
4649
+ run: (ctx, { businessId, ...data }) => send(ctx, "POST", secretKeys(businessId), data)
4608
4650
  }),
4609
- "runtimeTokens.rotate": operation({
4610
- op: "runtime_token.rotate",
4611
- run: (ctx, { businessId, tokenId }) => send(ctx, "POST", `${runtimeTokens(businessId)}/${seg(tokenId)}/rotate`)
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
- "runtimeTokens.revoke": operation({
4614
- op: "runtime_token.revoke",
4615
- run: (ctx, { businessId, tokenId }) => send(ctx, "DELETE", `${runtimeTokens(businessId)}/${seg(tokenId)}`)
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.7.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
- * Bind a logical backend to a direct upstream in one environment
192
+ * Set a backend's origin (every environment unless overridden)
193
193
  *
194
- * Bind a logical backend id to a concrete direct upstream URL in one environment. Previews inherit the production backend until a concrete override is bound. Omit environmentId for production.
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 (origin) for a business. Pick a transport mode: direct (public HTTPS URL, secured by Ed25519 request signing) or tunnel (private outbound-only cloudflared, secure bring-your-own-backend). Mark it default to route traffic to it.
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 runtime tokens)
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 backends (origins) — id, scope (production|environment), environmentId, name, slug, transport (direct|tunnel), default flag, and derived status. Backends are per-(business, environment) rows, so the same declared backend can legitimately appear once per scope and be default in each. Read-only.
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
- * Operation `business.create` · write · requires `business:create` · reconcile an unknown outcome with `business.list`.
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 runtimeTokens: {
1178
+ readonly secretKeys: {
1177
1179
  /**
1178
- * Create a runtime token (returns FS_RUNTIME_TOKEN once)
1180
+ * Create a secret key (returns it once)
1179
1181
  *
1180
- * Mint a new runtime token (fsrt_) for a backend. Returns the plaintext token ONCE — store it now (e.g. as FS_RUNTIME_TOKEN). Operations default to the backend's needs (gateway_verification, metering, health).
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 `runtime_token.mint` · write · requires `runtime_token:mint` · returns a one-time secret · reconcile an unknown outcome with `runtime_token.read`.
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<"runtimeTokens.mint">;
1186
+ readonly mint: Method<"secretKeys.mint">;
1185
1187
  /**
1186
- * List runtime tokens for a business
1188
+ * List secret keys for a business
1187
1189
  *
1188
- * List a business's runtime tokens (fsrt_) — id, last-four, operations, status, and env scope. Read-only; secrets are never shown.
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 `runtime_token.read` · read · requires `runtime_token:read` · offset pagination.
1192
+ * Operation `secret_key.read` · read · requires `secret_key:read` · offset pagination.
1191
1193
  */
1192
- readonly read: Method<"runtimeTokens.read">;
1194
+ readonly read: Method<"secretKeys.read">;
1193
1195
  /**
1194
- * Revoke a runtime token
1196
+ * Revoke a secret key
1195
1197
  *
1196
- * Revoke a runtime token. The backend using it stops verifying.
1198
+ * Revoke a secret key. The backend using it stops verifying.
1197
1199
  *
1198
- * Operation `runtime_token.revoke` · write · requires `runtime_token:revoke` · destructive · reconcile an unknown outcome with `runtime_token.read`.
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<"runtimeTokens.revoke">;
1202
+ readonly revoke: Method<"secretKeys.revoke">;
1201
1203
  /**
1202
- * Rotate a runtime token (returns a fresh FS_RUNTIME_TOKEN once)
1204
+ * Rotate a secret key (returns a fresh FS_SECRET_KEY once)
1203
1205
  *
1204
- * Rotate a runtime token: mint a fresh secret carrying the same scope and revoke the old one. Returns the new plaintext token ONCE.
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 `runtime_token.rotate` · write · requires `runtime_token:rotate` · destructive · returns a one-time secret · reconcile an unknown outcome with `runtime_token.read`.
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<"runtimeTokens.rotate">;
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
  *