@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.
Files changed (60) hide show
  1. package/README.md +79 -12
  2. package/dist/index.d.ts +2 -2
  3. package/dist/index.d.ts.map +1 -1
  4. package/dist/index.js +1399 -1538
  5. package/dist/index.js.map +4 -4
  6. package/dist/lib/agent/ai-sdk.d.ts +2 -1
  7. package/dist/lib/agent/ai-sdk.d.ts.map +1 -1
  8. package/dist/lib/agent/openai-agents.d.ts +2 -1
  9. package/dist/lib/agent/openai-agents.d.ts.map +1 -1
  10. package/dist/lib/client-name.d.ts +16 -0
  11. package/dist/lib/client-name.d.ts.map +1 -0
  12. package/dist/lib/client.d.ts +25 -1
  13. package/dist/lib/client.d.ts.map +1 -1
  14. package/dist/lib/emitters/interface.d.ts +4 -2
  15. package/dist/lib/emitters/interface.d.ts.map +1 -1
  16. package/dist/lib/emitters/snippet.d.ts.map +1 -1
  17. package/dist/lib/emitters/zod.d.ts +13 -3
  18. package/dist/lib/emitters/zod.d.ts.map +1 -1
  19. package/dist/lib/folder-index.d.ts +7 -0
  20. package/dist/lib/folder-index.d.ts.map +1 -0
  21. package/dist/lib/generate.d.ts +28 -3
  22. package/dist/lib/generate.d.ts.map +1 -1
  23. package/dist/lib/generator.d.ts +28 -29
  24. package/dist/lib/generator.d.ts.map +1 -1
  25. package/dist/lib/group-identifier.d.ts +7 -0
  26. package/dist/lib/group-identifier.d.ts.map +1 -0
  27. package/dist/lib/import-utilities.d.ts.map +1 -1
  28. package/dist/lib/input-schema-name.d.ts +4 -0
  29. package/dist/lib/input-schema-name.d.ts.map +1 -0
  30. package/dist/lib/model-name.d.ts +7 -0
  31. package/dist/lib/model-name.d.ts.map +1 -0
  32. package/dist/lib/module-file.d.ts +7 -0
  33. package/dist/lib/module-file.d.ts.map +1 -0
  34. package/dist/lib/one-module.d.ts +57 -0
  35. package/dist/lib/one-module.d.ts.map +1 -0
  36. package/dist/lib/options.d.ts +4 -6
  37. package/dist/lib/options.d.ts.map +1 -1
  38. package/dist/lib/readme/prop.emitter.d.ts +4 -4
  39. package/dist/lib/readme/prop.emitter.d.ts.map +1 -1
  40. package/dist/lib/readme/readme.d.ts.map +1 -1
  41. package/dist/lib/references.d.ts +43 -0
  42. package/dist/lib/references.d.ts.map +1 -0
  43. package/dist/lib/root-exports.d.ts +6 -0
  44. package/dist/lib/root-exports.d.ts.map +1 -0
  45. package/dist/lib/sdk.d.ts +17 -27
  46. package/dist/lib/sdk.d.ts.map +1 -1
  47. package/dist/lib/security.d.ts +2 -3
  48. package/dist/lib/security.d.ts.map +1 -1
  49. package/dist/lib/server-urls.d.ts.map +1 -1
  50. package/dist/lib/status-map.d.ts +2 -2
  51. package/dist/lib/status-map.d.ts.map +1 -1
  52. package/dist/lib/typescript-snippet.d.ts +4 -8
  53. package/dist/lib/typescript-snippet.d.ts.map +1 -1
  54. package/package.json +19 -6
  55. package/dist/lib/pagination-emit.d.ts +0 -3
  56. package/dist/lib/pagination-emit.d.ts.map +0 -1
  57. package/dist/lib/response-shape.d.ts +0 -22
  58. package/dist/lib/response-shape.d.ts.map +0 -1
  59. package/dist/lib/style.d.ts +0 -4
  60. 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
- controls the generated client class name. `minimal` mode writes client source
33
- files directly to `output`.
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 { OpenStatus } from './src/generated/openstatus/index.ts';
68
+ import { createOpenStatus } from './src/generated/openstatus/index.ts';
39
69
 
40
- const client = new OpenStatus({
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 = new ExampleClient({
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 = new ExampleClient({
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 = new OpenStatus({
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/generator.js';
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
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,6BAA6B,CAAC"}
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"}