@farthershore/client 0.1.0 → 0.3.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 +172 -0
  2. package/README.md +9 -8
  3. package/dist/index.js +105 -54
  4. package/dist/types/api.generated.d.ts +21 -7
  5. package/dist/types/generated/schemas.d.ts +3683 -0
  6. package/dist/types/helpers/wait-for-frontend-build.d.ts +12 -4
  7. package/dist/types/index.d.ts +2 -2
  8. package/dist/types/operations/agents.d.ts +204 -12
  9. package/dist/types/operations/agreements.d.ts +139 -9
  10. package/dist/types/operations/analytics.d.ts +27 -5
  11. package/dist/types/operations/audit-notifications.d.ts +64 -7
  12. package/dist/types/operations/auth.d.ts +12 -4
  13. package/dist/types/operations/backends.d.ts +211 -9
  14. package/dist/types/operations/billing.d.ts +60 -4
  15. package/dist/types/operations/businesses.d.ts +744 -27
  16. package/dist/types/operations/change-sets.d.ts +426 -7
  17. package/dist/types/operations/consumers.d.ts +133 -14
  18. package/dist/types/operations/define.d.ts +16 -5
  19. package/dist/types/operations/environments.d.ts +40 -4
  20. package/dist/types/operations/frontend.d.ts +20 -2
  21. package/dist/types/operations/index.d.ts +3941 -193
  22. package/dist/types/operations/maker-tokens.d.ts +175 -11
  23. package/dist/types/operations/organizations.d.ts +321 -19
  24. package/dist/types/operations/personas.d.ts +98 -8
  25. package/dist/types/operations/plans-usage.d.ts +69 -3
  26. package/dist/types/operations/platform.d.ts +420 -12
  27. package/dist/types/operations/portal.d.ts +409 -16
  28. package/dist/types/operations/promo-codes.d.ts +126 -6
  29. package/dist/types/operations/variables.d.ts +170 -7
  30. package/dist/types/operations/webhooks.d.ts +77 -14
  31. package/dist/types/surface-types.d.ts +25 -3
  32. package/dist/types/transport.d.ts +5 -10
  33. package/dist/types/types.d.ts +385 -411
  34. package/dist/types/version.d.ts +2 -2
  35. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -4,6 +4,178 @@ 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.3.0] - 2026-10-14
8
+
9
+ ### Added
10
+
11
+ - `businesses.docs.validate({ businessId, env?, files })` checks docs files
12
+ (`docs/_index.yaml` and MDX pages) the way the pull request check does,
13
+ without publishing anything. It retries like a read and returns
14
+ `DocsValidateResponse` (`issues`, errors first, then notes with a
15
+ `severity`). New exported type: `DocsValidateResponse`.
16
+
17
+ ## [0.2.0] - 2026-10-14
18
+
19
+ ### Changed
20
+
21
+ - **Breaking:** the last untyped `businesses.*` methods are typed from the zod
22
+ schemas in `@farthershore/contracts/business-contract-response`; no method
23
+ output is `unknown`, a loose record or an index signature any more.
24
+ `routes.read` → `BusinessRouteList` (one row per route, no compiled row
25
+ `id`), `contract.read` → `BusinessContract` (limits and meters typed),
26
+ `config.read` → `BusinessConfig` (`state: accepted | none | unreadable`,
27
+ the contract as `AcceptedBusinessContract` without an upstream credential's
28
+ token; no `ok`, contract hash or raw sync error; `githubSha` → `commitSha`,
29
+ `githubSyncStatus` → `repositorySyncStatus`), `configAttempts.read` →
30
+ `BusinessConfigAttemptList` (no raw proposal or payload), `status` →
31
+ `BusinessStatusResult` (runs report `publishStatus` / `billingStatus`;
32
+ applies' phases are `publish` / `billing`; `edgeCoherence` is replaced by
33
+ `serving: { status, coherent, message }`), `compile` →
34
+ `BusinessValidateResult` (was `ManifestCompileResult`; no record id, IR or
35
+ spec hash), `rbac.subjects.read` → `CustomPermissionSubjectList`,
36
+ `rbac.enable`/`disable` → `BusinessRbacUpdateResult`, `brand.uploadAsset` →
37
+ `BrandAssetUploadResult`, `subdomainAvailability.read` →
38
+ `ManagedSubdomainAvailability`. `PaginatedResult` and
39
+ `ManifestCompileDiagnostic` are removed (`BusinessDiagnostic`).
40
+ - **Breaking:** portal service-account / usage-limit and caller-identity
41
+ responses are typed from the zod schemas in
42
+ `@farthershore/contracts/{portal,auth}-response`. Every `portal.*` method
43
+ returns a real type instead of `unknown` (`PortalServiceAccountList`,
44
+ `PortalServiceAccountCreateResult`, …, `PortalUsageLimit(List)`,
45
+ `PortalUsageLimitDeleteResult`); `auth.context.issue` returns
46
+ `ContextTokenIssuance`. `MakerTokenContext` no longer carries `authVersion`;
47
+ `BuilderBootstrapContext` is the closed bootstrap (no `user.clerkUserId`,
48
+ organizations named by `{ id, type, name, slug }`).
49
+ - **Breaking:** operating-agent, bulletin, automation-rule, Knowledge Registry
50
+ and platform-operation responses are typed from the zod schemas in
51
+ `@farthershore/contracts/{agent,automation-rule,knowledge,platform-ops}-response`.
52
+ `AgentSummary`, `AgentStatus`, `AgentRunSummary` and `BulletinPost` are
53
+ closed (agent `config` is the closed `AgentConfig`); `agents.runs.show`
54
+ returns `AgentRunDetail` (was `Record<string, unknown>`); `automationRules.*`,
55
+ `knowledge.*.read`, `platform.resourceCounts.report`, `platform.denials.read`,
56
+ `platform.dependents.read` and `platform.workflowControl.{replay,rollback}`
57
+ return `AutomationRule(List)`, `KnowledgeIndex`, `ResourceCountReport`,
58
+ `DenialExplanation`, `BusinessDependents`, `ReplayResult` and
59
+ `ConfigRollbackPreview` instead of `unknown`. A run's `errorMessage` is a
60
+ fixed description of its `errorCode`; a run detail drops `traceRef` and
61
+ renames `resultJson` / `traceJson` to `result` / `trace`; an action receipt
62
+ carries `summary` / `reason` instead of its stored result. A config rollback
63
+ preview reports `currentCommitSha` (was `currentGithubSha`).
64
+ - **Breaking:** analytics, usage, plan-list and billing-connection responses
65
+ are typed from `@farthershore/contracts/{analytics,usage,billing}-response`.
66
+ `analytics.timeseries` / `latency` / `top` / `log` return their verb's
67
+ `{ result }` (`AnalyticsTimeseriesResult`, `AnalyticsPercentilesResult`,
68
+ `AnalyticsTopKResult`, `AnalyticsEventFeedResult`; `analytics.query` returns
69
+ `AnalyticsQueryResult`); `plans.read` returns `PlanList`, `usage.read`
70
+ `UsageSummary`, `usage.limits` `ManagementUsageLimitList`,
71
+ `billing.stripe.read` `StripeConnectionStatus`, `billing.stripe.delete`
72
+ `StripeDisconnectResult`, and `billing.taxSettings.read` / `update`
73
+ `TaxSettings` (all were `unknown`). Event-feed rows carry `request` instead
74
+ of the archived `payload`; the usage summary's `activeRuntimeKeys` is
75
+ `activeApiKeys`; usage limits name `plan: { key, version }` instead of
76
+ subscription and plan-version ids; the Stripe status has no account id.
77
+ - **Breaking:** variables, frontend, audit-log and notification-preference
78
+ responses are typed from the zod schemas in
79
+ `@farthershore/contracts/variable-response`, `frontend-response`,
80
+ `audit-log-response` and `communication`. `frontend.status` returns
81
+ `FrontendStatusResult`, `frontend.rollback` `FrontendRollbackResult` (a
82
+ preview `FrontendRollbackPreview`), `auditLogs.read` /
83
+ `auditLogs.business.read` `AuditLogPage`, and
84
+ `notifications.preferences.*` `NotificationPreferences`, instead of
85
+ `unknown`. `BusinessVariableRow` and `SecretMutationOperation` are generated
86
+ and closed: an operation drops `mutationId`, `state` and `result`, and its
87
+ `impact` is `{ integrations, subscriberCount }`; `generation` is `version`
88
+ on both. Frontend status renames
89
+ `activeReleaseHash` to `activeReleaseId` and a build's `manifestHash` to
90
+ `releaseId`.
91
+ - **Breaking:** `waitForFrontendBuild` reads the typed status (no `data`
92
+ envelope fallback); `BuildWaitResult.status` is the build status union (or
93
+ `UNKNOWN`). `readBuildDiagnostics` is removed: a build's `diagnostics` are
94
+ already typed.
95
+
96
+ - **Breaking:** agreement, promo-code and test-persona responses are typed from
97
+ the zod schemas in `@farthershore/contracts/{agreement,promo-code,persona}-response`.
98
+ `EconomicAgreement`, `SubjectPins` and `PromoCode` are closed; `AgreementPreview`
99
+ splits into `AgreementCreatePreview` / `AgreementAmendPreview` (typed effects);
100
+ `agreements.read` returns `EconomicAgreementList`; `personas.bootstrap`,
101
+ `personas.read`, `personas.rotate` and `personas.delete` return
102
+ `TestPersonaBootstrapResult`, `TestPersonaList`, `TestPersonaRotateResult` and
103
+ `TestPersonaDeleteResult` instead of `unknown`. `personas.bootstrap` no longer
104
+ takes `compiledPlanId` (pass `planKey`).
105
+ - **Breaking:** change set and Apply Timeline responses are typed from the zod
106
+ schemas in `@farthershore/contracts/change-set-response`.
107
+ `changeSets.propose` / `preview` / `proposalRead` return `ChangeSet`,
108
+ `proposalList` returns `ChangeSetList` (all were `unknown`), and a
109
+ `propose(…, { dryRun: true })` preview is typed `ChangeSetProposePreview`.
110
+ `ApplyTimelineEntry` / `ApplyTimelineEntryList` are closed and generated (the
111
+ list carries `environmentId`; apply phases are `publish` and `billing`).
112
+ - **Breaking:** organization and maker-token responses are typed from the zod
113
+ schemas in `@farthershore/contracts/organization-response` and
114
+ `maker-token-response`. Every `organizations.*` and `makerTokens.*` method
115
+ returns a real type instead of `unknown` (`OrganizationList`,
116
+ `OrganizationMembers`, `OrganizationRoleList`, `OrganizationOverview`,
117
+ `OrganizationBulletin`, `MakerTokenList`, `OrgMakerTokenCreateResult`,
118
+ `MakerTokenRotation`, …). `organizations.invitation.create` no longer
119
+ returns the accept token (it goes to the invitee by email only), so its
120
+ `meta.oneTimeSecret` is now `false` (code mode no longer gates or redacts it);
121
+ `makerTokens.create` takes a typed `businessScope`.
122
+ - **Breaking:** environment responses are typed from the zod schemas in
123
+ `@farthershore/contracts/environment-response`. `EnvironmentSummary` and
124
+ `EnvironmentListResult` are closed (no index signature; `branch` is always a
125
+ string), and `environments.create` returns the new `EnvironmentCreateResult`
126
+ (the environment plus `created` and `branchCreated`) instead of `unknown`.
127
+ - **Breaking:** business responses are typed from the zod schema in
128
+ `@farthershore/contracts` (generated into `src/generated/schemas.ts`).
129
+ `BusinessSummary` is closed (no index signature) and lists exactly what the
130
+ server sends; `businesses.read` / `businesses.rbac.read` return the new
131
+ `BusinessDetail` (with `environments`), `businesses.create` returns
132
+ `BusinessCreateResult` instead of `unknown`, and `businesses.publish` returns
133
+ `PublishBusinessResult` (a `{ dryRun: true }` call resolves to
134
+ `DryRunPreview<PublishBusinessResult>`, also exported as
135
+ `PublishBusinessPreview`). `PublishRelease` is derived from the same schema.
136
+ Each business plan carries `featured`.
137
+ - **Breaking:** backend and runtime-token responses are typed from the zod
138
+ schemas in `@farthershore/contracts/backend-response`. `backends.read` returns
139
+ `BackendList`, `backends.create` returns `BackendCreateResult` (a preview
140
+ resolves to `DryRunPreview<BackendCreatePreview>`), `backends.bind` returns
141
+ `BackendSummary`, `backends.delete` returns
142
+ `BackendDeleteResult`, `runtimeTokens.read` returns `RuntimeTokenList`, and
143
+ `runtimeTokens.mint` / `runtimeTokens.rotate` return `RuntimeTokenIssuance`
144
+ (the one-time plaintext `token`). `RuntimeTokenSummary` is generated from the
145
+ same schema. A backend's lifecycle is one `status` field; `agentStatus`,
146
+ `provisionStatus`, `readinessState` and `originHostname` are gone.
147
+ - **Breaking:** webhook responses are typed from the zod schemas in
148
+ `@farthershore/contracts/webhook-response`. `webhooks.read` returns
149
+ `WebhookEndpointList`, `webhooks.create` returns
150
+ `WebhookEndpointCreateResult` (the one-time signing `secret`),
151
+ `webhooks.update` returns `WebhookEndpointUpdateResult`,
152
+ `webhooks.rotateSecret` returns `WebhookEndpointRotateSecretResult` (the new
153
+ one-time `secret` plus `previousSecretExpiresAt`), `webhooks.delete` returns
154
+ `WebhookEndpointDeleteResult`, `webhooks.delivery.read` returns
155
+ `WebhookDeliveryList`, and `webhooks.eventType.read` returns
156
+ `WebhookEventTypeList`. `WebhookEndpoint`, `WebhookDelivery` and
157
+ `WebhookTestResult` are closed and generated from the same schemas; a
158
+ listed or updated endpoint has no `secret` field. A delivery's `status` is
159
+ `pending`, `success`, `failed` or `dead`; a test result always carries
160
+ `status`, `deliveryId`, `responseBody` and `error` (null when absent).
161
+ - New `webhooks.delivery.get({ businessId, webhookId, deliveryId })` returns
162
+ `WebhookDeliveryResult`: one delivery's metadata, the same fields as the
163
+ list. Neither the event payload nor the endpoint's response body is
164
+ returned (both can carry subscriber PII; no permission gates them yet).
165
+ - **Breaking:** consumer responses are typed from the zod schemas in
166
+ `@farthershore/contracts/consumer-response`. `consumers.read` returns
167
+ `BusinessConsumerList`, `consumers.migrateLatest` returns
168
+ `ConsumerMigrateLatestResult` (was `unknown`), `consumers.role.list` returns
169
+ `ConsumerRbacRoleList` and `consumers.apiKeys.list` returns
170
+ `ConsumerApiKeyList`; the other consumer types are generated from the same
171
+ schemas and closed. A member carries `accountRole` only (the stored `role`
172
+ enum is gone, also from `consumers.roles.assign`, which drops the membership
173
+ `id`). Migrate-latest answers `{ migrated, subscriberId, reason? }` with no
174
+ plan-version or subscription ids. `ConsumerRbacSettingsResult.defaultRoleKey`
175
+ is always present (null when unset).
176
+ - `operation<I, O, W>` takes an optional third type, the preview's `wouldHave`
177
+ when it differs from the output; `DryRunPreview<W>` uses it.
178
+
7
179
  ## [0.1.0] - 2026-10-12
8
180
 
9
181
  ### Added
package/README.md CHANGED
@@ -1,13 +1,14 @@
1
1
  # @farthershore/client
2
2
 
3
- The Farther Shore API client that the `farthershore` CLI and its MCP server
4
- run on: a namespaced, typed operation surface (`fs.runtimeTokens.revoke(…)`)
5
- over an authenticated `fetch` transport with exact retry and outcome
6
- semantics, pluggable credential sources, and typed errors.
7
-
8
- > **Status: `0.1.0`.** Pre-1.0: minor releases may include breaking changes.
9
- > Responses keep today's hand-written types; where none exists yet a method
10
- > returns `unknown`. Runtime schemas follow domain by domain.
3
+ The Farther Shore API client that the `farthershore` CLI runs on: a
4
+ namespaced, typed operation surface (`fs.runtimeTokens.revoke(…)`) over an
5
+ authenticated `fetch` transport with exact retry and outcome semantics,
6
+ pluggable credential sources, and typed errors.
7
+
8
+ > **Status: `0.3.0`.** Pre-1.0: minor releases may include breaking changes.
9
+ > Every response is typed. All but the publish-rollback receipt are generated
10
+ > from the platform's zod schemas (through the API's OpenAPI components), so a
11
+ > field exists in a type exactly when the server sends it.
11
12
 
12
13
  ```sh
13
14
  npm install @farthershore/client
package/dist/index.js CHANGED
@@ -1422,6 +1422,18 @@ var PLATFORM_OPERATION_DEFINITIONS = [
1422
1422
  detail: "Use `farthershore validate --business <business>`; it builds deterministically and calls this manifest-compile endpoint for the server verdict."
1423
1423
  }
1424
1424
  },
1425
+ {
1426
+ key: "business.docs.validate",
1427
+ class: "operate",
1428
+ domain: "businesses",
1429
+ // Runs the PR bot's docs check on files sent in the request and returns
1430
+ // its issues. Stores nothing; a repeat is a fresh observation.
1431
+ sideEffect: "read",
1432
+ unavailable: {
1433
+ reason: "served_by_other_command",
1434
+ detail: "Use `farthershore validate --business <business>`; it sends your docs/ files and shows the same issues a pull request's Docs comment would."
1435
+ }
1436
+ },
1425
1437
  { key: "business.read", class: "operate", domain: "businesses" },
1426
1438
  { key: "business.routes.read", class: "contract", domain: "businesses" },
1427
1439
  { key: "business.contract.read", class: "contract", domain: "businesses" },
@@ -1694,6 +1706,13 @@ var AGENT_OPERATION_AUTHORIZATIONS = {
1694
1706
  permission: "business:compile",
1695
1707
  targetKind: "business"
1696
1708
  },
1709
+ // Same read-effect authority as the manifest dry run: both are halves of
1710
+ // `farthershore validate`. (`business:docs_update` is the write permission
1711
+ // that toggles docs, not a check.)
1712
+ "business.docs.validate": {
1713
+ permission: "business:compile",
1714
+ targetKind: "business"
1715
+ },
1697
1716
  "business.delete": { permission: "business:delete", targetKind: "business" },
1698
1717
  "business.docs.disable": {
1699
1718
  permission: "business:docs_update",
@@ -2539,7 +2558,7 @@ var SPECS = {
2539
2558
  },
2540
2559
  "frontend.status": {
2541
2560
  summary: "Show the current frontend release, recent releases, and recent builds (incl. failure reasons)",
2542
- description: "Read a business's current frontend serve state (uiMode, active release hash + producing build, pin flag), the recent SUCCEEDED releases (rollback targets), and the recent builds \u2014 a FAILED build's `error` explains why a deploy didn't go live. Read-only.",
2561
+ description: "Read a business's current frontend serve state (uiMode, active release id + producing build, pin flag), the recent SUCCEEDED releases (rollback targets), and the recent builds \u2014 a FAILED build's `error` explains why a deploy didn't go live. Read-only.",
2543
2562
  destructive: false,
2544
2563
  oneTimeSecret: false,
2545
2564
  preview: false
@@ -2547,7 +2566,7 @@ var SPECS = {
2547
2566
  // DECISION: NEITHER side → destructive. Rollbacks are destructive: they re-activate an older frontend release for every visitor.
2548
2567
  "frontend.rollback": {
2549
2568
  summary: "Roll the business frontend back to a prior release (re-activate its releaseId)",
2550
- description: "Roll a business's frontend back to a prior release by its releaseId (manifest hash, from fs_frontend_status). Flips the live pointer back and pins it. The releaseId must belong to this target's build history.",
2569
+ description: "Roll a business's frontend back to a prior release by its releaseId (from fs_frontend_status). Flips the live pointer back and pins it. The releaseId must belong to this target's build history.",
2551
2570
  destructive: true,
2552
2571
  oneTimeSecret: false,
2553
2572
  preview: true,
@@ -2906,7 +2925,7 @@ var SPECS = {
2906
2925
  },
2907
2926
  "usage.read": {
2908
2927
  summary: "Show usage summary for the last 30 days",
2909
- description: "Read a business's usage summary \u2014 metered request counts and tier utilization. Without environmentId this rolls up EVERY environment. Read-only.",
2928
+ description: "Read a business's usage summary \u2014 request counts (all time and the last 30 days), active API keys, a per-member breakdown, and served requests that can never be rated. Without environmentId this rolls up EVERY environment. Read-only.",
2910
2929
  destructive: false,
2911
2930
  oneTimeSecret: false,
2912
2931
  preview: false,
@@ -2980,7 +2999,7 @@ var SPECS = {
2980
2999
  },
2981
3000
  "analytics.log": {
2982
3001
  summary: "Recent requests \u2014 the live metering signal, newest first",
2983
- description: "The most recent archived events for one business, newest first. Each row's `payload` carries the request detail (path, statusCode, latencyMs, orgId). Read-only.",
3002
+ description: "The most recent archived events for one business, newest first. Each request row's `request` carries the path, status code, subscriber, deny code and final response timing (gateway and backend milliseconds). Read-only.",
2984
3003
  destructive: false,
2985
3004
  oneTimeSecret: false,
2986
3005
  preview: false
@@ -3050,9 +3069,9 @@ var SPECS = {
3050
3069
  // exactly once; invitation reads never return it.
3051
3070
  "organization.invitation.create": {
3052
3071
  summary: "Invite a member to an organization",
3053
- description: "Invite a member to an organization. Returns the raw invitation token once; invitation listings never show it.",
3072
+ description: "Invite a member to an organization. The invitee receives the accept link by email; no response or listing ever carries the invitation token.",
3054
3073
  destructive: false,
3055
- oneTimeSecret: true,
3074
+ oneTimeSecret: false,
3056
3075
  preview: false,
3057
3076
  reconcile: { op: "organization.invitation.list_sent" }
3058
3077
  },
@@ -3209,7 +3228,7 @@ var SPECS = {
3209
3228
  },
3210
3229
  "stripe_connection.read": {
3211
3230
  summary: "Show the Stripe connection a business bills through (business override or org default)",
3212
- description: "Read the Stripe Connect account a business bills through \u2014 a per-business override when present, otherwise the organization default \u2014 including onboarding and tax-enrollment state. Read-only. Connecting Stripe is browser-only and has no tool.",
3231
+ description: "Read whether a business bills through a connected Stripe account \u2014 a per-business override when present, otherwise the organization default \u2014 and whether that account can take charges and card payments. Read-only. Connecting Stripe is browser-only and has no tool.",
3213
3232
  destructive: false,
3214
3233
  oneTimeSecret: false,
3215
3234
  preview: false
@@ -3523,6 +3542,13 @@ var SPECS = {
3523
3542
  oneTimeSecret: false,
3524
3543
  preview: false
3525
3544
  },
3545
+ "business.docs.validate": {
3546
+ summary: "Check docs files the way a pull request's docs check does",
3547
+ 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.",
3548
+ destructive: false,
3549
+ oneTimeSecret: false,
3550
+ preview: false
3551
+ },
3526
3552
  "manifest.apply": {
3527
3553
  summary: "Apply a compiled business manifest (git-triggered)",
3528
3554
  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.",
@@ -3884,6 +3910,11 @@ var ERROR_CODES = {
3884
3910
  // SSRF -- an attacker's endpoint could 302 to 169.254.169.254 and
3885
3911
  // bypass the runtime DNS check that runs before the initial fetch.
3886
3912
  WEBHOOK_REDIRECTED: "WEBHOOK_REDIRECTED",
3913
+ // A webhook create/update URL refused by the SSRF guard. ONE code and ONE
3914
+ // message for every refusal reason: telling "did not resolve" apart from
3915
+ // "resolves to a private address" (or echoing the address) would let a
3916
+ // caller map Core's internal network through the guard.
3917
+ WEBHOOK_URL_NOT_ALLOWED: "WEBHOOK_URL_NOT_ALLOWED",
3887
3918
  // Business-as-code (A5): contractual product state (plans / pricing /
3888
3919
  // gateway config / meters) is managed in the product's repo; core write
3889
3920
  // routes for it 409 once the product leaves its DRAFT creation window.
@@ -4222,8 +4253,14 @@ var verb = (op, name) => operation({
4222
4253
  run: (ctx, { businessId, query }) => runQuery(ctx, businessId, { verb: name, query })
4223
4254
  });
4224
4255
  var analyticsOperations = {
4225
- "analytics.timeseries": verb("analytics.timeseries", "timeseries"),
4226
- "analytics.latency": verb("analytics.latency", "percentiles"),
4256
+ "analytics.timeseries": verb(
4257
+ "analytics.timeseries",
4258
+ "timeseries"
4259
+ ),
4260
+ "analytics.latency": verb(
4261
+ "analytics.latency",
4262
+ "percentiles"
4263
+ ),
4227
4264
  "analytics.top": verb("analytics.top", "topK"),
4228
4265
  "analytics.log": verb("analytics.log", "eventFeed"),
4229
4266
  "analytics.query": operation({
@@ -4410,16 +4447,10 @@ var backendOperations = {
4410
4447
  op: "runtime_token.mint",
4411
4448
  run: (ctx, { businessId, ...data }) => send(ctx, "POST", runtimeTokens(businessId), data)
4412
4449
  }),
4413
- "runtimeTokens.rotate": operation(
4414
- {
4415
- op: "runtime_token.rotate",
4416
- run: (ctx, { businessId, tokenId }) => send(
4417
- ctx,
4418
- "POST",
4419
- `${runtimeTokens(businessId)}/${seg(tokenId)}/rotate`
4420
- )
4421
- }
4422
- ),
4450
+ "runtimeTokens.rotate": operation({
4451
+ op: "runtime_token.rotate",
4452
+ run: (ctx, { businessId, tokenId }) => send(ctx, "POST", `${runtimeTokens(businessId)}/${seg(tokenId)}/rotate`)
4453
+ }),
4423
4454
  "runtimeTokens.revoke": operation({
4424
4455
  op: "runtime_token.revoke",
4425
4456
  run: (ctx, { businessId, tokenId }) => send(ctx, "DELETE", `${runtimeTokens(businessId)}/${seg(tokenId)}`)
@@ -4430,13 +4461,22 @@ var backendOperations = {
4430
4461
  var billingOperations = {
4431
4462
  "billing.stripe.read": operation({
4432
4463
  op: "stripe_connection.read",
4433
- run: (ctx, { businessId }) => send(ctx, "GET", `/businesses/${seg(businessId)}/stripe/status`)
4464
+ run: (ctx, { businessId }) => send(
4465
+ ctx,
4466
+ "GET",
4467
+ `/businesses/${seg(businessId)}/stripe/status`
4468
+ )
4434
4469
  }),
4435
4470
  "billing.stripe.delete": operation({
4436
4471
  op: "stripe_connection.delete",
4437
- run: (ctx, { businessId, deleteAccount }) => send(ctx, "POST", `/businesses/${seg(businessId)}/stripe/disconnect`, {
4438
- deleteAccount: deleteAccount === true
4439
- })
4472
+ run: (ctx, { businessId, deleteAccount }) => send(
4473
+ ctx,
4474
+ "POST",
4475
+ `/businesses/${seg(businessId)}/stripe/disconnect`,
4476
+ {
4477
+ deleteAccount: deleteAccount === true
4478
+ }
4479
+ )
4440
4480
  }),
4441
4481
  "billing.taxSettings.read": operation({
4442
4482
  op: "tax_settings.read",
@@ -4570,6 +4610,19 @@ var businessOperations = {
4570
4610
  readOnly(ctx)
4571
4611
  )
4572
4612
  }),
4613
+ // Check docs files (`docs/_index.yaml` + MDX pages) the way the PR check
4614
+ // does, without publishing anything. Read-only, so it retries like a read.
4615
+ // `issues` lists errors first; notes after them carry a `severity`.
4616
+ "businesses.docs.validate": operation({
4617
+ op: "business.docs.validate",
4618
+ run: (ctx, { businessId, env, files }) => send(
4619
+ ctx,
4620
+ "POST",
4621
+ withQuery(`${business(businessId)}/docs/validate`, { env }),
4622
+ { files },
4623
+ readOnly(ctx)
4624
+ )
4625
+ }),
4573
4626
  "businesses.brand.update": patchBusiness("brand.update"),
4574
4627
  "businesses.brand.uploadAsset": operation({
4575
4628
  op: "brand.update",
@@ -4797,6 +4850,7 @@ var environmentOperations = {
4797
4850
  op: "environment.create",
4798
4851
  run: (ctx, { businessId, ...data }) => send(ctx, "POST", environments(businessId), data)
4799
4852
  }),
4853
+ /** Resolves with no body; an environment already gone also resolves. */
4800
4854
  "environments.delete": operation({
4801
4855
  op: "environment.delete",
4802
4856
  run: (ctx, { businessId, environment }) => send(ctx, "DELETE", `${environments(businessId)}/${seg(environment)}`)
@@ -5493,6 +5547,16 @@ var webhookOperations = {
5493
5547
  offset: num(offset)
5494
5548
  })
5495
5549
  )
5550
+ }),
5551
+ "webhooks.delivery.get": operation({
5552
+ op: "webhook.delivery.read",
5553
+ summary: "Show one delivery attempt for a webhook endpoint",
5554
+ pagination: null,
5555
+ run: (ctx, { businessId, webhookId, deliveryId }) => send(
5556
+ ctx,
5557
+ "GET",
5558
+ `${webhook(businessId, webhookId)}/deliveries/${seg(deliveryId)}`
5559
+ )
5496
5560
  })
5497
5561
  };
5498
5562
 
@@ -5963,23 +6027,8 @@ async function poll(options) {
5963
6027
  }
5964
6028
 
5965
6029
  // src/helpers/wait-for-frontend-build.ts
5966
- var SUCCESS = /* @__PURE__ */ new Set(["SUCCEEDED", "SUCCESS"]);
5967
- var FAILURE = /* @__PURE__ */ new Set(["FAILED", "ERROR", "CANCELLED", "TIMED_OUT"]);
6030
+ var FAILURE = /* @__PURE__ */ new Set(["FAILED", "CANCELLED"]);
5968
6031
  var SUPERSEDED = "SUPERSEDED";
5969
- function readBuilds(payload) {
5970
- const data = payload?.data ?? payload;
5971
- const builds = data?.builds;
5972
- return Array.isArray(builds) ? builds : [];
5973
- }
5974
- function readServingStatus(payload) {
5975
- const data = payload?.data ?? payload;
5976
- const status = data?.status;
5977
- return {
5978
- activeBuildId: str(status?.activeBuildId),
5979
- uiMode: str(status?.uiMode)
5980
- };
5981
- }
5982
- var str = (v) => typeof v === "string" ? v : null;
5983
6032
  async function waitForFrontendBuild(source, input) {
5984
6033
  const intervalMs = input.intervalMs ?? 5e3;
5985
6034
  const sleep = input.sleep ?? sleepFor;
@@ -5992,6 +6041,7 @@ async function waitForFrontendBuild(source, input) {
5992
6041
  buildId: input.buildId ?? null,
5993
6042
  ref: null,
5994
6043
  error: null,
6044
+ diagnostics: [],
5995
6045
  activated: false,
5996
6046
  activeBuildId: null,
5997
6047
  timedOut: false
@@ -6009,39 +6059,40 @@ async function waitForFrontendBuild(source, input) {
6009
6059
  },
6010
6060
  signal ? { signal } : void 0
6011
6061
  );
6012
- const builds = readBuilds(payload).filter(
6013
- (build) => input.ref === void 0 || str(build.ref) === input.ref
6062
+ const builds = payload.builds.filter(
6063
+ (build) => input.ref === void 0 || build.ref === input.ref
6014
6064
  );
6015
- const serving = readServingStatus(payload);
6065
+ const serving = payload.status;
6016
6066
  const firstUnpinnedPoll = !baselined;
6017
6067
  if (firstUnpinnedPoll) {
6018
6068
  baselined = true;
6019
6069
  for (const build of builds) {
6020
- unpinnedBaselineIds.add(str(build.id));
6070
+ unpinnedBaselineIds.add(build.id);
6021
6071
  }
6022
6072
  }
6023
- const eligibleBuilds = input.buildId == null && input.ref === void 0 ? builds.filter((build) => !unpinnedBaselineIds.has(str(build.id))) : builds;
6024
- const row = (followId ? builds.find((b) => str(b.id) === followId) : void 0) ?? eligibleBuilds[0];
6073
+ const eligibleBuilds = input.buildId == null && input.ref === void 0 ? builds.filter((build) => !unpinnedBaselineIds.has(build.id)) : builds;
6074
+ const row = (followId ? builds.find((b) => b.id === followId) : void 0) ?? eligibleBuilds[0];
6025
6075
  if (row) {
6026
- const status = str(row.status) ?? "UNKNOWN";
6027
- const rowId = str(row.id);
6076
+ const status = row.status;
6077
+ const rowId = row.id;
6028
6078
  last = {
6029
6079
  status,
6030
6080
  buildId: rowId,
6031
- ref: str(row.ref),
6032
- error: str(row.error),
6081
+ ref: row.ref,
6082
+ error: row.error,
6083
+ diagnostics: row.diagnostics,
6033
6084
  activated: serving.uiMode === "custom-react" && serving.activeBuildId !== null && serving.activeBuildId === rowId,
6034
6085
  activeBuildId: serving.activeBuildId,
6035
6086
  timedOut: false
6036
6087
  };
6037
- if (followId === null && rowId !== null) followId = rowId;
6088
+ if (followId === null) followId = rowId;
6038
6089
  if (FAILURE.has(status)) return last;
6039
- if (SUCCESS.has(status) && last.activated) return last;
6090
+ if (status === "SUCCEEDED" && last.activated) return last;
6040
6091
  if (status === SUPERSEDED) {
6041
6092
  const successor = eligibleBuilds.find(
6042
- (b) => str(b.ref) === str(row.ref) && str(b.id) !== str(row.id)
6093
+ (b) => b.ref === row.ref && b.id !== row.id
6043
6094
  );
6044
- followId = successor ? str(successor.id) : null;
6095
+ followId = successor ? successor.id : null;
6045
6096
  }
6046
6097
  }
6047
6098
  if (now() >= deadline) return { ...last, timedOut: true };
@@ -6092,7 +6143,7 @@ function diagnosticsOf(parsed) {
6092
6143
  }
6093
6144
 
6094
6145
  // src/version.ts
6095
- var CLIENT_VERSION = "0.1.0";
6146
+ var CLIENT_VERSION = "0.3.0";
6096
6147
  var CLIENT_PRODUCT = `@farthershore/client/${CLIENT_VERSION}`;
6097
6148
 
6098
6149
  // src/transport.ts
@@ -107,7 +107,7 @@ export interface FartherShoreApi {
107
107
  /**
108
108
  * Recent requests — the live metering signal, newest first
109
109
  *
110
- * The most recent archived events for one business, newest first. Each row's `payload` carries the request detail (path, statusCode, latencyMs, orgId). Read-only.
110
+ * The most recent archived events for one business, newest first. Each request row's `request` carries the path, status code, subscriber, deny code and final response timing (gateway and backend milliseconds). Read-only.
111
111
  *
112
112
  * Operation `analytics.log` · read · requires `analytics:read`.
113
113
  */
@@ -272,7 +272,7 @@ export interface FartherShoreApi {
272
272
  /**
273
273
  * Show the Stripe connection a business bills through (business override or org default)
274
274
  *
275
- * Read the Stripe Connect account a business bills through — a per-business override when present, otherwise the organization default — including onboarding and tax-enrollment state. Read-only. Connecting Stripe is browser-only and has no tool.
275
+ * Read whether a business bills through a connected Stripe account — a per-business override when present, otherwise the organization default — and whether that account can take charges and card payments. Read-only. Connecting Stripe is browser-only and has no tool.
276
276
  *
277
277
  * Operation `stripe_connection.read` · read · requires `stripe_connection:read`.
278
278
  */
@@ -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
@@ -713,7 +721,7 @@ export interface FartherShoreApi {
713
721
  /**
714
722
  * Roll the business frontend back to a prior release (re-activate its releaseId)
715
723
  *
716
- * Roll a business's frontend back to a prior release by its releaseId (manifest hash, from fs_frontend_status). Flips the live pointer back and pins it. The releaseId must belong to this target's build history.
724
+ * Roll a business's frontend back to a prior release by its releaseId (from fs_frontend_status). Flips the live pointer back and pins it. The releaseId must belong to this target's build history.
717
725
  *
718
726
  * Operation `frontend.rollback` · write · requires `frontend:rollback` · destructive · supports `dryRun` · reconcile an unknown outcome with `frontend.status`.
719
727
  */
@@ -721,7 +729,7 @@ export interface FartherShoreApi {
721
729
  /**
722
730
  * Show the current frontend release, recent releases, and recent builds (incl. failure reasons)
723
731
  *
724
- * Read a business's current frontend serve state (uiMode, active release hash + producing build, pin flag), the recent SUCCEEDED releases (rollback targets), and the recent builds — a FAILED build's `error` explains why a deploy didn't go live. Read-only.
732
+ * Read a business's current frontend serve state (uiMode, active release id + producing build, pin flag), the recent SUCCEEDED releases (rollback targets), and the recent builds — a FAILED build's `error` explains why a deploy didn't go live. Read-only.
725
733
  *
726
734
  * Operation `frontend.status` · read · requires `frontend:read`.
727
735
  */
@@ -850,9 +858,9 @@ export interface FartherShoreApi {
850
858
  /**
851
859
  * Invite a member to an organization
852
860
  *
853
- * Invite a member to an organization. Returns the raw invitation token once; invitation listings never show it.
861
+ * Invite a member to an organization. The invitee receives the accept link by email; no response or listing ever carries the invitation token.
854
862
  *
855
- * Operation `organization.invitation.create` · write · requires `organization_invitation:create` · returns a one-time secret · reconcile an unknown outcome with `organization.invitation.list_sent`.
863
+ * Operation `organization.invitation.create` · write · requires `organization_invitation:create` · reconcile an unknown outcome with `organization.invitation.list_sent`.
856
864
  */
857
865
  readonly create: Method<"organizations.invitation.create">;
858
866
  /**
@@ -1219,7 +1227,7 @@ export interface FartherShoreApi {
1219
1227
  /**
1220
1228
  * Show usage summary for the last 30 days
1221
1229
  *
1222
- * Read a business's usage summary — metered request counts and tier utilization. Without environmentId this rolls up EVERY environment. Read-only.
1230
+ * Read a business's usage summary — request counts (all time and the last 30 days), active API keys, a per-member breakdown, and served requests that can never be rated. Without environmentId this rolls up EVERY environment. Read-only.
1223
1231
  *
1224
1232
  * Operation `usage.read` · read · requires `usage:read`.
1225
1233
  */
@@ -1295,6 +1303,12 @@ export interface FartherShoreApi {
1295
1303
  */
1296
1304
  readonly delete: Method<"webhooks.delete">;
1297
1305
  readonly delivery: {
1306
+ /**
1307
+ * Show one delivery attempt for a webhook endpoint
1308
+ *
1309
+ * Operation `webhook.delivery.read` · read · requires `webhook:delivery_read`.
1310
+ */
1311
+ readonly get: Method<"webhooks.delivery.get">;
1298
1312
  /**
1299
1313
  * List recent delivery attempts for a webhook endpoint
1300
1314
  *