@farthershore/client 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/CHANGELOG.md +18 -0
  2. package/README.md +7 -1
  3. package/dist/index.js +113 -16
  4. package/dist/types/api.generated.d.ts +23 -5
  5. package/dist/types/envelope.d.ts +2 -0
  6. package/dist/types/errors.d.ts +13 -0
  7. package/dist/types/generated/schemas.d.ts +68 -17
  8. package/dist/types/index.d.ts +1 -1
  9. package/dist/types/operations/agents.d.ts +9 -9
  10. package/dist/types/operations/agreements.d.ts +7 -7
  11. package/dist/types/operations/analytics.d.ts +5 -5
  12. package/dist/types/operations/audit-notifications.d.ts +6 -6
  13. package/dist/types/operations/auth.d.ts +4 -4
  14. package/dist/types/operations/backends.d.ts +8 -11
  15. package/dist/types/operations/billing.d.ts +4 -4
  16. package/dist/types/operations/businesses.d.ts +38 -24
  17. package/dist/types/operations/change-sets.d.ts +6 -6
  18. package/dist/types/operations/consumers.d.ts +13 -13
  19. package/dist/types/operations/define.d.ts +6 -2
  20. package/dist/types/operations/environments.d.ts +5 -4
  21. package/dist/types/operations/frontend.d.ts +2 -2
  22. package/dist/types/operations/index.d.ts +308 -182
  23. package/dist/types/operations/maker-tokens.d.ts +9 -9
  24. package/dist/types/operations/organizations.d.ts +21 -21
  25. package/dist/types/operations/personas.d.ts +8 -8
  26. package/dist/types/operations/plans-usage.d.ts +3 -3
  27. package/dist/types/operations/platform.d.ts +12 -12
  28. package/dist/types/operations/portal.d.ts +11 -11
  29. package/dist/types/operations/promo-codes.d.ts +15 -5
  30. package/dist/types/operations/variables.d.ts +22 -8
  31. package/dist/types/operations/webhooks.d.ts +105 -12
  32. package/dist/types/surface-types.d.ts +16 -10
  33. package/dist/types/types.d.ts +3 -0
  34. package/dist/types/version.d.ts +2 -2
  35. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -4,6 +4,24 @@ All notable changes to the API client are documented here. This package
4
4
  versions independently from the CLI and the other SDKs. Pre-1.0: minor versions
5
5
  may include breaking changes.
6
6
 
7
+ ## [0.4.0] - 2026-10-28
8
+
9
+ ### Changed
10
+
11
+ - **Breaking:** `organizations.overview.read` → `OrganizationOverview.organization.stripeConnected`
12
+ is renamed **`billingConnected`** (generated `Schemas["OrganizationOverview"]`
13
+ too). Requires the matching platform release.
14
+
15
+ ## [0.3.0] - 2026-10-14
16
+
17
+ ### Added
18
+
19
+ - `businesses.docs.validate({ businessId, env?, files })` checks docs files
20
+ (`docs/_index.yaml` and MDX pages) the way the pull request check does,
21
+ without publishing anything. It retries like a read and returns
22
+ `DocsValidateResponse` (`issues`, errors first, then notes with a
23
+ `severity`). New exported type: `DocsValidateResponse`.
24
+
7
25
  ## [0.2.0] - 2026-10-14
8
26
 
9
27
  ### Changed
package/README.md CHANGED
@@ -5,7 +5,7 @@ namespaced, typed operation surface (`fs.runtimeTokens.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.2.0`.** Pre-1.0: minor releases may include breaking changes.
8
+ > **Status: `0.3.0`.** Pre-1.0: minor releases may include breaking changes.
9
9
  > Every response is typed. All but the publish-rollback receipt 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.
@@ -54,6 +54,12 @@ Every operation is a method `fs.<namespace>.<method>(input, options?)`:
54
54
  `DRY_RUN_NOT_SUPPORTED` before sending anything. `retry: "none"` makes a
55
55
  single attempt.
56
56
 
57
+ On preview-capable methods, literal `{ dryRun: true }` resolves to
58
+ `DryRunPreview<W>` (`{ dryRun: true, wouldHave: W }`), while omitted options or
59
+ `{ dryRun: false }` resolve to the write result. A `CallOptions` variable
60
+ resolves to the union, so check `"dryRun" in result` before using the result.
61
+ `W` is the preview payload, which can differ from the write result.
62
+
57
63
  The namespace path comes from the operation key (`runtime_token.revoke` →
58
64
  `fs.runtimeTokens.revoke`). The namespaces:
59
65
 
package/dist/index.js CHANGED
@@ -714,6 +714,12 @@ var PLATFORM_PERMISSION_CATALOG = {
714
714
  defaultRoles: OWNER_ADMIN,
715
715
  delegation: "maker_token"
716
716
  }),
717
+ "webhook:delivery_payload_read": permission("webhook:delivery_payload_read", {
718
+ effect: "read",
719
+ allowedTargetKinds: BUSINESS,
720
+ defaultRoles: OWNER_ADMIN,
721
+ delegation: "user_session_only"
722
+ }),
717
723
  "webhook:delivery_read": permission("webhook:delivery_read", {
718
724
  effect: "read",
719
725
  allowedTargetKinds: BUSINESS,
@@ -1056,6 +1062,11 @@ var PLATFORM_OPERATION_DEFINITIONS = [
1056
1062
  { key: "bulletin.read", class: "operate", domain: "agents" },
1057
1063
  { key: "bulletin.ack", class: "operate", domain: "agents" },
1058
1064
  { key: "bulletin.resolve", class: "operate", domain: "agents" },
1065
+ {
1066
+ key: "webhook.delivery.payload.read",
1067
+ class: "operate",
1068
+ domain: WEBHOOKS_DOMAIN
1069
+ },
1059
1070
  { key: "webhook.delivery.read", class: "operate", domain: WEBHOOKS_DOMAIN },
1060
1071
  { key: "promo_code.read", class: "operate", domain: PROMO_CODES_DOMAIN },
1061
1072
  { key: "promo_code.create", class: "operate", domain: PROMO_CODES_DOMAIN },
@@ -1422,6 +1433,18 @@ var PLATFORM_OPERATION_DEFINITIONS = [
1422
1433
  detail: "Use `farthershore validate --business <business>`; it builds deterministically and calls this manifest-compile endpoint for the server verdict."
1423
1434
  }
1424
1435
  },
1436
+ {
1437
+ key: "business.docs.validate",
1438
+ class: "operate",
1439
+ domain: "businesses",
1440
+ // Runs the PR bot's docs check on files sent in the request and returns
1441
+ // its issues. Stores nothing; a repeat is a fresh observation.
1442
+ sideEffect: "read",
1443
+ unavailable: {
1444
+ reason: "served_by_other_command",
1445
+ detail: "Use `farthershore validate --business <business>`; it sends your docs/ files and shows the same issues a pull request's Docs comment would."
1446
+ }
1447
+ },
1425
1448
  { key: "business.read", class: "operate", domain: "businesses" },
1426
1449
  { key: "business.routes.read", class: "contract", domain: "businesses" },
1427
1450
  { key: "business.contract.read", class: "contract", domain: "businesses" },
@@ -1694,6 +1717,13 @@ var AGENT_OPERATION_AUTHORIZATIONS = {
1694
1717
  permission: "business:compile",
1695
1718
  targetKind: "business"
1696
1719
  },
1720
+ // Same read-effect authority as the manifest dry run: both are halves of
1721
+ // `farthershore validate`. (`business:docs_update` is the write permission
1722
+ // that toggles docs, not a check.)
1723
+ "business.docs.validate": {
1724
+ permission: "business:compile",
1725
+ targetKind: "business"
1726
+ },
1697
1727
  "business.delete": { permission: "business:delete", targetKind: "business" },
1698
1728
  "business.docs.disable": {
1699
1729
  permission: "business:docs_update",
@@ -2031,6 +2061,10 @@ var AGENT_OPERATION_AUTHORIZATIONS = {
2031
2061
  },
2032
2062
  "webhook.create": { permission: "webhook:create", targetKind: "business" },
2033
2063
  "webhook.delete": { permission: "webhook:delete", targetKind: "business" },
2064
+ "webhook.delivery.payload.read": {
2065
+ permission: "webhook:delivery_payload_read",
2066
+ targetKind: "business"
2067
+ },
2034
2068
  "webhook.delivery.read": {
2035
2069
  permission: "webhook:delivery_read",
2036
2070
  targetKind: "business"
@@ -2458,7 +2492,7 @@ var SPECS = {
2458
2492
  },
2459
2493
  "environment.create": {
2460
2494
  summary: "Create a preview environment bound to a git branch",
2461
- description: "Create a preview environment bound to a git branch. Provide a name and the git branch it tracks.",
2495
+ description: "Create a preview environment from its env/NAME branch. The environment name is derived from the branch; names are lowercase slugs of at most 63 characters.",
2462
2496
  destructive: false,
2463
2497
  oneTimeSecret: false,
2464
2498
  preview: false,
@@ -2615,10 +2649,12 @@ var SPECS = {
2615
2649
  // webhook list and delete it; deliveries need the id it never received.
2616
2650
  reconcile: { op: "webhook.read" }
2617
2651
  },
2618
- // DECISION: NEITHER side → destructive (+ oneTimeSecret, already declared). Rotation retires the previous signing secret (after its 24h dual-sign window) and returns the new one once.
2652
+ // DECISION: NEITHER side → destructive (+ oneTimeSecret, already declared).
2653
+ // Rotation returns a new secret once. Readable retired secrets get a 24h
2654
+ // dual-sign window; unreadable ones are dropped immediately.
2619
2655
  "webhook.rotate_secret": {
2620
- summary: "Issue a new signing secret (returned once); the old one keeps verifying for 24h",
2621
- description: "Issue a replacement signing secret for a webhook endpoint. Returns the new secret once; deliveries carry both signatures for 24 hours so the receiver can roll over without a gap.",
2656
+ summary: "Issue a new signing secret (returned once); readable old secrets verify for 24h",
2657
+ description: "Issue a replacement signing secret for a webhook endpoint. Returns the new secret once. When the old secret is readable, deliveries carry both signatures for 24 hours. Repairing an unreadable old secret drops it immediately and returns previousSecretExpiresAt: null; install the new secret before deliveries can verify.",
2622
2658
  destructive: true,
2623
2659
  oneTimeSecret: true,
2624
2660
  preview: false,
@@ -2631,9 +2667,16 @@ var SPECS = {
2631
2667
  oneTimeSecret: false,
2632
2668
  preview: false
2633
2669
  },
2670
+ "webhook.delivery.payload.read": {
2671
+ summary: "Read a webhook delivery payload and response",
2672
+ description: "Read the exact webhook event envelope and the last response diagnostic. Requires webhook:delivery_payload_read, available to owner and admin user sessions only. Response diagnostics are capped at 4096 characters; unreachable endpoints get a plain-language reason that never names a host or IP.",
2673
+ destructive: false,
2674
+ oneTimeSecret: false,
2675
+ preview: false
2676
+ },
2634
2677
  "webhook.delivery.read": {
2635
2678
  summary: "List recent delivery attempts for a webhook endpoint",
2636
- description: "List recent delivery attempts for a webhook endpoint. Payload and response body are intentionally omitted.",
2679
+ description: "List recent delivery attempts for a webhook endpoint. Lists omit payloads and response bodies. Single-delivery reads include them only with webhook:delivery_payload_read.",
2637
2680
  destructive: false,
2638
2681
  oneTimeSecret: false,
2639
2682
  preview: false,
@@ -2831,7 +2874,7 @@ var SPECS = {
2831
2874
  },
2832
2875
  "business_variable.read": {
2833
2876
  summary: "List variables: FS_PUBLIC_* values, secret metadata only",
2834
- description: "Lists variables. Returns readable FS_PUBLIC_* values; every other variable is a write-only secret and only its lifecycle metadata is returned.",
2877
+ description: "Lists variables. Returns readable FS_PUBLIC_* values; every other variable is a write-only secret and only its lifecycle metadata is returned. Each entry includes its business or environment scope and source environmentId.",
2835
2878
  destructive: false,
2836
2879
  oneTimeSecret: false,
2837
2880
  preview: false
@@ -3523,6 +3566,13 @@ var SPECS = {
3523
3566
  oneTimeSecret: false,
3524
3567
  preview: false
3525
3568
  },
3569
+ "business.docs.validate": {
3570
+ summary: "Check docs files the way a pull request's docs check does",
3571
+ description: "Runs the same docs check a pull request gets on the docs/ files sent, and returns the issues its Docs comment would show. Nothing is saved or published; a repeat returns a fresh result.",
3572
+ destructive: false,
3573
+ oneTimeSecret: false,
3574
+ preview: false
3575
+ },
3526
3576
  "manifest.apply": {
3527
3577
  summary: "Apply a compiled business manifest (git-triggered)",
3528
3578
  description: "The repo pipeline applies the compiled IR on a push/release through the same neutral apply service. `farthershore validate` runs the identical verdict locally WITHOUT applying; `farthershore apply-timeline list` shows what the platform applied.",
@@ -3684,6 +3734,7 @@ var ERROR_CODES = {
3684
3734
  ORGANIZATION_NOT_FOUND: "ORGANIZATION_NOT_FOUND",
3685
3735
  ORG_HAS_ACTIVE_SUBSCRIPTIONS: "ORG_HAS_ACTIVE_SUBSCRIPTIONS",
3686
3736
  ORGANIZATION_HAS_PAID_SUBSCRIBERS: "ORGANIZATION_HAS_PAID_SUBSCRIBERS",
3737
+ BILLING_AUTHORITY_RECONCILIATION_REQUIRED: "BILLING_AUTHORITY_RECONCILIATION_REQUIRED",
3687
3738
  BUSINESS_HAS_PAID_SUBSCRIBERS: "BUSINESS_HAS_PAID_SUBSCRIBERS",
3688
3739
  // PR-H: returned with HTTP 409 from DELETE /builder/organizations/:orgId
3689
3740
  // (and the defense-in-depth Clerk-deletion guard) when the org still has
@@ -3977,7 +4028,7 @@ var RUNTIME_ERROR_CODE_TO_ERROR_CODE = {
3977
4028
  var RUNTIME_ERROR_CODE_VALUES = Object.values(RUNTIME_ERROR_CODES);
3978
4029
  function paidSubscriberDeletionMessage(code) {
3979
4030
  if (code === ERROR_CODES.BUSINESS_HAS_PAID_SUBSCRIBERS) {
3980
- return "Cancel or migrate this business's paid subscribers before deleting it.";
4031
+ return "Cancel or migrate paid subscriptions and resolve remaining purchased or promotional credit, including credit held by archived customers, before deleting this business.";
3981
4032
  }
3982
4033
  if (code === ERROR_CODES.ORGANIZATION_HAS_PAID_SUBSCRIBERS) {
3983
4034
  return "Cancel or migrate the paid subscribers of every business in this organization before deleting it.";
@@ -3985,6 +4036,17 @@ function paidSubscriberDeletionMessage(code) {
3985
4036
  return void 0;
3986
4037
  }
3987
4038
 
4039
+ // ../contracts/dist/request-id.js
4040
+ var REQUEST_ID_HEADER = "x-request-id";
4041
+ var MAX_REQUEST_ID_LENGTH = 128;
4042
+ var REQUEST_ID_PATTERN = /^[A-Za-z0-9._:-]+$/;
4043
+ function isValidRequestId(value) {
4044
+ return typeof value === "string" && value.length > 0 && value.length <= MAX_REQUEST_ID_LENGTH && REQUEST_ID_PATTERN.test(value);
4045
+ }
4046
+ function adoptableRequestId(value) {
4047
+ return isValidRequestId(value) ? value : null;
4048
+ }
4049
+
3988
4050
  // src/errors.ts
3989
4051
  var FartherShoreError = class extends Error {
3990
4052
  constructor(message, status, extra) {
@@ -4000,6 +4062,7 @@ var FartherShoreError = class extends Error {
4000
4062
  this.retryable = extra?.retryable;
4001
4063
  this.retryDisposition = extra?.retryDisposition;
4002
4064
  this.outcomeUnknown = extra?.outcomeUnknown;
4065
+ this.requestId = adoptableRequestId(extra?.requestId) ?? adoptableRequestId(extra?.headers?.get?.(REQUEST_ID_HEADER)) ?? void 0;
4003
4066
  if (extra?.headers !== void 0)
4004
4067
  Object.defineProperty(this, "headers", {
4005
4068
  value: extra.headers,
@@ -4022,6 +4085,12 @@ var FartherShoreError = class extends Error {
4022
4085
  * the client never repeats such a write on its own.
4023
4086
  */
4024
4087
  outcomeUnknown;
4088
+ /**
4089
+ * The id the server logged the failed request under — quote it when
4090
+ * reporting the failure. From the error envelope, else a valid
4091
+ * `x-request-id` response header; absent when no answer arrived.
4092
+ */
4093
+ requestId;
4025
4094
  /** Plain data (no `cause`, no stack) — safe to serialize and log. */
4026
4095
  toJSON() {
4027
4096
  const json = {
@@ -4037,6 +4106,7 @@ var FartherShoreError = class extends Error {
4037
4106
  json.retryDisposition = this.retryDisposition;
4038
4107
  if (this.outcomeUnknown !== void 0)
4039
4108
  json.outcomeUnknown = this.outcomeUnknown;
4109
+ if (this.requestId !== void 0) json.requestId = this.requestId;
4040
4110
  return json;
4041
4111
  }
4042
4112
  };
@@ -4057,7 +4127,10 @@ var FartherShoreTransportError = class extends FartherShoreError {
4057
4127
 
4058
4128
  // src/operations/define.ts
4059
4129
  function operation(entry) {
4060
- return entry;
4130
+ return { ...entry, preview: false };
4131
+ }
4132
+ function previewOperation(entry) {
4133
+ return { ...entry, preview: true };
4061
4134
  }
4062
4135
  function seg(value) {
4063
4136
  return encodeURIComponent(value);
@@ -4393,11 +4466,11 @@ var backendOperations = {
4393
4466
  })
4394
4467
  )
4395
4468
  }),
4396
- "backends.create": operation({
4469
+ "backends.create": previewOperation({
4397
4470
  op: "backend.create",
4398
4471
  run: (ctx, { businessId, ...data }) => send(ctx, "POST", backends(businessId), data)
4399
4472
  }),
4400
- "backends.bind": operation({
4473
+ "backends.bind": previewOperation({
4401
4474
  op: "backend.bind",
4402
4475
  run: (ctx, { businessId, backend, ...data }) => send(ctx, "PATCH", `${backends(businessId)}/${seg(backend)}`, data)
4403
4476
  }),
@@ -4554,7 +4627,7 @@ var businessOperations = {
4554
4627
  withQuery(`${business(businessId)}/deployments`, { env })
4555
4628
  )
4556
4629
  }),
4557
- "businesses.publish": operation({
4630
+ "businesses.publish": previewOperation({
4558
4631
  op: "business.publish",
4559
4632
  run: (ctx, { businessId, ...body }) => send(
4560
4633
  ctx,
@@ -4584,6 +4657,19 @@ var businessOperations = {
4584
4657
  readOnly(ctx)
4585
4658
  )
4586
4659
  }),
4660
+ // Check docs files (`docs/_index.yaml` + MDX pages) the way the PR check
4661
+ // does, without publishing anything. Read-only, so it retries like a read.
4662
+ // `issues` lists errors first; notes after them carry a `severity`.
4663
+ "businesses.docs.validate": operation({
4664
+ op: "business.docs.validate",
4665
+ run: (ctx, { businessId, env, files }) => send(
4666
+ ctx,
4667
+ "POST",
4668
+ withQuery(`${business(businessId)}/docs/validate`, { env }),
4669
+ { files },
4670
+ readOnly(ctx)
4671
+ )
4672
+ }),
4587
4673
  "businesses.brand.update": patchBusiness("brand.update"),
4588
4674
  "businesses.brand.uploadAsset": operation({
4589
4675
  op: "brand.update",
@@ -4657,7 +4743,7 @@ var changeSetOperations = {
4657
4743
  return entry;
4658
4744
  }
4659
4745
  }),
4660
- "changeSets.propose": operation({
4746
+ "changeSets.propose": previewOperation({
4661
4747
  op: "change_set.propose",
4662
4748
  run: (ctx, { businessId, subscriberId, env, ...body }) => send(
4663
4749
  ctx,
@@ -4831,7 +4917,7 @@ var frontendOperations = {
4831
4917
  })
4832
4918
  )
4833
4919
  }),
4834
- "frontend.rollback": operation({
4920
+ "frontend.rollback": previewOperation({
4835
4921
  op: "frontend.rollback",
4836
4922
  run: (ctx, { businessId, ...data }) => send(
4837
4923
  ctx,
@@ -5518,6 +5604,14 @@ var webhookOperations = {
5518
5604
  "GET",
5519
5605
  `${webhook(businessId, webhookId)}/deliveries/${seg(deliveryId)}`
5520
5606
  )
5607
+ }),
5608
+ "webhooks.delivery.payload.read": operation({
5609
+ op: "webhook.delivery.payload.read",
5610
+ run: (ctx, { businessId, webhookId, deliveryId }) => send(
5611
+ ctx,
5612
+ "GET",
5613
+ `${webhook(businessId, webhookId)}/deliveries/${seg(deliveryId)}/payload`
5614
+ )
5521
5615
  })
5522
5616
  };
5523
5617
 
@@ -6079,6 +6173,7 @@ function errorEnvelopeOf(body) {
6079
6173
  if (typeof raw.retryable === "boolean") envelope.retryable = raw.retryable;
6080
6174
  if (raw.retryDisposition === "safe_to_repeat" || raw.retryDisposition === "reconcile_before_repeat")
6081
6175
  envelope.retryDisposition = raw.retryDisposition;
6176
+ if (typeof raw.requestId === "string") envelope.requestId = raw.requestId;
6082
6177
  return envelope;
6083
6178
  }
6084
6179
  function retrySignalOf(envelope) {
@@ -6104,7 +6199,7 @@ function diagnosticsOf(parsed) {
6104
6199
  }
6105
6200
 
6106
6201
  // src/version.ts
6107
- var CLIENT_VERSION = "0.2.0";
6202
+ var CLIENT_VERSION = "0.4.0";
6108
6203
  var CLIENT_PRODUCT = `@farthershore/client/${CLIENT_VERSION}`;
6109
6204
 
6110
6205
  // src/transport.ts
@@ -6197,7 +6292,8 @@ function outcomeUnknownError(status, envelope, fallbackMessage, parsed, headers)
6197
6292
  param: envelope?.param,
6198
6293
  retryable: false,
6199
6294
  retryDisposition: "reconcile_before_repeat",
6200
- outcomeUnknown: true
6295
+ outcomeUnknown: true,
6296
+ requestId: envelope?.requestId
6201
6297
  });
6202
6298
  }
6203
6299
  function requestAbortedError(cause) {
@@ -6349,7 +6445,8 @@ function httpError(res, policy, parsed) {
6349
6445
  // `diagnosticsOf` keeps the TOP-LEVEL sibling arrays readable too.
6350
6446
  details: envelope?.details ?? diagnosticsOf(parsed),
6351
6447
  retryable: envelope?.retryable,
6352
- retryDisposition: envelope?.retryDisposition
6448
+ retryDisposition: envelope?.retryDisposition,
6449
+ requestId: envelope?.requestId
6353
6450
  }
6354
6451
  );
6355
6452
  }
@@ -421,6 +421,14 @@ export interface FartherShoreApi {
421
421
  * Operation `business.docs.enable` · write · requires `business:docs_update` · reconcile an unknown outcome with `business.read`.
422
422
  */
423
423
  readonly enable: Method<"businesses.docs.enable">;
424
+ /**
425
+ * Check docs files the way a pull request's docs check does
426
+ *
427
+ * Runs the same docs check a pull request gets on the docs/ files sent, and returns the issues its Docs comment would show. Nothing is saved or published; a repeat returns a fresh result.
428
+ *
429
+ * Operation `business.docs.validate` · read · requires `business:compile`.
430
+ */
431
+ readonly validate: Method<"businesses.docs.validate">;
424
432
  };
425
433
  /**
426
434
  * List businesses in the current org
@@ -687,7 +695,7 @@ export interface FartherShoreApi {
687
695
  /**
688
696
  * Create a preview environment bound to a git branch
689
697
  *
690
- * Create a preview environment bound to a git branch. Provide a name and the git branch it tracks.
698
+ * Create a preview environment from its env/NAME branch. The environment name is derived from the branch; names are lowercase slugs of at most 63 characters.
691
699
  *
692
700
  * Operation `environment.create` · write · requires `environment:create` · reconcile an unknown outcome with `environment.read`.
693
701
  */
@@ -1255,7 +1263,7 @@ export interface FartherShoreApi {
1255
1263
  /**
1256
1264
  * List variables: FS_PUBLIC_* values, secret metadata only
1257
1265
  *
1258
- * Lists variables. Returns readable FS_PUBLIC_* values; every other variable is a write-only secret and only its lifecycle metadata is returned.
1266
+ * Lists variables. Returns readable FS_PUBLIC_* values; every other variable is a write-only secret and only its lifecycle metadata is returned. Each entry includes its business or environment scope and source environmentId.
1259
1267
  *
1260
1268
  * Operation `business_variable.read` · read · requires `business_variable:read`.
1261
1269
  */
@@ -1301,10 +1309,20 @@ export interface FartherShoreApi {
1301
1309
  * Operation `webhook.delivery.read` · read · requires `webhook:delivery_read`.
1302
1310
  */
1303
1311
  readonly get: Method<"webhooks.delivery.get">;
1312
+ readonly payload: {
1313
+ /**
1314
+ * Read a webhook delivery payload and response
1315
+ *
1316
+ * Read the exact webhook event envelope and the last response diagnostic. Requires webhook:delivery_payload_read, available to owner and admin user sessions only. Response diagnostics are capped at 4096 characters; unreachable endpoints get a plain-language reason that never names a host or IP.
1317
+ *
1318
+ * Operation `webhook.delivery.payload.read` · read · requires `webhook:delivery_payload_read`.
1319
+ */
1320
+ readonly read: Method<"webhooks.delivery.payload.read">;
1321
+ };
1304
1322
  /**
1305
1323
  * List recent delivery attempts for a webhook endpoint
1306
1324
  *
1307
- * List recent delivery attempts for a webhook endpoint. Payload and response body are intentionally omitted.
1325
+ * List recent delivery attempts for a webhook endpoint. Lists omit payloads and response bodies. Single-delivery reads include them only with webhook:delivery_payload_read.
1308
1326
  *
1309
1327
  * Operation `webhook.delivery.read` · read · requires `webhook:delivery_read` · offset pagination.
1310
1328
  */
@@ -1329,9 +1347,9 @@ export interface FartherShoreApi {
1329
1347
  */
1330
1348
  readonly read: Method<"webhooks.read">;
1331
1349
  /**
1332
- * Issue a new signing secret (returned once); the old one keeps verifying for 24h
1350
+ * Issue a new signing secret (returned once); readable old secrets verify for 24h
1333
1351
  *
1334
- * Issue a replacement signing secret for a webhook endpoint. Returns the new secret once; deliveries carry both signatures for 24 hours so the receiver can roll over without a gap.
1352
+ * Issue a replacement signing secret for a webhook endpoint. Returns the new secret once. When the old secret is readable, deliveries carry both signatures for 24 hours. Repairing an unreadable old secret drops it immediately and returns previousSecretExpiresAt: null; install the new secret before deliveries can verify.
1335
1353
  *
1336
1354
  * Operation `webhook.rotate_secret` · write · requires `webhook:update` · destructive · returns a one-time secret · reconcile an unknown outcome with `webhook.read`.
1337
1355
  */
@@ -14,6 +14,8 @@ export type ErrorEnvelope = {
14
14
  param?: string;
15
15
  retryable?: boolean;
16
16
  retryDisposition?: RetryDisposition;
17
+ /** The id the server logged the request under (a support reference). */
18
+ requestId?: string;
17
19
  };
18
20
  /** The server's retry verdict on a failed request. */
19
21
  export type RetrySignal = {
@@ -18,6 +18,11 @@ export type FartherShoreErrorOptions = {
18
18
  cause?: unknown;
19
19
  /** Response headers of the HTTP answer that failed, when one arrived. */
20
20
  headers?: Headers;
21
+ /**
22
+ * The id the server logged the failed request under (the envelope's
23
+ * `error.requestId`). Defaults to a valid `x-request-id` response header.
24
+ */
25
+ requestId?: string;
21
26
  };
22
27
  /** The plain-data form of a {@link FartherShoreError} (`toJSON()`). */
23
28
  export type FartherShoreErrorJSON = {
@@ -31,6 +36,8 @@ export type FartherShoreErrorJSON = {
31
36
  retryable?: boolean;
32
37
  retryDisposition?: RetryDisposition;
33
38
  outcomeUnknown?: boolean;
39
+ /** The server's reference for the failed request, when it gave one. */
40
+ requestId?: string;
34
41
  };
35
42
  /**
36
43
  * Every failure the client reports. Carries the canonical `code` from the
@@ -64,6 +71,12 @@ export declare class FartherShoreError extends Error {
64
71
  * so spreading or serializing an error never copies them.
65
72
  */
66
73
  readonly headers?: Headers;
74
+ /**
75
+ * The id the server logged the failed request under — quote it when
76
+ * reporting the failure. From the error envelope, else a valid
77
+ * `x-request-id` response header; absent when no answer arrived.
78
+ */
79
+ readonly requestId?: string;
67
80
  constructor(message: string, status?: number | undefined, extra?: FartherShoreErrorOptions);
68
81
  /** Plain data (no `cause`, no stack) — safe to serialize and log. */
69
82
  toJSON(): FartherShoreErrorJSON;