@farthershore/client 0.0.0-stage → 0.1.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 (42) hide show
  1. package/CHANGELOG.md +34 -0
  2. package/README.md +251 -2
  3. package/dist/index.js +6997 -0
  4. package/dist/types/api.generated.d.ts +1356 -0
  5. package/dist/types/credentials.d.ts +78 -0
  6. package/dist/types/envelope.d.ts +48 -0
  7. package/dist/types/errors.d.ts +86 -0
  8. package/dist/types/helpers/abort.d.ts +7 -0
  9. package/dist/types/helpers/paginate.d.ts +32 -0
  10. package/dist/types/helpers/poll.d.ts +26 -0
  11. package/dist/types/helpers/refs.d.ts +84 -0
  12. package/dist/types/helpers/wait-for-frontend-build.d.ts +43 -0
  13. package/dist/types/index.d.ts +24 -0
  14. package/dist/types/operations/agents.d.ts +48 -0
  15. package/dist/types/operations/agreements.d.ts +44 -0
  16. package/dist/types/operations/analytics.d.ts +25 -0
  17. package/dist/types/operations/audit-notifications.d.ts +33 -0
  18. package/dist/types/operations/auth.d.ts +16 -0
  19. package/dist/types/operations/backends.d.ts +53 -0
  20. package/dist/types/operations/billing.d.ts +15 -0
  21. package/dist/types/operations/businesses.d.ts +92 -0
  22. package/dist/types/operations/change-sets.d.ts +43 -0
  23. package/dist/types/operations/consumers.d.ts +49 -0
  24. package/dist/types/operations/define.d.ts +91 -0
  25. package/dist/types/operations/environments.d.ts +19 -0
  26. package/dist/types/operations/frontend.d.ts +13 -0
  27. package/dist/types/operations/index.d.ts +1036 -0
  28. package/dist/types/operations/maker-tokens.d.ts +30 -0
  29. package/dist/types/operations/organizations.d.ts +71 -0
  30. package/dist/types/operations/personas.d.ts +46 -0
  31. package/dist/types/operations/plans-usage.d.ts +18 -0
  32. package/dist/types/operations/platform.d.ts +47 -0
  33. package/dist/types/operations/portal.d.ts +49 -0
  34. package/dist/types/operations/promo-codes.d.ts +19 -0
  35. package/dist/types/operations/variables.d.ts +25 -0
  36. package/dist/types/operations/webhooks.d.ts +67 -0
  37. package/dist/types/surface-types.d.ts +54 -0
  38. package/dist/types/surface.d.ts +35 -0
  39. package/dist/types/transport.d.ts +119 -0
  40. package/dist/types/types.d.ts +469 -0
  41. package/dist/types/version.d.ts +8 -0
  42. package/package.json +53 -3
@@ -0,0 +1,469 @@
1
+ /** A business as `GET /businesses` lists it (only the fields the client reads are typed). */
2
+ export type BusinessSummary = {
3
+ id: string;
4
+ name: string;
5
+ displayName?: string | null;
6
+ description?: string | null;
7
+ status?: "DRAFT" | "ACTIVE";
8
+ runtimeHostname?: string | null;
9
+ portalHostname?: string | null;
10
+ [key: string]: unknown;
11
+ };
12
+ /** An environment row as `GET /businesses/:id/environments` lists it. */
13
+ export type EnvironmentSummary = {
14
+ id: string;
15
+ name: string;
16
+ branch?: string | null;
17
+ [key: string]: unknown;
18
+ };
19
+ /** One Apply Timeline entry (only the fields the client selects on are typed). */
20
+ export type ApplyTimelineEntry = {
21
+ id: string;
22
+ status: string;
23
+ branch: string;
24
+ commitSha: string;
25
+ prNumber: number | null;
26
+ releaseTag: string | null;
27
+ [key: string]: unknown;
28
+ };
29
+ /** `GET /businesses/:id/apply-timeline` response. */
30
+ export type ApplyTimelineEntryList = {
31
+ data: ApplyTimelineEntry[];
32
+ };
33
+ /** Offset pagination block. */
34
+ export type OffsetPagination = {
35
+ total: number;
36
+ limit: number;
37
+ offset: number;
38
+ hasMore: boolean;
39
+ };
40
+ /** `GET /businesses/:id/environments` response. */
41
+ export type EnvironmentListResult = {
42
+ data: EnvironmentSummary[];
43
+ pagination: OffsetPagination;
44
+ };
45
+ /** WS-C semver bump kinds. */
46
+ export type SemverBump = "major" | "minor" | "patch";
47
+ /** Release overrides a publish MAY carry (all optional). */
48
+ export type PublishBusinessBody = {
49
+ bump?: SemverBump;
50
+ version?: string;
51
+ acceptBreaking?: boolean;
52
+ };
53
+ /** The `_release` block the publish route returns. */
54
+ export type PublishRelease = {
55
+ compilationRecordId: string | null;
56
+ previousVersion: string | null;
57
+ computedBump: SemverBump;
58
+ version: string;
59
+ tagCreated: boolean;
60
+ changeSummary: string;
61
+ reasons: string[];
62
+ status: "PENDING" | "PREVIEW";
63
+ };
64
+ /** `GET /management/businesses/subdomain-availability` response. */
65
+ export type ManagedSubdomainAvailability = {
66
+ /** The normalized subdomain the server checked. */
67
+ subdomain: string;
68
+ available: boolean;
69
+ };
70
+ /** One deployment run row from `GET /businesses/:id/deployments`. */
71
+ export type DeploymentRunSummary = {
72
+ id: string;
73
+ status: string | null;
74
+ edgePublishStatus: string | null;
75
+ createdAt: string;
76
+ [key: string]: unknown;
77
+ };
78
+ /** Diagnostic from a dry-run compile (one per error/warning). */
79
+ export type ManifestCompileDiagnostic = {
80
+ code: string;
81
+ message: string;
82
+ path?: string | string[];
83
+ };
84
+ /** Verdict of the dry-run validate route (`POST /businesses/:id/manifest/compile`). */
85
+ export type ManifestCompileResult = {
86
+ success: boolean;
87
+ compilationRecordId?: string;
88
+ irHash?: string;
89
+ environment?: {
90
+ name: string;
91
+ production: boolean;
92
+ };
93
+ errors: ManifestCompileDiagnostic[];
94
+ warnings: ManifestCompileDiagnostic[];
95
+ dryRun?: boolean;
96
+ lifecyclePlan?: unknown;
97
+ economicChange?: boolean;
98
+ specHash?: string;
99
+ };
100
+ export type WebhookEndpoint = {
101
+ id: string;
102
+ url: string;
103
+ /** Environment the endpoint receives events for; null = every environment. */
104
+ environmentId?: string | null;
105
+ events: string[];
106
+ enabled: boolean;
107
+ failCount?: number;
108
+ disabledAt?: string | null;
109
+ createdAt?: string;
110
+ updatedAt?: string;
111
+ secret?: string;
112
+ [key: string]: unknown;
113
+ };
114
+ /** `POST …/webhooks/:id/test` response (`data.success` is the headline). */
115
+ export type WebhookTestResult = {
116
+ data: {
117
+ success: boolean;
118
+ status?: number;
119
+ durationMs: number;
120
+ responseBody?: string | null;
121
+ error?: string;
122
+ [key: string]: unknown;
123
+ };
124
+ };
125
+ export type WebhookDelivery = {
126
+ id: string;
127
+ eventType: string;
128
+ status: string;
129
+ attempts: number;
130
+ responseStatus?: number | null;
131
+ environmentId?: string | null;
132
+ lastAttemptAt?: string | null;
133
+ nextAttemptAt?: string | null;
134
+ createdAt?: string;
135
+ [key: string]: unknown;
136
+ };
137
+ export type PaginatedResult<T> = {
138
+ data?: T[];
139
+ total?: number;
140
+ pagination?: Record<string, unknown>;
141
+ [key: string]: unknown;
142
+ };
143
+ export type AgentSummary = {
144
+ id: string;
145
+ role: string;
146
+ enabled: boolean;
147
+ config: Record<string, unknown>;
148
+ lastRunAt: string | null;
149
+ createdAt?: string;
150
+ updatedAt?: string;
151
+ [key: string]: unknown;
152
+ };
153
+ export type AgentRunSummary = {
154
+ id: string;
155
+ status: string;
156
+ trigger: string;
157
+ dispatchedAt: string | null;
158
+ finishedAt: string | null;
159
+ errorCode: string | null;
160
+ errorMessage: string | null;
161
+ createdAt: string;
162
+ [key: string]: unknown;
163
+ };
164
+ export type AgentStatus = AgentSummary & {
165
+ recentRuns: AgentRunSummary[];
166
+ usage: {
167
+ tokensIn: number;
168
+ tokensOut: number;
169
+ actionsCount: number;
170
+ };
171
+ };
172
+ export type BulletinPost = {
173
+ id: string;
174
+ kind: string;
175
+ role: string;
176
+ title: string;
177
+ body: string;
178
+ dataJson: Record<string, unknown>;
179
+ severity: string;
180
+ status: string;
181
+ changeSetId: string | null;
182
+ createdAt: string;
183
+ updatedAt: string;
184
+ [key: string]: unknown;
185
+ };
186
+ export type PromoCodeKind = "percent_off" | "amount_off" | "free_months";
187
+ export type PromoCodeStatus = "ACTIVE" | "ARCHIVED";
188
+ export type PromoCode = {
189
+ id: string;
190
+ businessId: string | null;
191
+ code: string;
192
+ kind: PromoCodeKind;
193
+ amount: number | null;
194
+ durationMonths: number;
195
+ applicablePlanIds: string[];
196
+ maxRedemptions: number | null;
197
+ redemptionCount: number;
198
+ activeFrom?: string | null;
199
+ activeUntil?: string | null;
200
+ status: PromoCodeStatus;
201
+ stripeCouponId?: string | null;
202
+ stripePromotionCodeId?: string | null;
203
+ createdAt?: string;
204
+ updatedAt?: string;
205
+ [key: string]: unknown;
206
+ };
207
+ export type CreatePromoCodeInput = {
208
+ code: string;
209
+ kind: PromoCodeKind;
210
+ amount?: number | null;
211
+ durationMonths: number;
212
+ applicablePlanIds?: string[];
213
+ maxRedemptions?: number | null;
214
+ activeFrom?: string | null;
215
+ activeUntil?: string | null;
216
+ };
217
+ export type UpdatePromoCodeInput = Partial<CreatePromoCodeInput> & {
218
+ status?: PromoCodeStatus;
219
+ };
220
+ /**
221
+ * The lowercase account-tier vocabulary every agent surface speaks. The
222
+ * stored membership enum (`OWNER|ADMIN|VIEWER`) is projected alongside it as
223
+ * `role`; `VIEWER` maps to `member`.
224
+ */
225
+ export declare const ACCOUNT_ROLES: readonly ["owner", "admin", "member"];
226
+ export type AccountRole = (typeof ACCOUNT_ROLES)[number];
227
+ /** One member of a subscribing organization, as the consumer list projects it. */
228
+ export type BusinessConsumerMember = {
229
+ userExternalId: string;
230
+ /** Raw stored membership enum: `OWNER | ADMIN | VIEWER`. */
231
+ role: string;
232
+ /** Canonical lowercase account tier; `null` when the stored value is unknown. */
233
+ accountRole: AccountRole | null;
234
+ businessRoleKeys: string[];
235
+ staleRoleKeys: string[];
236
+ [key: string]: unknown;
237
+ };
238
+ export type BusinessConsumer = {
239
+ id: string;
240
+ businessId: string;
241
+ status: string;
242
+ ownerType?: string | null;
243
+ ownerOrganizationId?: string | null;
244
+ ownerName?: string | null;
245
+ planId?: string | null;
246
+ planName?: string | null;
247
+ createdAt?: string;
248
+ rbac?: {
249
+ enabled: boolean;
250
+ roles: unknown[];
251
+ };
252
+ members?: BusinessConsumerMember[];
253
+ [key: string]: unknown;
254
+ };
255
+ /** The per-subscriber Managed-RBAC enablement flag. */
256
+ export type ConsumerRbacSettingsResult = {
257
+ enabled: boolean;
258
+ defaultRoleKey?: string;
259
+ [key: string]: unknown;
260
+ };
261
+ /** One subscriber-owned role row (ACCOUNT or CUSTOM). */
262
+ export type ConsumerRbacRole = {
263
+ roleKey: string;
264
+ name: string;
265
+ permissions: string[];
266
+ kind: string;
267
+ createdAt: string;
268
+ [key: string]: unknown;
269
+ };
270
+ /**
271
+ * One consumer API key as the builder plane sees it: metadata only. No hash,
272
+ * no lookup prefix, no raw key; `displayPrefix` is already redacted.
273
+ */
274
+ export type ConsumerApiKey = {
275
+ id: string;
276
+ name: string | null;
277
+ displayPrefix: string;
278
+ status: string;
279
+ kind: string;
280
+ createdAt: string;
281
+ lastUsedAt: string | null;
282
+ expiresAt: string | null;
283
+ revokedAt: string | null;
284
+ [key: string]: unknown;
285
+ };
286
+ export type BlockConsumerResult = {
287
+ blocked: true;
288
+ subscriberId: string;
289
+ apiKeysRevoked: number;
290
+ alreadyBlocked: boolean;
291
+ [key: string]: unknown;
292
+ };
293
+ export type RemoveConsumerResult = {
294
+ removed: true;
295
+ subscriberId: string;
296
+ subscriptionsRemoved: number;
297
+ apiKeysRevoked: number;
298
+ [key: string]: unknown;
299
+ };
300
+ /** The membership after a set-replace business-role assignment. */
301
+ export type ConsumerMemberRolesResult = {
302
+ id: string;
303
+ userExternalId: string;
304
+ role: string;
305
+ businessRoleKeys: string[];
306
+ [key: string]: unknown;
307
+ };
308
+ /**
309
+ * A variable row from the list endpoint. `value` is populated ONLY for an
310
+ * active public (`FS_PUBLIC_*`) row; a secret's value is never returned.
311
+ */
312
+ export type BusinessVariableRow = {
313
+ name: string;
314
+ /** Derived from the name: `FS_PUBLIC_*` is public, everything else secret. */
315
+ visibility: "public" | "secret";
316
+ /** Present only for an active public variable; always null for a secret. */
317
+ value: string | null;
318
+ hasValue: boolean;
319
+ lifecycleStatus: string;
320
+ generation: number | null;
321
+ [key: string]: unknown;
322
+ };
323
+ /** An asynchronous secret mutation and its progress. */
324
+ export type SecretMutationOperation = {
325
+ operationId: string;
326
+ mutationId: string;
327
+ kind: "CREATE" | "ROTATE" | "REVOKE" | "DELETE";
328
+ status: "PENDING" | "PROCESSING" | "WAITING_RETRY" | "SUCCEEDED" | "ABORTED";
329
+ state: string;
330
+ generation: number;
331
+ pending: boolean;
332
+ attemptCount: number;
333
+ nextAttemptAt: string;
334
+ lastAttemptAt: string | null;
335
+ lastError: {
336
+ code: string;
337
+ message: string;
338
+ } | null;
339
+ completedAt: string | null;
340
+ impact: unknown;
341
+ result: unknown;
342
+ };
343
+ /** An economic agreement (builder surface). */
344
+ export type EconomicAgreement = {
345
+ id: string;
346
+ businessId: string;
347
+ environmentId: string | null;
348
+ environmentScope: string;
349
+ subjectId: string;
350
+ usagePricingBinding: {
351
+ mode: "current" | "current_with_contract_terms" | "fixed_version";
352
+ pricingPolicyId: string;
353
+ contractPricingVersionId?: string;
354
+ pricingPolicyVersionId?: string;
355
+ };
356
+ newMeterPolicy: string;
357
+ newMeasurePolicy: string;
358
+ effectiveAt: string;
359
+ expiresAt: string | null;
360
+ createdAt: string;
361
+ contractPricingVersions: Array<{
362
+ id: string;
363
+ version: number;
364
+ termsHash: string;
365
+ terms: Record<string, unknown>;
366
+ effectiveAt: string;
367
+ createdAt: string;
368
+ }>;
369
+ };
370
+ export type AgreementPreview = {
371
+ effect: Record<string, unknown>;
372
+ confirmationToken: string;
373
+ };
374
+ export type SubjectPins = {
375
+ subjectId: string;
376
+ businessId: string;
377
+ environmentId: string | null;
378
+ recurringPricePin: Record<string, unknown> | null;
379
+ usagePricingBinding: Record<string, unknown>;
380
+ migrateToLatest: {
381
+ status: "deferred";
382
+ };
383
+ };
384
+ /** A runtime token as the server reports it (never the secret). */
385
+ export type RuntimeTokenSummary = {
386
+ allowedMeters: string[];
387
+ allowedRoutes: string[];
388
+ backendId: string | null;
389
+ businessId: string;
390
+ createdAt: string;
391
+ environmentId: string | null;
392
+ id: string;
393
+ kind: "live" | "test";
394
+ lastFour: string;
395
+ lastUsedAt: string | null;
396
+ operations: ("gateway_verification" | "metering" | "health" | "tunnel" | "drift_report")[];
397
+ revokedAt: string | null;
398
+ rotatedFromId: string | null;
399
+ status: "active" | "revoked";
400
+ };
401
+ /** The delegable-permission vocabulary, grouped by subject. */
402
+ export type MakerTokenPermissionCatalog = {
403
+ entries: Array<{
404
+ subject: string;
405
+ title?: string;
406
+ permissions: string[];
407
+ }>;
408
+ };
409
+ /** A CLI login's view of itself (`fscli_` session). */
410
+ export type CliSessionContext = {
411
+ kind: "cli_user";
412
+ credentialType: "cli_session";
413
+ sessionId: string;
414
+ userId: string;
415
+ organizationId: string;
416
+ role: string;
417
+ };
418
+ /** A maker token's view of itself, including its granted permissions. */
419
+ export type MakerTokenContext = {
420
+ kind: "maker";
421
+ credentialType: "maker_token";
422
+ tokenId: string;
423
+ organizationId: string;
424
+ authVersion: number;
425
+ grantedPermissions: string[];
426
+ businessScopeMode: "ALL" | "SELECTED";
427
+ selectedBusinessIds: string[];
428
+ };
429
+ /** A builder (dashboard) session's view of itself. */
430
+ export type BuilderBootstrapContext = {
431
+ user: {
432
+ id: string;
433
+ clerkUserId: string;
434
+ };
435
+ activeOrganization: {
436
+ id: string;
437
+ name?: string;
438
+ slug?: string;
439
+ };
440
+ memberships: Array<{
441
+ organization: {
442
+ id: string;
443
+ name?: string;
444
+ slug?: string;
445
+ };
446
+ role: string;
447
+ }>;
448
+ };
449
+ /** Who the credential is (`fs.auth.context.read()`). */
450
+ export type CallerContext = CliSessionContext | MakerTokenContext | ({
451
+ kind: "builder";
452
+ } & BuilderBootstrapContext);
453
+ /** A persona browser handoff. */
454
+ export type PersonaHandoff = {
455
+ data: {
456
+ personaId: string;
457
+ environmentId: string;
458
+ portalUrl: string;
459
+ handoffToken: string;
460
+ expiresAt: string;
461
+ };
462
+ };
463
+ /** A persona handoff plus the CLI-process-only local-preview proxy lease. */
464
+ export type PersonaLocalPreviewLease = {
465
+ data: PersonaHandoff["data"] & {
466
+ localProxyLease: string;
467
+ localProxyLeaseExpiresAt: string;
468
+ };
469
+ };
@@ -0,0 +1,8 @@
1
+ /**
2
+ * This package's version, sent in the `x-fs-client` header. Kept in step with
3
+ * `package.json` by `version.test.ts` and checked in the built bundle by
4
+ * `scripts/check-pack.mjs`.
5
+ */
6
+ export declare const CLIENT_VERSION = "0.1.0";
7
+ /** The `x-fs-client` product token for this package. */
8
+ export declare const CLIENT_PRODUCT = "@farthershore/client/0.1.0";
package/package.json CHANGED
@@ -1,6 +1,56 @@
1
1
  {
2
2
  "name": "@farthershore/client",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.1.0",
4
+ "description": "Farther Shore API client: the authenticated HTTP transport, credential sources, and typed errors shared by the CLI and agent tooling",
5
+ "type": "module",
6
+ "sideEffects": false,
7
+ "main": "./dist/index.js",
8
+ "module": "./dist/index.js",
9
+ "types": "./dist/types/index.d.ts",
10
+ "exports": {
11
+ ".": {
12
+ "types": "./dist/types/index.d.ts",
13
+ "import": "./dist/index.js"
14
+ }
15
+ },
16
+ "files": [
17
+ "dist",
18
+ "README.md",
19
+ "CHANGELOG.md"
20
+ ],
21
+ "publishConfig": {
22
+ "access": "public"
23
+ },
24
+ "keywords": [
25
+ "farthershore",
26
+ "api",
27
+ "client",
28
+ "sdk"
29
+ ],
30
+ "author": "Farther Shore",
31
+ "devDependencies": {
32
+ "@types/node": "^22.20.1",
33
+ "esbuild": "^0.28.1",
34
+ "eslint": "^9.39.5",
35
+ "eslint-plugin-sonarjs": "^4.2.0",
36
+ "fast-check": "3.23.2",
37
+ "prettier": "^3.9.6",
38
+ "typescript": "^6.0.3",
39
+ "typescript-eslint": "^8.66.0",
40
+ "vitest": "^4.1.10",
41
+ "@farthershore/contracts": "0.62.0"
42
+ },
43
+ "engines": {
44
+ "node": ">=22"
45
+ },
46
+ "license": "MIT",
47
+ "scripts": {
48
+ "build": "tsc --noEmit && node scripts/build.mjs",
49
+ "typecheck": "tsc --noEmit",
50
+ "lint": "eslint .",
51
+ "lint:fix": "eslint . --fix",
52
+ "test": "vitest run",
53
+ "pack:check": "node scripts/check-pack.mjs",
54
+ "generate:api": "UPDATE_API_TYPES=1 vitest run src/api.generated.test.ts"
55
+ }
6
56
  }