@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.
- package/lib/api.d.ts +165 -0
- package/lib/api.d.ts.map +1 -0
- package/lib/api.js +178 -0
- package/lib/api.js.map +1 -0
- package/lib/codegen/cli.d.ts +29 -0
- package/lib/codegen/cli.d.ts.map +1 -0
- package/lib/codegen/cli.js +165 -0
- package/lib/codegen/cli.js.map +1 -0
- package/lib/codegen/emit.d.ts +129 -0
- package/lib/codegen/emit.d.ts.map +1 -0
- package/lib/codegen/emit.js +105 -0
- package/lib/codegen/emit.js.map +1 -0
- package/lib/codegen/format.d.ts +23 -0
- package/lib/codegen/format.d.ts.map +1 -0
- package/lib/codegen/format.js +28 -0
- package/lib/codegen/format.js.map +1 -0
- package/lib/codegen/generator.d.ts +334 -0
- package/lib/codegen/generator.d.ts.map +1 -0
- package/lib/codegen/generator.js +691 -0
- package/lib/codegen/generator.js.map +1 -0
- package/lib/codegen/graph.d.ts +36 -0
- package/lib/codegen/graph.d.ts.map +1 -0
- package/lib/codegen/graph.js +136 -0
- package/lib/codegen/graph.js.map +1 -0
- package/lib/codegen/members.d.ts +25 -0
- package/lib/codegen/members.d.ts.map +1 -0
- package/lib/codegen/members.js +55 -0
- package/lib/codegen/members.js.map +1 -0
- package/lib/codegen/naming.d.ts +29 -0
- package/lib/codegen/naming.d.ts.map +1 -0
- package/lib/codegen/naming.js +74 -0
- package/lib/codegen/naming.js.map +1 -0
- package/lib/codegen/openapi-cli.d.ts +38 -0
- package/lib/codegen/openapi-cli.d.ts.map +1 -0
- package/lib/codegen/openapi-cli.js +107 -0
- package/lib/codegen/openapi-cli.js.map +1 -0
- package/lib/codegen/openapi.d.ts +115 -0
- package/lib/codegen/openapi.d.ts.map +1 -0
- package/lib/codegen/openapi.js +1220 -0
- package/lib/codegen/openapi.js.map +1 -0
- package/lib/codegen/operations.d.ts +24 -0
- package/lib/codegen/operations.d.ts.map +1 -0
- package/lib/codegen/operations.js +56 -0
- package/lib/codegen/operations.js.map +1 -0
- package/lib/codegen/pagination.d.ts +39 -0
- package/lib/codegen/pagination.d.ts.map +1 -0
- package/lib/codegen/pagination.js +33 -0
- package/lib/codegen/pagination.js.map +1 -0
- package/lib/codegen/prelude.d.ts +15 -0
- package/lib/codegen/prelude.d.ts.map +1 -0
- package/lib/codegen/prelude.js +60 -0
- package/lib/codegen/prelude.js.map +1 -0
- package/lib/error-category.d.ts +28 -0
- package/lib/error-category.d.ts.map +1 -0
- package/lib/error-category.js +46 -0
- package/lib/error-category.js.map +1 -0
- package/lib/errors.d.ts +1 -0
- package/lib/errors.d.ts.map +1 -1
- package/lib/errors.js +1 -0
- package/lib/errors.js.map +1 -1
- package/lib/json-patch.d.ts +25 -32
- package/lib/json-patch.d.ts.map +1 -1
- package/lib/json-patch.js +23 -95
- package/lib/json-patch.js.map +1 -1
- package/lib/pagination.d.ts +37 -51
- package/lib/pagination.d.ts.map +1 -1
- package/lib/pagination.js +72 -90
- package/lib/pagination.js.map +1 -1
- package/lib/protocol-http.d.ts +74 -0
- package/lib/protocol-http.d.ts.map +1 -0
- package/lib/protocol-http.js +554 -0
- package/lib/protocol-http.js.map +1 -0
- package/lib/protocol-rest.d.ts +124 -0
- package/lib/protocol-rest.d.ts.map +1 -0
- package/lib/protocol-rest.js +242 -0
- package/lib/protocol-rest.js.map +1 -0
- package/lib/retry.d.ts +8 -2
- package/lib/retry.d.ts.map +1 -1
- package/lib/retry.js +21 -15
- package/lib/retry.js.map +1 -1
- package/lib/schema.d.ts +7 -8
- package/lib/schema.d.ts.map +1 -1
- package/lib/schema.js +7 -8
- package/lib/schema.js.map +1 -1
- package/lib/trait.d.ts +150 -0
- package/lib/trait.d.ts.map +1 -0
- package/lib/trait.js +107 -0
- package/lib/trait.js.map +1 -0
- package/package.json +18 -75
- package/src/api.ts +446 -0
- package/src/codegen/cli.ts +268 -0
- package/src/codegen/emit.ts +207 -0
- package/src/codegen/format.ts +47 -0
- package/src/codegen/generator.ts +1153 -0
- package/src/codegen/graph.ts +151 -0
- package/src/codegen/members.ts +71 -0
- package/src/codegen/naming.ts +86 -0
- package/src/codegen/openapi-cli.ts +166 -0
- package/src/codegen/openapi.ts +1450 -0
- package/src/codegen/operations.ts +76 -0
- package/src/codegen/pagination.ts +71 -0
- package/src/codegen/prelude.ts +70 -0
- package/src/error-category.ts +84 -0
- package/src/errors.ts +2 -0
- package/src/json-patch.ts +26 -110
- package/src/pagination.ts +86 -142
- package/src/protocol-http.ts +699 -0
- package/src/protocol-rest.ts +367 -0
- package/src/retry.ts +20 -21
- package/src/schema.ts +7 -8
- package/src/trait.ts +238 -0
- package/README.md +0 -30
- package/lib/client.d.ts +0 -167
- package/lib/client.d.ts.map +0 -1
- package/lib/client.js +0 -659
- package/lib/client.js.map +0 -1
- package/lib/schemas.d.ts +0 -60
- package/lib/schemas.d.ts.map +0 -1
- package/lib/schemas.js +0 -79
- package/lib/schemas.js.map +0 -1
- package/lib/sensitive.d.ts +0 -71
- package/lib/sensitive.d.ts.map +0 -1
- package/lib/sensitive.js +0 -96
- package/lib/sensitive.js.map +0 -1
- package/lib/traits.d.ts +0 -421
- package/lib/traits.d.ts.map +0 -1
- package/lib/traits.js +0 -737
- package/lib/traits.js.map +0 -1
- package/src/client.ts +0 -1177
- package/src/schemas.ts +0 -128
- package/src/sensitive.ts +0 -119
- 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
|
package/lib/client.d.ts.map
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
|