@farthershore/client 0.0.0-stage → 0.2.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 +196 -0
- package/README.md +252 -2
- package/dist/index.js +7009 -0
- package/dist/types/api.generated.d.ts +1362 -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/generated/schemas.d.ts +3670 -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 +51 -0
- package/dist/types/index.d.ts +24 -0
- package/dist/types/operations/agents.d.ts +240 -0
- package/dist/types/operations/agreements.d.ts +174 -0
- package/dist/types/operations/analytics.d.ts +47 -0
- package/dist/types/operations/audit-notifications.d.ts +90 -0
- package/dist/types/operations/auth.d.ts +24 -0
- package/dist/types/operations/backends.d.ts +255 -0
- package/dist/types/operations/billing.d.ts +71 -0
- package/dist/types/operations/businesses.d.ts +795 -0
- package/dist/types/operations/change-sets.d.ts +462 -0
- package/dist/types/operations/consumers.d.ts +168 -0
- package/dist/types/operations/define.d.ts +102 -0
- package/dist/types/operations/environments.d.ts +55 -0
- package/dist/types/operations/frontend.d.ts +31 -0
- package/dist/types/operations/index.d.ts +4773 -0
- package/dist/types/operations/maker-tokens.d.ts +194 -0
- package/dist/types/operations/organizations.d.ts +373 -0
- package/dist/types/operations/personas.d.ts +136 -0
- package/dist/types/operations/plans-usage.d.ts +84 -0
- package/dist/types/operations/platform.d.ts +455 -0
- package/dist/types/operations/portal.d.ts +442 -0
- package/dist/types/operations/promo-codes.d.ts +139 -0
- package/dist/types/operations/variables.d.ts +188 -0
- package/dist/types/operations/webhooks.d.ts +130 -0
- package/dist/types/surface-types.d.ts +76 -0
- package/dist/types/surface.d.ts +35 -0
- package/dist/types/transport.d.ts +114 -0
- package/dist/types/types.d.ts +440 -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
|
+
}
|