@sdk-it/typescript 0.46.2 → 0.46.4

package/README.md

@@ -16,11 +16,10 @@ generated in `minimal` mode.
 ## Generate from an OpenAPI document
 
 ```typescript
+import { loadSpec } from '@sdk-it/spec';
 import { generate } from '@sdk-it/typescript';
 
-const spec = await fetch('https://api.openstatus.dev/v1/openapi').then(
-  (response) => response.json(),
-);
+const spec = await loadSpec('https://api.openstatus.dev/openapi.yaml');
 
 await generate(spec, {
   output: './src/generated/openstatus',
@@ -29,8 +28,9 @@ await generate(spec, {
 });
 ```
 
-`name` controls the generated client class name. `minimal` mode writes client
-source files directly to `output`.
+`loadSpec` accepts a URL or a local path and reads JSON or YAML. `name`
+controls the generated client class name. `minimal` mode writes client source
+files directly to `output`.
 
 ## Use the generated client
 
@@ -38,14 +38,48 @@ source files directly to `output`.
 import { OpenStatus } from './src/generated/openstatus/index.ts';
 
 const client = new OpenStatus({
-  baseUrl: 'https://api.openstatus.dev/v1',
-  'x-openstatus-key': process.env.OPENSTATUS_API_KEY,
+  baseUrl: 'https://api.openstatus.dev',
+  credentials: {
+    ApiKeyAuth: process.env.OPENSTATUS_API_KEY,
+  },
 });
 
-const reports = await client.request('GET /status_report', {});
+const reports = await client.request(
+  'POST /rpc/openstatus.status_report.v1.StatusReportService/ListStatusReports',
+  {},
+);
 console.log(reports);
 ```
 
+## Security credentials
+
+Credential keys are the exact names from `components.securitySchemes`.
+Generated types enforce the value required by each scheme:
+
+- API keys, Bearer/custom HTTP, OAuth 2, and OpenID Connect use a string.
+- HTTP Basic uses `{ username, password }`.
+- Mutual TLS uses `true`; the configured `fetch` implementation owns the
+  client certificate.
+
+Each value may instead be a sync or async provider. Providers receive the
+scheme name plus the current operation's OpenAPI scopes or roles:
+
+```typescript
+const client = new ExampleClient({
+  baseUrl: 'https://api.example.com',
+  credentials: {
+    oauth: async ({ scopes }) => issueToken(scopes),
+    bearer: ({ roles }) => tokenForRoles(roles),
+  },
+});
+```
+
+The client preserves OpenAPI security semantics: alternatives in the security
+array are OR, schemes inside one requirement are AND, `security: []` sends no
+credentials, and an empty requirement (`{}`) permits anonymous access. When
+anonymous and authenticated alternatives coexist, configured authentication
+is preferred.
+
 `request` returns unwrapped response data. It throws `ParseError` when input
 validation fails and an `APIError` subclass when the server returns a
 non-successful response:
@@ -58,12 +92,17 @@ import {
 } from './src/generated/openstatus/index.ts';
 
 const client = new OpenStatus({
-  baseUrl: 'https://api.openstatus.dev/v1',
-  'x-openstatus-key': process.env.OPENSTATUS_API_KEY,
+  baseUrl: 'https://api.openstatus.dev',
+  credentials: {
+    ApiKeyAuth: process.env.OPENSTATUS_API_KEY,
+  },
 });
 
 try {
-  const report = await client.request('GET /status_report/{id}', { id: '42' });
+  const report = await client.request(
+    'POST /rpc/openstatus.status_report.v1.StatusReportService/GetStatusReport',
+    { id: '42' },
+  );
   console.log(report);
 } catch (error) {
   if (error instanceof ParseError) {