@distilled.cloud/core 0.30.3 → 1.0.0-rc.2

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 (132) hide show
  1. package/lib/api.d.ts +165 -0
  2. package/lib/api.d.ts.map +1 -0
  3. package/lib/api.js +178 -0
  4. package/lib/api.js.map +1 -0
  5. package/lib/codegen/cli.d.ts +29 -0
  6. package/lib/codegen/cli.d.ts.map +1 -0
  7. package/lib/codegen/cli.js +165 -0
  8. package/lib/codegen/cli.js.map +1 -0
  9. package/lib/codegen/emit.d.ts +129 -0
  10. package/lib/codegen/emit.d.ts.map +1 -0
  11. package/lib/codegen/emit.js +105 -0
  12. package/lib/codegen/emit.js.map +1 -0
  13. package/lib/codegen/format.d.ts +23 -0
  14. package/lib/codegen/format.d.ts.map +1 -0
  15. package/lib/codegen/format.js +28 -0
  16. package/lib/codegen/format.js.map +1 -0
  17. package/lib/codegen/generator.d.ts +334 -0
  18. package/lib/codegen/generator.d.ts.map +1 -0
  19. package/lib/codegen/generator.js +691 -0
  20. package/lib/codegen/generator.js.map +1 -0
  21. package/lib/codegen/graph.d.ts +36 -0
  22. package/lib/codegen/graph.d.ts.map +1 -0
  23. package/lib/codegen/graph.js +136 -0
  24. package/lib/codegen/graph.js.map +1 -0
  25. package/lib/codegen/members.d.ts +25 -0
  26. package/lib/codegen/members.d.ts.map +1 -0
  27. package/lib/codegen/members.js +55 -0
  28. package/lib/codegen/members.js.map +1 -0
  29. package/lib/codegen/naming.d.ts +29 -0
  30. package/lib/codegen/naming.d.ts.map +1 -0
  31. package/lib/codegen/naming.js +74 -0
  32. package/lib/codegen/naming.js.map +1 -0
  33. package/lib/codegen/openapi-cli.d.ts +38 -0
  34. package/lib/codegen/openapi-cli.d.ts.map +1 -0
  35. package/lib/codegen/openapi-cli.js +107 -0
  36. package/lib/codegen/openapi-cli.js.map +1 -0
  37. package/lib/codegen/openapi.d.ts +115 -0
  38. package/lib/codegen/openapi.d.ts.map +1 -0
  39. package/lib/codegen/openapi.js +1220 -0
  40. package/lib/codegen/openapi.js.map +1 -0
  41. package/lib/codegen/operations.d.ts +24 -0
  42. package/lib/codegen/operations.d.ts.map +1 -0
  43. package/lib/codegen/operations.js +56 -0
  44. package/lib/codegen/operations.js.map +1 -0
  45. package/lib/codegen/pagination.d.ts +39 -0
  46. package/lib/codegen/pagination.d.ts.map +1 -0
  47. package/lib/codegen/pagination.js +33 -0
  48. package/lib/codegen/pagination.js.map +1 -0
  49. package/lib/codegen/prelude.d.ts +15 -0
  50. package/lib/codegen/prelude.d.ts.map +1 -0
  51. package/lib/codegen/prelude.js +60 -0
  52. package/lib/codegen/prelude.js.map +1 -0
  53. package/lib/error-category.d.ts +28 -0
  54. package/lib/error-category.d.ts.map +1 -0
  55. package/lib/error-category.js +46 -0
  56. package/lib/error-category.js.map +1 -0
  57. package/lib/errors.d.ts +1 -0
  58. package/lib/errors.d.ts.map +1 -1
  59. package/lib/errors.js +1 -0
  60. package/lib/errors.js.map +1 -1
  61. package/lib/json-patch.d.ts +25 -32
  62. package/lib/json-patch.d.ts.map +1 -1
  63. package/lib/json-patch.js +23 -95
  64. package/lib/json-patch.js.map +1 -1
  65. package/lib/pagination.d.ts +37 -51
  66. package/lib/pagination.d.ts.map +1 -1
  67. package/lib/pagination.js +72 -90
  68. package/lib/pagination.js.map +1 -1
  69. package/lib/protocol-http.d.ts +74 -0
  70. package/lib/protocol-http.d.ts.map +1 -0
  71. package/lib/protocol-http.js +554 -0
  72. package/lib/protocol-http.js.map +1 -0
  73. package/lib/protocol-rest.d.ts +124 -0
  74. package/lib/protocol-rest.d.ts.map +1 -0
  75. package/lib/protocol-rest.js +242 -0
  76. package/lib/protocol-rest.js.map +1 -0
  77. package/lib/retry.d.ts +8 -2
  78. package/lib/retry.d.ts.map +1 -1
  79. package/lib/retry.js +21 -15
  80. package/lib/retry.js.map +1 -1
  81. package/lib/schema.d.ts +7 -8
  82. package/lib/schema.d.ts.map +1 -1
  83. package/lib/schema.js +7 -8
  84. package/lib/schema.js.map +1 -1
  85. package/lib/trait.d.ts +150 -0
  86. package/lib/trait.d.ts.map +1 -0
  87. package/lib/trait.js +107 -0
  88. package/lib/trait.js.map +1 -0
  89. package/package.json +18 -75
  90. package/src/api.ts +446 -0
  91. package/src/codegen/cli.ts +268 -0
  92. package/src/codegen/emit.ts +207 -0
  93. package/src/codegen/format.ts +47 -0
  94. package/src/codegen/generator.ts +1153 -0
  95. package/src/codegen/graph.ts +151 -0
  96. package/src/codegen/members.ts +71 -0
  97. package/src/codegen/naming.ts +86 -0
  98. package/src/codegen/openapi-cli.ts +166 -0
  99. package/src/codegen/openapi.ts +1450 -0
  100. package/src/codegen/operations.ts +76 -0
  101. package/src/codegen/pagination.ts +71 -0
  102. package/src/codegen/prelude.ts +70 -0
  103. package/src/error-category.ts +84 -0
  104. package/src/errors.ts +2 -0
  105. package/src/json-patch.ts +26 -110
  106. package/src/pagination.ts +86 -142
  107. package/src/protocol-http.ts +699 -0
  108. package/src/protocol-rest.ts +367 -0
  109. package/src/retry.ts +20 -21
  110. package/src/schema.ts +7 -8
  111. package/src/trait.ts +238 -0
  112. package/README.md +0 -30
  113. package/lib/client.d.ts +0 -167
  114. package/lib/client.d.ts.map +0 -1
  115. package/lib/client.js +0 -659
  116. package/lib/client.js.map +0 -1
  117. package/lib/schemas.d.ts +0 -60
  118. package/lib/schemas.d.ts.map +0 -1
  119. package/lib/schemas.js +0 -79
  120. package/lib/schemas.js.map +0 -1
  121. package/lib/sensitive.d.ts +0 -71
  122. package/lib/sensitive.d.ts.map +0 -1
  123. package/lib/sensitive.js +0 -96
  124. package/lib/sensitive.js.map +0 -1
  125. package/lib/traits.d.ts +0 -421
  126. package/lib/traits.d.ts.map +0 -1
  127. package/lib/traits.js +0 -737
  128. package/lib/traits.js.map +0 -1
  129. package/src/client.ts +0 -1177
  130. package/src/schemas.ts +0 -128
  131. package/src/sensitive.ts +0 -119
  132. package/src/traits.ts +0 -996
package/src/trait.ts ADDED
@@ -0,0 +1,238 @@
1
+ export const annotationMetaSymbol = Symbol.for(
2
+ "@distilled.cloud/core/annotation-meta",
3
+ );
4
+
5
+ type Annotatable = {
6
+ annotate(annotations: any): Annotatable;
7
+ };
8
+
9
+ export interface Annotation {
10
+ <A extends Annotatable>(schema: A): A;
11
+ readonly [annotationMetaSymbol]: Array<{
12
+ symbol: symbol | string;
13
+ value: unknown;
14
+ }>;
15
+ readonly [key: symbol]: unknown;
16
+ readonly [key: string]: unknown;
17
+ }
18
+
19
+ /**
20
+ * Build a pipeable schema annotation carrying `value` under `sym`. Exported
21
+ * so SDK packages can define their own protocol traits (e.g. cloudflare's
22
+ * envelope traits, aws's smithy traits) with the same mechanics as the
23
+ * generic ones here. Keys may be symbols or plain strings — effect Schema
24
+ * annotation dictionaries accept both.
25
+ */
26
+ export function makeAnnotation<T>(sym: symbol | string, value: T): Annotation {
27
+ const fn = <A extends Annotatable>(schema: A): A =>
28
+ schema.annotate({ [sym]: value }) as A;
29
+ (fn as any)[annotationMetaSymbol] = [{ symbol: sym, value }];
30
+ (fn as any)[sym] = value;
31
+ return fn as Annotation;
32
+ }
33
+
34
+ /**
35
+ * Combine several annotations into one — needed where only a single
36
+ * annotations object can be supplied (e.g. the second argument of
37
+ * `S.Class`).
38
+ */
39
+ export function all(...annotations: Annotation[]): Annotation {
40
+ const entries: Array<{ symbol: symbol | string; value: unknown }> = [];
41
+ const raw: Record<symbol | string, unknown> = {};
42
+ for (const a of annotations) {
43
+ for (const entry of a[annotationMetaSymbol]) {
44
+ entries.push(entry);
45
+ raw[entry.symbol] = entry.value;
46
+ }
47
+ }
48
+ const fn = <A extends Annotatable>(schema: A): A => schema.annotate(raw) as A;
49
+ (fn as any)[annotationMetaSymbol] = entries;
50
+ for (const { symbol: sym, value } of entries) {
51
+ (fn as any)[sym] = value;
52
+ }
53
+ return fn as Annotation;
54
+ }
55
+
56
+ //#region Generic Operation traits
57
+ //#endregion
58
+
59
+ //#region Generic Http traits
60
+
61
+ export interface HttpTrait {
62
+ readonly method:
63
+ | "GET"
64
+ | "POST"
65
+ | "PUT"
66
+ | "PATCH"
67
+ | "DELETE"
68
+ | "HEAD"
69
+ | "OPTIONS";
70
+ /** URI template relative to the service base URL, e.g. `/accounts/{account_id}/foo`. */
71
+ readonly uri: string;
72
+ /** Default success status code (a `ResponseCode()` member can still read the actual code). */
73
+ readonly code?: number;
74
+ /**
75
+ * Request body encoding. Default is JSON; `"multipart"` sends
76
+ * multipart/form-data — body members become form parts (objects
77
+ * JSON-encoded) and members marked `FormDataFile()` append their files.
78
+ * `"form-urlencoded"` sends application/x-www-form-urlencoded with
79
+ * Stripe-style bracket notation for nested objects and arrays (see
80
+ * `buildRequest`).
81
+ */
82
+ readonly contentType?: "multipart" | "form-urlencoded";
83
+ /**
84
+ * Explicit `Content-Type` for a whole-body (`HttpBody()`) member carrying a
85
+ * preserialized payload, when the API requires a specific media type rather
86
+ * than JSON (e.g. `application/x-ndjson` for Vectorize insert/upsert). The
87
+ * member value is sent verbatim (string/bytes) under this media type.
88
+ */
89
+ readonly bodyMediaType?: string;
90
+ /**
91
+ * Explicit `Accept` for the operation, when the API serves more than one
92
+ * response media type. Atlas pins an API version this way (e.g.
93
+ * `application/vnd.atlas.2024-05-30+json` — `application/json` alone is a
94
+ * 406). Protocols that don't read it fall back to their own default.
95
+ */
96
+ readonly accept?: string;
97
+ }
98
+
99
+ export const httpSymbol = Symbol.for("@distilled.cloud/core/http");
100
+ /**
101
+ * Operation-level HTTP binding: the request method + URI template. Stamped on
102
+ * the input schema so the protocol can build the request line. URI `{labels}`
103
+ * are filled from members marked with `Label()`.
104
+ */
105
+ export const Http = (trait: HttpTrait) => makeAnnotation(httpSymbol, trait);
106
+
107
+ export const labelSymbol = Symbol.for("@distilled.cloud/core/http/label");
108
+ /** Bind a member to a `{name}` placeholder in the operation's URI template. */
109
+ export const Label = (name?: string) =>
110
+ makeAnnotation(labelSymbol, name ?? true);
111
+
112
+ export const responseCodeSymbol = Symbol.for(
113
+ "@distilled.cloud/core/http/response-code",
114
+ );
115
+ export const ResponseCode = () => makeAnnotation(responseCodeSymbol, true);
116
+
117
+ export const headerSymbol = Symbol.for("@distilled.cloud/core/http/header");
118
+ export const Header = (name?: string) =>
119
+ makeAnnotation(headerSymbol, name ?? true);
120
+
121
+ export const bodySymbol = Symbol.for("@distilled.cloud/core/http/body");
122
+ export const Body = (name?: string) => makeAnnotation(bodySymbol, name ?? true);
123
+
124
+ export const querySymbol = Symbol.for("@distilled.cloud/core/http/query");
125
+ export const Query = (name?: string) =>
126
+ makeAnnotation(querySymbol, name ?? true);
127
+
128
+ export const deepQuerySymbol = Symbol.for(
129
+ "@distilled.cloud/core/http/deep-query",
130
+ );
131
+ /**
132
+ * Binds a struct-valued input member to a family of DOTTED query parameters:
133
+ * `{ account: { id, name } }` with `DeepQuery("account")` serializes as
134
+ * `?account.id=…&account.name=…` (null/undefined entries skipped). This is
135
+ * how several list endpoints model their filters on the wire (e.g.
136
+ * Cloudflare zones list `account.id` / `account.name`) while the TS surface
137
+ * keeps the nested-object shape (v0 parity).
138
+ */
139
+ export const DeepQuery = (name?: string) =>
140
+ makeAnnotation(deepQuerySymbol, name ?? true);
141
+
142
+ export const httpBodySymbol = Symbol.for("@distilled.cloud/core/http-body");
143
+ /**
144
+ * Marks the input member whose value IS the entire request body (raw arrays/
145
+ * scalars — e.g. endpoints that POST a bare JSON array). Mirrors
146
+ * `smithy.api#httpPayload`.
147
+ */
148
+ export const HttpBody = () => makeAnnotation(httpBodySymbol, true);
149
+
150
+ export const formDataFileSymbol = Symbol.for(
151
+ "@distilled.cloud/core/form-data-file",
152
+ );
153
+ /**
154
+ * Marks an input member holding `File`/`Blob` parts for a multipart upload
155
+ * (`Http({ contentType: "multipart" })`). Each file is appended to the form
156
+ * under its own filename.
157
+ */
158
+ export const FormDataFile = () => makeAnnotation(formDataFileSymbol, true);
159
+ //#endregion
160
+
161
+ //#region Generic JSON traits
162
+
163
+ export const keyDictionarySymbol = Symbol.for(
164
+ "@distilled.cloud/core/key-dictionary",
165
+ );
166
+ /**
167
+ * Deep TS-name→wire-name key dictionary for members whose full structure is
168
+ * not modeled (opaque `Document` content). The protocol renames any matching
169
+ * key at any depth on encode (and the reverse on decode); keys not in the
170
+ * dictionary pass through verbatim.
171
+ *
172
+ * A value may be an array of wire names when the API itself is inconsistent
173
+ * (e.g. queues consumer responses name the worker script `script_name` on
174
+ * create/update but `script` on get/list): the first entry is the canonical
175
+ * wire name used on encode; decode maps every listed spelling back to the
176
+ * TS name.
177
+ */
178
+ export type KeyDictionaryEntries = Record<
179
+ string,
180
+ string | ReadonlyArray<string>
181
+ >;
182
+
183
+ export const KeyDictionary = (dict: KeyDictionaryEntries) =>
184
+ makeAnnotation(keyDictionarySymbol, dict);
185
+
186
+ export const unionCasesSymbol = Symbol.for("@distilled.cloud/core/union-cases");
187
+ /**
188
+ * Marks an opaque schema standing in for a discriminated union of object
189
+ * cases, carrying each case's TS-facing key set. For APIs that return every
190
+ * case's keys with `null` for the inactive ones, the protocol uses these key
191
+ * sets to pick the active case and drop the others, so consumers' `"key" in
192
+ * value` discrimination works.
193
+ */
194
+ export const UnionCases = (cases: ReadonlyArray<ReadonlyArray<string>>) =>
195
+ makeAnnotation(unionCasesSymbol, cases);
196
+ //#endregion
197
+
198
+ //#region Error matcher traits
199
+
200
+ export const errorMatchersSymbol = Symbol.for(
201
+ "@distilled.cloud/core/error-matchers",
202
+ );
203
+
204
+ /**
205
+ * One wire-matching rule for a typed error class. A matcher matches a wire
206
+ * failure when every present field matches: `code` equals the wire error's
207
+ * code, `status` equals the HTTP status, and `message` either equals the
208
+ * error message (string form) or satisfies `includes` (substring) /
209
+ * `matches` (regex). A matcher with no fields matches nothing.
210
+ */
211
+ export interface ErrorMatcher {
212
+ readonly code?: number;
213
+ readonly status?: number;
214
+ readonly message?:
215
+ | string
216
+ | { readonly includes?: string; readonly matches?: string };
217
+ }
218
+
219
+ /**
220
+ * Stamp wire-matching rules onto a generated error class. Protocols consult
221
+ * these to decide which of an operation's declared error classes a failed
222
+ * response should surface as (most specific matcher wins; ties break by
223
+ * declaration order — see `matchTypedError` in `core/protocol-http`).
224
+ */
225
+ export const applyErrorMatchers = <C>(
226
+ cls: C,
227
+ matchers: ReadonlyArray<ErrorMatcher>,
228
+ ): C => {
229
+ (cls as any)[errorMatchersSymbol] = matchers;
230
+ return cls;
231
+ };
232
+
233
+ /** Read the matchers stamped on an error class, if any. */
234
+ export const getErrorMatchers = (
235
+ cls: unknown,
236
+ ): ReadonlyArray<ErrorMatcher> | undefined =>
237
+ (cls as any)?.[errorMatchersSymbol];
238
+ //#endregion
package/README.md DELETED
@@ -1,30 +0,0 @@
1
- # @distilled.cloud/sdk-core
2
-
3
- Shared infrastructure for all Distilled SDKs. Provides the client factory, HTTP trait annotations, error classes, error categories, pagination utilities, and retry policies.
4
-
5
- ## What's in here
6
-
7
- - **`client.ts`** — `API.make()` and `API.makePaginated()` factories that create Effect operations from annotated schemas
8
- - **`traits.ts`** — Schema annotations for HTTP bindings (`T.Http`, `T.PathParam`, `T.HttpHeader`, `T.JsonName`, etc.)
9
- - **`errors.ts`** — Base error classes (`NotFound`, `Unauthorized`, `Forbidden`, `TooManyRequests`, etc.) with status code matching
10
- - **`category.ts`** — Error categories (`AuthError`, `ThrottlingError`, `ServerError`, etc.) for retry logic and semantic grouping
11
- - **`pagination.ts`** — `paginatePages`/`paginateItems` stream utilities
12
- - **`retry.ts`** — Retry policy configuration
13
- - **`sensitive.ts`** — Sensitive data schemas (wraps values in `Redacted`)
14
- - **`json-patch.ts`** — JSON Patch (RFC 6902) implementation for spec patching
15
-
16
- ## Usage
17
-
18
- This package is not intended to be used directly. It's a dependency of the provider SDKs (`@distilled.cloud/aws`, `@distilled.cloud/cloudflare`, etc.).
19
-
20
- ```typescript
21
- // Provider packages import from core like this:
22
- import { makeAPI } from "@distilled.cloud/sdk-core/client";
23
- import * as T from "@distilled.cloud/sdk-core/traits";
24
- import { NotFound, Forbidden } from "@distilled.cloud/sdk-core/errors";
25
- import * as Category from "@distilled.cloud/sdk-core/category";
26
- ```
27
-
28
- ## License
29
-
30
- MIT
package/lib/client.d.ts DELETED
@@ -1,167 +0,0 @@
1
- import * as Context from "effect/Context";
2
- import * as Effect from "effect/Effect";
3
- import * as Schema from "effect/Schema";
4
- import * as Stream from "effect/Stream";
5
- import { type PaginatedTrait, type PaginationStrategy } from "./pagination.ts";
6
- import { type Policy as RetryPolicy } from "./retry.ts";
7
- import * as Traits from "./traits.ts";
8
- /**
9
- * An operation that can be used in two ways:
10
- * 1. Direct call: `yield* operation(input)` - returns Effect with requirements
11
- * 2. Yield first: `const fn = yield* operation` - captures services, returns requirement-free function
12
- */
13
- export type OperationMethod<I, A, E, R, RequestOptions = never> = Effect.Effect<(input: I, requestOptions?: RequestOptions) => Effect.Effect<A, E, never>, never, R> & ((input: I, requestOptions?: RequestOptions) => Effect.Effect<A, E, R>);
14
- /**
15
- * A paginated operation that additionally has `.pages()` and `.items()` methods.
16
- */
17
- type PaginatedItem<A> = A extends ReadonlyArray<infer Item> ? Item : A extends {
18
- result: ReadonlyArray<infer Item>;
19
- } ? Item : A extends {
20
- result?: ReadonlyArray<infer Item> | null | undefined;
21
- } ? Item : A extends {
22
- result: {
23
- items: ReadonlyArray<infer Item>;
24
- };
25
- } ? Item : A extends {
26
- result?: {
27
- items?: ReadonlyArray<infer Item> | null | undefined;
28
- } | null | undefined;
29
- } ? Item : unknown;
30
- export type PaginatedOperationMethod<I, A, E, R, RequestOptions = never> = OperationMethod<I, A, E, R, RequestOptions> & {
31
- pages: (input: I, requestOptions?: RequestOptions) => Stream.Stream<A, E, R>;
32
- items: (input: I, requestOptions?: RequestOptions) => Stream.Stream<PaginatedItem<A>, E, R>;
33
- };
34
- type ResolvedClientCredentials<Creds> = Creds extends Effect.Effect<infer Resolved, any, any> ? Resolved : Creds;
35
- /**
36
- * Configuration for the API client factory.
37
- * SDKs provide this to customize how errors are matched and credentials are applied.
38
- */
39
- export interface ClientConfig<Creds, RequestOptions = never> {
40
- /** The credentials service tag */
41
- credentials: Context.ServiceClass<any, any, Effect.Effect<Creds>>;
42
- /** Get the base URL from credentials */
43
- getBaseUrl: (creds: ResolvedClientCredentials<Creds>) => string;
44
- /** Get authorization header(s) from credentials */
45
- getAuthHeaders: (creds: ResolvedClientCredentials<Creds>) => Record<string, string>;
46
- /**
47
- * Map provider-specific per-call request options into transport headers.
48
- * Request options are intentionally separate from the operation input and
49
- * are never passed through the body/query/path schema encoder.
50
- */
51
- getRequestHeaders?: (requestOptions: RequestOptions | undefined, context: {
52
- input: Record<string, unknown>;
53
- method: string;
54
- pathTemplate: string;
55
- parts: Traits.RequestParts;
56
- credentials: ResolvedClientCredentials<Creds>;
57
- }) => Record<string, string>;
58
- /** Match an error response body to a typed error.
59
- * Should return Effect.fail(error) for known errors,
60
- * or Effect.fail(fallbackError) for unknown errors.
61
- * The optional `errors` parameter provides per-operation typed error classes.
62
- * The optional `headers` parameter is the response header bag (lowercase
63
- * keys) — for retryable status codes, pass `retryAfter: parseRetryAfterForStatus(status, headers)`
64
- * from `@distilled.cloud/core/retry-after` when a standard `Retry-After` /
65
- * `RateLimit` hint is present; omit `retryAfter` when there is no hint (the
66
- * default retry policy still uses exponential backoff). The status-gated
67
- * helper avoids attaching stale `retryAfter` to non-retryable classes
68
- * (BadRequest/401/404/etc.). The maximum honored hint is capped (default
69
- * 60s) — override with \`DISTILLED_SERVER_RETRY_HINT_CAP_MS\` or provide
70
- * \`ServerRetryHintCapMs\` via \`Layer\` from \`@distilled.cloud/core/retry\`.
71
- */
72
- matchError: (status: number, body: unknown, errors?: readonly ApiErrorClass[], headers?: Record<string, string | undefined>) => Effect.Effect<never, unknown>;
73
- /** Parse error class for schema decode failures */
74
- ParseError: new (props: {
75
- body: unknown;
76
- cause: unknown;
77
- }) => unknown;
78
- /**
79
- * Optional transform applied to the response body before schema decoding.
80
- * For example, Cloudflare wraps responses in `{ result: <data>, ... }`.
81
- */
82
- transformResponse?: (body: unknown) => unknown;
83
- /**
84
- * Optional predicate identifying a successful-status (2xx) response whose
85
- * body is actually an error envelope. Some APIs (notably Cloudflare) return
86
- * errors with HTTP 200 and a `success: false` flag instead of a 4xx status.
87
- * When this returns `true`, the body is routed through {@link matchError}
88
- * (with the operation's typed `errors`) exactly like a status>=400 response,
89
- * so per-operation typed error matchers still apply. SDKs that always signal
90
- * errors via status codes leave this unset (the default no-ops).
91
- */
92
- isErrorEnvelope?: (body: unknown) => boolean;
93
- /**
94
- * Optional transform applied to encoded request parts before building the
95
- * outbound HTTP request.
96
- */
97
- transformRequestParts?: (input: {
98
- input: Record<string, unknown>;
99
- method: string;
100
- pathTemplate: string;
101
- parts: Traits.RequestParts;
102
- requestOptions: RequestOptions | undefined;
103
- }) => Traits.RequestParts;
104
- /**
105
- * The SDK's `Retry` Context.Service tag. Each per-SDK client wires its
106
- * own tag here so callers can install a blanket policy at the layer
107
- * level (e.g. `myEffect.pipe(Cloudflare.Retry.transient)`) and have
108
- * every API call below it pick it up — same pattern as
109
- * `packages/aws/src/client/api.ts`.
110
- *
111
- * `makeAPI` reads the policy via `Effect.serviceOption(retry)` on every
112
- * call and falls back to `Retry.makeDefault` (transient/throttling/server
113
- * with capped exponential backoff + jitter, 5 attempts) when no policy
114
- * is provided.
115
- */
116
- retry: Context.Key<any, RetryPolicy>;
117
- }
118
- /**
119
- * Base API error type - any error class with at least a _tag and message.
120
- * Uses `new (...args: any[])` to accommodate error classes with extra fields (e.g. `code`).
121
- */
122
- export type ApiErrorClass = {
123
- new (...args: any[]): {
124
- readonly _tag: string;
125
- readonly message: string;
126
- };
127
- };
128
- /**
129
- * Operation configuration with optional operation-specific errors.
130
- * Supports both `inputSchema`/`outputSchema` and `input`/`output` aliases.
131
- */
132
- export interface OperationConfig<I extends Schema.Top, O extends Schema.Top, E extends readonly ApiErrorClass[] = readonly ApiErrorClass[]> {
133
- inputSchema?: I;
134
- outputSchema?: O;
135
- /** Alias for inputSchema (used by Cloudflare/GCP generators) */
136
- input?: I;
137
- /** Alias for outputSchema (used by Cloudflare/GCP generators) */
138
- output?: O;
139
- errors?: E;
140
- }
141
- /**
142
- * Paginated operation configuration.
143
- */
144
- export interface PaginatedOperationConfig<I extends Schema.Top, O extends Schema.Top, E extends readonly ApiErrorClass[] = readonly ApiErrorClass[]> extends OperationConfig<I, O, E> {
145
- pagination?: PaginatedTrait;
146
- }
147
- /**
148
- * Creates an API namespace bound to a specific SDK's client configuration.
149
- *
150
- * @example
151
- * ```ts
152
- * // In planetscale-sdk/src/client.ts
153
- * export const API = makeAPI({
154
- * credentials: Credentials,
155
- * getBaseUrl: (c) => c.apiBaseUrl,
156
- * getAuthHeaders: (c) => ({ Authorization: c.token }),
157
- * matchError: matchPlanetScaleError,
158
- * ParseError: PlanetScaleParseError,
159
- * });
160
- * ```
161
- */
162
- export declare const makeAPI: <Creds, RequestOptions = never>(config: ClientConfig<Creds, RequestOptions>) => {
163
- make: <I extends Schema.Top, O extends Schema.Top, const E extends readonly ApiErrorClass[] = readonly []>(configFn: () => OperationConfig<I, O, E>) => OperationMethod<Schema.Schema.Type<I>, Schema.Schema.Type<O>, InstanceType<E[number]>, Creds, RequestOptions>;
164
- makePaginated: <I extends Schema.Top, O extends Schema.Top, const E extends readonly ApiErrorClass[] = readonly []>(configFn: () => PaginatedOperationConfig<I, O, E>, paginateFn?: PaginationStrategy) => PaginatedOperationMethod<Schema.Schema.Type<I>, Schema.Schema.Type<O>, InstanceType<E[number]>, Creds, RequestOptions>;
165
- };
166
- export {};
167
- //# sourceMappingURL=client.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}