@sdk-it/typescript 0.46.11 → 0.47.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/README.md +79 -12
- package/dist/index.d.ts +2 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1399 -1538
- package/dist/index.js.map +4 -4
- package/dist/lib/agent/ai-sdk.d.ts +2 -1
- package/dist/lib/agent/ai-sdk.d.ts.map +1 -1
- package/dist/lib/agent/openai-agents.d.ts +2 -1
- package/dist/lib/agent/openai-agents.d.ts.map +1 -1
- package/dist/lib/client-name.d.ts +16 -0
- package/dist/lib/client-name.d.ts.map +1 -0
- package/dist/lib/client.d.ts +25 -1
- package/dist/lib/client.d.ts.map +1 -1
- package/dist/lib/emitters/interface.d.ts +4 -2
- package/dist/lib/emitters/interface.d.ts.map +1 -1
- package/dist/lib/emitters/snippet.d.ts.map +1 -1
- package/dist/lib/emitters/zod.d.ts +13 -3
- package/dist/lib/emitters/zod.d.ts.map +1 -1
- package/dist/lib/folder-index.d.ts +7 -0
- package/dist/lib/folder-index.d.ts.map +1 -0
- package/dist/lib/generate.d.ts +28 -3
- package/dist/lib/generate.d.ts.map +1 -1
- package/dist/lib/generator.d.ts +28 -29
- package/dist/lib/generator.d.ts.map +1 -1
- package/dist/lib/group-identifier.d.ts +7 -0
- package/dist/lib/group-identifier.d.ts.map +1 -0
- package/dist/lib/import-utilities.d.ts.map +1 -1
- package/dist/lib/input-schema-name.d.ts +4 -0
- package/dist/lib/input-schema-name.d.ts.map +1 -0
- package/dist/lib/model-name.d.ts +7 -0
- package/dist/lib/model-name.d.ts.map +1 -0
- package/dist/lib/module-file.d.ts +7 -0
- package/dist/lib/module-file.d.ts.map +1 -0
- package/dist/lib/one-module.d.ts +57 -0
- package/dist/lib/one-module.d.ts.map +1 -0
- package/dist/lib/options.d.ts +4 -6
- package/dist/lib/options.d.ts.map +1 -1
- package/dist/lib/readme/prop.emitter.d.ts +4 -4
- package/dist/lib/readme/prop.emitter.d.ts.map +1 -1
- package/dist/lib/readme/readme.d.ts.map +1 -1
- package/dist/lib/references.d.ts +43 -0
- package/dist/lib/references.d.ts.map +1 -0
- package/dist/lib/root-exports.d.ts +6 -0
- package/dist/lib/root-exports.d.ts.map +1 -0
- package/dist/lib/sdk.d.ts +17 -27
- package/dist/lib/sdk.d.ts.map +1 -1
- package/dist/lib/security.d.ts +2 -3
- package/dist/lib/security.d.ts.map +1 -1
- package/dist/lib/server-urls.d.ts.map +1 -1
- package/dist/lib/status-map.d.ts +2 -2
- package/dist/lib/status-map.d.ts.map +1 -1
- package/dist/lib/typescript-snippet.d.ts +4 -8
- package/dist/lib/typescript-snippet.d.ts.map +1 -1
- package/package.json +19 -6
- package/dist/lib/pagination-emit.d.ts +0 -3
- package/dist/lib/pagination-emit.d.ts.map +0 -1
- package/dist/lib/response-shape.d.ts +0 -22
- package/dist/lib/response-shape.d.ts.map +0 -1
- package/dist/lib/style.d.ts +0 -4
- package/dist/lib/style.d.ts.map +0 -1
package/README.md
CHANGED
|
@@ -19,26 +19,55 @@ generated in `minimal` mode.
|
|
|
19
19
|
import { loadSpec } from '@sdk-it/spec';
|
|
20
20
|
import { generate } from '@sdk-it/typescript';
|
|
21
21
|
|
|
22
|
-
const spec = await loadSpec('https://api.openstatus.dev/openapi.yaml');
|
|
22
|
+
const { spec } = await loadSpec('https://api.openstatus.dev/openapi.yaml');
|
|
23
23
|
|
|
24
24
|
await generate(spec, {
|
|
25
25
|
output: './src/generated/openstatus',
|
|
26
26
|
mode: 'minimal',
|
|
27
27
|
name: 'OpenStatus',
|
|
28
|
+
packageName: '@acme/openstatus',
|
|
28
29
|
});
|
|
29
30
|
```
|
|
30
31
|
|
|
31
|
-
`loadSpec` accepts a URL or a local path and reads JSON or YAML. `name`
|
|
32
|
-
|
|
33
|
-
|
|
32
|
+
`loadSpec` accepts a URL or a local path and reads JSON or YAML. The required `name`
|
|
33
|
+
sets the names of the generated exports, such as `createOpenStatus` and
|
|
34
|
+
`OpenStatusEndpoints`. The required `packageName` is the npm name of the
|
|
35
|
+
generated package: the README installs and imports it, and `full` mode writes
|
|
36
|
+
it to `package.json`. `generate` refuses an empty `packageName`. `minimal` mode
|
|
37
|
+
writes client source files directly to `output`.
|
|
38
|
+
|
|
39
|
+
The exports use `name` in PascalCase. `generate`, `render` and `renderModule`
|
|
40
|
+
refuse a name that does not become a TypeScript identifier (`'2024 api'`
|
|
41
|
+
becomes `2024Api`), whose default instance is a reserved word (`'Default'`), or
|
|
42
|
+
that makes a name the SDK already declares or exports (`'Request'` makes the
|
|
43
|
+
default instance `request`, and the SDK root exports `request`).
|
|
44
|
+
`clientName(name)` gives the name that the exports use, and throws the same
|
|
45
|
+
error.
|
|
46
|
+
|
|
47
|
+
## Render the SDK in memory
|
|
48
|
+
|
|
49
|
+
`render` returns the SDK source files and does not read or write the disk. Use
|
|
50
|
+
it when a tool needs the code but not the files, for example a compiler plugin.
|
|
51
|
+
|
|
52
|
+
```typescript
|
|
53
|
+
import { render } from '@sdk-it/typescript';
|
|
54
|
+
|
|
55
|
+
const files = await render(spec, {
|
|
56
|
+
name: 'OpenStatus',
|
|
57
|
+
useTsExtension: true,
|
|
58
|
+
});
|
|
59
|
+
// files['client.ts'], files['index.ts'], files['models/index.ts'], …
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
The keys are paths relative to the SDK source folder. The result contains the
|
|
63
|
+
index files. `generate` writes the same source files to `output`.
|
|
34
64
|
|
|
35
65
|
## Use the generated client
|
|
36
66
|
|
|
37
67
|
```typescript
|
|
38
|
-
import {
|
|
68
|
+
import { createOpenStatus } from './src/generated/openstatus/index.ts';
|
|
39
69
|
|
|
40
|
-
const client =
|
|
41
|
-
baseUrl: 'https://api.openstatus.dev',
|
|
70
|
+
const client = createOpenStatus({
|
|
42
71
|
credentials: {
|
|
43
72
|
ApiKeyAuth: process.env.OPENSTATUS_API_KEY,
|
|
44
73
|
},
|
|
@@ -51,6 +80,25 @@ const reports = await client.request(
|
|
|
51
80
|
console.log(reports);
|
|
52
81
|
```
|
|
53
82
|
|
|
83
|
+
`create<Name>(settings)` returns a client. The settings are `baseUrl`,
|
|
84
|
+
`headers`, `credentials`, `fetch`, and `skipValidation`.
|
|
85
|
+
|
|
86
|
+
When the spec names one server or no servers, the SDK also exports a default
|
|
87
|
+
instance with no settings. Its name is `<Name>` in camel case, such as
|
|
88
|
+
`openStatus`. Without servers, its `baseUrl` is `/`, as OpenAPI 3.2 specifies.
|
|
89
|
+
When the spec names two or more servers, the SDK has no default instance, and
|
|
90
|
+
`create<Name>` requires `baseUrl`.
|
|
91
|
+
|
|
92
|
+
```typescript
|
|
93
|
+
import { openStatus } from './src/generated/openstatus/index.ts';
|
|
94
|
+
|
|
95
|
+
openStatus.setOptions({
|
|
96
|
+
credentials: { ApiKeyAuth: process.env.OPENSTATUS_API_KEY },
|
|
97
|
+
});
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
`baseUrl` can be absolute or relative, such as `'/api'`. A relative `baseUrl` resolves against the page location (`globalThis.location`). Where there is no page location, as in Node.js or React Native, a request with a relative `baseUrl` rejects with a `TypeError`. Use an absolute URL there.
|
|
101
|
+
|
|
54
102
|
## Security credentials
|
|
55
103
|
|
|
56
104
|
Credential keys are the exact names from `components.securitySchemes`.
|
|
@@ -69,7 +117,7 @@ configured `fetch` passes `credentials: 'include'`) and for a host proxy that
|
|
|
69
117
|
injects `Authorization` on the client's behalf:
|
|
70
118
|
|
|
71
119
|
```typescript
|
|
72
|
-
const client =
|
|
120
|
+
const client = createExample({
|
|
73
121
|
baseUrl: '/api',
|
|
74
122
|
fetch: (request) => fetch(request, { credentials: 'include' }),
|
|
75
123
|
credentials: { session: true },
|
|
@@ -80,7 +128,7 @@ Each value may instead be a sync or async provider. Providers receive the
|
|
|
80
128
|
scheme name plus the current operation's OpenAPI scopes or roles:
|
|
81
129
|
|
|
82
130
|
```typescript
|
|
83
|
-
const client =
|
|
131
|
+
const client = createExample({
|
|
84
132
|
baseUrl: 'https://api.example.com',
|
|
85
133
|
credentials: {
|
|
86
134
|
oauth: async ({ scopes }) => issueToken(scopes),
|
|
@@ -102,12 +150,11 @@ non-successful response:
|
|
|
102
150
|
```typescript
|
|
103
151
|
import {
|
|
104
152
|
APIError,
|
|
105
|
-
OpenStatus,
|
|
106
153
|
ParseError,
|
|
154
|
+
createOpenStatus,
|
|
107
155
|
} from './src/generated/openstatus/index.ts';
|
|
108
156
|
|
|
109
|
-
const client =
|
|
110
|
-
baseUrl: 'https://api.openstatus.dev',
|
|
157
|
+
const client = createOpenStatus({
|
|
111
158
|
credentials: {
|
|
112
159
|
ApiKeyAuth: process.env.OPENSTATUS_API_KEY,
|
|
113
160
|
},
|
|
@@ -130,6 +177,25 @@ try {
|
|
|
130
177
|
}
|
|
131
178
|
```
|
|
132
179
|
|
|
180
|
+
## Page through results
|
|
181
|
+
|
|
182
|
+
When an operation has pagination, `client.request` resolves to a page. A page
|
|
183
|
+
has the fields of the response body, such as `page.items`, and these methods:
|
|
184
|
+
|
|
185
|
+
- `hasNextPage()` tells if there is a next page.
|
|
186
|
+
- `getNextPage({ signal })` fetches the next page and returns it as a new page.
|
|
187
|
+
- `iterPages({ signal })` yields the current page, then each next page.
|
|
188
|
+
|
|
189
|
+
The `signal` option is optional. Iterate a page, or the result of
|
|
190
|
+
`client.request` without `await`, to get each item of all pages. In this
|
|
191
|
+
example, `GET /items` is an operation with pagination:
|
|
192
|
+
|
|
193
|
+
```typescript
|
|
194
|
+
for await (const item of client.request('GET /items', { limit: 20 })) {
|
|
195
|
+
console.log(item);
|
|
196
|
+
}
|
|
197
|
+
```
|
|
198
|
+
|
|
133
199
|
## Format generated code
|
|
134
200
|
|
|
135
201
|
`formatCode` runs after generation and receives the actual source directory plus
|
|
@@ -149,6 +215,7 @@ const spec = await fetch('https://petstore.swagger.io/v2/swagger.json').then(
|
|
|
149
215
|
await generate(spec, {
|
|
150
216
|
output: './src/generated/petstore',
|
|
151
217
|
name: 'PetStore',
|
|
218
|
+
packageName: '@acme/petstore',
|
|
152
219
|
formatCode: async ({ output, env }) => {
|
|
153
220
|
await execFileAsync('prettier', [output, '--write'], { env });
|
|
154
221
|
},
|
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
+
export * from './lib/client-name.js';
|
|
1
2
|
export * from './lib/generate.js';
|
|
2
|
-
export * from './lib/
|
|
3
|
-
export * from './lib/sdk.js';
|
|
3
|
+
export * from './lib/model-name.js';
|
|
4
4
|
export * from './lib/typescript-snippet.js';
|
|
5
5
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","
|
|
1
|
+
{"version":3,"file":"index.d.ts","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC"}
|