@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.
- package/CHANGELOG.md +34 -0
- package/README.md +251 -2
- package/dist/index.js +6997 -0
- package/dist/types/api.generated.d.ts +1356 -0
- package/dist/types/credentials.d.ts +78 -0
- package/dist/types/envelope.d.ts +48 -0
- package/dist/types/errors.d.ts +86 -0
- package/dist/types/helpers/abort.d.ts +7 -0
- package/dist/types/helpers/paginate.d.ts +32 -0
- package/dist/types/helpers/poll.d.ts +26 -0
- package/dist/types/helpers/refs.d.ts +84 -0
- package/dist/types/helpers/wait-for-frontend-build.d.ts +43 -0
- package/dist/types/index.d.ts +24 -0
- package/dist/types/operations/agents.d.ts +48 -0
- package/dist/types/operations/agreements.d.ts +44 -0
- package/dist/types/operations/analytics.d.ts +25 -0
- package/dist/types/operations/audit-notifications.d.ts +33 -0
- package/dist/types/operations/auth.d.ts +16 -0
- package/dist/types/operations/backends.d.ts +53 -0
- package/dist/types/operations/billing.d.ts +15 -0
- package/dist/types/operations/businesses.d.ts +92 -0
- package/dist/types/operations/change-sets.d.ts +43 -0
- package/dist/types/operations/consumers.d.ts +49 -0
- package/dist/types/operations/define.d.ts +91 -0
- package/dist/types/operations/environments.d.ts +19 -0
- package/dist/types/operations/frontend.d.ts +13 -0
- package/dist/types/operations/index.d.ts +1036 -0
- package/dist/types/operations/maker-tokens.d.ts +30 -0
- package/dist/types/operations/organizations.d.ts +71 -0
- package/dist/types/operations/personas.d.ts +46 -0
- package/dist/types/operations/plans-usage.d.ts +18 -0
- package/dist/types/operations/platform.d.ts +47 -0
- package/dist/types/operations/portal.d.ts +49 -0
- package/dist/types/operations/promo-codes.d.ts +19 -0
- package/dist/types/operations/variables.d.ts +25 -0
- package/dist/types/operations/webhooks.d.ts +67 -0
- package/dist/types/surface-types.d.ts +54 -0
- package/dist/types/surface.d.ts +35 -0
- package/dist/types/transport.d.ts +119 -0
- package/dist/types/types.d.ts +469 -0
- package/dist/types/version.d.ts +8 -0
- package/package.json +53 -3
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
import type { OrganizationsResponse } from "./transport.js";
|
|
2
|
+
/** What a source hands the transport for one request. */
|
|
3
|
+
export type AccessGrant = {
|
|
4
|
+
token: string;
|
|
5
|
+
/** The organization the token acts in, when known. */
|
|
6
|
+
organizationId?: string;
|
|
7
|
+
/** Extra headers that travel with this token (organization selection). */
|
|
8
|
+
headers?: Readonly<Record<string, string>>;
|
|
9
|
+
};
|
|
10
|
+
/**
|
|
11
|
+
* What the transport lends a source: the organization selection it was
|
|
12
|
+
* created with, and an UNAUTHENTICATED JSON sender that shares its retry,
|
|
13
|
+
* timeout, and error classification (for token exchange endpoints).
|
|
14
|
+
*/
|
|
15
|
+
export type CredentialContext = {
|
|
16
|
+
readonly organizationId?: string;
|
|
17
|
+
readonly requiredOrganizationId?: string;
|
|
18
|
+
sendJson<T>(method: string, path: string, init: {
|
|
19
|
+
headers?: Readonly<Record<string, string>>;
|
|
20
|
+
body?: string;
|
|
21
|
+
signal?: AbortSignal;
|
|
22
|
+
/** `"none"`: one attempt. */
|
|
23
|
+
retry?: "none";
|
|
24
|
+
}, policy: "read" | "write"): Promise<{
|
|
25
|
+
data: T;
|
|
26
|
+
headers: Headers | undefined;
|
|
27
|
+
/** Local clock when the answer was read. */
|
|
28
|
+
receivedAt: number;
|
|
29
|
+
}>;
|
|
30
|
+
};
|
|
31
|
+
export type AccessTokenRequest = {
|
|
32
|
+
signal?: AbortSignal;
|
|
33
|
+
/**
|
|
34
|
+
* The server rejected `rejectedToken` (401): mint a new one unless the
|
|
35
|
+
* cached token has already moved on.
|
|
36
|
+
*/
|
|
37
|
+
forceRefresh?: boolean;
|
|
38
|
+
rejectedToken?: string;
|
|
39
|
+
context: CredentialContext;
|
|
40
|
+
};
|
|
41
|
+
export interface CredentialSource {
|
|
42
|
+
/** `"cli_exchange"`, `"bearer"`, `"consumer"`, or a custom kind. */
|
|
43
|
+
readonly kind: string;
|
|
44
|
+
/** True when a 401 can be cured by minting a fresh token. */
|
|
45
|
+
readonly refreshable?: boolean;
|
|
46
|
+
getAccessToken(request: AccessTokenRequest): Promise<AccessGrant>;
|
|
47
|
+
/** Organizations the credential can act in (user credentials only). */
|
|
48
|
+
listOrganizations?(context: CredentialContext, signal?: AbortSignal, options?: {
|
|
49
|
+
retry?: "none";
|
|
50
|
+
}): Promise<OrganizationsResponse>;
|
|
51
|
+
/**
|
|
52
|
+
* The organization the credential acts in, resolving it if needed.
|
|
53
|
+
* `retry: "none"`: every request made to resolve it is a single attempt.
|
|
54
|
+
*/
|
|
55
|
+
selectedOrganizationId?(context: CredentialContext, signal?: AbortSignal, options?: {
|
|
56
|
+
retry?: "none";
|
|
57
|
+
}): Promise<string | undefined>;
|
|
58
|
+
}
|
|
59
|
+
/** A static bearer token, sent as is (OAuth access tokens, remote use). */
|
|
60
|
+
export declare function bearerCredentials(token: string): CredentialSource;
|
|
61
|
+
/**
|
|
62
|
+
* A subscriber (consumer) session for the portal plane: the bearer plus the
|
|
63
|
+
* environment and subscribing organization it acts for. Never exchanged.
|
|
64
|
+
*/
|
|
65
|
+
export declare function consumerCredentials(input: {
|
|
66
|
+
token: string;
|
|
67
|
+
environmentId: string;
|
|
68
|
+
organizationId: string;
|
|
69
|
+
}): CredentialSource;
|
|
70
|
+
/** True for the raw credentials {@link cliExchangeCredentials} exchanges. */
|
|
71
|
+
export declare function isExchangeCredential(rawToken: string): boolean;
|
|
72
|
+
/**
|
|
73
|
+
* A CLI login (`fscli_…`, user-bound) or a maker token (`mk_…`,
|
|
74
|
+
* organization-bound), exchanged for a short-lived access token before use
|
|
75
|
+
* and re-exchanged ahead of its expiry or after a 401. Any other token is
|
|
76
|
+
* sent as is.
|
|
77
|
+
*/
|
|
78
|
+
export declare function cliExchangeCredentials(rawToken: string): CredentialSource;
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
import type { RetryDisposition } from "./errors.js";
|
|
2
|
+
/**
|
|
3
|
+
* The ONE reader of the platform's error envelope. The canonical shape is
|
|
4
|
+
* `{ error: { code, message, details?, retryable?, retryDisposition? } }`; a
|
|
5
|
+
* few legacy routes still answer `{ error: "message" }`, and the compiler
|
|
6
|
+
* reports diagnostics in TOP-LEVEL `errors` / `warnings` arrays beside it.
|
|
7
|
+
*/
|
|
8
|
+
export type ErrorEnvelope = {
|
|
9
|
+
code?: string;
|
|
10
|
+
message?: string;
|
|
11
|
+
/** Any JSON value: Core's `AppError.details` is `unknown`. */
|
|
12
|
+
details?: unknown;
|
|
13
|
+
/** The offending request field, when the server names one. */
|
|
14
|
+
param?: string;
|
|
15
|
+
retryable?: boolean;
|
|
16
|
+
retryDisposition?: RetryDisposition;
|
|
17
|
+
};
|
|
18
|
+
/** The server's retry verdict on a failed request. */
|
|
19
|
+
export type RetrySignal = {
|
|
20
|
+
retryable?: boolean;
|
|
21
|
+
retryDisposition?: RetryDisposition;
|
|
22
|
+
};
|
|
23
|
+
/**
|
|
24
|
+
* Normalize a parsed response body's `error` member. `undefined` when the body
|
|
25
|
+
* carries no envelope (not JSON, `error` absent or `null`).
|
|
26
|
+
*/
|
|
27
|
+
export declare function errorEnvelopeOf(body: unknown): ErrorEnvelope | undefined;
|
|
28
|
+
/**
|
|
29
|
+
* The retry verdict an envelope carries. A disposition counts only alongside
|
|
30
|
+
* an explicit boolean `retryable`; without one the status policy decides.
|
|
31
|
+
*/
|
|
32
|
+
export declare function retrySignalOf(envelope: ErrorEnvelope | undefined): RetrySignal;
|
|
33
|
+
/**
|
|
34
|
+
* The server's own proof that a failed request did not run: it marks the
|
|
35
|
+
* error `retryable` AND `safe_to_repeat`. Honoured at ANY status — the server
|
|
36
|
+
* answers some 5xx (a delete whose teardown failed before anything was
|
|
37
|
+
* deleted) with this verdict.
|
|
38
|
+
*/
|
|
39
|
+
export declare function isServerSafeToRepeat(signal: RetrySignal | undefined): boolean;
|
|
40
|
+
/**
|
|
41
|
+
* Compiler diagnostics live in TOP-LEVEL `errors` / `warnings` arrays beside
|
|
42
|
+
* `error`. Surface them as `details` so normal error handling prints them;
|
|
43
|
+
* `undefined` when there are none.
|
|
44
|
+
*/
|
|
45
|
+
export declare function diagnosticsOf(parsed: unknown): {
|
|
46
|
+
errors?: unknown[];
|
|
47
|
+
warnings?: unknown[];
|
|
48
|
+
} | undefined;
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Required recovery protocol for a failed mutation, as the server states it:
|
|
3
|
+
* `safe_to_repeat` — nothing ran, the same request may be sent again;
|
|
4
|
+
* `reconcile_before_repeat` — it may have run, read current state first.
|
|
5
|
+
*/
|
|
6
|
+
export type RetryDisposition = "safe_to_repeat" | "reconcile_before_repeat";
|
|
7
|
+
/** Stable codes for a request that got no authoritative HTTP answer. */
|
|
8
|
+
export type TransportErrorCode = "NETWORK_ERROR" | "TIMEOUT" | "REQUEST_ABORTED" | "OUTCOME_UNKNOWN";
|
|
9
|
+
export type FartherShoreErrorOptions = {
|
|
10
|
+
code?: string;
|
|
11
|
+
/** As the server sent it: an object, a validator's issue array, … */
|
|
12
|
+
details?: unknown;
|
|
13
|
+
param?: string;
|
|
14
|
+
retryable?: boolean;
|
|
15
|
+
retryDisposition?: RetryDisposition;
|
|
16
|
+
outcomeUnknown?: boolean;
|
|
17
|
+
/** The underlying failure (a network error, a body parse error). */
|
|
18
|
+
cause?: unknown;
|
|
19
|
+
/** Response headers of the HTTP answer that failed, when one arrived. */
|
|
20
|
+
headers?: Headers;
|
|
21
|
+
};
|
|
22
|
+
/** The plain-data form of a {@link FartherShoreError} (`toJSON()`). */
|
|
23
|
+
export type FartherShoreErrorJSON = {
|
|
24
|
+
name: string;
|
|
25
|
+
message: string;
|
|
26
|
+
status?: number;
|
|
27
|
+
code?: string;
|
|
28
|
+
/** As the server sent it: an object, a validator's issue array, … */
|
|
29
|
+
details?: unknown;
|
|
30
|
+
param?: string;
|
|
31
|
+
retryable?: boolean;
|
|
32
|
+
retryDisposition?: RetryDisposition;
|
|
33
|
+
outcomeUnknown?: boolean;
|
|
34
|
+
};
|
|
35
|
+
/**
|
|
36
|
+
* Every failure the client reports. Carries the canonical `code` from the
|
|
37
|
+
* `{ error: { code, message, details? } }` envelope, the HTTP `status` (0 when
|
|
38
|
+
* no HTTP answer arrived), and the server's retry verdict, so callers can
|
|
39
|
+
* branch on data instead of message text.
|
|
40
|
+
*
|
|
41
|
+
* `code`/`details` are optional because the same class is used for local
|
|
42
|
+
* failures (bad input, missing configuration) where there is no server code.
|
|
43
|
+
*/
|
|
44
|
+
export declare class FartherShoreError extends Error {
|
|
45
|
+
status?: number | undefined;
|
|
46
|
+
readonly code?: string;
|
|
47
|
+
/** As the server sent it: an object, a validator's issue array, … */
|
|
48
|
+
readonly details?: unknown;
|
|
49
|
+
/** Offending field/param, when known. */
|
|
50
|
+
readonly param?: string;
|
|
51
|
+
/** Authoritative server retry verdict, when the response supplied one. */
|
|
52
|
+
readonly retryable?: boolean;
|
|
53
|
+
/** Required recovery protocol for the failed mutation, when supplied. */
|
|
54
|
+
readonly retryDisposition?: RetryDisposition;
|
|
55
|
+
/**
|
|
56
|
+
* True when a write was sent but no authoritative answer proves whether it
|
|
57
|
+
* ran (a 5xx or a lost response). Read current state before repeating it;
|
|
58
|
+
* the client never repeats such a write on its own.
|
|
59
|
+
*/
|
|
60
|
+
readonly outcomeUnknown?: boolean;
|
|
61
|
+
/**
|
|
62
|
+
* Response headers of the HTTP answer that failed (`Retry-After`, request
|
|
63
|
+
* ids), when one arrived. Non-enumerable and not part of {@link toJSON},
|
|
64
|
+
* so spreading or serializing an error never copies them.
|
|
65
|
+
*/
|
|
66
|
+
readonly headers?: Headers;
|
|
67
|
+
constructor(message: string, status?: number | undefined, extra?: FartherShoreErrorOptions);
|
|
68
|
+
/** Plain data (no `cause`, no stack) — safe to serialize and log. */
|
|
69
|
+
toJSON(): FartherShoreErrorJSON;
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* A request reached the fetch boundary but no authoritative HTTP response
|
|
73
|
+
* arrived. It IS a `FartherShoreError` (status 0) so callers keep its code and
|
|
74
|
+
* retryability: `NETWORK_ERROR` / `TIMEOUT` on a read are retryable; a write
|
|
75
|
+
* that may have reached the server is `OUTCOME_UNKNOWN` (reconcile first); a
|
|
76
|
+
* caller-aborted request is `REQUEST_ABORTED`. The original failure is kept
|
|
77
|
+
* as `cause`.
|
|
78
|
+
*/
|
|
79
|
+
export declare class FartherShoreTransportError extends FartherShoreError {
|
|
80
|
+
readonly code: TransportErrorCode;
|
|
81
|
+
constructor(message: string, cause: unknown, extra?: {
|
|
82
|
+
code: TransportErrorCode;
|
|
83
|
+
retryable: boolean;
|
|
84
|
+
outcomeUnknown?: boolean;
|
|
85
|
+
});
|
|
86
|
+
}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import { FartherShoreTransportError } from "../errors.js";
|
|
2
|
+
/** The error a helper throws when its caller cancels it. */
|
|
3
|
+
export declare function abortedError(_signal: AbortSignal): FartherShoreTransportError;
|
|
4
|
+
/** Throw when `signal` has fired. */
|
|
5
|
+
export declare function throwIfAborted(signal: AbortSignal | undefined): void;
|
|
6
|
+
/** Sleep `ms`, settling early (rejected) when `signal` fires. */
|
|
7
|
+
export declare function sleepFor(ms: number, signal?: AbortSignal): Promise<void>;
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import type { CallOptions } from "../operations/define.js";
|
|
2
|
+
import type { OperationMeta } from "../surface-types.js";
|
|
3
|
+
/** A namespaced method `paginate` can walk. */
|
|
4
|
+
export type PaginatedMethod<I, O> = ((input: I, options?: CallOptions) => Promise<O>) & {
|
|
5
|
+
readonly meta: Pick<OperationMeta, "path" | "pagination"> & Partial<Pick<OperationMeta, "maxPageSize">>;
|
|
6
|
+
};
|
|
7
|
+
/** The element type of one page. */
|
|
8
|
+
export type PageItem<O> = O extends readonly (infer T)[] ? T : O extends {
|
|
9
|
+
data: readonly (infer T)[];
|
|
10
|
+
} ? T : O extends {
|
|
11
|
+
items: readonly (infer T)[];
|
|
12
|
+
} ? T : unknown;
|
|
13
|
+
export type PaginateOptions = {
|
|
14
|
+
/** Stop after this many items (across pages). */
|
|
15
|
+
maxItems?: number;
|
|
16
|
+
/** Cancels the walk (and the in-flight page request). */
|
|
17
|
+
signal?: AbortSignal;
|
|
18
|
+
};
|
|
19
|
+
export declare const NOT_PAGINATED = "NOT_PAGINATED";
|
|
20
|
+
export declare const PAGINATION_NOT_ADVANCING = "PAGINATION_NOT_ADVANCING";
|
|
21
|
+
/** A starting `offset` or `limit` that is not a non-negative whole number. */
|
|
22
|
+
export declare const INVALID_PAGE_PARAMETER = "INVALID_PAGE_PARAMETER";
|
|
23
|
+
/**
|
|
24
|
+
* Iterate every item of a paginated method, page by page.
|
|
25
|
+
*
|
|
26
|
+
* ```ts
|
|
27
|
+
* for await (const env of paginate(fs.environments.read, { businessId })) …
|
|
28
|
+
* ```
|
|
29
|
+
*/
|
|
30
|
+
export declare function paginate<I extends object | undefined, O>(method: PaginatedMethod<I, O>, input: I, options?: PaginateOptions): AsyncGenerator<PageItem<O>, void, undefined>;
|
|
31
|
+
/** Collect a paginated method into one array (bounded by `maxItems`). */
|
|
32
|
+
export declare function collect<I extends object | undefined, O>(method: PaginatedMethod<I, O>, input: I, options?: PaginateOptions): Promise<PageItem<O>[]>;
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
export type PollOptions<T> = {
|
|
2
|
+
/** Read the current state. */
|
|
3
|
+
check: (signal?: AbortSignal) => Promise<T>;
|
|
4
|
+
/** True once `value` is the state being waited for. */
|
|
5
|
+
until: (value: T) => boolean;
|
|
6
|
+
/** Wait between checks (default 1000 ms). */
|
|
7
|
+
intervalMs?: number;
|
|
8
|
+
/** Give up after this many milliseconds from the start. */
|
|
9
|
+
deadlineMs: number;
|
|
10
|
+
/** Cancels the wait. */
|
|
11
|
+
signal?: AbortSignal;
|
|
12
|
+
/** Test seams. */
|
|
13
|
+
sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
|
|
14
|
+
now?: () => number;
|
|
15
|
+
};
|
|
16
|
+
export type PollResult<T> = {
|
|
17
|
+
/** The last value read. */
|
|
18
|
+
value: T;
|
|
19
|
+
/** True when the deadline passed before `until` held. */
|
|
20
|
+
timedOut: boolean;
|
|
21
|
+
};
|
|
22
|
+
/**
|
|
23
|
+
* Check until `until(value)` holds or the deadline passes. Always checks at
|
|
24
|
+
* least once; the last value is returned either way.
|
|
25
|
+
*/
|
|
26
|
+
export declare function poll<T>(options: PollOptions<T>): Promise<PollResult<T>>;
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
import type { CallOptions, ListQuery } from "../operations/define.js";
|
|
2
|
+
import type { BusinessSummary, EnvironmentListResult, EnvironmentSummary } from "../types.js";
|
|
3
|
+
/** What the business lookups call. `fs` satisfies it. */
|
|
4
|
+
export type BusinessListSource = {
|
|
5
|
+
businesses: {
|
|
6
|
+
list(input: {
|
|
7
|
+
limit: number;
|
|
8
|
+
offset: number;
|
|
9
|
+
query?: ListQuery;
|
|
10
|
+
}, options?: CallOptions): Promise<readonly BusinessSummary[]>;
|
|
11
|
+
};
|
|
12
|
+
};
|
|
13
|
+
/** What the environment lookups call. `fs` satisfies it. */
|
|
14
|
+
export type EnvironmentListSource = {
|
|
15
|
+
environments: {
|
|
16
|
+
read(input: {
|
|
17
|
+
businessId: string;
|
|
18
|
+
limit: number;
|
|
19
|
+
offset: number;
|
|
20
|
+
query?: ListQuery;
|
|
21
|
+
}, options?: CallOptions): Promise<EnvironmentListResult>;
|
|
22
|
+
};
|
|
23
|
+
};
|
|
24
|
+
export type RefSource = BusinessListSource & EnvironmentListSource;
|
|
25
|
+
export type LookupOptions = {
|
|
26
|
+
signal?: AbortSignal;
|
|
27
|
+
};
|
|
28
|
+
/**
|
|
29
|
+
* Whether `ref` names a business: its id, its name (case-insensitive), or a
|
|
30
|
+
* runtime/portal hostname or the hostname's first label.
|
|
31
|
+
*/
|
|
32
|
+
export declare function findBusinessByRef<B extends {
|
|
33
|
+
id: string;
|
|
34
|
+
name: string;
|
|
35
|
+
runtimeHostname?: string | null;
|
|
36
|
+
portalHostname?: string | null;
|
|
37
|
+
}>(businesses: readonly B[], ref: string): B | undefined;
|
|
38
|
+
/**
|
|
39
|
+
* Walk the caller's business list up to the page cap. `complete` is false
|
|
40
|
+
* when the walk stopped at the cap with the last page still full.
|
|
41
|
+
*/
|
|
42
|
+
export declare function listAllBusinesses(source: BusinessListSource, query?: ListQuery, options?: LookupOptions): Promise<{
|
|
43
|
+
businesses: BusinessSummary[];
|
|
44
|
+
complete: boolean;
|
|
45
|
+
}>;
|
|
46
|
+
/**
|
|
47
|
+
* Paged business-ref lookup:
|
|
48
|
+
* - `matched`: the ref names this business (sound at any page depth);
|
|
49
|
+
* - `absent`: PROVEN absence — the FIRST page came back short, so one
|
|
50
|
+
* request saw the whole list. A short page deeper in the walk is not
|
|
51
|
+
* proof: a row deleted between two fetches shifts the window;
|
|
52
|
+
* - `inconclusive`: no proof either way (page cap, or a deep short page).
|
|
53
|
+
*/
|
|
54
|
+
export declare function findBusinessPaged(source: BusinessListSource, ref: string, options?: LookupOptions): Promise<{
|
|
55
|
+
outcome: "matched";
|
|
56
|
+
business: BusinessSummary;
|
|
57
|
+
} | {
|
|
58
|
+
outcome: "absent";
|
|
59
|
+
} | {
|
|
60
|
+
outcome: "inconclusive";
|
|
61
|
+
}>;
|
|
62
|
+
/** Every environment of a business (the server's own paging, to the end). */
|
|
63
|
+
export declare function listAllEnvironments(source: EnvironmentListSource, businessId: string, query?: ListQuery, options?: LookupOptions): Promise<EnvironmentSummary[]>;
|
|
64
|
+
/** Resolve a business id, slug, name or hostname to the business id. */
|
|
65
|
+
export declare function resolveBusiness(source: BusinessListSource, ref: string, options?: LookupOptions): Promise<string>;
|
|
66
|
+
/** Resolve an environment name (case-insensitive) or id to its row. */
|
|
67
|
+
export declare function resolveEnvironment(source: EnvironmentListSource, businessId: string, ref: string, options?: LookupOptions): Promise<EnvironmentSummary>;
|
|
68
|
+
/** Reference resolvers bound to one client. */
|
|
69
|
+
export type Refs = {
|
|
70
|
+
/** A business id, slug, name or hostname → the business id. */
|
|
71
|
+
business(slugOrId: string, options?: LookupOptions): Promise<string>;
|
|
72
|
+
/** An environment name or id → the environment row. */
|
|
73
|
+
environment(businessId: string, nameOrId: string, options?: LookupOptions): Promise<EnvironmentSummary>;
|
|
74
|
+
};
|
|
75
|
+
/**
|
|
76
|
+
* Bind the resolvers to a client:
|
|
77
|
+
*
|
|
78
|
+
* ```ts
|
|
79
|
+
* const refs = createRefs(fs);
|
|
80
|
+
* const businessId = await refs.business("acme");
|
|
81
|
+
* const preview = await refs.environment(businessId, "preview");
|
|
82
|
+
* ```
|
|
83
|
+
*/
|
|
84
|
+
export declare function createRefs(source: RefSource): Refs;
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
import type { CallOptions } from "../operations/define.js";
|
|
2
|
+
/** What the wait calls. `fs` satisfies it. */
|
|
3
|
+
export type FrontendStatusSource = {
|
|
4
|
+
frontend: {
|
|
5
|
+
status(input: {
|
|
6
|
+
businessId: string;
|
|
7
|
+
environmentId?: string;
|
|
8
|
+
ref?: string;
|
|
9
|
+
}, options?: CallOptions): Promise<unknown>;
|
|
10
|
+
};
|
|
11
|
+
};
|
|
12
|
+
export interface BuildWaitResult {
|
|
13
|
+
status: string;
|
|
14
|
+
buildId: string | null;
|
|
15
|
+
ref: string | null;
|
|
16
|
+
error: string | null;
|
|
17
|
+
/** True only when the platform serves this exact successful build as custom-react. */
|
|
18
|
+
activated: boolean;
|
|
19
|
+
/** The currently served build, retained for timeout diagnostics. */
|
|
20
|
+
activeBuildId: string | null;
|
|
21
|
+
/** True when the wait ended because the deadline passed, not a verdict. */
|
|
22
|
+
timedOut: boolean;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* Poll `frontend status` until the build identified by `buildId` settles.
|
|
26
|
+
*
|
|
27
|
+
* Falls back to "the newest build row" when the trigger response carried no id,
|
|
28
|
+
* so a slightly older core still gets useful behaviour instead of hanging.
|
|
29
|
+
*/
|
|
30
|
+
export declare function waitForFrontendBuild(source: FrontendStatusSource, input: {
|
|
31
|
+
businessId: string;
|
|
32
|
+
environmentId?: string | undefined;
|
|
33
|
+
buildId?: string | null;
|
|
34
|
+
/** Immutable Git commit SHA expected from a push or release. */
|
|
35
|
+
ref?: string | undefined;
|
|
36
|
+
timeoutMs: number;
|
|
37
|
+
intervalMs?: number;
|
|
38
|
+
/** Cancels the wait (and the in-flight status read). */
|
|
39
|
+
signal?: AbortSignal;
|
|
40
|
+
/** Injectable so tests don't sleep. */
|
|
41
|
+
sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
|
|
42
|
+
now?: () => number;
|
|
43
|
+
}): Promise<BuildWaitResult>;
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
export { createFartherShore, listOperations, DRY_RUN_NOT_SUPPORTED, UNKNOWN_OPERATION, } from "./surface.js";
|
|
2
|
+
export type { CreateFartherShoreOptions, FartherShore } from "./surface.js";
|
|
3
|
+
export type { FartherShoreApi } from "./api.generated.js";
|
|
4
|
+
export type { DerivedApi, Method, MethodInput, MethodOutput, OperationMeta, } from "./surface-types.js";
|
|
5
|
+
export type { CallOptions, ListQuery, RequestBody, } from "./operations/define.js";
|
|
6
|
+
export type { MethodPath } from "./operations/index.js";
|
|
7
|
+
export * from "./types.js";
|
|
8
|
+
export { collect, paginate, INVALID_PAGE_PARAMETER, NOT_PAGINATED, PAGINATION_NOT_ADVANCING, } from "./helpers/paginate.js";
|
|
9
|
+
export type { PageItem, PaginatedMethod, PaginateOptions, } from "./helpers/paginate.js";
|
|
10
|
+
export { createRefs, findBusinessByRef, findBusinessPaged, listAllBusinesses, listAllEnvironments, resolveBusiness, resolveEnvironment, } from "./helpers/refs.js";
|
|
11
|
+
export type { BusinessListSource, EnvironmentListSource, LookupOptions, RefSource, Refs, } from "./helpers/refs.js";
|
|
12
|
+
export { poll } from "./helpers/poll.js";
|
|
13
|
+
export type { PollOptions, PollResult } from "./helpers/poll.js";
|
|
14
|
+
export { waitForFrontendBuild } from "./helpers/wait-for-frontend-build.js";
|
|
15
|
+
export type { BuildWaitResult, FrontendStatusSource, } from "./helpers/wait-for-frontend-build.js";
|
|
16
|
+
export { createTransport, CLIENT_HEADER, REDIRECT_NOT_FOLLOWED, REQUEST_TIMEOUT_MS, SURFACE_HEADER, } from "./transport.js";
|
|
17
|
+
export type { CreateTransportOptions, OrganizationSummary, OrganizationsResponse, RawRequestOptions, RawResponse, RetryMode, RetryOptions, Transport, TransportRequestOptions, } from "./transport.js";
|
|
18
|
+
export { bearerCredentials, cliExchangeCredentials, consumerCredentials, isExchangeCredential, } from "./credentials.js";
|
|
19
|
+
export type { AccessGrant, AccessTokenRequest, CredentialContext, CredentialSource, } from "./credentials.js";
|
|
20
|
+
export { FartherShoreError, FartherShoreTransportError } from "./errors.js";
|
|
21
|
+
export type { FartherShoreErrorJSON, FartherShoreErrorOptions, RetryDisposition, TransportErrorCode, } from "./errors.js";
|
|
22
|
+
export { diagnosticsOf, errorEnvelopeOf } from "./envelope.js";
|
|
23
|
+
export type { ErrorEnvelope } from "./envelope.js";
|
|
24
|
+
export { CLIENT_VERSION } from "./version.js";
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
import type { AgentStatus, AgentSummary, BulletinPost } from "../types.js";
|
|
2
|
+
type BusinessRef = {
|
|
3
|
+
businessId: string;
|
|
4
|
+
};
|
|
5
|
+
type AgentRef = BusinessRef & {
|
|
6
|
+
role: string;
|
|
7
|
+
};
|
|
8
|
+
export declare const agentOperations: {
|
|
9
|
+
"agents.list": import("./define.js").OperationEntry<BusinessRef, {
|
|
10
|
+
agents: AgentSummary[];
|
|
11
|
+
availableRoles: string[];
|
|
12
|
+
}>;
|
|
13
|
+
"agents.status": import("./define.js").OperationEntry<AgentRef, AgentStatus>;
|
|
14
|
+
"agents.runs.show": import("./define.js").OperationEntry<BusinessRef & {
|
|
15
|
+
role: string;
|
|
16
|
+
} & {
|
|
17
|
+
runId: string;
|
|
18
|
+
}, Record<string, unknown>>;
|
|
19
|
+
"agents.enable": import("./define.js").OperationEntry<BusinessRef & {
|
|
20
|
+
role: string;
|
|
21
|
+
} & {
|
|
22
|
+
config?: Record<string, unknown>;
|
|
23
|
+
}, AgentSummary>;
|
|
24
|
+
"agents.disable": import("./define.js").OperationEntry<BusinessRef & {
|
|
25
|
+
role: string;
|
|
26
|
+
} & {
|
|
27
|
+
config?: Record<string, unknown>;
|
|
28
|
+
}, AgentSummary>;
|
|
29
|
+
"bulletin.list": import("./define.js").OperationEntry<BusinessRef & {
|
|
30
|
+
kind?: string;
|
|
31
|
+
status?: string;
|
|
32
|
+
cursor?: string;
|
|
33
|
+
limit?: number | string;
|
|
34
|
+
}, {
|
|
35
|
+
items: BulletinPost[];
|
|
36
|
+
nextCursor: string | null;
|
|
37
|
+
}>;
|
|
38
|
+
"bulletin.read": import("./define.js").OperationEntry<BusinessRef & {
|
|
39
|
+
postId: string;
|
|
40
|
+
}, BulletinPost>;
|
|
41
|
+
"bulletin.ack": import("./define.js").OperationEntry<BusinessRef & {
|
|
42
|
+
postId: string;
|
|
43
|
+
}, BulletinPost>;
|
|
44
|
+
"bulletin.resolve": import("./define.js").OperationEntry<BusinessRef & {
|
|
45
|
+
postId: string;
|
|
46
|
+
}, BulletinPost>;
|
|
47
|
+
};
|
|
48
|
+
export {};
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import type { AgreementPreview, EconomicAgreement, OffsetPagination, SubjectPins } from "../types.js";
|
|
2
|
+
import { type RequestBody } from "./define.js";
|
|
3
|
+
type BusinessRef = {
|
|
4
|
+
businessId: string;
|
|
5
|
+
};
|
|
6
|
+
type AgreementRef = BusinessRef & {
|
|
7
|
+
agreementId: string;
|
|
8
|
+
};
|
|
9
|
+
export declare const agreementOperations: {
|
|
10
|
+
"agreements.read": import("./define.js").OperationEntry<BusinessRef & {
|
|
11
|
+
subjectId?: string;
|
|
12
|
+
environmentId?: string;
|
|
13
|
+
limit?: number;
|
|
14
|
+
offset?: number;
|
|
15
|
+
}, {
|
|
16
|
+
data: EconomicAgreement[];
|
|
17
|
+
pagination?: OffsetPagination;
|
|
18
|
+
}>;
|
|
19
|
+
"agreements.get": import("./define.js").OperationEntry<AgreementRef, EconomicAgreement>;
|
|
20
|
+
"agreements.pins": import("./define.js").OperationEntry<BusinessRef & {
|
|
21
|
+
subjectId: string;
|
|
22
|
+
}, SubjectPins>;
|
|
23
|
+
"agreements.previewCreate": import("./define.js").OperationEntry<BusinessRef & {
|
|
24
|
+
body: RequestBody;
|
|
25
|
+
}, AgreementPreview>;
|
|
26
|
+
"agreements.create": import("./define.js").OperationEntry<BusinessRef & {
|
|
27
|
+
body: RequestBody & {
|
|
28
|
+
confirmationToken: string;
|
|
29
|
+
};
|
|
30
|
+
}, EconomicAgreement>;
|
|
31
|
+
"agreements.previewAmend": import("./define.js").OperationEntry<BusinessRef & {
|
|
32
|
+
agreementId: string;
|
|
33
|
+
} & {
|
|
34
|
+
body: RequestBody;
|
|
35
|
+
}, AgreementPreview>;
|
|
36
|
+
"agreements.amend": import("./define.js").OperationEntry<BusinessRef & {
|
|
37
|
+
agreementId: string;
|
|
38
|
+
} & {
|
|
39
|
+
body: RequestBody & {
|
|
40
|
+
confirmationToken: string;
|
|
41
|
+
};
|
|
42
|
+
}, EconomicAgreement>;
|
|
43
|
+
};
|
|
44
|
+
export {};
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
type QueryInput = {
|
|
2
|
+
businessId: string;
|
|
3
|
+
/** The verb's query in the analytics DSL (domain, range, filters, …). */
|
|
4
|
+
query: unknown;
|
|
5
|
+
};
|
|
6
|
+
export declare const analyticsOperations: {
|
|
7
|
+
"analytics.timeseries": import("./define.js").OperationEntry<QueryInput, {
|
|
8
|
+
result: unknown;
|
|
9
|
+
}>;
|
|
10
|
+
"analytics.latency": import("./define.js").OperationEntry<QueryInput, {
|
|
11
|
+
result: unknown;
|
|
12
|
+
}>;
|
|
13
|
+
"analytics.top": import("./define.js").OperationEntry<QueryInput, {
|
|
14
|
+
result: unknown;
|
|
15
|
+
}>;
|
|
16
|
+
"analytics.log": import("./define.js").OperationEntry<QueryInput, {
|
|
17
|
+
result: unknown;
|
|
18
|
+
}>;
|
|
19
|
+
"analytics.query": import("./define.js").OperationEntry<QueryInput & {
|
|
20
|
+
verb: string;
|
|
21
|
+
}, {
|
|
22
|
+
result: unknown;
|
|
23
|
+
}>;
|
|
24
|
+
};
|
|
25
|
+
export {};
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
type AuditFilter = {
|
|
2
|
+
organizationId: string;
|
|
3
|
+
action?: string;
|
|
4
|
+
actorUserId?: string;
|
|
5
|
+
decision?: string;
|
|
6
|
+
from?: string;
|
|
7
|
+
to?: string;
|
|
8
|
+
limit?: number;
|
|
9
|
+
};
|
|
10
|
+
type BusinessAuditFilter = AuditFilter & {
|
|
11
|
+
businessId: string;
|
|
12
|
+
};
|
|
13
|
+
export declare const auditNotificationOperations: {
|
|
14
|
+
"auditLogs.read": import("./define.js").OperationEntry<AuditFilter & {
|
|
15
|
+
cursor?: string;
|
|
16
|
+
}, unknown>;
|
|
17
|
+
"auditLogs.business.read": import("./define.js").OperationEntry<AuditFilter & {
|
|
18
|
+
businessId: string;
|
|
19
|
+
} & {
|
|
20
|
+
cursor?: string;
|
|
21
|
+
}, unknown>;
|
|
22
|
+
"auditLogs.export": import("./define.js").OperationEntry<AuditFilter, string>;
|
|
23
|
+
"auditLogs.business.export": import("./define.js").OperationEntry<BusinessAuditFilter, string>;
|
|
24
|
+
"notifications.preferences.read": import("./define.js").OperationEntry<{
|
|
25
|
+
businessId: string;
|
|
26
|
+
}, unknown>;
|
|
27
|
+
"notifications.preferences.update": import("./define.js").OperationEntry<{
|
|
28
|
+
businessId: string;
|
|
29
|
+
master?: boolean;
|
|
30
|
+
categories?: Record<string, boolean>;
|
|
31
|
+
}, unknown>;
|
|
32
|
+
};
|
|
33
|
+
export {};
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import type { OrganizationsResponse } from "../transport.js";
|
|
2
|
+
import type { CallerContext } from "../types.js";
|
|
3
|
+
export declare const authOperations: {
|
|
4
|
+
"auth.context.read": import("./define.js").OperationEntry<void, CallerContext>;
|
|
5
|
+
"auth.context.issue": import("./define.js").OperationEntry<{
|
|
6
|
+
businessId: string;
|
|
7
|
+
externalOrgId: string;
|
|
8
|
+
actorId: string;
|
|
9
|
+
ttlSeconds?: number;
|
|
10
|
+
}, {
|
|
11
|
+
token: string;
|
|
12
|
+
expiresAt: string;
|
|
13
|
+
}>;
|
|
14
|
+
"auth.listOrganizations": import("./define.js").OperationEntry<void, OrganizationsResponse>;
|
|
15
|
+
"auth.selectedOrganization": import("./define.js").OperationEntry<void, string | undefined>;
|
|
16
|
+
};
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
import type { RuntimeTokenSummary } from "../types.js";
|
|
2
|
+
type BusinessRef = {
|
|
3
|
+
businessId: string;
|
|
4
|
+
};
|
|
5
|
+
/**
|
|
6
|
+
* Backends and runtime tokens are per-(business, environment) rows.
|
|
7
|
+
* `environmentId` filters a listing: an environment id, `"production"` for the
|
|
8
|
+
* production rows, or omitted for every scope.
|
|
9
|
+
*/
|
|
10
|
+
type ScopeFilter = BusinessRef & {
|
|
11
|
+
environmentId?: string;
|
|
12
|
+
limit?: number;
|
|
13
|
+
offset?: number;
|
|
14
|
+
};
|
|
15
|
+
export declare const backendOperations: {
|
|
16
|
+
"backends.read": import("./define.js").OperationEntry<ScopeFilter, unknown>;
|
|
17
|
+
"backends.create": import("./define.js").OperationEntry<BusinessRef & {
|
|
18
|
+
name: string;
|
|
19
|
+
slug?: string;
|
|
20
|
+
/** `null` (or omitted) is the production scope. */
|
|
21
|
+
environmentId?: string | null;
|
|
22
|
+
transportMode?: "direct" | "tunnel";
|
|
23
|
+
runner?: "embedded" | "sidecar" | null;
|
|
24
|
+
runtime?: string | null;
|
|
25
|
+
originUrl?: string | null;
|
|
26
|
+
isDefault?: boolean;
|
|
27
|
+
}, unknown>;
|
|
28
|
+
"backends.bind": import("./define.js").OperationEntry<BusinessRef & {
|
|
29
|
+
/** The logical backend slug or id. */
|
|
30
|
+
backend: string;
|
|
31
|
+
environmentId?: string | null;
|
|
32
|
+
originUrl: string;
|
|
33
|
+
}, unknown>;
|
|
34
|
+
"backends.delete": import("./define.js").OperationEntry<BusinessRef & {
|
|
35
|
+
backendId: string;
|
|
36
|
+
}, unknown>;
|
|
37
|
+
"runtimeTokens.read": import("./define.js").OperationEntry<ScopeFilter, unknown>;
|
|
38
|
+
"runtimeTokens.mint": import("./define.js").OperationEntry<BusinessRef & {
|
|
39
|
+
environmentId?: string | null;
|
|
40
|
+
backendId?: string | null;
|
|
41
|
+
kind?: "live" | "test";
|
|
42
|
+
operations?: string[];
|
|
43
|
+
allowedMeters?: string[];
|
|
44
|
+
allowedRoutes?: string[];
|
|
45
|
+
}, unknown>;
|
|
46
|
+
"runtimeTokens.rotate": import("./define.js").OperationEntry<BusinessRef & {
|
|
47
|
+
tokenId: string;
|
|
48
|
+
}, unknown>;
|
|
49
|
+
"runtimeTokens.revoke": import("./define.js").OperationEntry<BusinessRef & {
|
|
50
|
+
tokenId: string;
|
|
51
|
+
}, RuntimeTokenSummary>;
|
|
52
|
+
};
|
|
53
|
+
export {};
|