diff --git a/README.md b/README.md index 3f3da714..d29e1084 100644 --- a/README.md +++ b/README.md @@ -148,7 +148,7 @@ Each supported language ships the same eight: The `getting-started` skill is the entry point: it directs the agent to clone and grep the real SDK source, so every fact is grounded in the actual contract rather than model knowledge. -Across the marketplace that's **91 language packs and 887 skills**. See +Across the marketplace that's **91 language packs and 890 skills**. See [`plugins/paypal/README.md`](plugins/paypal/README.md) for a worked example. ## Repository structure diff --git a/plugins/plaid/.claude-plugin/plugin.json b/plugins/plaid/.claude-plugin/plugin.json index b256fd4a..efd0eb84 100644 --- a/plugins/plaid/.claude-plugin/plugin.json +++ b/plugins/plaid/.claude-plugin/plugin.json @@ -1,8 +1,8 @@ { "name": "plaid", "displayName": "The Plaid API", - "version": "0.2.0", - "description": "Integrate and consume the APIMatic-generated The Plaid API SDK — bundled skills for C#/.NET, python, TypeScript.", + "version": "0.2.1", + "description": "Integrate and consume the APIMatic-generated The Plaid API SDK — bundled skills for C#/.NET, Python, TypeScript.", "author": { "name": "APIMatic", "email": "developer@apimatic.io" @@ -14,5 +14,8 @@ "./skills/dotnet", "./skills/python", "./skills/typescript" + ], + "agents": [ + "./scoped/agents/the-plaid-api-planner.md" ] } diff --git a/plugins/plaid/.codex-plugin/plugin.json b/plugins/plaid/.codex-plugin/plugin.json new file mode 100644 index 00000000..2d903296 --- /dev/null +++ b/plugins/plaid/.codex-plugin/plugin.json @@ -0,0 +1,10 @@ +{ + "name": "plaid", + "version": "0.2.1", + "description": "Integrate and consume the APIMatic-generated The Plaid API SDK — bundled skills for C#/.NET, Python, TypeScript.", + "skills": "./skills", + "interface": { + "displayName": "The Plaid API", + "developerName": "APIMatic" + } +} diff --git a/plugins/plaid/.cursor-plugin/plugin.json b/plugins/plaid/.cursor-plugin/plugin.json index b256fd4a..f1260e46 100644 --- a/plugins/plaid/.cursor-plugin/plugin.json +++ b/plugins/plaid/.cursor-plugin/plugin.json @@ -1,8 +1,8 @@ { "name": "plaid", "displayName": "The Plaid API", - "version": "0.2.0", - "description": "Integrate and consume the APIMatic-generated The Plaid API SDK — bundled skills for C#/.NET, python, TypeScript.", + "version": "0.2.1", + "description": "Integrate and consume the APIMatic-generated The Plaid API SDK — bundled skills for C#/.NET, Python, TypeScript.", "author": { "name": "APIMatic", "email": "developer@apimatic.io" diff --git a/plugins/plaid/README.md b/plugins/plaid/README.md index f11eae7b..4702322d 100644 --- a/plugins/plaid/README.md +++ b/plugins/plaid/README.md @@ -1,6 +1,6 @@ # The Plaid API SDK Plugin -A plugin whose skills teach a coding agent to install and use the APIMatic-generated **The Plaid API SDK**, in C#/.NET, python, TypeScript. Every SDK fact the skills state is grounded in the SDK's own source and generated documentation, not in what a model remembers about this API. +A plugin whose skills teach a coding agent to install and use the APIMatic-generated **The Plaid API SDK**, in C#/.NET, Python, TypeScript. Every SDK fact the skills state is grounded in the SDK's own source and generated documentation, not in what a model remembers about this API. ## What's inside @@ -9,5 +9,16 @@ One skill set per language. The entry point is that language's getting-started s | Language | Skill prefix | Skills | | --- | --- | --- | | C#/.NET | `dotnet-` | `dotnet-authentication`, `dotnet-calling-endpoints`, `dotnet-client-initialization`, `dotnet-configuration-resilience`, `dotnet-error-handling`, `dotnet-getting-started`, `dotnet-integrate-the-plaid-api`, `dotnet-models`, `dotnet-testing` | -| python | `python-` | `python-authentication`, `python-calling-endpoints`, `python-client-initialization`, `python-configuration-resilience`, `python-error-handling`, `python-getting-started`, `python-integrate-the-plaid-api`, `python-models`, `python-testing` | -| TypeScript | `typescript-` | `typescript-authentication`, `typescript-calling-endpoints`, `typescript-client-initialization`, `typescript-configuration-resilience`, `typescript-error-handling`, `typescript-getting-started`, `typescript-integrate-the-plaid-api`, `typescript-models`, `typescript-testing` | +| Python | `python-` | `python-authentication`, `python-calling-endpoints`, `python-client-initialization`, `python-configuration-resilience`, `python-error-handling`, `python-event-streams`, `python-file-handling`, `python-getting-started`, `python-integrate-the-plaid-api`, `python-models`, `python-testing` | +| TypeScript | `typescript-` | `typescript-authentication`, `typescript-calling-endpoints`, `typescript-client-initialization`, `typescript-configuration-resilience`, `typescript-error-handling`, `typescript-event-streams`, `typescript-getting-started`, `typescript-integrate-the-plaid-api`, `typescript-models`, `typescript-testing` | + +## Agents + +| Agent | What it does | +| --- | --- | +| `the-plaid-api-planner` | Writes `the-plaid-api-plan.md`, the plan and its contract sheet, before any project code is written, and revises it in place. `dotnet-integrate-the-plaid-api`, `typescript-integrate-the-plaid-api` and `python-integrate-the-plaid-api` each start it once the SDK is installed or its source reached, on the main agent's own model. | + +How each host gets it: + +- **Claude Code** loads it from `scoped/agents/` with the plugin and lists it as `plaid:the-plaid-api-planner`. Its file sets `model: inherit`, so it runs on the main agent's model. +- **Where no subagent tool lists it** (a host that doesn't load a plugin's agents, or subagents turned off), the main agent says so in one line and writes the plan itself before any code. diff --git a/plugins/plaid/plugin.json b/plugins/plaid/plugin.json index b256fd4a..f1260e46 100644 --- a/plugins/plaid/plugin.json +++ b/plugins/plaid/plugin.json @@ -1,8 +1,8 @@ { "name": "plaid", "displayName": "The Plaid API", - "version": "0.2.0", - "description": "Integrate and consume the APIMatic-generated The Plaid API SDK — bundled skills for C#/.NET, python, TypeScript.", + "version": "0.2.1", + "description": "Integrate and consume the APIMatic-generated The Plaid API SDK — bundled skills for C#/.NET, Python, TypeScript.", "author": { "name": "APIMatic", "email": "developer@apimatic.io" diff --git a/plugins/plaid/scoped/agents/the-plaid-api-planner.md b/plugins/plaid/scoped/agents/the-plaid-api-planner.md new file mode 100644 index 00000000..21dbd0d4 --- /dev/null +++ b/plugins/plaid/scoped/agents/the-plaid-api-planner.md @@ -0,0 +1,21 @@ +--- +name: "the-plaid-api-planner" +description: "The The Plaid API planner. It writes the-plaid-api-plan.md, the plan and its map-grounded contract sheet, before any project code is written, and revises it in place when the main agent sends a clarification. Main agent: start it when an integrate skill of this plugin tells you to, once per integration, with the user's whole request, the name of the integrate skill you loaded, the absolute project root and the absolute path to write the-plaid-api-plan.md to, plus the SDK source's path where that skill says to pass it; edit no project file until it has returned and you have read that file; send revisions to the same agent rather than starting a second." +model: "inherit" +tools: "Read, Grep, Skill, Write, Edit, Bash" +--- + +You are the The Plaid API planner. You write `the-plaid-api-plan.md` — the plan and its contract sheet — before any project code is written, and you revise it when the main agent sends a clarification. You never write or fix project code, and you never start another agent: you are the planner the workflow asks for. + +**Your instructions are the integrate skill your task names** — this plugin's `-integrate-the-plaid-api` skill for the project's language. Load it, and the getting-started skill it has you load first. Your job is everything that skill puts in `the-plaid-api-plan.md`: the plan, its contract sheet and every table and block the sheet carries, wherever the skill describes them, grounded exactly as the skill says. Skip what belongs to the main agent: *The planner agent* (you are that agent), the read-only prerequisites, the required reading it does before implementing, and the implementation itself. Where your task gives the path of the SDK source the main agent reached, read the map and the source there; reach the SDK source yourself only when it gives none. + +## Plan mode + +Your task gives you the user's whole request, the integrate skill to follow, the absolute project root, the absolute path to write to and, where the integrate skill has the main agent reach the SDK source first, the absolute path to it. Write `the-plaid-api-plan.md` at exactly the path to write to; if none was given, use `/the-plaid-api-plan.md` and say so when you return. It is the only project file you write. Read the project's code only where a table needs it, such as where the codebase already keeps its records, and only read it: do not edit project code, install anything into the project, or run its build or tests. + +Return the plan's path, a one-paragraph summary, and its **Assumptions & Blockers** section verbatim. + +## Revision mode + +When the main agent sends a clarification, a correction or a gap, revise `the-plaid-api-plan.md` in place with targeted edits — edit the changed rows, append a new section; never rewrite the whole file to change a few rows. Reply with ONLY the changed or added rows, verbatim, plus one sentence of context: the main agent works from your reply and does not re-read the file. + diff --git a/plugins/plaid/skills/dotnet/dotnet-authentication/SKILL.md b/plugins/plaid/skills/dotnet/dotnet-authentication/SKILL.md index 5a594f7b..101187ee 100644 --- a/plugins/plaid/skills/dotnet/dotnet-authentication/SKILL.md +++ b/plugins/plaid/skills/dotnet/dotnet-authentication/SKILL.md @@ -1,24 +1,24 @@ --- name: "dotnet-authentication" -description: "Authentication for the The Plaid API .NET SDK in C# — this API authenticates with an API key in a header and OAuth 2.0 client credentials, and this skill gives the credential each scheme takes, the ThePlaidApiClientOptions property to set it on, and the startup check that keeps a missing secret from surfacing as a 401. Load before wiring credentials into the client, or when a call comes back 401/403." +description: "Load before wiring credentials into the The Plaid API .NET SDK client in C#, or when a call throws AuthSchemeException or comes back 401/403. Covers an API key in a header and OAuth 2.0 client credentials: the credential each scheme takes, the ThePlaidApiClientOptions property it goes on, the environment variable that fills it when unset, and a startup check that fails fast on a missing secret." --- # Authenticating the The Plaid API .NET SDK client -This API authenticates with an API key in a header and OAuth 2.0 client credentials. APIMatic surfaces each scheme as a **nullable credentials property** on `ThePlaidApiClientOptions`; set the ones below, then construct the client (see `dotnet-client-initialization`). +This API authenticates with an API key in a header and OAuth 2.0 client credentials. Each scheme is a **nullable credentials property** on `ThePlaidApiClientOptions`; set the ones below, then construct the client (see `dotnet-client-initialization`). | Scheme | Property on `ThePlaidApiClientOptions` | Credential | | --- | --- | --- | -| API key — `PLAID-CLIENT-ID` header | `ClientId` | `string` | -| API key — `PLAID-SECRET` header | `Secret` | `string` | -| API key — `Plaid-Version` header | `PlaidVersion` | `string` | -| OAuth 2.0 client credentials | `Oauth2` | `OAuth2ClientCredentials` | +| API key — `PLAID-CLIENT-ID` header | `ClientId` | `string?` | +| API key — `PLAID-SECRET` header | `Secret` | `string?` | +| API key — `Plaid-Version` header | `PlaidVersion` | `string?` | +| OAuth 2.0 client credentials | `Oauth2` | `OAuth2ClientCredentials?` | -**That table is the entire authentication surface of this SDK.** `ThePlaidApi.Core.Authentication` ships *every* scheme class APIMatic supports as shared runtime code, including kinds this API does not use, so read what is configurable off the properties above rather than off that folder. +**That table, the provider delegate beside each static credential and the environment variables below are the entire authentication surface of this SDK.** `ThePlaidApi.Core.Authentication` also holds scheme classes this API does not use, so read what is configurable off the properties above rather than off that folder. ## API key (header) — `ClientId` -The key travels in the `PLAID-CLIENT-ID` request header. The header name is fixed by the generated scheme — you supply only the value: +The key travels in the `PLAID-CLIENT-ID` request header. The header name is fixed — you supply only the value: ```csharp options.ClientId = "API_KEY"; @@ -26,7 +26,7 @@ options.ClientId = "API_KEY"; ## API key (header) — `Secret` -The key travels in the `PLAID-SECRET` request header. The header name is fixed by the generated scheme — you supply only the value: +The key travels in the `PLAID-SECRET` request header. The header name is fixed — you supply only the value: ```csharp options.Secret = "API_KEY"; @@ -34,7 +34,7 @@ options.Secret = "API_KEY"; ## API key (header) — `PlaidVersion` -The key travels in the `Plaid-Version` request header. The header name is fixed by the generated scheme — you supply only the value: +The key travels in the `Plaid-Version` request header. The header name is fixed — you supply only the value: ```csharp options.PlaidVersion = "API_KEY"; @@ -53,53 +53,75 @@ options.Oauth2 = new OAuth2ClientCredentials { ClientId = "...", ClientSecret = "...", - Scope = "..." // optional + Scope = "user:write" // required by Plaid: its token endpoint rejects a request without a scope }; ``` -The SDK fetches the token from `https://api.plaid.com/oauth2/apiv2/token` and caches it, acquiring a fresh one when it expires; on a `401` it invalidates the cached token and re-acquires. The token request carries the client id and secret as HTTP Basic credentials, so `ClientSecret` is required. +The SDK fetches the token from `/oauth/token` on the selected environment (`https://production.plaid.com` or `https://sandbox.plaid.com`) and caches it, acquiring a fresh one when it expires; on a `401` it drops the cached token, acquires a new one and re-sends the call once (the upload exception is under **Token caching & refresh**). The token request carries the client id and secret in the form body. -## Token caching & refresh - -- Tokens are cached in-memory, **per client instance**, and reused until **30s** before expiry. -- **Nothing here refreshes.** The grants above are not wired to `IOAuth2RefreshableTokenStrategy` — when a token expires the whole grant re-runs. A `refresh_token` in the response is discarded, because the non-refreshable `OAuthToken` has no binding for it. Do not infer refresh behaviour from what the provider returns. -- On `401`, the cached token is invalidated and re-acquired on the next call — the failing request is **not** retried. -- **Invalidation is a hint, not a barrier.** `Invalidate()` clears the cache without taking the fetch lock, so a token fetch already in flight can complete and re-populate it. That is deliberate — the refreshed token post-dates the invalidation — but it means "invalidate then immediately read" is not a guarantee of a fresh token. +## Credential providers -⚠ **If the token response omits `expires_in`, the token never expires as far as the SDK is concerned.** `expires_in` is RECOMMENDED but not required by RFC 6749, and the SDK's expiry check short-circuits to "not expired" when it is absent — so the first token is cached for the life of the client and the only thing that ever replaces it is a `401`. That is usually fine and occasionally not: a token revoked server-side keeps being sent until a request fails with it. If your provider omits `expires_in` and you need proactive rotation, supply your own token strategy (below) rather than trying to bound the cache. +Every static credential above has a companion **provider** property on `ThePlaidApiClientOptions`: a delegate the SDK asks on every request, for a secret that rotates while the process runs. Set it instead of the credential — a provider wins over both the credential property and its environment variable. -### Supplying your own token source - -The token strategy is a public extension point: `ThePlaidApiClientOptions` exposes a strategy property beside each credentials property, and the generated client falls back to the built-in strategy only when you leave it null. The strategy is used only when the credentials property beside it is also set, and `GetToken` receives that object. - -| Grant | Strategy property on `ThePlaidApiClientOptions` | Type | +| Credential | Provider | Delegate | | --- | --- | --- | -| Client credentials | `Oauth2TokenStrategy` | `IOAuth2TokenStrategy` | +| `options.ClientId` | `options.ClientIdProvider` | `CredentialProvider?` | +| `options.Secret` | `options.SecretProvider` | `CredentialProvider?` | +| `options.PlaidVersion` | `options.PlaidVersionProvider` | `CredentialProvider?` | ```csharp -options.Oauth2 = new OAuth2ClientCredentials { /* its required members */ }; -options.Oauth2TokenStrategy = new MyTokenStrategy(); // Task GetToken(creds, ct) +options.ClientIdProvider = async ct => await vault.ReadAsync("api-key", ct); ``` -Reach for it when the token must come from somewhere other than the SDK's own call to the token endpoint — a shared cache across processes, a secrets broker, a sidecar that already holds a valid token, or a test double. The per-client in-memory cache above still wraps whatever you return. +- The provider runs inside every attempt, before the request is sent, and counts against the per-attempt `options.Retry.Timeout` — keep it fast, and cache in your own code when the source is slow. +- A provider that returns `null` means the credential is unavailable for that call: the call fails with `AuthSchemeException` naming the scheme, even on an operation that accepts anonymous callers. Under **OR**, the next configured alternative is tried first. +- A provider that throws fails the call with `AuthSchemeException` wrapping the exception; an `OperationCanceledException` for the call's own token passes through unwrapped. + +## Token caching & refresh + +- Tokens are cached in-memory, **per client instance**, and reused until **30s** before expiry. +- **`options.Oauth2` mints one token per scope set.** An operation that declares scopes gets a token requested with exactly those scopes (the SDK map's **Auth** bullet lists them); operations that declare none share one token requested without a scope. +- **Nothing here refreshes**: when a token expires the whole grant re-runs, and a `refresh_token` in the response is ignored — do not infer refresh behaviour from what the provider returns. +- On `401`, the rejected token is dropped, a new one is obtained and the failing request is **re-sent once** — under every retry setting, including `RetryOptions.Disabled()`; a second `401` is returned to you. A request whose body cannot be re-sent (a binary or file upload) is not re-sent, but its `401` still drops the cached token, so the next call recovers. +- After a `401` clears the cache, a token fetch already in flight can still re-populate it, so the next call is not guaranteed a newly fetched token. + +Setting `Scope` on the credentials replaces the per-scheme behaviour above with one token requested with that value; an empty `Scope` requests none. + +⚠ **If the token response omits `expires_in`, the SDK treats the token as never expiring**: it is cached for the client's lifetime and replaced only after a `401`, so a token revoked server-side keeps being sent until a request fails with it — a failure the one re-send above recovers, at the cost of a round trip. ## Combining the schemes -This SDK generates more than one credentials property, and its operations compose them. You configure the composition by setting the relevant properties on `ThePlaidApiClientOptions` — the generated client wires the rest. +This SDK has more than one credentials property, and its operations compose them; you choose by which properties on `ThePlaidApiClientOptions` you set. -**AND (`AuthSchemeAll`) — every scheme in the group is applied to the request.** Leave one of them unconfigured and the request still goes out, just without that credential; the provider decides what to make of a half-authenticated call. +**AND — every scheme in the group is applied to the request.** Leave one of them unconfigured and the call fails before anything is sent with `AuthSchemeException` naming each missing scheme; there is no half-authenticated call. -**OR (`AuthSchemeAny`) — alternatives, tried in order.** Schemes with **no credentials configured are skipped, not tried**; the first configured scheme that succeeds wins, and `AuthSchemeException` is thrown only if every *configured* scheme fails. Configure exactly the one you intend to use — an extra credential set "just in case" changes which scheme authenticates the call. **Which one that is, is not a preference:** each scheme's **API Provider Notes** above are where the provider states when its scheme applies. +**OR — alternatives, in the order the API lists them.** Schemes with **no credentials configured are skipped, not tried**; the first configured scheme that applies wins, and `AuthSchemeException` is thrown when none is configured, naming every alternative, or when every configured one fails. Configure exactly the one you intend to use — an extra credential set "just in case" changes which scheme authenticates the call. **Which one that is, is not a preference:** each scheme's **API Provider Notes** above are where the provider states when its scheme applies. ## Operations that need no credentials -Some operations on this API are public: the generated endpoint uses `NoneAuthScheme` and sends no credential, whatever you set on `ThePlaidApiClientOptions`. You still construct the same client — there is no separate unauthenticated client — and the credentials you configured are simply not applied to those calls. +Some operations on this API are public: they send no credential, whatever you set on `ThePlaidApiClientOptions`. You still construct the same client — there is no separate unauthenticated client — and the credentials you configured are simply not applied to those calls. -## ⚠ Missing credentials must stop the app from starting +## Environment variables + +A credentials property left `null` is read from an environment variable when the client is constructed — the SDK name in upper snake case, the property name in upper snake case, and for a multi-member credential the member: + +| Property on `ThePlaidApiClientOptions` | Environment variables | +| --- | --- | +| `ClientId` | `THE_PLAID_API_CLIENT_ID` | +| `Secret` | `THE_PLAID_API_SECRET` | +| `PlaidVersion` | `THE_PLAID_API_PLAID_VERSION` | +| `Oauth2` | `THE_PLAID_API_OAUTH2_CLIENT_ID`, `THE_PLAID_API_OAUTH2_CLIENT_SECRET`, `THE_PLAID_API_OAUTH2_SCOPE` (optional to the SDK, but Plaid requires a scope) | + +- A value set in code always wins over the environment. +- A variable that is unset, empty or whitespace counts as not configured. +- A multi-member credential is used only when every required variable is set. If some are missing the property stays `null`; constructing the client never throws, and a call that requires that credential fails before anything is sent. +- Variables are read once, when the client is constructed. Changing them afterwards has no effect on an existing client. -⚠ **Configure nothing and the request goes out unauthenticated — no exception.** An unset credentials property on `ThePlaidApiClientOptions` yields a no-op scheme, not an error, so the call reaches the provider with no credential and comes back `401`. The SDK will never tell you that you forgot to supply one; only the provider will, one round-trip later and one layer away from the cause. +Binding `ThePlaidApiClientOptions` from `IConfiguration` keeps both paths: a property the binding leaves `null` still falls back to its variable. The README's **Credentials from environment variables** section shows the binding. -**A required credential that is not configured is a deployment fault, not a request fault.** If the app boots with a blank secret, an operator sees a provider outage, retry logic hammers a call that can never succeed, and the actual cause — an unset environment variable — is two layers away from the symptom. +## ⚠ Missing credentials must stop the app from starting + +⚠ **Configure nothing and the first call that needs the credential throws.** A credentials property on `ThePlaidApiClientOptions` that nothing fills — code, a provider or an environment variable — fails the call with `AuthSchemeException` before anything is sent, naming the scheme. That is a request-time failure for a deployment fault: catch it at startup instead. **Validate at startup and refuse to boot.** Bind the credentials into your own options type and make the host check it before the app serves anything: @@ -120,24 +142,28 @@ if (string.IsNullOrWhiteSpace(settings.ClientId)) "user-secrets, or your secret store before starting the app."); ``` +**If the SDK's environment variables supply the credential**, `ValidateOnStart()` sees nothing: the SDK reads the variable itself, and a settings type bound from `IConfiguration` would refuse to boot a host the SDK authenticates. Check the variable instead, with the same guard before the host is ready — the **Or environment variable** column below names it. + +**If a provider supplies the credential**, there is nothing to check at startup: the delegate is asked on every request, so the check belongs where the provider reads the secret, and a provider that returns `null` fails the call with `AuthSchemeException`. + Three rules for the message it fails with: -- **Name the missing config key**, so the operator knows what to set — `"ThePlaidApiClient:ClientId is not configured"`, not `"authentication failed"`. +- **Name the missing config key or variable**, so the operator knows what to set — `"ThePlaidApiClient:ClientId is not configured"`, not `"authentication failed"`. - **Never echo the value**, present or absent — no length, no prefix, no masked form. A "configured: AC1234…" line is a secret in a log. - **Do not fall back to a default, a placeholder, or an unauthenticated client.** Booting degraded hides the fault and pushes it to the first caller. Check every value **the scheme you chose** needs. The rows below are not one checklist: the schemes above are alternatives, so a row belonging to a scheme you are not using needs no value at all, and demanding one at startup blocks a boot that would have worked. Validate the rows whose property you set, and no others: -| Value to validate | Feeds `ThePlaidApiClientOptions` property | -| --- | --- | -| `ClientId` | `ClientId` | -| `Secret` | `Secret` | -| `PlaidVersion` | `PlaidVersion` | -| `ClientId` | `Oauth2` | -| `ClientSecret` | `Oauth2` | +| Value to validate | Feeds `ThePlaidApiClientOptions` property | Or environment variable | +| --- | --- | --- | +| `ClientId` | `ClientId` | `THE_PLAID_API_CLIENT_ID` | +| `Secret` | `Secret` | `THE_PLAID_API_SECRET` | +| `PlaidVersion` | `PlaidVersion` | `THE_PLAID_API_PLAID_VERSION` | +| `ClientId` | `Oauth2` | `THE_PLAID_API_OAUTH2_CLIENT_ID` | +| `ClientSecret` | `Oauth2` | `THE_PLAID_API_OAUTH2_CLIENT_SECRET` | ## Notes -- Set credentials **before** constructing the client, or inside the `AddThePlaidApiClient(options => ...)` callback when registering via DI. `ThePlaidApiClientOptions` is read at construction; mutating it afterwards does not re-wire an existing client. -- Keep secrets out of source — load them from configuration (environment variables, a secret store, or any other `IConfiguration` source) instead of hardcoding, either inside the `AddThePlaidApiClient(options => ...)` callback for a host or via a `ConfigurationBuilder()...Build()` chain for a console app. +- Set credentials **before** constructing the client, or inside the `AddThePlaidApiClient(options => ...)` callback when registering via DI. `ThePlaidApiClientOptions` is read at construction; mutating it afterwards does not re-wire an existing client. A provider is the one way to change a credential without a new client: the delegate you set before construction is asked on every request, so a rotated secret reaches the next call; assigning a different delegate afterwards has no effect (see **Credential providers**). +- Keep secrets out of source — load them from configuration (environment variables, a secret store, or any other `IConfiguration` source) instead of hardcoding, either inside the `AddThePlaidApiClient(options => ...)` callback for a host or via a `ConfigurationBuilder()...Build()` chain for a console app — or leave the property unset and let the SDK read its environment variable (see **Environment variables**). diff --git a/plugins/plaid/skills/dotnet/dotnet-calling-endpoints/SKILL.md b/plugins/plaid/skills/dotnet/dotnet-calling-endpoints/SKILL.md index fb0db712..866cee13 100644 --- a/plugins/plaid/skills/dotnet/dotnet-calling-endpoints/SKILL.md +++ b/plugins/plaid/skills/dotnet/dotnet-calling-endpoints/SKILL.md @@ -1,6 +1,6 @@ --- name: dotnet-calling-endpoints -description: Calling operations on an APIMatic-generated .NET SDK in C# — finding the controller that owns an operation, required vs optional parameters, request and response envelope shapes, async usage, and cancellation. Load before writing the first call to an SDK operation, or when an operation's shape or return type is unclear. +description: Load before writing the first call to an operation on an APIMatic .NET SDK in C#, or when an operation's input or return type is unclear — finding the controller that owns an operation, the per-operation request record, the requestOptions and cancellationToken arguments, response shapes and cancellation. --- # Calling endpoints on an APIMatic .NET SDK @@ -16,7 +16,8 @@ names follow no fixed verb/resource pattern, so take the real name from the shee ## Method signature convention -Every endpoint method is `async` (returns a `Task`) and takes at most three parameters, in a fixed order: +Every endpoint method is `async` (returns a `Task`; there are no sync overloads) and takes at most three +parameters, in a fixed order: ```csharp public Task<{ReturnType}> {Operation}( @@ -44,13 +45,7 @@ public Task<{ReturnType}> {Operation}( positional call that skips it puts your `CancellationToken` where a `RequestOptions?` is expected, and the call fails to compile with `CS1503: Argument N: cannot convert from 'System.Threading.CancellationToken' to '{RootNamespace}.Core.RequestOptions?'`. Pass `cancellationToken:` by name and the problem cannot arise. -- **The contract sheet is the source of truth for the record.** Which members are `required`, which are - nullable, which carry a default — and whether there is a `Body` — varies per operation. Take each - operation's record from the contract sheet (grounded from the SDK map/source), not from memory. - **Return type** varies by operation — see [Reading the response](#making-the-call-and-reading-the-response). -- Methods are **async-only** (no sync overloads) and **throw `ApiException`** on API errors — one leaf - of the SDK's `SdkException` family, which also covers connection failures and timeouts — see - `dotnet-error-handling`. ## Building the request record @@ -59,10 +54,10 @@ what you owe it: | Property | Meaning | You | |---|---|---| -| `public required T X { get; init; }` | required, no spec default | **must** set it — the compiler enforces this | -| `public T X { get; init; } = value;` | the spec declares a default | set it only to override; leaving it sends the default | +| `public required T X { get; init; }` | required, no default | **must** set it — the compiler enforces this | +| `public T X { get; init; } = value;` | has a default | set it only to override; leaving it sends the default | | `public T? X { get; init; }` | optional, no default | leave it unset to omit it from the request | -| `public T X { get; } = value;` | the spec fixes the value (`const`) | cannot set it — it is sent as declared | +| `public T X { get; } = value;` | a fixed value (`const`) | cannot set it — it is always sent | ```csharp var response = await client.{ApiGroup}.{Operation}( @@ -79,34 +74,25 @@ var response = await client.{ApiGroup}.{Operation}( - **Property names are PascalCase C# names, not wire names.** `per_page` on the wire is `PerPage` on the record. The wire keys appear only inside the generated method body, as `new Param("per_page", request.PerPage)` — read names off the record, never off that list. -- **The record is never serialized**, so it carries no `[JsonPropertyName]`. Its members may carry constraint - attributes (`[Minimum(0)]`, `[MaxLength(256)]`); they document the API's limits and nothing in the SDK - enforces them before the call. +- **The record is never serialized**, so it carries no `[JsonPropertyName]`. Constraint attributes on its + members (`[Minimum(0)]`, `[MaxLength(256)]`) are not enforced — see **dotnet-models**. - **A JSON, plain-text or binary body is always the member `Body`** (`Body_` in the rare API that also has a parameter literally named `body`). A `application/x-www-form-urlencoded` or multipart form has **no** `Body`: each - form field is its own property on the record, and the generator assembles the form itself. + form field is its own property on the record, and the SDK assembles the form itself. ## Files A file is a `BinaryContent`, built with an object initializer that sets all three: a `Stream`, a `FileName` -(may be `null`) and a `ContentType` -(a `MediaTypeHeaderValue`). A `Stream` or `byte[]` also converts to one, typed `application/octet-stream` and -named only for a `FileStream`; the SDK does not apply the spec's media type, so set `ContentType` whenever the spec -declares one, and `FileName` when the API needs a name. The SDK never disposes or rewinds your stream, and never retries a call -that sends a file. +(may be `null`) and a `ContentType` (a `MediaTypeHeaderValue`). A `Stream` or `byte[]` also converts to one, +typed `application/octet-stream` whatever media type the operation documents, and named only for a +`FileStream` — so set `ContentType` whenever the API expects a specific type, and `FileName` when it needs a +name. The SDK never disposes or rewinds your stream, and never retries a call that sends a file. ## Building request models -**A form-bodied operation has no `Body` member.** Where the API declares a -`application/x-www-form-urlencoded` or multipart request, the generator emits the fields as *individual -members of the request record* and assembles the form itself — there is no body model to construct and no -`Body` to set. -In an API built that way this is the majority shape, not an exception. The contract sheet says -which you are looking at; the record settles it. - -For the JSON case: request bodies are immutable `record`s built with object-initializer syntax (no -builders). `required` members must be set; optional ones are nullable and are omitted from the JSON when -left null. The body model is the type of the request record's `Body` member — a different type from the +A JSON request body is an immutable `record` built with object-initializer syntax (no builders). +`required` members must be set; optional ones are nullable and are omitted from the JSON when left null. +The body model is the type of the request record's `Body` member — a different type from the request record itself — so take its exact name from the contract sheet (grounded from the SDK map/source): ```csharp @@ -134,21 +120,14 @@ var body = new {RequestType} ## Enums -Enums are type-safe string- **or int-**enums (`OpenStringEnum` / `OpenIntEnum`), not C# enums — use -the static constants. There is no `FromValue`: a value the spec does not declare cannot be constructed, and -a raw value resolves through `{EnumType}.TryGetKnownValue(value, out var known)`. See **dotnet-models** for -read-back semantics (implicit conversion to the underlying value, `==` / `Is` against raw values, and the -generated `Match`). - -```csharp -SomeProp = {EnumType}.SomeConstant; -SomeProp = {EnumType}.TryGetKnownValue(configured, out var known) ? known : {EnumType}.SomeConstant; -``` +Enums are `OpenStringEnum` / `OpenIntEnum` records, not C# enums: use the static constants +(`{EnumType}.SomeConstant`). There is no `FromValue`; resolve a raw value with +`{EnumType}.TryGetKnownValue(value, out var known)`. See **dotnet-models**. ## Union types, collections, and dates Some properties are not plain scalars: polymorphic `OneOf`/`AnyOf` unions (built with **factory methods**, -not object-initializers, and read via `TryGet…`), `IReadOnlyList`/`IReadOnlyDictionary` collections, and +not object-initializers, and read via `TryGet…` or `Match`), `IReadOnlyList`/`IReadOnlyDictionary` collections, and `DateTimeOffset` dates. If a request property or response field is one of these, see **dotnet-models** for how to construct and read it. @@ -189,20 +168,12 @@ contract sheet's response-envelope column names the return type and the inner fi bounds the read, and a drop while you read throws a raw `IOException` from your read, not `SdkConnectionException`. -Endpoints in the same family can differ — one nests the resource, another returns it directly — so let each -method's return type guide how you read it. - -An operation may also expose an optional **`{Operation}Result`** sibling that returns -`ApiResult` — the outcome (the response, or a typed/`RawError` error) instead of -throwing, with the HTTP status and headers available on both. It's optionally generated, so it may not -exist. See **dotnet-error-handling**. +A non-throwing **`{Operation}Result`** sibling may exist — see **dotnet-error-handling**. ## Cancellation -Every operation takes a `CancellationToken` as its last argument, passed as `cancellationToken:`, with -`RequestOptions? requestOptions = null` immediately before it — so the token is last, never second-to-last. To bound an individual call with a -timeout, use the per-request cancellation pattern in **dotnet-configuration-resilience** (it owns -timeouts). +Pass the token as `cancellationToken:` (see the signature above). To bound a call with a timeout, see +**dotnet-configuration-resilience** § *Bounding a call*. ## Worked example — a list/GET call @@ -223,7 +194,7 @@ var results = await client.{ApiGroup}.{Operation}( Filter = {EnumType}.SomeConstant, Q = "search text", PerPage = 20 // literal must match the member's type — a `20d` against an `int` is CS0266 - }, // StartDate is left unset and omitted; Page keeps the spec default + }, // StartDate is left unset and omitted; Page keeps its default cancellationToken: ct); foreach (var item in results) diff --git a/plugins/plaid/skills/dotnet/dotnet-client-initialization/SKILL.md b/plugins/plaid/skills/dotnet/dotnet-client-initialization/SKILL.md index 948c68eb..494ded7a 100644 --- a/plugins/plaid/skills/dotnet/dotnet-client-initialization/SKILL.md +++ b/plugins/plaid/skills/dotnet/dotnet-client-initialization/SKILL.md @@ -1,6 +1,6 @@ --- name: dotnet-client-initialization -description: Creating and registering an APIMatic-generated .NET SDK client in C# — construction, the builder/options shape, HttpClient ownership and lifetime, and dependency-injection registration in ASP.NET Core. Load before wiring the client into an application's service container or writing the factory that builds it. +description: Load before constructing an APIMatic .NET SDK client in C#, registering it in a service container, or writing the factory that builds it — the client options class, HttpClient ownership and lifetime, dependency-injection registration in ASP.NET Core, and inbound webhooks. --- # Initializing an APIMatic .NET SDK client @@ -22,12 +22,9 @@ object: public {Api}Client(HttpClient httpClient, {Api}ClientOptions options) ``` -Operations are exposed on the client. Most are grouped under **controller properties** (one per API resource -group) and called `client.{ApiGroup}.{Operation}(...)` — for example, a `Widgets` controller's -`ListWidgets` operation is `client.Widgets.ListWidgets(new ListWidgetsRequest { ... })`. An operation that belongs to no group sits -**directly on the client**, called `client.{Operation}(...)`. The available controller properties (and any -direct operations) come from the contract sheet (grounded from the SDK map/source), -not a decompiled or reflected view of the installed package. See `dotnet-calling-endpoints`. +Operations hang off **controller properties** (`client.{ApiGroup}.{Operation}(...)`) or sit directly on the +client (`client.{Operation}(...)`). Take them from the contract sheet (grounded from the SDK map/source), not +a decompiled or reflected view of the installed package — see `dotnet-calling-endpoints`. The options class always carries these knobs (auth properties vary per API — see `dotnet-authentication`): @@ -41,19 +38,16 @@ public class {Api}ClientOptions public ServerOptions Server { get; set; } = new(); public IReadOnlyList Hooks { get; set; } = []; // request/response observation — // see dotnet-configuration-resilience § Hooks - // + one nullable credentials property per auth scheme the API declares, and — for an OAuth2 - // scheme — a nullable {Scheme}TokenStrategy hook alongside it (see dotnet-authentication) + // + one nullable credentials property per auth scheme the API declares, and — for a static + // scheme — a nullable {Scheme}Provider delegate asked on every request (see dotnet-authentication) } ``` -`Logging` is a real property, not a placeholder — the SDK has a **built-in** request/response logger, and -what an unset `Logging.LoggerFactory` means depends on how the client is built. Under `Add{Api}Client` the -extension fills it from the container's `ILoggerFactory`, so logging is **already on** at your host's level. -On a client you construct yourself it falls through to a `{APICLIENTTYPENAME}_LOG` environment variable that -can switch logging — including unredacted JSON request bodies — on from outside your code. Set it -explicitly either way; **dotnet-configuration-resilience** has the full table. Tuning these knobs — `Retry` (retries, backoff, per-attempt timeout), `Logging`, and -`Server` / `Environment` (server selection and **overriding the base URL**), plus pagination — is covered in -**dotnet-configuration-resilience**. +`Logging` is a **built-in** request/response logger: under `Add{Api}Client` it is **already on**; on a client +you construct yourself a `{API}_LOG` environment variable — `{API}` being the SDK name in upper snake case — can +turn it on, unredacted JSON bodies included. Set `Logging.LoggerFactory` explicitly either way. +**dotnet-configuration-resilience** covers +`Retry`, `Logging`, `Server` / `Environment` (including **overriding the base URL**) and pagination. ## Direct instantiation @@ -64,7 +58,8 @@ using {RootNamespace}.Servers; var options = new {Api}ClientOptions { Environment = ServerEnvironment.Default(), // pick the environment your API exposes - // ...set the auth credentials property your API uses (see dotnet-authentication) + // ...set the auth credentials property your API uses, or leave it null and set its + // {API}_* environment variable instead (see dotnet-authentication) }; var httpClient = new HttpClient(); // reuse a single long-lived instance @@ -77,32 +72,19 @@ The SDK does **not** own the `HttpClient` — you provide it. Reuse one instance (or use `IHttpClientFactory`); do not create one per request. Attach custom `HttpMessageHandler`s here for logging, proxies, or custom TLS (see `dotnet-configuration-resilience`). -**Keep both the `HttpClient` and the SDK client long-lived — the client is not a stateless wrapper.** The -only thing you hand it is the HTTP pipeline; its constructor builds the rest and then owns it: - -- the **resilience pipelines** — two Polly pipelines are eagerly built from `options.Retry`; -- the **logger** — constructed here, which is also where the `{APICLIENTTYPENAME}_LOG` environment variable - is read; -- the **auth schemes**, and for an OAuth2 SDK the auth scheme *is* the access-token cache — an instance - field on the scheme object. - -That last one is the reason a per-request client is a real cost rather than a stylistic one: a fresh client -starts with an empty token cache, so **every resolution pays a token request on its first call**. Three -calls through three transient clients is three token round-trips where a shared client makes one. - -Reuse one `HttpClient` (or let `IHttpClientFactory` own it) *and* one SDK client for the app's lifetime. -Construct per request only where you genuinely need different credentials per request — and then expect the -token fetch. +**Keep the SDK client long-lived too.** Its constructor builds and owns the retry pipelines (from +`options.Retry`), the logger (reading `{API}_LOG`) and the auth schemes — for OAuth2 the scheme +holds the access-token cache, so a fresh client starts with an empty cache and **pays a token request on its +first call**. Reuse one SDK client for the app's lifetime; construct per request only where credentials +genuinely differ per request, and expect the token fetch. ## Choosing the server / base URL -Environments are modeled as a `ServerEnvironment` string-enum with one constant per environment the API -defines (e.g. `ServerEnvironment.Production`, or region constants). Select one on `options.Environment`. -Overriding a templated parameter or the base URL is nested **per server AND per environment** — -`options.Server.{ServerName}.{Environment}.BaseUrl` (with any templated params at the same level), NOT -directly on `ServerOptions`. **dotnet-configuration-resilience** documents this in full and owns -server / base-URL configuration. The exact constants and template parameters for your API come from the -contract sheet (grounded from the SDK map/source). +Select the environment with `options.Environment = ServerEnvironment.{Environment}` — one constant per +environment (e.g. `ServerEnvironment.Production`, or region constants). Base-URL and templated-parameter +overrides live at `options.Server.{ServerName}.{Environment}`, NOT directly on `ServerOptions` — see +**dotnet-configuration-resilience**. The constants and template parameters come from the contract sheet +(grounded from the SDK map/source). ## Dependency injection (ASP.NET Core / generic host) @@ -122,18 +104,13 @@ builder.Services.Add{Api}Client(options => }); ``` -⚠ **The extension registers the client as a `singleton`, and that has a consequence worth planning for.** -A singleton calls `CreateClient()` *once* and holds that `HttpClient` for the process lifetime, so -`IHttpClientFactory`'s handler rotation never applies to it and a DNS change is cached indefinitely — the -classic symptom is an app that keeps calling a decommissioned IP after a provider fails over, and only a -restart fixes it. (A transient registration avoids *this* problem — each resolution takes a fresh `HttpClient` and the -pooled pipeline stays rotated — but it buys stale-DNS safety with a fresh, empty OAuth token cache per -resolution, so it is a trade, not a fix. See the lifetime note above.) - -The actual fix is cheap: set `PooledConnectionLifetime` on the primary handler so the pool recycles -connections on a timer, and keep the SDK client long-lived. Registering yourself over a named `HttpClient` -(below) gives you the same control plus an unshared pipeline. Confirm the registration in the extension rather than trusting this paragraph if your SDK was -generated by a different version — it is one line, and the contract sheet carries it. +⚠ **The extension registers the client as a `singleton`.** It calls `CreateClient()` *once* and holds that +`HttpClient` for the process lifetime, so `IHttpClientFactory`'s handler rotation never applies to it and a +DNS change is never picked up — the app keeps calling a decommissioned IP after a provider fails over, until +a restart. A transient registration avoids stale DNS but pays a fresh, empty OAuth token cache per +resolution (see the lifetime note above). The fix: set `PooledConnectionLifetime` on the primary handler so +the pool recycles connections on a timer, and keep the SDK client long-lived. Registering yourself over a +named `HttpClient` (below) gives you the same control plus an unshared pipeline. To attach custom `DelegatingHandler`s (logging, proxies, custom TLS) under this DI registration, configure the **default, unnamed** factory client it resolves — e.g. @@ -145,10 +122,8 @@ yourself over a **named** `HttpClient` — the same shape the extension uses, mi ### Registering over a named `HttpClient` -The full shape. **`Timeout` is not optional to think about** — the default is `100s`, which matches the SDK's -own per-attempt retry timeout. On defaults a hung provider costs you ~100s on a `POST` and **~407s on a -`GET`**, because the SDK's per-attempt timeout is itself a retry trigger on the retryable verbs (see -**dotnet-configuration-resilience**). Either number is an outage, not a timeout: +The full shape. **Set `Timeout`**: the default `100s` bounds one attempt, and a hung provider costs ~100s on +a `POST` and ~407s on a `GET` (see **dotnet-configuration-resilience** § *Bounding a call*): ```csharp using {RootNamespace}; @@ -175,10 +150,8 @@ services.AddSingleton(sp => }); ``` -Both knobs above are load-bearing and they answer different failures: `PooledConnectionLifetime` keeps DNS -fresh behind a long-lived client, and `Timeout` stops a hung provider from holding a request, a pooled connection and the caller open (~100s, -and ~407s on a retryable verb — see **dotnet-configuration-resilience**). Setting -only the first is the common mistake — it looks like the resilience box is ticked. +`PooledConnectionLifetime` keeps DNS fresh behind a long-lived client; `Timeout` stops a hung provider holding +the request. Set both. Then inject it: @@ -191,30 +164,19 @@ public sealed class MyService({Api}Client client) ## Inbound webhooks — what `Core/Webhooks/` does and does not give you -Every emitted SDK ships a `Core/Webhooks/` tree: `WebhookRequest`, `WebhookEvent<…>`, -`WebhookEventParser<…>`, and a `Signing/` folder holding `SignatureVerifier`. Three facts about it, verified -on both sampled 4.0.0 SDKs, decide whether any of it is usable: - -- **`SignatureVerifier` is `internal sealed`, with no `InternalsVisibleTo`.** You cannot call it, construct - it, or subclass it from your code. It is fully implemented — HMAC, digest encodings, replay tolerance — - and on both samples it has **zero callers**. -- **`WebhookEventParser.Parse` verifies nothing.** It parses the body with `JsonDocument.Parse`, - checks the root is a JSON object, and hands off to an abstract `CreateEvent`. The name reads like a - security boundary; it is a deserializer. -- **`WebhookEventParser` and `WebhookEvent` are `public abstract`, and neither sampled SDK generates a - concrete subclass**, because neither spec declares webhook events. The public machinery has nothing to - instantiate — a base class waiting on generated code that was never emitted. - -So on an SDK with no generated events, signature verification is yours to write, against the provider's -published scheme. `WebhookRequest` remains useful on its own — `FromStream`, `FromBytes`, `TryGetHeader` -give you a body-and-headers holder to verify against — but it computes nothing for you. - -> **Not settled by either sample.** Whether a spec that *does* declare webhook events generates a concrete -> parser, and whether that generated parser calls the internal `SignatureVerifier`, is unknown here — no -> sampled SDK exercises it. An `internal` verifier is exactly what you would expect if generated code is -> its intended caller, so do not read "verification happens outside the SDK" as a property of the -> generator. It is what is true when no events were generated. Look for a `WebhookEvent` subclass in the -> emitted tree before assuming either way. +Every SDK ships `Core/Webhooks/`: `WebhookRequest` (`FromStream`, `FromBytes`, `TryGetHeader` — a +body-and-headers holder) and the `public abstract` `WebhookEventParser` and `WebhookEvent<…>`. +**`WebhookEventParser.Parse` verifies nothing** — it checks the body is a JSON object and builds the +event; it is a deserializer, not a security boundary. + +If the SDK has a `{RootNamespace}.Webhooks` namespace, it holds a concrete `{Api}WebhookParser`, registered +by `services.Add{Api}Webhooks()`. If that namespace also holds a public `{Api}WebhookSignatureVerifier`, +verify with its `bool Verify(WebhookRequest)` before you parse: it is built from `WebhookOptions` (`Secret`, +`TimeProvider`, and `ReplayTolerance` where present) and registered by +`services.Add{Api}WebhookSignatureVerifier(o => o.Secret = ...)`; its constructor throws +`InvalidOperationException` on a blank `Secret`. Without that class, verification is yours to write against +the provider's published scheme — `Core/Webhooks/Signing/SignatureVerifier` is `internal` and cannot be +called from your code. ## Next diff --git a/plugins/plaid/skills/dotnet/dotnet-configuration-resilience/SKILL.md b/plugins/plaid/skills/dotnet/dotnet-configuration-resilience/SKILL.md index 8d1c807a..e1e44431 100644 --- a/plugins/plaid/skills/dotnet/dotnet-configuration-resilience/SKILL.md +++ b/plugins/plaid/skills/dotnet/dotnet-configuration-resilience/SKILL.md @@ -1,20 +1,17 @@ --- name: dotnet-configuration-resilience -description: Client configuration and resilience for an APIMatic-generated .NET SDK in C# — retries and backoff, timeouts and cancellation, base-URL/server selection, list pagination, SSE streaming, and request/response logging. Load before you register or tune the client — the option names alone do not reveal which calls retry, what a timeout actually bounds, or what you must still set yourself. +description: Load before registering or tuning an APIMatic .NET SDK client in C# — retries and backoff, timeouts and cancellation, base-URL/server selection, list pagination, SSE streaming, request/response logging and hooks. Load it even when the option names look obvious; they don't show which calls retry or what a timeout bounds. --- # Configuration & resilience for an APIMatic .NET SDK -> **One skill, every shape.** This file covers every configuration surface the 4.0.0 generator -> emits. Which parts YOUR SDK exercises — which pagination strategy an operation gets, whether any -> operation declares an idempotency-key parameter, which server variables exist — are facts of the -> API definition, not of this skill: take them from the contract sheet or the map, and **apply -> only the guidance that matches**. +> **One skill, every shape.** This file covers every configuration surface the SDK can have. Which +> ones YOUR SDK uses — the pagination strategy of each operation, any idempotency-key parameters, the +> server variables — is in the contract sheet or the map: **apply only the guidance that matches**. Most types below live under `{RootNamespace}.Core.Configuration` and `{RootNamespace}.Servers`; the exception family (`SdkException` and its leaves — see **dotnet-error-handling**) sits under `.Core.Exceptions` and the per-call `RequestOptions` under `.Core`. Each section names its own namespace. -All of them are generic across APIMatic .NET SDKs built by this generator. ## ServerOptions configuration for each Environment @@ -61,7 +58,7 @@ client to change environment. | Setting | Default | | --- | --- | | `StatusCodesToRetry` | `408, 429, 500, 502, 503, 504` | -| `HttpMethodsToRetry` | `GET, HEAD, PUT, OPTIONS` (idempotent only — gates **every** retry trigger, see notes) | +| `HttpMethodsToRetry` | `GET, HEAD, PUT, OPTIONS` — gates every transient retry trigger, not the OAuth2 `401` re-send (Notes) | | `MaxRetries` | `3` | | `Delay` | `1s` | | `BackOffFactor` | `2` | @@ -70,23 +67,12 @@ client to change environment. | `Timeout` | `100s` (**per attempt**) — **too long for any interactive path; set it explicitly** | | `OnRetry` | `null` | -**Do the arithmetic on those defaults before you accept them.** `MaxRetries = 3` means up to 4 attempts, each -bounded at `100s`, with `1s + 2s + 4s` of backoff between them. What that costs depends on the **verb**, because -`HttpMethodsToRetry` gates *every* retry trigger — including the per-attempt timeout firing (see Notes): - -| Provider behaviour | On a retryable verb (`GET`/`HEAD`/`PUT`/`OPTIONS`) | On any other verb | -| --- | --- | --- | -| **Hangs** (no response at all) | up to **4 × 100s + 7s ≈ 407s** — the per-attempt timeout fires and the rejection **is** retried | ≤ **100s** — one attempt, then the call ends | -| **Fails retryably** (a `503`, a connection reset) | up to **≈ 407s** — each attempt can burn nearly the full timeout | ≤ **100s** — one attempt at the provider's own latency; never resent | - -So the worst case on a `GET` is ≈**7 minutes** on the defaults — almost all of it per-attempt `Timeout`, -not backoff — and up to ≈**9.7 minutes** -(`4 × 100s + 3 × 60s`) against a provider that answers every attempt with a large `Retry-After`, since that -header replaces the backoff and clamps at 60s (see Notes). Either way it is nowhere near the ≈100s the -`Timeout` value suggests. The SDK's send path is fully async, so no thread is blocked — but the request, a -pooled connection and the caller's browser are all held open for that whole window. Treat every default in -this table as a value you have chosen only once you have written it down; `Timeout` in particular has no -defensible default for a request-path call. +**Worst case on the defaults:** up to 4 attempts × `100s` + `1s + 2s + 4s` of backoff ≈ **407s** on a +retryable verb (`GET`/`HEAD`/`PUT`/`OPTIONS`) — whether the provider hangs (the per-attempt timeout is itself +retried) or fails retryably — and up to ≈ **9.7 minutes** (`4 × 100s + 3 × 60s`) if every attempt returns a +large `Retry-After`. Any other verb gets one attempt, ≤ **100s** — two when an OAuth2 `401` is re-sent +(Notes). The request, a pooled connection and your caller are held open for that whole window, so choose +every value in this table deliberately; `Timeout` has no safe default for a request-path call. Customize — always by `with` on `Default()`: every `RetryOptions` member is `required`, so a partial `new RetryOptions { MaxRetries = 5 }` does not compile: @@ -107,80 +93,55 @@ Notes: - The *n*th retry waits `Delay * BackOffFactor^(n-1) + random(0, MaxJitter)` — so the 1st retry waits `Delay` (1s), the 2nd `Delay * BackOffFactor` (2s), and so on. Set `UseExponentialBackoff = false` for a constant `Delay` between attempts. -- **`HttpMethodsToRetry` gates every trigger, not just the status one.** `ShouldHandle` reads - `method is in HttpMethodsToRetry && (transport fault || status is in StatusCodesToRetry)` — the method check - is a top-level `&&` sitting above *both* arms. So with the defaults a `POST`/`PATCH`/`DELETE` is **never** - resent by the SDK: not on a `503`, not on a connection reset, not on a timeout. This is the control that - keeps a non-idempotent write from executing twice, and it is on by default. Adding a verb to - `HttpMethodsToRetry` removes that protection for **every** operation that uses the verb, not just the one - you had in mind — read *Making a write safe under retries* below before you do. -- **Three things trigger a retry on an eligible verb**, and one of them is easy to miss: - `HttpRequestException` (connection reset, DNS failure, dropped socket); `TimeoutRejectedException` — the - SDK's **own per-attempt `Timeout` firing**; and a response whose status is in `StatusCodesToRetry`. Because - the per-attempt timeout is itself a retry trigger, a hung provider on a `GET` costs the *whole* budget - (4 × `Timeout` + backoff), not one `Timeout`. A `TaskCanceledException` — from your own - `CancellationToken`, or from `HttpClient.Timeout` — is **not** in the set and ends the call where it fires. -- **You never catch `TimeoutRejectedException` or the raw `HttpRequestException`.** Polly classifies the - raw exceptions *inside* the pipeline, so retry behaviour is exactly as described above; what leaves the - pipeline is wrapped once, by cause. An exhausted per-attempt `Timeout` reaches your `catch` as - `SdkTimeoutException` — message `"GET https://host/path received no response within 100 s."`, - `Timeout` the window that elapsed, the Polly rejection as `InnerException`. A connection reset, DNS - failure or dropped socket reaches you as `SdkConnectionException` — `"{call} could not be sent: …"` with - the `HttpRequestException` as `InnerException`. Both derive from `SdkException`, so the call's `Method` - and `RequestUri` are on the exception. Your **own** cancellation is the one thing that is never wrapped: - it surfaces as the usual `OperationCanceledException` / `TaskCanceledException`, so the *type* now tells - the SDK's timeout and your cancellation apart — no inner-exception sniffing needed. +- **`HttpMethodsToRetry` gates every transient trigger** — status, transport fault and timeout alike. With + the defaults a `POST`/`PATCH`/`DELETE` is **never** resent on any of them: not on a `503`, not on a + connection reset, not on a timeout — which keeps a non-idempotent write from executing twice. The one + exception is the OAuth2 `401` re-send in the next note, which this list does not gate. Adding a verb removes + that protection for **every** operation using it — read *Making a write safe under retries* below first. +- **An OAuth2 `401` is re-sent once, on any verb.** A call authenticated by an OAuth2 scheme (alone or in an + AND/OR group) that gets a `401` drops the cached token, fetches a new one and is re-sent once — whatever + `HttpMethodsToRetry`, `MaxRetries` or `RetryOptions.Disabled()` say. A request whose body cannot be + replayed (a binary body, a multipart form with a binary part) is not re-sent: its `401` reaches you, and + the next call fetches a fresh token. A static credential's `401` is never re-sent. +- **On an eligible verb three things trigger a retry:** an `HttpRequestException` (connection reset, DNS + failure, dropped socket), the SDK's **own per-attempt `Timeout` firing**, and a status in + `StatusCodesToRetry`. A `TaskCanceledException` — from your own `CancellationToken`, or from + `HttpClient.Timeout` — is **not** retried and ends the call where it fires. +- **What reaches your `catch`:** an exhausted per-attempt `Timeout` as `SdkTimeoutException` (`Timeout` is + the window that elapsed), a connection reset, DNS failure or dropped socket as `SdkConnectionException`; + the raw exception is the `InnerException`, never what you catch. Your own cancellation surfaces unwrapped, + as `OperationCanceledException` / `TaskCanceledException`. See **dotnet-error-handling** for the family + and its messages. - **`Retry-After` overrides the computed backoff.** If the failing response carries a `Retry-After` header (delta-seconds or an HTTP date) that value is used as the delay instead of `Delay × BackOffFactor^n + jitter`. Both paths are then clamped to a hard **60s** ceiling that is not configurable — a provider asking for a 10-minute pause gets 60s, and a large `BackOffFactor` cannot push a single delay past a minute. -- **Multipart is not blanket-excluded.** Retry eligibility is decided per request type *before* the - pipeline runs: a binary-body request with its payload **present** never retries (with the optional - payload absent it is an empty send and stays eligible); a multipart/form-data request retries - **unless it carries a binary part**; JSON, form-url-encoded and empty-body requests are eligible. - An ineligible request is **not** left unprotected — it runs on a *timeout-only* pipeline built - from the same `RetryOptions`, so it keeps the per-attempt `Timeout` and loses only the retry - strategy. -- `Timeout` is **per attempt**, not total — to cap a whole call, use a `CancellationToken` (below). It is - nullable: set `Timeout = null` to disable the per-attempt timeout entirely. +- **Some requests never retry:** one whose binary body is present, or a multipart form with a binary part. + They still get the per-attempt `Timeout`. JSON, form-url-encoded, other multipart and empty-body requests + follow the verb rule. +- `Timeout` is nullable: `null` disables the per-attempt timeout. To cap a whole call, use a + `CancellationToken` (*Bounding a call* below). - `OnRetry`'s `RetryAttempt` also carries `Reason` — `RetryReason.Status(HttpStatusCode)` or - `RetryReason.Failure(Exception)` — log it to record *why* each retry fired. - -⚠▶▶ **A per-attempt timeout does not bound a REQUEST.** If one handler makes more than one SDK call — -a loop over recipients or invoices, a fan-out, a send-then-schedule pair — the per-call timeouts **add up**, and -they add up *faster* when each failure is caught so the work can continue: every swallowed timeout -costs its full bound and the next call still runs. Two calls at 30s is a 60s request; three is 90s. -Put one deadline on the whole handler and pass its token to every call inside it: - -```csharp -using var cts = CancellationTokenSource.CreateLinkedTokenSource(ct); -cts.CancelAfter(TimeSpan.FromSeconds(20)); // the REQUEST's budget, not one call's -var deadline = cts.Token; -// pass `deadline` — not `ct` — to every SDK call in this handler -``` - -**The check, and it is arithmetic, not judgement:** `calls in this handler × per-call timeout` must -sit under the budget you are willing to make a caller wait. If it does not, the per-call timeout is -not a bound on anything the caller can perceive. Count the calls in the loop, not the calls in the -snippet — a handler that processes every record on file makes as many calls as there are -records. + `RetryReason.Failure(Exception)` — log it to record *why* each retry fired. The per-attempt `Timeout` + firing arrives as `RetryReason.Failure(TimeoutRejectedException)` and a dropped connection as + `RetryReason.Failure(HttpRequestException)`, so switch on the exception type to tell them apart. ### Making a write safe under retries -**Start from what the defaults already give you.** `HttpMethodsToRetry` gates every trigger (see Notes), so -out of the box the SDK never resends a `POST`, `PATCH` or `DELETE` — on any trigger. Two gaps remain: +**Start from what the defaults already give you:** the SDK never resends a `POST`, `PATCH` or `DELETE` on a +transient failure (see Notes). Three gaps remain: -- **`PUT` *is* in the default list.** HTTP calls `PUT` idempotent; your provider's `PUT` may still carry a - per-call side effect — an audit row, an outbound webhook, a metered charge — that a resend duplicates. -- **"The SDK did not resend it" is not "the write did not happen."** A transport failure on a `POST` leaves - the outcome *unknown*: the bytes may have reached the provider before the socket died. That is a - reconciliation problem, and no retry setting solves it. +- **An OAuth2 `401` is re-sent on every verb.** That write reaches the provider twice. A `401` usually means + the provider did nothing, but a guard or a test that counts sends sees two. +- **`PUT` *is* in the default list.** Your provider's `PUT` may still carry a per-call side effect — an audit + row, an outbound webhook, a metered charge — that a resend duplicates. +- **"The SDK did not resend it" is not "the write did not happen."** A transport failure on a write leaves + the outcome *unknown*: the bytes may have reached the provider before the socket died. No retry setting + solves that — see *A write whose outcome is unknown*. -**Retries can be turned off.** `RetryOptions.Disabled()` is `Default() with { MaxRetries = 0 }`, and the -factory skips the retry strategy outright when `MaxRetries <= 0` rather than handing `0` to Polly — so there -is no `MaxRetryAttempts >= 1` validation error and no `MaxRetries = 1` floor. `Disabled()` keeps the -per-attempt `Timeout`; only the retries go. The pipeline is built once in the client constructor, so this is a +**Retries can be turned off per client.** `RetryOptions.Disabled()` is `Default() with { MaxRetries = 0 }`; +it keeps the per-attempt `Timeout`. The pipeline is built in the client constructor, so this is a per-**client** choice, not a per-call one. **Decide which requirement you are meeting before you pick a remedy — they are not interchangeable:** @@ -189,66 +150,37 @@ per-**client** choice, not a per-call one. anything counts sends — a side effect the provider records per call, an audit trail, a test asserting exactly one upstream write — these do not satisfy it, and nothing about the code will look wrong. - *"At most one write may reach the provider"* → option 4. It is the only one that holds the count at one - **regardless of configuration**. Two others hold it at one *today*, each with its own way of quietly - stopping: the default `HttpMethodsToRetry` holds until someone widens the list, and option 3 holds until - someone re-enables retries on that client. Neither failure announces itself. + **regardless of configuration**. Two others hold it at one *today* for transient failures, each with its + own way of quietly stopping: the default `HttpMethodsToRetry` holds until someone widens the list, and + option 3 holds until someone re-enables retries on that client. Neither failure announces itself, and + neither stops the OAuth2 `401` re-send. The four, **weakest guarantee first** — so do not read the numbering as a recommendation order: 1. **Make the write idempotent at the provider** — a client-supplied unique reference or idempotency key, where the API offers one. Makes a resend *harmless* rather than rarer; the send count stays above one. - Look at **every member of the operation's `{Operation}Request` record**, not just its body model. The - generator can put a provider's idempotency key in any of three places, and only one of them is the body: - - - a **header member** — a `string?` property on the record, which the method sends as - `new HeaderParam("...", request.X)`; - - a **form field** — a member the method routes into `FormUrlEncodedRequest.Create(new Param(...))`. - Do not search for a nullable type here: the same key can be declared **`required`** on one - operation and `string?` on the next. Match on the member reaching a - `new Param("...", request.X)` in the form body, not on its nullability; - - a field on the **body model** — the type of the record's `Body` member. - - A body-model-only search finds nothing on the first two and concludes wrongly that the API offers no key. - Ask the contract sheet for the operation's full request record, not just its body shape. - - Note that **whether the provider actually rejects a duplicate value is not visible in the record or the - model**. Such a field is typically just a nullable string, equally consistent with a uniqueness-enforced - key and with a free-text label. Verify against live traffic before relying on it; if it is not enforced, - this gives you nothing. - - ⚠ **An `Idempotency-Key` header on the wire is usually not the provider's key.** The generator puts - one on **every** non-GET operation and on no GET. Its value is almost always `Guid.NewGuid()`, injected - by the generator: not a spec parameter, no doc comment, nothing the caller can reach. The exception is - an operation whose own spec declares `Idempotency-Key` as a parameter, where the generator defers to - the caller's value. - - So the header's *presence* tells you nothing — only the **source of its value** does, and that is visible - in the method body, not the signature: `new HeaderParam("Idempotency-Key", request.X)` sends the - caller's key, `new HeaderParam("Idempotency-Key", Guid.NewGuid())` is injected. Three consequences, all - of which cut against the reading you would naturally take: - - - **An injected key makes nothing safe unless your provider consumes that exact header name.** Most APIs - do not document `Idempotency-Key` as their mechanism, and on those it is inert. - - **The value is fresh per call.** `Guid.NewGuid()` is evaluated at the call site, before the resilience - pipeline runs — so it is stable across the SDK's *internal* retry attempts, and different on every - *caller-level* retry. The resend that a job re-running after a timeout produces is exactly the one it - cannot deduplicate. - - **It can sit alongside the real key, under a near-identical name.** One request can carry both the - injected `Idempotency-Key` *header* and a spec-declared `IdempotencyKey` *form field*; only the second - one means anything. Matching on the name alone picks the wrong one. - - The trap is not that an injected key is useless; it is that it is *visible*. Seeing `Idempotency-Key` go - out on the wire, or in a log, reads as evidence that idempotency is handled. Treat it as absent until you - have confirmed both that the provider consumes that header name and that a record member feeds it — and note - the default `HttpMethodsToRetry` includes `PUT`, so a `PUT` is resent by the SDK itself under a header - that probably means nothing to the provider. + Check **every member of the operation's `{Operation}Request` record**, not just its body model — ask the + contract sheet for the full record. The key can be a **header member** (a `string?` the method sends as + `new HeaderParam("...", request.X)`), a **form field** (a member passed to `new Param("...", request.X)` + in the form body — `required` on one operation and `string?` on the next, so match on the `Param`, not + on nullability), or a field of the **`Body` model**. Whether the provider actually rejects a duplicate + value is not visible in the SDK — such a field is typically just a nullable string; verify it against + live traffic before relying on it. + + ⚠ **Every non-GET call sends an `Idempotency-Key` header.** Unless the method fills it from the record + (`new HeaderParam("Idempotency-Key", request.X)`), its value is `Guid.NewGuid()`: stable across the SDK's + own retries, new on every call you make — so it cannot deduplicate a caller-level retry — and inert + unless the provider documents that header. It can sit beside a real `IdempotencyKey` form field under a + near-identical name; only the record member counts. Seeing the header on the wire or in a log is not + evidence that idempotency is handled: treat it as absent until the provider documents that header name + and a record member feeds it. 2. **Reconcile after a failure** — on a transport failure on a write, re-read provider state to establish what actually happened instead of assuming nothing did. (Same reflex as an unreadable write response — see `dotnet-error-handling`.) Detects a duplicate; does not prevent one. How: see *A write whose outcome is unknown* below. -3. **A separate client for writes**, built with `Retry = RetryOptions.Disabled()`. Removes SDK-side resends - entirely while keeping the per-attempt `Timeout`. Worth doing when you have widened `HttpMethodsToRetry` +3. **A separate client for writes**, built with `Retry = RetryOptions.Disabled()`. Removes the transient + resends while keeping the per-attempt `Timeout`; the OAuth2 `401` re-send stays (Notes). Worth doing when you have widened `HttpMethodsToRetry` for the read path and need the write path held at one send regardless. 4. **A `DelegatingHandler` that refuses a re-send it did not authorise** — the only option that holds the count at one no matter how the client is configured, because a blocked attempt never reaches the @@ -256,24 +188,19 @@ The four, **weakest guarantee first** — so do not read the numbering as a reco duplicate would be externally visible or costly to undo, and combine it with option 2 to settle the outcome of the one send you allowed. - Two details decide whether it works, and both are easy to get wrong: + Two details decide whether it works: - - **Do not keep the "already sent" marker on the `HttpRequestMessage`.** A fresh request object is built - for each attempt, so a marker set via `HttpRequestOptionsKey` is gone by the retry and the guard never - fires — measured: 4 sends, i.e. no protection at all. Keep the count in state that outlives the - request, such as an `AsyncLocal` scope the caller opens around the write; retries run inside the - caller's async context, so the scope flows into the handler on every attempt (measured: 1 send). - - **Do not throw an `HttpRequestException` to refuse**, and do not let the refusal path time out — both - are retry triggers, so the refusal itself becomes retryable. Throw a private sentinel type that derives - from `Exception`; it propagates out unwrapped, and your integration boundary translates it. + - **Keep the "already sent" count in state that outlives the request** — e.g. an `AsyncLocal` scope the + caller opens around the write; retries run inside the caller's async context, so the scope reaches the + handler on every attempt. Each attempt builds a fresh `HttpRequestMessage`, so a marker set via + `HttpRequestOptionsKey` is gone by the retry and the guard never fires. + - **Refuse by throwing a private type derived from `Exception`**, not `HttpRequestException`, and don't + let the refusal time out — both are retry triggers. The private type propagates unwrapped; your + integration boundary translates it. Count the send *before* it goes out. A request that failed on the way out may still have been received, - so "this may already have taken effect" is the only safe reading — surface it as an **unknown outcome** - to be settled by re-reading provider state (option 2), not as a definite failure. - -`HttpMethodsToRetry` **is** the primary control here — it gates every trigger, and keeping non-idempotent -verbs out of it is most of the job. The options above cover what it cannot: a `PUT` with side effects, a list -you have widened, and the unknown outcome a transport failure leaves behind. + so surface it as an **unknown outcome** settled by re-reading provider state (option 2), not as a + definite failure. **All four bound the call YOU make to the provider. None of them is a reason to change the contract your own callers see.** Taking an idempotency key from your callers can be a deliberate API design; @@ -345,23 +272,16 @@ There are three places a bound can live, and **two of the three are per-attempt* Both per-attempt timeouts stop when the response headers arrive; reading the body after that is bounded only by your `CancellationToken` (on an event stream, also by `StreamReadTimeout`, below). -**`HttpClient.Timeout` is applied per attempt here, which is not obvious.** It is enforced by a CTS created -inside each `SendAsync`, and the retry pipeline sits *above* `SendAsync` — so every retry gets a fresh full -`Timeout`. - -**Two per-attempt timeouts, and on a retryable verb only one of them ends the call.** -`options.Retry.Timeout` expiring raises `TimeoutRejectedException` *inside* the pipeline, which *is* in the retry set — on an eligible verb the -attempt is retried and the cost multiplies (that is the ≈407s row above); only once the retries run out does -the SDK convert it to the `SdkTimeoutException` you catch. `HttpClient.Timeout` expiring raises -`TaskCanceledException` inside the pipeline, which is *not* in the set — so it ends the call the first time -it fires, on any verb — and the SDK converts that too, into the **same** `SdkTimeoutException` (with -`Timeout = HttpClient.Timeout`), so a caller cannot tell from the type which knob fired; `Timeout` says -which. (On a non-retryable verb the distinction collapses: neither is retried and both end the call on -the first fire.) That asymmetry makes `HttpClient.Timeout` the cheapest bound on the wait for the response -headers: a `10s` value bounds that wait at ≈10s whatever the verb. What it does not bound is a provider that fails *retryably* just under the limit on every attempt — that still costs -≈ `4 × 10s + 7s ≈ 47s`. It is also the only bound left standing if you set `options.Retry.Timeout = null`. A -good backstop and the cheapest fix for a hang before the headers; still not a call budget. (An *infinite* `HttpClient.Timeout` -never fires, and a `TaskCanceledException` under one is not the SDK's to explain — it passes through raw.) +**`HttpClient.Timeout` also applies per attempt** — every retry gets a fresh full window. + +**On a retryable verb only one of the two per-attempt timeouts ends the call.** `options.Retry.Timeout` +firing is retried (the ≈407s case); `HttpClient.Timeout` firing is not — it ends the call the first time, on +any verb — so a `10s` value bounds the wait for the response headers at ≈10s, though a provider failing +*retryably* just under it on every attempt still costs ≈ `4 × 10s + 7s ≈ 47s`. Both surface as +`SdkTimeoutException`, whose `Timeout` says which fired. With `options.Retry.Timeout = null` it is the only +per-attempt bound left. An *infinite* `HttpClient.Timeout` never fires, and a `TaskCanceledException` under one +passes through unwrapped. A good backstop and the cheapest fix for a hang before the headers; still not a call +budget. Set all three — they catch different failures. The per-attempt bounds cap one attempt's wait for the headers; the token caps the sum, which is the only thing your caller experiences: @@ -393,11 +313,11 @@ async Task Bounded(Func> call, CancellationToke Then every operation goes through `Bounded(...)`, and the budget is one value in one place. -**The invariant to check:** your worst case — `attempts × per-attempt timeout + total backoff` — must sit -below the deadline your own caller is working to. If it does not, the caller times out first and your retries -are burning provider capacity for a response nobody is still waiting for. A `TaskCanceledException` from your -own token is **not** retried and **not** wrapped (see Notes above), so the token cuts the call cleanly and -surfaces as itself. +**The check:** `calls in the handler × (attempts × per-attempt timeout + backoff)` must sit below the +deadline your own caller is working to — count loop iterations, not lines of code. A handler that makes +several SDK calls (a loop over recipients or invoices, a fan-out, a send-then-schedule pair) adds up their +bounds, and faster when each failure is caught so the work continues; pass one `Bounded` deadline token to +every call in it. Cancelling that token is not retried, so it cuts the call cleanly. ## The clock — `TimeProvider` @@ -405,29 +325,22 @@ Every place the SDK reads time goes through **one** option, `options.TimeProvide `System.TimeProvider`, default `TimeProvider.System`): the retry backoff and the `Retry-After` arithmetic, the per-attempt `Timeout`, the SSE idle window (`StreamReadTimeout`, below), OAuth2 token expiry, webhook replay tolerance (its own `WebhookOptions.TimeProvider`) and the elapsed-milliseconds figure in the response -log line. There is no second clock inside the engine — a component that needs time is handed this one, and -never falls back to `TimeProvider.System` on its own. +log line. ```csharp options.TimeProvider = TimeProvider.System; // the default; set it only to substitute a clock ``` -Under `services.Add{Api}Client(...)` the option is **seeded from the container before your `configure` -callback runs**: a `TimeProvider` you registered — in any order relative to the SDK registration — is picked -up, and a value you assign in `configure` wins over it. The SDK **never registers** a `TimeProvider` in your -container, so it neither collides with yours nor leaves one behind. The precedence is: explicit option > -container registration > `TimeProvider.System`. The same seeding applies to -`Add{Api}WebhookSignatureVerifier` for webhooks. +Under `services.Add{Api}Client(...)`, a `TimeProvider` registered in your container — in any order relative +to the SDK registration — is used unless your `configure` callback sets one: explicit option > container +registration > `TimeProvider.System`. The SDK **never registers** a `TimeProvider` itself. The same applies to +`Add{Api}WebhookSignatureVerifier`. -The practical consequence is for tests: one fake clock on `options.TimeProvider` drives retries, idle -timeouts and token expiry together, with no real sleeps. Use a provider that **implements timers** — -`FakeTimeProvider` from `Microsoft.Extensions.TimeProvider.Testing` — because the backoff and the idle -window are timers on the provider; a `GetUtcNow`-only fake throws when the SDK asks for one. See -**dotnet-testing** § *Fake the clock*. +To fake it in tests, see **dotnet-testing** § *Fake the clock*. ## Pagination -Operations the API marks as paginated return **`Pageable<{PageResponse}, {Item}>`**, and the shape catches +Paginated operations return **`Pageable<{PageResponse}, {Item}>`**, and the shape catches people out: `Pageable` implements `IAsyncEnumerable<`**`TItem`**`>`, so a plain `await foreach` walks **individual items**, not pages. The SDK fetches each page and advances the paging state for you — one of five strategies (offset, cursor, keyset, `Link`-header, or page-number), chosen per operation. @@ -476,18 +389,6 @@ me when to stop" as the *only* stop condition and you have written an unbounded returning a next-page link, a cursor that fails to advance, or a filter the provider quietly ignores will each spin until something else kills the request. -What that failure looks like in production — the request does not return slowly, it **does not return at -all**: - -``` -status=0 upstream=55909 -CLIENT_ERROR:TaskCanceledException:The request was canceled due to the configured -HttpClient.Timeout of 75 seconds elapsing. -``` - -Tens of thousands of provider calls billed, the caller left holding a dead request, and no error the -provider can be blamed for. The bug is entirely on the consuming side. - **Every page loop needs at least one bound that does not depend on the provider's cooperation.** Pick the one that matches the use case; a page cap is the cheapest and is never wrong: @@ -516,7 +417,7 @@ If there is no such convention and the return type genuinely cannot change, thro silently. ⚠⚠ **A `LogWarning` at the cap followed by `return results;` is the defect.** Log it as well, never instead. -**No-throw variant.** Where generated, a sibling `{Operation}Result` returns +**No-throw variant.** Where it exists, a sibling `{Operation}Result` returns `Pageable, {Item}>` — the same streaming, but its **`.AsPages(ct)`** hands you an `ApiResult` per page that you inspect instead of it throwing: @@ -536,15 +437,13 @@ await foreach (var result in client.{ApiGroup}.{Operation}Result(request, cancel > Not every list endpoint is paginated. An operation with no pagination metadata is a plain list call > (returns a list or a wrapper — see **dotnet-calling-endpoints**); to page one of those, drive its own -> `page`/`perPage` query params yourself and stop when a page returns fewer than `perPage` items. -> **A hand-driven loop needs the same bound as an auto-paginated one** — "fewer than `perPage`" and -> "no next-page link" are both provider-supplied stop conditions, and neither is a bound. Carry a page -> cap alongside it (see *Never leave a page loop unbounded* above). +> `page`/`perPage` query params yourself, stop when a page returns fewer than `perPage` items, and carry +> the same page cap (see *Never leave a page loop unbounded* above). ## Streaming (Server-Sent Events) -Operations the API marks as streaming (`text/event-stream`) are generated to **return -`Task>`** — `await` the call once to open the stream, then `await foreach` the +A streaming (`text/event-stream`) operation **returns `Task>`** — `await` the +call once to open the stream, then `await foreach` the frames as the server emits them. `{Item}` is `string` for a plain-text stream, or a typed model for a JSON event stream. @@ -573,28 +472,16 @@ catch (SdkConnectionException ex) // the connection dropped mid-st } ``` -**Idle timeout.** A stalled stream is bounded by the **`StreamReadTimeout` client option** — the maximum -wait **between frames**, a `TimeSpan?` on `{Api}ClientOptions` defaulting to **60 s**; set it to `null` to -wait indefinitely. It bounds only the wait for the server between frames, never your own processing time -inside the loop. When it elapses the SDK tears the stream down and the enumeration throws -`SdkTimeoutException` with `Timeout` set to the window that elapsed — the same leaf that reports a -per-attempt timeout on an ordinary call, so one `catch (SdkTimeoutException)` covers both. The window is -measured on `options.TimeProvider` (see *The clock* above), so a fake clock drives it in tests. - -**Errors** (all under `{RootNamespace}.Core.Exceptions`, all `SdkException`s that name the call): -- **Before the stream opens** — the opening `await` throws `ApiException`, with `TError` the same - two-case shape as any operation: a typed `{Operation}Error` (Case A) or `RawError` (Case B), per what the - operation declares (see **dotnet-error-handling**). -- **While enumerating** — there is no SSE-specific exception type; the family's ordinary leaves apply: - - `SdkTimeoutException` — no frame arrived within `StreamReadTimeout`; carries `Timeout`. - - `ResponseDeserializationException` — a frame couldn't be parsed as `{Item}`; carries `TargetType` and - the underlying `JsonException` (or `FormatException` for a parsed scalar) as `InnerException`. The raw - frame text is **not** on the exception or in its message. A plain-`string` stream cannot raise it. - - `SdkConnectionException` — the connection dropped mid-stream (`"{call} could not read the response - body: …"`, the `IOException` / `HttpRequestException` as `InnerException`). -- Retries do **not** apply once the stream is open; cancel via the `CancellationToken` - (`stream.WithCancellation(ct)`) to stop early — your cancellation surfaces as `OperationCanceledException`, - never wrapped. +**Idle timeout.** `StreamReadTimeout` on `{Api}ClientOptions` (a `TimeSpan?`, default **60 s**, `null` to +wait indefinitely) bounds the wait **between frames**, never your own processing inside the loop. When it +elapses the SDK tears the stream down and the enumeration throws `SdkTimeoutException` with `Timeout` set to +the window — the same leaf as a per-attempt timeout, so one `catch (SdkTimeoutException)` covers both. + +**Errors:** the opening `await` throws `ApiException` — Case A or B, as for any operation (see +**dotnet-error-handling**). While enumerating there is no SSE-specific type; the three leaves in the sample +apply. The raw frame text is **not** on `ResponseDeserializationException` or in its message, and a +plain-`string` stream cannot raise it. Retries do **not** apply once the stream is open; cancel with +`stream.WithCancellation(ct)` to stop early. ## Logging @@ -606,7 +493,7 @@ and one of the three cases is almost certainly your production path: | how the client is built | `LoggerFactory` null means | | --- | --- | | `services.Add{Api}Client(...)` | the extension fills it from the container's `ILoggerFactory` — **logging is already on**, at your host's minimum level, and the request line goes to your normal log sinks | -| `new {Api}Client(httpClient, options)` by hand | `NullLoggerFactory` — nothing is written, *unless* `{APICLIENTTYPENAME}_LOG` is set (see below) | +| `new {Api}Client(httpClient, options)` by hand | `NullLoggerFactory` — nothing is written, *unless* `{API}_LOG` is set (see below) | | you assign it yourself | your factory is used and the environment variable is ignored outright | The first row is the one that surprises people: in any ASP.NET Core or generic-host app the SDK is logging @@ -628,9 +515,8 @@ options.Logging = new LoggingOptions }; ``` -What it emits, and at which level — every row is additionally gated by `_logger.IsEnabled(level)`, so a -factory whose minimum level is `Warning` emits no request line at all; the SDK's switches are a *second* -gate, not the only one: +What it emits, and at which level — each row is also filtered by your `ILoggerFactory`'s minimum level, so a +`Warning` minimum emits no request line at all: | Event | Level | On by default | | --- | --- | --- | @@ -659,27 +545,22 @@ not. On any endpoint that carries card data, bank details, personal data or a cr switching this on writes that data to your logs. Leave it off in production; turn it on for one endpoint at a time behind a flag you can prove is off. -⚠▶▶ **An environment variable turns all of this on without a code change.** When -`options.Logging.LoggerFactory` is *still* `null` at construction — which in practice means a client you -constructed yourself, since `Add{Api}Client` always fills it (it calls `AddHttpClient()`, which registers an -`ILoggerFactory`) — the SDK reads -`{APICLIENTTYPENAME}_LOG`, the client type name upper-cased plus `_LOG`. It accepts `info`, `debug` or -`trace`, and writes to **stderr** through a built-in console logger. `debug` additionally forces request *and* response headers on; **`trace` additionally forces -`LogRequestBody` on**, i.e. unredacted JSON bodies to stderr on a host you may not control. Assigning -`LoggerFactory` yourself disables the variable outright — which is the reason to set it explicitly in -production even when you point it at `NullLoggerFactory.Instance`. - -**Per-call override.** Every generated operation takes a `RequestOptions? requestOptions = null` argument -with two properties: `LogLevel?` — the logging override this section covers — and `Hooks`, the per-call -hook list (see *Hooks* below). Passing `new RequestOptions { LogLevel = LogLevel.Debug }` **sets** the -verbosity for that one call without touching the client's configuration — useful for tracing one failing -endpoint. Two things about it are easy to get wrong: - -- It **replaces** the per-switch defaults in *both* directions, rather than only raising them. `Trace` turns - the body and headers on even when `LogRequestBody` is `false`; a value *above* `Information` — `Warning`, - say — switches the request line and the success response line **off** for that call. -- It cannot lift a level your `ILoggerFactory` has filtered out. `_logger.IsEnabled(level)` is still ANDed in - front, so a per-call `Trace` against a factory whose minimum is `Information` logs nothing extra. +⚠ **An environment variable turns all of this on without a code change.** When +`options.Logging.LoggerFactory` is *still* `null` at construction — in practice a client you constructed +yourself, since `Add{Api}Client` always fills it — the SDK reads `{API}_LOG`, the SDK name in upper snake +case plus `_LOG`. It accepts `info`, `debug` or `trace`, and writes to **stderr** through a +built-in console logger. `debug` also forces request *and* response headers on; **`trace` also forces +`LogRequestBody` on** — unredacted JSON bodies to stderr on a host you may not control. Assigning +`LoggerFactory` yourself — even `NullLoggerFactory.Instance` — disables the variable, so set it explicitly in +production. + +**Per-call override.** `new RequestOptions { LogLevel = LogLevel.Debug }`, passed as the `requestOptions` +argument every operation takes (see **dotnet-calling-endpoints**), **sets** the verbosity for that one call +without touching the client's configuration. It replaces the per-switch defaults in *both* directions: `Trace` +turns the body and headers on even when `LogRequestBody` is `false`, and a level above `Information` — +`Warning`, say — turns the request line and the success response line **off** for that call. It cannot get +past your `ILoggerFactory`'s minimum level: a per-call `Trace` against an `Information` minimum logs nothing +extra. ### Hooks — the SDK's own request/response seam @@ -705,11 +586,10 @@ The facts that decide how you use them: rate-limit budgets, a request-id echo) — the operation's return value carries only the body. A per-call hook can close over a local, which puts the observed value in scope in the same method's `catch`; a client-wide hook needs `AsyncLocal` or a scoped service to reach it. -- **A hook is an observation seam, not a veto point.** An exception thrown from a hook is not retried - (the transport arm retries only `HttpRequestException` and the timeout rejection) — it just fails the - call, and a throwing `OnResponse` fails a call that succeeded on the wire. To refuse a re-send, use - the write-guard `DelegatingHandler` under *Make the write idempotent* — a blocked attempt must never - reach the network, which no observation hook can guarantee. +- **A hook is an observation seam, not a veto point.** An exception thrown from a hook is not retried — it + fails the call, and a throwing `OnResponse` fails a call that succeeded on the wire. To refuse a re-send, + use the write-guard `DelegatingHandler` (option 4 under *Making a write safe under retries*): a blocked + attempt never reaches the network, which no hook can guarantee. ### When you still want a `DelegatingHandler` @@ -738,51 +618,30 @@ var httpClient = new HttpClient(new LoggingHandler { InnerHandler = new HttpClie var client = new {Api}Client(httpClient, options); ``` -With DI, the SDK's `Add{Api}Client` resolves the **default (unnamed)** `IHttpClientFactory` client, so attach -the handler to that one — register it and configure the default client *before* (or alongside) the SDK -registration: - -```csharp -services.AddTransient(); -services.AddHttpClient(Options.DefaultName).AddHttpMessageHandler(); -services.Add{Api}Client(options => { /* ... */ }); // resolves CreateClient() → the default client -``` - -The handler then runs on every SDK call — but so does everything else you configure on the default client, -for **every other unnamed `CreateClient()` consumer in the app**. If that blast radius is unwelcome, skip the -extension and register the client over a **named** `HttpClient` instead -(`services.AddHttpClient("my-api").AddHttpMessageHandler()`, then construct -`new {Api}Client(factory.CreateClient("my-api"), options)`), which keeps the handler, timeout and primary -handler scoped to this SDK. See **dotnet-client-initialization**. - -The `OnRetry` callback above is also a convenient place to observe retry activity. +Under `Add{Api}Client`, attach it to the **default (unnamed)** `HttpClient` the extension resolves +(`services.AddHttpClient(Options.DefaultName).AddHttpMessageHandler()`, with the handler +registered as transient) — which also affects every other unnamed consumer in the app — or register the +client over a **named** `HttpClient`; see **dotnet-client-initialization**. ### Verify on the wire (first run of any new integration) **Run the built-in logger on the first execution of any new call and inspect the output** — the default `Information` request line is enough, so this costs one `LoggerFactory` assignment. Path/template params are -not type-checked against the route (internally the value is -`object?`; it is normalised *through* JSON — which is why an enum contributes its wire value and not its C# -member name — then substituted as the resulting scalar's plain text, URL-escaped, by a plain string -replace), and on a **successful** response the -SDK returns only the deserialized body — it never surfaces the request URL or status (see -**dotnet-error-handling**). So a wrong verb, a leftover `{placeholder}`, or a mis-serialized path segment -**compiles cleanly** and produces no in-band signal; the only symptom is a runtime `404`/`422`. +not type-checked against the route (an enum contributes its wire value, not its C# member name), and a +**successful** call returns only the deserialized body — never the request URL or status. So a wrong verb, a +leftover `{placeholder}`, or a mis-serialized path segment **compiles cleanly** and shows only as a runtime +`404`/`422`. Checklist for the first printed request: 1. the **verb** matches the operation (a `404` on a path you believe exists often means the wrong method); -2. the **path** is fully formed. The failure to watch for is silent and unobvious: a path parameter whose - value is null or empty collapses to **nothing**, leaving a doubled slash (`/orders//authorize`) — not a - leftover marker. (An unbound `{placeholder}` would survive, but the generator supplies every declared - path param, so that is only reachable through a hand-set `BaseUrl`; and it prints percent-encoded, - `%7Bid%7D`, not as `{id}`.) +2. the **path** is fully formed — a null or empty path parameter collapses to **nothing**, leaving a + doubled slash (`/orders//authorize`), not a leftover marker. Only a `{placeholder}` in a hand-set + `BaseUrl` survives, and it prints percent-encoded (`%7Bid%7D`); 3. each **path-param segment** is the value the API expects — for an enum that is the **wire value** - (frequently ALL-CAPS), not the C# member name; the generated constants carry it. Nothing normalises - casing and there is no public factory, so the only way an unexpected string reaches the URL is a value - the server itself sent and your code echoed back — check `IsKnownValue()` before reusing one as input; -4. the query params you set actually appear in the query string — remembering that a value is masked - unless its key is on the known-safe list (`cursor`, `dates`, `datetime`, `limit`, `offset`, `page`, - `since`, `size`, `strings`), so for anything else you are checking that the key is present, not what it - carries. + (frequently ALL-CAPS), not the C# member name; check `IsKnownValue()` before echoing a server-sent value + back (see **dotnet-models**); +4. the query params you set actually appear in the query string — a value is masked unless its key is on + the known-safe list (see *Logging*), so for any other key you are checking that it is present, not what + it carries. Drop the level back once verified. diff --git a/plugins/plaid/skills/dotnet/dotnet-error-handling/SKILL.md b/plugins/plaid/skills/dotnet/dotnet-error-handling/SKILL.md index b4fd301b..81e5f32c 100644 --- a/plugins/plaid/skills/dotnet/dotnet-error-handling/SKILL.md +++ b/plugins/plaid/skills/dotnet/dotnet-error-handling/SKILL.md @@ -1,6 +1,6 @@ --- name: dotnet-error-handling -description: Error and exception handling for an APIMatic-generated .NET SDK in C# — load before writing any try/catch around an SDK call, an exception-translation layer, or error middleware. Covers which exception types actually reach your catch blocks, how to read status codes and error bodies safely, and the traps that make an otherwise reasonable catch ladder silently wrong. +description: Load before writing any try/catch around a call on an APIMatic .NET SDK in C#, an exception-translation layer or error middleware — which exception types reach your catch, the SdkException family, typed error bodies versus RawError, reading status codes and error bodies, and the non-throwing ApiResult variant. --- # Error handling for an APIMatic .NET SDK @@ -8,26 +8,21 @@ description: Error and exception handling for an APIMatic-generated .NET SDK in > Throughout this skill, `{...}` is a placeholder for a name you take from your SDK (e.g. `{Operation}`, > `{ApiGroup}`, `{RootNamespace}`) — replace it with the concrete identifier from the source. > -> **One skill, every error shape.** This file covers every shape the 4.0.0 generator can emit. -> Which shapes YOUR SDK uses — which case each operation is, whether typed bodies carry a status, -> which `TryGet…` accessors exist — are facts of the API definition, not of this skill: take them -> from the operation's map row or the contract sheet, and **apply only the guidance that -> matches**. An API can be all Case B, nearly all Case A, or a mix. +> **One skill, every error shape.** This file covers every error shape the SDK can have. Which ones +> YOUR SDK uses — which case each operation is, whether typed bodies carry a status, which `TryGet…` +> accessors exist — is on the operation's map row or the contract sheet: **apply only the guidance +> that matches**. An API can be all Case B, nearly all Case A, or a mix. Endpoint methods **throw on non-success responses** by default (for a non-throwing alternative, see the **`ApiResult`** section below). The thrown type is always the generic `ApiException` — but `TError` comes in **two shapes**, depending on the operation: - **Typed model (Case A)** — a per-operation `{Operation}Error` (subclass of `ApiError`) exists under - `Errors/` for the operation; `TError` is that type and you read it with typed `TryGet*` accessors. + `Errors/` for the operation; `TError` is that type. Dispatch on it with its exhaustive `Match` (one + `on{Arm}` per declared body plus a required `otherwise`), or read one body with a `TryGet*` accessor. - **`RawError` (Case B)** — when the operation has no `{Operation}Error` type, `TError` is `RawError` *directly*. `RawError` is **not** an `ApiError` and has **no** `TryGet*` / `TryGetRawError` accessors; you - read the status and body straight off `ex.Error`. How common this is, is an API fact — some APIs are almost - entirely Case B, others almost entirely Case A; each operation's map row says which it is. - -`ApiException` is declared `public sealed class ApiException : ApiException` with **no** -`where TError : ApiError` constraint — which is exactly why `TError` can be either an `ApiError` model or a -`RawError`. + read the status and body straight off `ex.Error`. ### The `SdkException` family @@ -41,7 +36,7 @@ SdkException (abstract) Method, RequestUri — the call │ └─ ResponseDeserializationException TargetType — a body (success OR error) did not match the declared type ├─ SdkConnectionException — — no usable response: could not send, or could not read the body │ └─ SdkTimeoutException (sealed) Timeout — an attempt, the transport, or an SSE stream went silent -└─ AuthSchemeException (sealed) SchemeFailures — a credential could not be applied +└─ AuthSchemeException (sealed) SchemeFailures — a required credential is not configured, a provider returned nothing, or a credential could not be applied ``` Three rules follow from the shape, and the rest of this skill applies them: @@ -49,47 +44,31 @@ Three rules follow from the shape, and the rest of this skill applies them: - **Catch specific to general.** `ApiException` means *the server answered* (you have a status); `SdkConnectionException` means *it did not*; `SdkException` is *everything the SDK raises*. A ladder that handles only `ApiException` is incomplete — see *Connection failures* below. -- **The raw cause is always `InnerException`** — the `JsonException`, the `HttpRequestException`, the Polly - timeout rejection, the token endpoint's own failure — never the thing you catch. +- **The raw cause is always `InnerException`** — the `JsonException`, the `HttpRequestException`, the + per-attempt timeout's rejection, the token endpoint's own failure — never the thing you catch. - **Your own cancellation is never wrapped.** An `OperationCanceledException` from a token *you* cancelled passes through untouched; a `catch (SdkException)` does not see it. -The messages are a contract, asserted verbatim by the SDK's own tests, and each names the call with its query -stripped: `"GET https://host/path returned 400 (BadRequest)."`, `"{call} could not be sent: …"`, +Every message names the call with its query stripped: `"GET https://host/path returned 400 (BadRequest)."`, +`"{call} could not be sent: …"`, `"{call} could not read the response body: …"`, `"{call} received no response within 100 s."`, `"{call} returned a body that could not be deserialized into {Type}."`. A log line therefore identifies the failing call without a typed catch. -These types live in **distinct** namespaces — `Core.*` is **not** a single namespace, so don't assume -`ApiError` sits with the exceptions under `Core.Exceptions`: - -- the whole `SdkException` family → `{RootNamespace}.Core.Exceptions` -- `ApiError` **and** `RawError` → `{RootNamespace}.Core.ErrorResponse` -- the per-operation `{Operation}Error` models (e.g. `CreateWidgetError`) → `{RootNamespace}.Errors` +`Core.*` is **not** one namespace — don't assume `ApiError` sits with the exceptions: -So a typed (Case A) catch needs up to **four** namespaces, not three — how many depends on whether you -spell the `out` types out or use `out var`: - -| namespace | what you need from it | +| namespace | holds | | --- | --- | -| `{RootNamespace}.Core.Exceptions` | `ApiException` — the exception itself (and the rest of the family) | -| `{RootNamespace}.Errors` | the `{Operation}Error` you name in the `catch` | -| `{RootNamespace}.Core.ErrorResponse` | `RawError`, which the inherited `TryGetRawError` hands back | -| *depends on the body* | the **typed body** a `TryGet…` yields — see below | +| `{RootNamespace}.Core.Exceptions` | the whole `SdkException` family, `ApiException` included | +| `{RootNamespace}.Core.ErrorResponse` | `ApiError` and `RawError` (which the inherited `TryGetRawError` hands back) | +| `{RootNamespace}.Errors` | the per-operation `{Operation}Error` models (e.g. `CreateWidgetError`) | -**The fourth is not a fixed namespace.** A typed body is whatever the API definition declared, so where -its type lives follows the body's schema kind — a model in `{RootNamespace}.Models`, a union in +A typed body's type lives wherever its schema kind puts it — a model in `{RootNamespace}.Models`, a union in `.Models.OneOf` / `.Models.AnyOf`, an enum in `.Models.Enums`, a binary body in `.Core.Models` -(`ErrorByteContent`), and a map or dynamic body in no SDK namespace at all -(`IReadOnlyDictionary` needs `System.Collections.Generic` and `System.Text.Json`). A -scalar body — `TryGetString`, `TryGetLong` — needs nothing. Read the accessor's `out` type and import what -*it* names; do not assume `.Models`. - -The last two rows only bite when you write the `out` type out. `out var` needs neither, which is why the -template below imports three namespaces and not four — it uses `out var` for the typed bodies and names -`RawError` explicitly. A Case B catch needs only -`Core.Exceptions` and `Core.ErrorResponse`. This namespace layout is identical across the APIMatic .NET SDKs -checked. +(`ErrorByteContent`), a map or dynamic body in the BCL (`IReadOnlyDictionary` needs +`System.Collections.Generic` and `System.Text.Json`); a scalar body (`TryGetString`, `TryGetLong`) needs +nothing. Import what an `out` type you spell out names — `out var` needs none, which is why the template +below imports three namespaces. ## Catch the exception @@ -147,17 +126,23 @@ memory: 1. **List *every* `TryGet...` accessor the operation's `{Operation}Error` declares.** The operation's map row already lists them (with the HTTP status each maps to); take them from the contract sheet. - They are the `public bool TryGet...(out ...)` methods on the `{Operation}Error` type (grounded + They are the `public bool TryGet...([NotNullWhen(true)] out ...? value)` methods, a bare `out` for a + value-type body such as `long`, on the `{Operation}Error` type (grounded from the SDK map/source). These accessors are generated per operation — one per distinct error body the operation maps — and their names embed the body type. Expect a mix of: - **typed-body accessors** named after a model or scalar — `TryGetValidationErrors`, `TryGetProblemDetails`, `TryGetString`, `TryGetLong`, …; - - **status-specific `RawError` accessors** — e.g. `TryGetNoContent(out RawError)` — the names on your operation come from its map row; - - the inherited **`TryGetRawError(out RawError)`**, which every `{Operation}Error` exposes. -2. **Write one `if` / `else if` branch per `TryGet*` method — cover them all, and put `TryGetRawError` - *last*.** Each public `TryGet*` corresponds to a status/body the operation can return; skip one and you - silently drop that response. `TryGetRawError` must be the final branch because it is **not** a catch-all - (see below) — it only fires for statuses that have no more-specific accessor. + - **status-specific `RawError` accessors** — e.g. `TryGetNoContent([NotNullWhen(true)] out RawError? value)` — the names on your operation come from its map row; + - the inherited **`TryGetRawError([NotNullWhen(true)] out RawError? error)`**, which every `{Operation}Error` exposes. +2. **Dispatch through `ex.Error.Match(...)`, passing every arm by name.** `Match` has one `on{Arm}` + parameter per `TryGet{Arm}` accessor (same stem, same value) plus a required `otherwise` that receives + the `RawError` of a status the operation does not declare — the compiler refuses a call that leaves an + arm out, so no response is silently dropped. Pass the arms by name: they are positional, in the + ordinal order of their names, and a regenerated SDK whose operation gains or loses an error body + changes the signature (a source and binary break for a positional call site). Reach for a single + `TryGet{Arm}` only when one body is all you need, and for `TryGetRawError` only as the accessor + behind `otherwise`: it is **not** a catch-all — a status with a typed or status-specific accessor + (a `422` validation payload, `TryGetNoContent`) leaves it **false**. ```csharp using {RootNamespace}.Core.Exceptions; // ApiException @@ -171,38 +156,19 @@ try } catch (ApiException<{Operation}Error> ex) { - // ex.StatusCode / ex.Headers are always here; the body is behind the accessors below. - // ONE branch per public TryGet* declared on {Operation}Error — copy the exact names from the class - // under Errors/. The TryGet{...} names below are PLACEHOLDERS; yours are named after this operation's - // responses (a typed body may be a model OR a scalar such as TryGetString/TryGetLong). - if (ex.Error.TryGet{TypedBody1}(out var body1)) // e.g. TryGetValidationErrors — a typed body - { - // inspect body1 - } - else if (ex.Error.TryGet{TypedBody2}(out var body2)) // e.g. TryGetProblemDetails — another typed body - { - // inspect body2 - } - else if (ex.Error.TryGet{Status}(out RawError statusRaw)) // e.g. TryGetNoContent(out RawError) — status-specific - { - Console.Error.WriteLine($"HTTP {(int)statusRaw.StatusCode}"); - } - // ... KEEP GOING: one else-if for EVERY remaining TryGet* the class declares — do not stop early ... - else if (ex.Error.TryGetRawError(out RawError raw)) // ALWAYS LAST: fallback for untyped statuses only - { - Console.Error.WriteLine($"HTTP {(int)raw.StatusCode}: {raw.ReadAsString()}"); - } + // ex.StatusCode / ex.Headers are always here; the body is behind the arms below. + // ONE named arm per public TryGet* declared on {Operation}Error — copy the exact names from the class + // under Errors/ (on{Body} pairs with TryGet{Body}). The on{...} names below are PLACEHOLDERS; yours are + // named after this operation's responses (a typed body may be a model OR a scalar such as onString/onLong). + ex.Error.Match( + on{TypedBody1}: body1 => { /* inspect body1 — e.g. onValidationErrors */ }, + on{TypedBody2}: body2 => { /* inspect body2 — e.g. onProblemDetails */ }, + on{Status}: statusRaw => Console.Error.WriteLine($"HTTP {(int)statusRaw.StatusCode}"), // e.g. onNoContent + // ... one named arm for EVERY remaining TryGet* the class declares — the compiler enforces it ... + otherwise: raw => Console.Error.WriteLine($"HTTP {(int)raw.StatusCode}: {raw.ReadAsString()}")); // undeclared status } ``` -**Why `TryGetRawError` goes last — it is not a universal fallback.** It returns a raw body **only** for -statuses that have no more-specific accessor on this `{Operation}Error`; a status that has a typed accessor -(e.g. a `422` validation payload) lands in that typed slot and leaves `TryGetRawError` **false**. The -status-specific `RawError` accessors (e.g. `TryGetNoContent(out RawError)`) are likewise **not** surfaced by -`TryGetRawError`. So if you check `TryGetRawError` first — or omit any of the more-specific accessors — those -typed and status-specific bodies are silently dropped. Enumerate the class and handle every accessor -explicitly. - **Don't factor error-reading into a shared helper typed as `ApiError`.** The typed `TryGet*` accessors live on the concrete `{Operation}Error`, *not* on the `ApiError` base — which exposes only `TryGetRawError`. A helper like `string Describe(ApiError e)` can therefore reach **only** `TryGetRawError`, so for any status @@ -233,24 +199,25 @@ catch (ApiException ex) } ``` -Case B needs no `.Errors` using — `RawError` lives under `{RootNamespace}.Core.ErrorResponse`. Its public -members are `StatusCode`, `ReadAsBytes`/`ReadAsString`/`ReadAsJson`; note +Case B needs no `.Errors` using. `RawError`'s public members are `StatusCode`, +`ReadAsBytes`/`ReadAsString`/`ReadAsJson`; note `ReadAsJson()` **throws `JsonException`** when the body isn't valid JSON — and a `RawError` body may not be (a gateway or proxy can answer with HTML or plain text), so prefer `ReadAsString()` unless you know it's JSON. ## Result-style alternative — `ApiResult` (no throwing) -The generator can **optionally** emit a result-style variant of an operation — so it's not guaranteed to -exist. When enabled, it appears as a **sibling method** named `{Operation}Result` (next to the throwing -`{Operation}`), returning `Task>` and **does not throw** on a non-success -status — the error is carried in the returned value instead. (`{TError}` is the same two-case shape as -above: a typed `{Operation}Error`, or `RawError`.) `ApiResult` is a public -`readonly struct` under `{RootNamespace}.Core.Models`. If the controller has no `{Operation}Result` -overload, this variant wasn't generated — use the throwing method with `try/catch` instead. +An operation may have a **sibling method** named `{Operation}Result` (next to the throwing `{Operation}`), +returning `Task>`; it **does not throw** on a non-success status — the error +is carried in the returned value instead. (`{TError}` is the same two-case shape as above: a typed +`{Operation}Error`, or `RawError`.) `ApiResult` is a public `readonly struct` under +`{RootNamespace}.Core.Models`. If the controller has no `{Operation}Result`, use the throwing method with +`try/catch`. Unlike the throwing path, `ApiResult` exposes the HTTP **`StatusCode`** and **`Headers`** on *both* success -and failure — so this is the variant to use when you need the status code, rate-limit headers, or pagination -`Link` headers. +and failure — so this is the variant to use when you need a 2xx's status code, rate-limit headers, or +pagination `Link` headers. The other way to read them on the success path is an `SdkHook.OnResponse` hook +(see **dotnet-configuration-resilience** § Hooks); on the error path every `ApiException` already carries +`StatusCode` and `Headers`. ```csharp using {RootNamespace}.Core.Models; // ApiResult @@ -269,7 +236,7 @@ if (result.TryGetResponse(out var response)) // success else if (result.TryGetError(out var error)) // failure { // 'error' is the same TError as the throwing path: - // Case A → typed {Operation}Error (use its TryGet* accessors, then TryGetRawError) + // Case A → typed {Operation}Error (dispatch with error.Match(on{Arm}: …, otherwise: …), or read one arm with TryGet*) // Case B → RawError (read error.StatusCode / error.ReadAsString()) Console.Error.WriteLine($"HTTP {(int)result.StatusCode}"); } @@ -290,13 +257,11 @@ var (isSuccess, response, error) = result; ## Connection failures, and guarding every call -The `ApiException` catches above cover API errors (the server replied with a non-2xx status). They -do **not** cover connection failures — host unreachable, DNS failure, dropped connection, or timeout. Those -come through as **`SdkConnectionException`** (could not send, or could not read the body) and its leaf -**`SdkTimeoutException`** (an attempt, the transport, or an SSE stream went silent — `Timeout` says which -window), which a `catch (ApiException<...>)` will not match. If that catch is your only guard, a connection -failure escapes and takes down whatever was running the call. The raw `HttpRequestException` is the -`InnerException`; you never catch it directly. +The `ApiException` catches above cover API errors only. No usable response — host unreachable, DNS +failure, dropped connection, timeout — throws **`SdkConnectionException`** or its leaf **`SdkTimeoutException`** +(`Timeout` says which window), with the raw cause in `InnerException`. A `catch (ApiException<...>)` does +not match them; if it is your only guard, a connection failure escapes and takes down whatever was running +the call. **A file download is the exception:** a drop while you read the returned `BinaryContent` throws a raw `IOException` from your read, not `SdkConnectionException`. @@ -313,14 +278,11 @@ catch (ApiException<{Operation}Error> ex) // a Case A operation — typed { // Carry the body's identity fields (the provider's own error code or name, any correlation // id) — the typed body is the only thing that carries them, and it does not outlive this - // catch. Check the accessors in the SAME order as the Case A ladder above: every typed - // accessor this operation declares (names from its map row), then the RawError-yielding - // arms LAST. Carry ex.StatusCode alongside whichever branch fires. - if (ex.Error.TryGet{Body}(out {Body} e)) - throw new {ProviderException}(e.{MessageField} /* + identity fields — names from the model's map row */, ex.StatusCode, ex); - if (ex.Error.TryGetRawError(out RawError raw)) - throw new {ProviderException}($"HTTP {(int)ex.StatusCode}", ex.StatusCode, ex); - throw new {ProviderException}("unrecognised error shape", ex.StatusCode, ex); + // catch. Dispatch through Match so every declared body is handled and an undeclared status lands + // in otherwise; carry ex.StatusCode alongside whichever arm fires. + throw ex.Error.Match( + on{Body}: e => new {ProviderException}(e.{MessageField} /* + identity fields — names from the model's map row */, ex.StatusCode, ex), + otherwise: raw => new {ProviderException}($"HTTP {(int)ex.StatusCode}", ex.StatusCode, ex)); } catch (ApiException ex) // a Case B operation — no typed body, just the status { @@ -343,9 +305,9 @@ catch (SdkConnectionException ex) // could not send / could not r { throw new {ProviderException}("provider unreachable", ex); // no status — nothing usable answered } -catch (AuthSchemeException ex) // OUR credential could not be applied — see Notes +catch (AuthSchemeException ex) // OUR credential is missing, its provider returned nothing, or it could not be applied — see Notes { - throw new {ProviderException}("provider credentials rejected", ex); + throw new {ProviderException}("provider credentials missing or rejected", ex); } // Do NOT add `catch (OperationCanceledException)`: the caller's own cancellation is not a provider // failure and the SDK never wraps it — let it propagate. @@ -371,29 +333,19 @@ outcome and apply the identical catch ladder at every call site — same order, When the same kind of failure (a validation rejection, say) becomes a different result on a different operation, callers can't reason about it. One shared ladder, not per-call improvisation. -**Keep distinct failures distinct — and pick the discriminator from what the error path actually -delivers.** Your error type needs to carry something that separates "you sent something invalid" -from "the provider is down". The reflex is the HTTP status; whether you *can* carry one is an API -fact, settled from the contract sheet before the boundary is written: - -- **Every `ApiException` carries `StatusCode`** — Case A and Case B alike, and the - `ResponseDeserializationException` too — so the transport status is always available to carry - and to key the ladder on. A provider **4xx** the caller can act on surfaces as that same client - **4xx**; transport failures and unknowns surface as **5xx**. -- **Operations with a typed `{Operation}Error`** (Case A) usually have a **better** discriminator - than the status: the body's own **identity fields** — the provider's error code or name, - fine-grained issue codes, a correlation id — which say more than a status would (whether each - field is `required` or nullable is on the model's map row). A typed error class can route - several documented statuses into ONE accessor, so the accessor that fired and `ex.StatusCode` - are two different facts — carry both. Some operations add status-specific - `TryGet…(out RawError)` accessors as well. The operation's map row lists all of it. -- **Accessor names differ per operation** — they embed the body type (`TryGet{Body}`), so a - guessed name is a compile error (`CS1061`), not a runtime surprise. Take each name from the - operation's own map row every time. - -Whichever discriminator applies, collapsing every failure into one blanket status (e.g. 502 for -everything) throws away the one signal that separates "you sent something invalid" from "the -provider is down." +**Keep distinct failures distinct.** Your error type needs to carry something that separates "you sent +something invalid" from "the provider is down": + +- **Every `ApiException` carries `StatusCode`** — Case A, Case B and `ResponseDeserializationException` + alike — so a provider **4xx** the caller can act on can surface as that same **4xx**, and transport + failures and unknowns as **5xx**. +- **A Case A body usually discriminates better** — its **identity fields**: the provider's error code or + name, fine-grained issue codes, a correlation id (whether each is `required` is on the model's map row). + One accessor can cover several documented statuses, so carry both the body fields and `ex.StatusCode`. + Accessor names embed the body type, so a guessed one fails to compile (`CS1061`) — take each from the + operation's map row. + +Never collapse every failure into one blanket status (e.g. 502 for everything). One ladder, in the single place where your error type becomes a caller-facing status. This is where the discriminator you carried gets read back — a ladder with **no branch reading it** is @@ -438,27 +390,19 @@ bucket; validation, conflict and not-found are the caller's to fix. And keep the 5xx: a status or code you have not mapped is an unknown, not a caller error — the provider can add one without warning you. -**Status and headers on the *success* path** are not on the return value — for metrics on a 2xx, or -rate-limit headers, use the `{Operation}Result` sibling (above) or an `SdkHook.OnResponse` hook -(`options.Hooks` client-wide, or `requestOptions.Hooks` per call — see -**dotnet-configuration-resilience** § Hooks). On the *error* path you need neither: every -`ApiException` already carries `StatusCode` and `Headers`. Hooks run once per attempt, so under retry -"the status" they observe means the last attempt's. - -**An unreadable body is not one case but two — decide which before you map it.** An unreadable -**success** body is genuinely unknown: 5xx. An unreadable **error** body is not — the provider -rejected the request and only the *detail* was lost, so answering 5xx tells a retrying caller to -keep retrying something that can never succeed. The exception below tells you which you have. - -**A body that does not match the model is a third failure kind — catch it and sanitize.** The -server can return a body that no longer matches the declared type; the SDK wraps the -`System.Text.Json.JsonException` in **`ResponseDeserializationException`** — an `ApiException` -(so `StatusCode`, `Headers` and `ContentType` are on it) that also names the `TargetType` it was -building, with the `JsonException` as `InnerException`. It is **not** an `ApiException`, so a -ladder with only typed catches lets it through — and if it reaches a generic handler that writes -`exception.Message` the response leaks the SDK type name and the call URL. Catch it at the same -boundary and convert it with a caller-safe message, and **read `ex.StatusCode` to tell the two cases -apart**: +**A body that does not match the model is a third failure kind — catch it and sanitize.** The SDK +throws **`ResponseDeserializationException`** — an `ApiException` (so `StatusCode`, `Headers` and +`ContentType` are on it) that names the `TargetType` it was building, with the `JsonException` as +`InnerException`. It is **not** an `ApiException`, so a ladder with only typed catches lets it +through, and a generic handler that writes `exception.Message` leaks the SDK type name and the call URL. +It fires on a success body (a `OneOf` or `AnyOf` response type is the exception: its Unknown slot takes a +body no variant accepts, see `dotnet-models`), and on an error body that doesn't fit the operation's +`{Operation}Error` — +then your typed `catch` never fires, and there is no fallback to `RawError`. Catch it at the same boundary +with a caller-safe message, and **read `ex.StatusCode` to tell the two cases apart**: an unreadable +**success** body is genuinely unknown (5xx); an unreadable **error** body means the provider rejected the +request and only the *detail* was lost — keep that status, or a retrying caller keeps retrying something +that can never succeed: catch (ResponseDeserializationException ex) { @@ -467,15 +411,6 @@ apart**: throw new {ProviderException}("The provider returned a response that could not be processed.", ex.StatusCode, ex); } -**The error-path variant used to lose the status; it no longer does.** `{Operation}Error` models are -generated per operation and can disagree with the body the API really sends on that status. When they -do, the parse fails *while the error object is being constructed* and the SDK throws -`ResponseDeserializationException` **instead of** `ApiException<{Operation}Error>` — your typed -`catch` never fires. But the status, headers and content type ride on the exception, so "you were -rejected and I lost the reason" is fully expressible: map it by `ex.StatusCode` like any other -`ApiException`, not as a 5xx. The SDK deliberately does *not* degrade an unparseable error body to -`RawError`: a silent fallback would hide the contract drift that is the real defect here. - **Never map a parse failure onto a domain *absence*.** "I could not read the answer" is not "the provider said no." It is tempting on a lookup — an unreadable body and a genuine miss both leave you without a record — but they are different facts and only one of them is a *fact*. Where a lookup @@ -483,10 +418,8 @@ gates a create, that conversion turns a corrupt response into a spurious create; produces a confident wrong answer, which is worse than an error. If the operation's miss really is signalled by an empty body, match on *empty*, not on *unparseable*. -The rule generalizes: whatever converts SDK failures into your own type must carry only a -caller-safe message — never surface `ex.ToString()` or `exception.Message` from an SDK or -framework exception on the wire (the same leak the `ApiError.ToString()` bare-type-name trap -above produces). +Whatever converts SDK failures into your own type carries only a caller-safe message — never an SDK or +framework exception's `ToString()` or `Message` on the wire. **A successful reply can still hand you `null`.** An omitted optional member reads `null`, and so does a JSON `null` on a required string, list, model or enum. An absent required member, or `null` on a @@ -495,20 +428,20 @@ call, and every object you reach them through (`x.Y` before `x.Y.Z`). ## Notes -- A call can also throw `AuthSchemeException` (under `{RootNamespace}.Core.Exceptions`) — a credential - could not be *applied*, which is not an API error. It is an `SdkException` (so it names the API call you - made) but **not** an `ApiException`, so the typed catches above won't match it — give it its own arm, as - the ladder does. It carries `IReadOnlyList SchemeFailures`: with a **single** failing scheme, +- A call can also throw `AuthSchemeException` (under `{RootNamespace}.Core.Exceptions`) — a required + credential is not *configured*, or a credential provider *returned nothing*, so the call fails before + anything is sent, naming the scheme and carrying an empty `SchemeFailures`; or a credential could not be + *applied*. None of these is an API error. It is an + `SdkException` (so it names the API call you made) but **not** an `ApiException`, so the typed catches + above won't match it — give it its own arm, as the ladder does. It carries + `IReadOnlyList SchemeFailures`: with a **single** failing scheme, that failure is also the `InnerException` directly and the list's only entry; with **several** (an SDK whose API composes schemes with OR and none succeeded), `InnerException` is an `AggregateException` of them. The classic cause is an OAuth2 token endpoint refusing the client credentials: the token endpoint's own `ApiException` (pointing at the token URL, with its status) is the **cause** inside the `AuthSchemeException`, not what your `catch` sees — so log `InnerException` to learn *why* auth failed. An `AuthSchemeException` is never wrapped in another. -- Retries happen automatically before an exception is thrown, and `HttpMethodsToRetry` - (`GET/HEAD/PUT/OPTIONS` by default) gates **every** trigger — status, transport fault, and the SDK's own - per-attempt timeout alike. So an error on a `POST`/`PATCH`/`DELETE`, or on a call that sends a file, - surfaces on the first attempt, with no resend. That is not the same as "the write did not happen": a transport failure (`SdkConnectionException`) - may have been thrown after the bytes reached the provider, so the outcome is *unknown* and the caller needs - to be told that rather than "it failed". A per-attempt timeout that outlives its retries surfaces as - `SdkTimeoutException`. See **dotnet-configuration-resilience**. +- Retries run before anything is thrown; a call that sends a file is never retried, and with the defaults + neither is a `POST`/`PATCH`/`DELETE` — except that an OAuth2 `401` is re-sent once on any verb, a file + upload excepted. A transport failure on a write leaves its outcome *unknown* — tell the + caller that, not "it failed". See **dotnet-configuration-resilience**. diff --git a/plugins/plaid/skills/dotnet/dotnet-getting-started/SKILL.md b/plugins/plaid/skills/dotnet/dotnet-getting-started/SKILL.md index ec152f2a..2c5327c1 100644 --- a/plugins/plaid/skills/dotnet/dotnet-getting-started/SKILL.md +++ b/plugins/plaid/skills/dotnet/dotnet-getting-started/SKILL.md @@ -1,17 +1,15 @@ --- name: "dotnet-getting-started" -description: "The Plaid API .NET SDK identity and lookup layer (.NET/C# only) you load directly — install, root namespace, environments, auth pattern, and the SDK map (shipped inside the SDK source repo): every operation signature and error case by lookup, plus the source file declaring each model, enum and error type. Load it for every contract fact, never memory; dotnet-integrate-the-plaid-api is the workflow that uses it." +description: "Load for any The Plaid API .NET SDK contract fact in C#, instead of memory: install, namespaces, environments, auth, and the SDK map giving every operation signature and error case and the file declaring each model, enum and error type. .NET/C# only; dotnet-integrate-the-plaid-api is the workflow that drives it." --- # Getting started with the The Plaid API .NET SDK -> **Who this skill is for.** This is the **map layer**: load it to ground every The Plaid API SDK fact. `dotnet-integrate-the-plaid-api` is the workflow that drives it — you collect the contracts for the work in scope into `the-plaid-api-plan.md`, implement from that sheet, and come back to the one map page a row cites for any fact the sheet is missing. Every contract fact comes from here, never from memory. +> **Map layer** for `dotnet-integrate-the-plaid-api`: the contracts in scope go into `the-plaid-api-plan.md`; come back to the map page a row cites for any fact the sheet lacks. -This is the **SDK-specific** entry point. For general patterns that apply to any APIMatic-generated .NET SDK (auth, calling endpoints, models, error handling, retries, testing), see the companion API-agnostic skills: `dotnet-client-initialization`, `dotnet-authentication`, `dotnet-calling-endpoints`, `dotnet-models`, `dotnet-error-handling`, `dotnet-configuration-resilience`, `dotnet-testing`. +Usage companions: `dotnet-client-initialization`, `dotnet-authentication`, `dotnet-calling-endpoints`, `dotnet-models`, `dotnet-error-handling`, `dotnet-configuration-resilience`, `dotnet-testing`. The SDK map is authoritative for the SDK's *surface* (signatures, model shapes, enums, which error type an operation throws); the companions are the *usage layer* — how to call each piece and the gotchas a signature cannot show. Reading the map or source does not replace a step's companion: at each step below, load the companion *and* confirm names against the map. -**The SDK map and these companion skills are complementary — load both.** The map (generated from the SDK source, which remains the ground truth) is authoritative for the SDK's *surface* (signatures, model shapes, enums, which error type an operation throws); the companion skills are the *usage layer* on top — the best-practice way to call each piece and the gotchas a signature cannot show. Reading the map or source does not remove the need to load the skill for that step, so at each step below, load the companion *and* confirm names against the map. - -> **Ground every signature, model, enum, and error type in the SDK map** (`sdk-map.md` + `map/operations/`, inside the SDK source repo — see the *SDK source* section for obtaining it). The map is **method-first**: operation signatures, error cases with their `TryGet…` accessors, pagination and server/auth wiring are on its pages by lookup — and for every type an operation names, the map names the **file that declares it**, so a shape question (fields, wire names, enum values, union accessors) is one targeted file open, never a search. When a map-sourced name fails to compile, re-read the file its row names; **never fill the gap from memory.** Do **not** decompile or reflect over the installed reference, do **not** fetch SDK files from the web ad hoc, and do **not** grep or run other expensive searches over the clone. +> **Ground every signature, model, enum, and error type in the SDK map** (`sdk-map.md` + `map/operations/`, inside the SDK source repo — see the *SDK source* section for obtaining it); **never fill a gap from memory.** ## SDK identity @@ -24,12 +22,10 @@ This is the **SDK-specific** entry point. For general patterns that apply to any | Client class | `ThePlaidApiClient` | | Options class | `ThePlaidApiClientOptions` | | Auth | **API key** in the `PLAID-CLIENT-ID` header — set `ClientId`
**API key** in the `PLAID-SECRET` header — set `Secret`
**API key** in the `Plaid-Version` header — set `PlaidVersion`
**OAuth 2.0** client credentials — set `Oauth2` | -| Environments | `ServerEnvironment.Production` *(default)* → `Default` `https://production.plaid.com`, `AccessTokenServer` `https://api.plaid.com/oauth2/apiv2`
`ServerEnvironment.Environment2` → `Default` `https://sandbox.plaid.com`, `AccessTokenServer` `https://api.plaid.com/oauth2/apiv2` | -| Log environment variable | `THEPLAIDAPICLIENT_LOG` | +| Environments | `ServerEnvironment.Production` *(default)* → `https://production.plaid.com`
`ServerEnvironment.Environment2` → `https://sandbox.plaid.com` | +| Log environment variable | `THE_PLAID_API_LOG` | | Target framework | `netstandard2.0` (C# `LangVersion 14`) | -The table above is **orientation, not a copy-paste recipe** — it gives you the names and facts (install, namespaces, the auth *pattern*, the environments), while the actual integration code comes from the companion skills. Load every one the contract sheet's REQUIRED READING names before you start implementing (`dotnet-integrate-the-plaid-api` makes that binding); the **Integration workflow** below says which governs which step. - ## Namespaces (using-directives) The SDK splits its public types across **separate child namespaces**. C# does **not** import child namespaces transitively, so `using ThePlaidApi.Models;` alone does **not** make enums, union types, or error types visible — you get `CS0103`/`CS0246` ("name/type does not exist") on build. Add a separate `using` for each kind of type you reference: @@ -46,32 +42,31 @@ Models, enums, union types and the generated error types each sit in their own c This SDK is **not published to a package feed**, so there is no `dotnet add package` for it. Build it from its repository — , branch `main` — and reference the resulting assembly from the project that will call The Plaid API, then write the `using` directives from the table above. -> **Build against the assembly built from that repository, and do not copy the SDK source into your repository.** A copy is a fork: the next time the SDK is regenerated the copy stays behind, and the map then describes code you are not building against. The map is read from the read-only **reference clone** the *SDK source* section below describes, which lives in the system temp directory, is obtained at the start of SDK work and is never part of the build. +> **Build against the assembly built from that repository; never copy the SDK source into your repository** — a copy is a fork the map stops describing. The map is read from the read-only **reference clone** (*SDK source* below), never part of the build. ## SDK map — look up first, open the named file second, never grep -The SDK ships a generated map **inside the SDK source repo**, at the SDK root — the map and the SDK regenerate together in one repo, so they cannot drift apart. The map is **method-first**: operation contracts are on its pages; model, enum and error **shapes are deliberately not duplicated there** — the map names the file declaring each type, and you read the shape in that file. Every path below is relative to the SDK root in the clone — obtain it first (next section): +The map sits at the SDK root **inside the SDK source repo** and always matches the source beside it. It is **method-first**: operation contracts are on its pages; for model, enum and error shapes it names the file declaring each type, and you read the shape in that file. Every path below is relative to the SDK root in the clone — obtain it first (next section): - **`sdk-map.md`** — the index and the read-once pages: SDK identity, client construction and the full options surface, the error-handling model (Case A typed / Case B raw), the **defaults table** for operations, the model/enum/error directory conventions, *Namespaces by content type*, and *Servers & auth*. - **`map/operations/`** — one page per controller, one block per operation: the exact C# signature with its request record's required members, the return type, the error case (A: typed `{Operation}Error` with its `TryGet…` accessors and their statuses / B: `RawError`), pagination and server-group bullets **only where they differ from the defaults**, and a **Type sources** table naming the file that declares every type the operation mentions. -- **Shapes live in the source, one type per file.** Every file under `src/ThePlaidApi/Models/`, `src/ThePlaidApi/Errors/` and `src/ThePlaidApi/Requests/` declares exactly one public type named after the file, so a type name *is* its path: take it from the operation's Type sources table (or the kind's directory — records `src/ThePlaidApi/Models/`, enums `src/ThePlaidApi/Models/Enums/`, typed errors `src/ThePlaidApi/Errors/`, request records `src/ThePlaidApi/Requests/`, or `src/ThePlaidApi/Requests//` for an operation on a controller; an operation with several tags is filed under the first tag it declares) and read the fields, `required` flags, enum values and, on a model, the `[JsonPropertyName]` wire names from that one file (a request record is never serialized and carries none). The compiler is the backstop: a wrong name fails to build. +- **Shapes live in the source, one type per file.** Every file under `src/ThePlaidApi/Models/`, `src/ThePlaidApi/Errors/` and `src/ThePlaidApi/Requests/` declares exactly one public type named after the file, so a type name *is* its path (the directories are under *Layout* below), or take it from the operation's Type sources table. Read the fields, `required` flags, enum values and, on a model, the `[JsonPropertyName]` wire names from that one file, scoped (a request record is never serialized and carries none). The compiler is the backstop: a wrong name fails to build. -**This map is how you traverse the SDK.** Do **not** grep, glob, `find`, or otherwise scan the clone to locate an operation, model, enum, union, or error type — the map (and the name-is-path convention) is the locator. Instead: +**Never grep, glob, `find` or otherwise scan the clone to locate anything** — the map and the name-is-path rule are the locator. Instead: 1. Open `sdk-map.md` and follow its controller table to the operations pages in scope; read every contract fact (signature, error accessors, pagination) by lookup. 2. **Silence means the default.** The index's defaults table states what holds for every operation (throw-only, no pagination, the default server group, inputs as one request record); an operation's block states only what differs. A block silent on pagination has none — take the default and move on rather than opening the source to confirm it. -3. For a **shape** (model fields, enum values, union accessors, a typed error's payload), open the one declaring file the map names — that is the normal flow here, not a fallback — and read it scoped. -4. The **HTTP verb/route and the endpoint's behavioural prose** live on the operation method itself — the XML `` docs in the `Api/{Controller}.cs` file the page header names; what each input means is in the per-member docs on its request record. Read them there when wire-level detail or call-acceptance semantics matter; never reconstruct a route from memory. +3. The **HTTP verb/route and the endpoint's behavioural prose** live on the operation method itself — the XML `` docs in the `Api/{Controller}.cs` file the page header names; what each input means is in the per-member docs on its request record. Read them there when wire-level detail or call-acceptance semantics matter; never reconstruct a route from memory. Keep lookups cheap — the rules that keep a session's context small: -- Collect the contracts for **every** in-scope operation in **one** pass — signatures and error accessors from the map pages, then required fields with wire names and enum values from the declaring files those pages name — into the **contract sheet** in `the-plaid-api-plan.md`, then implement from the sheet. Do not re-open a map page or source file per field, and never re-look-up a fact the sheet already carries. +- Collect every in-scope contract in **one** pass into the **contract sheet** in `the-plaid-api-plan.md` (format in `dotnet-integrate-the-plaid-api`); never re-look-up a fact the sheet already carries. - When you do open a source file, read it **scoped**: with an offset/limit, or a search for the one symbol — never dump a whole file into the conversation. - Never open the SDK's `api-reference.md` — the map supersedes it. ## SDK source — get it first; the map lives inside it -The SDK source is where the map lives, so **getting it is the first step of SDK work this session, not a fallback**: one shallow clone at the recorded ref, into the **system temp directory** (`/the-plaid-api-sdk-src/`), reused for the whole session. It is a read-only reference, never in the project repo, and **not** a build dependency. Opening the **one declaring file** a map page names is the normal flow here — that is where model, enum and error shapes live. What stays off-limits is *locating* anything by scanning: every file you open is one the map named, opened scoped, never found by grep. +The SDK source is where the map lives, so **getting it is the first step of SDK work this session, not a fallback**: one shallow clone at the recorded ref, into the **system temp directory** (`/the-plaid-api-sdk-src/`), reused for the whole session. It is a read-only reference, never in the project repo, and **not** a build dependency. **Clone once, up front**, into a fresh timestamped folder under `/the-plaid-api-sdk-src/`, and reuse that folder for the rest of your session: @@ -89,35 +84,35 @@ git clone --filter=blob:none --branch main https://github.com/context-plugins/pl # Reuse $dir for the rest of your session (it is your clone path). ``` -The source you read is branch `main`: a branch is a moving target, not a pin — it can be regenerated after this plugin ships, and then the map you read describes code the package no longer matches. If a name from the map fails to compile, trust the compiler, re-read the source file the map's row names, and report the mismatch; never patch around it from memory. +The source you read is branch `main`: a branch is a moving target, not a pin — it can move after this plugin ships, and then the map you read describes code the package no longer matches. If a name from the map fails to compile, trust the compiler, re-read the source file the map's row names, and report the mismatch; never patch around it from memory. The clone stays in the system temp directory, and `the-plaid-api-plan.md` never carries its path — the plan must stay portable. Then confirm the SDK shape **only** from the clone — not by either of these: -- **Do not decompile or run reflection over the built assembly.** A compiled assembly drops what the source carries and the other skills rely on: the XML ``/parameter doc-comments, the exact parameter names and order, and each method's internal request-builder list. -- **Do not fetch SDK files from the web one at a time** as your way in — `…/blob/…` pages return HTML (not source) and guessed paths fail, which is exactly how ad-hoc fetching breaks. Read the local clone instead; only if you truly cannot clone (`git` is unavailable), fetch a **raw** URL derived from the source repo above — never a `…/blob/…` page. +- **Do not decompile or run reflection over the built assembly.** It drops what the source carries and the other skills rely on: the XML ``/parameter doc-comments and the exact parameter names and order. +- **Do not fetch SDK files from the web one at a time** as your way in — `…/blob/…` pages return HTML, not source. Read the local clone instead; only if you truly cannot clone (`git` is unavailable), fetch a **raw** URL derived from the source repo above — never a `…/blob/…` page. Layout — where the SDK map's file references resolve, relative to the SDK root in the clone (open these directly; do not scan for them): - `src/ThePlaidApi/Api/` — one file per controller/group; **this is where the operation methods live** (the HTTP verb and route, and the XML `` docs carrying the endpoint's behavioural prose). The map's per-controller pages name the exact file. -- `src/ThePlaidApi/Models/` (+ `src/ThePlaidApi/Models/Enums/`) — body and response models, unions and enums; one public type per file, named after the file. -- `src/ThePlaidApi/Requests/` — one request record per operation that takes input, carrying the per-member docs for each input; a controller's records sit in `src/ThePlaidApi/Requests//` (an operation with several tags is filed under the first tag it declares). +- `src/ThePlaidApi/Models/` (+ `src/ThePlaidApi/Models/Enums/`) — body and response models, unions and enums. +- `src/ThePlaidApi/Requests/` — one request record per operation that takes input, carrying the per-member docs for each input; a controller's records sit in `src/ThePlaidApi/Requests//` (an operation on several controllers has one record, in one of their folders — its Type sources table names which). - `src/ThePlaidApi/Errors/` — per-operation `{Operation}Error` types (only Case-A operations have one; the map's rows say which case each operation is). - `src/ThePlaidApi/Core/` — HTTP infrastructure (the `SdkException` family, `RawError`, auth, retries, `SdkHook`). - `src/ThePlaidApi/Servers/`, `src/ThePlaidApi/ThePlaidApiClient.cs`, `src/ThePlaidApi/ServiceCollectionExtensions.cs` — environments, the client, DI. -**Leave the clone where it sits — do not delete it, copy it or edit it.** It is a read-only reference with nothing of yours in it, and keeping it is what lets every later step in this session reuse it instead of cloning again. An edit made in it never reaches the SDK, so report what needs changing instead of patching it; the OS reaps the temp directory on its own, and a future session simply makes its own timestamped clone. +**Leave the clone in place and unedited** — later steps reuse it instead of cloning again, and an edit made in it never reaches the SDK, so report what needs changing instead. The OS reaps the temp directory on its own. ## Idempotency — the real keys are on the map; the injected header is not one -The generator injects an `Idempotency-Key: Guid.NewGuid()` header on **every non-GET operation that does not already declare that header itself** — fresh on every call, invisible to you, and **not** an idempotency key in any meaningful sense: a value that changes per call deduplicates nothing, and The Plaid API may not document reading that header at all. `dotnet-configuration-resilience` explains why a visible header like this is worse than an absent one. +**Every non-GET call sends an `Idempotency-Key` header.** Unless the operation's request record carries that header as a member, its value is a fresh `Guid.NewGuid()` on every call — it deduplicates nothing, and The Plaid API may not read the header at all, so never cite it as a key. -Whether an operation takes a **real**, caller-supplied key is an API fact, visible on that operation's request record: look for a key-shaped member (an idempotency key, a request id) in the record file its **Type sources** table names. Its semantics — retention windows, when it is mandatory — are provider prose, in that member's XML docs and the method's `` in the `Api/` file the page names. Some APIs expose **`If-Match` optimistic concurrency** instead — a different guarantee (reject my write if the resource changed) solving a different problem (lost updates, not duplicates); those members show on the request record too. For every write with no key, the answer is reconciliation — `dotnet-configuration-resilience` — not hope. +Whether an operation takes a **real**, caller-supplied key is visible on that operation's request record: look for a key-shaped member (an idempotency key, a request id) in the record file its **Type sources** table names. Its semantics — retention windows, when it is mandatory — are in that member's XML docs and the method's `` in the `Api/` file the page names. An **`If-Match`** member on the record guards against lost updates, not duplicates. For every write with no key, the answer is reconciliation: `dotnet-configuration-resilience`. ## Sensitive data — check the request models before you log anything -Whether this API's **request** models carry fields you must never log — card or bank numbers, personal data, message content — is a shape question: each request model's declaring file (the map's Type sources table names it) lists every field with its `[JsonPropertyName]` wire name. If the scope touches such a field, three generator facts decide your logging posture (all in `dotnet-configuration-resilience`): JSON request bodies are logged **verbatim** when `LogRequestBody` is on, with no redaction; form bodies are masked only by deny-list; and leaving `options.Logging.LoggerFactory` unset arms the `THEPLAIDAPICLIENT_LOG` environment variable, whose `trace` level forces body logging on with no code change and no deploy. So on any build that can carry such a field: `LogRequestBody` stays off, `LoggerFactory` is set explicitly in production, and your own diagnostics never echo a request body on those paths. +Whether this API's **request** models carry fields you must never log — card or bank numbers, personal data, message content — is a shape question: each request model's declaring file (the map's Type sources table names it) lists every field with its `[JsonPropertyName]` wire name. If the scope touches such a field, the SDK's logging decides your posture (see `dotnet-configuration-resilience`): JSON request bodies are logged **verbatim** when `LogRequestBody` is on, with no redaction; form bodies are masked only by deny-list; and leaving `options.Logging.LoggerFactory` unset arms the `THE_PLAID_API_LOG` environment variable, whose `trace` level forces body logging on with no code change and no deploy. So on any build that can carry such a field: `LogRequestBody` stays off, `LoggerFactory` is set explicitly in production, and your own diagnostics never echo a request body on those paths. Responses are often safer — many APIs return masked variants of what requests carry raw — but that too is a model-shape fact: check the response model's file before assuming. @@ -125,21 +120,21 @@ Responses are often safer — many APIs return masked variants of what requests On a success the SDK returns only the deserialized body: the HTTP status and headers of a successful call are **not on the return value**, and unless the map's error-handling model notes no-throw `{Operation}Result` siblings for this SDK, there is no non-throwing variant to get them from. On an error, what is reachable depends on the operation's error case — its map row: a Case B `RawError` carries `StatusCode`; a typed Case A body may or may not (see `dotnet-error-handling`). -**Hooks are the SDK's own seam for transport metadata.** `options.Hooks` (client-wide) and `requestOptions.Hooks` (per call, appended after the client-wide list) take `SdkHook` instances; `SdkHook.OnResponse((response, context) => …)` sees every raw `HttpResponseMessage` — status, `Retry-After`, rate-limit budget headers, a request-id echo for correlation — and `SdkHook.OnRequest` the outgoing request. A hook runs **inside the retry pipeline, once per attempt**, so "the" value is the last attempt's; a per-call hook can close over a local, which puts the observed value in scope in the same method's `catch`. `RawClient.ExecuteResult` does return an `ApiResult`, but `RawClient` is `internal sealed`, so hooks — not reflection, and not a `DelegatingHandler` you would otherwise need — are the supported way in. +The status and headers of a successful call (`Retry-After`, rate-limit budgets, a request-id echo) are reachable only through **hooks** — `SdkHook.OnResponse` on `options.Hooks`, or per call on `requestOptions.Hooks`, running once per attempt; see *Hooks* in `dotnet-configuration-resilience`. ## The `dotnet-*` skill names are not unique across plugins -Every APIMatic .NET plugin ships this same set of `dotnet-*` skill names. Copies from the **same generator version** are byte-identical, so between those plugins a collision is harmless. A copy from a **different generator version** is not — it describes a different runtime, and an older plugin's retry eligibility, request-options surface and unknown-field handling all differ from this SDK's. **Load the copy that ships with THIS plugin**: write plugin-qualified names where your harness supports them, and where it does not, confirm the copy you loaded describes the runtime this SDK actually ships — `RequestOptions` carrying both a log level and `Hooks`, and a `src/ThePlaidApi/Core/Hooks/SdkHook.cs` in the source. The `X-APIMatic-Gen-Version` wire header does not distinguish these surfaces, so it is not the check. +Every APIMatic .NET plugin ships this same set of `dotnet-*` skill names, and a copy from another plugin may describe a different runtime. **Load the copy that ships with this plugin**: write plugin-qualified names where your harness supports them, and where it does not, confirm the copy you loaded describes the runtime this SDK ships — `RequestOptions` carrying both a log level and `Hooks`, and a `src/ThePlaidApi/Core/Hooks/SdkHook.cs` in the source. The `X-APIMatic-Gen-Version` wire header does not distinguish these runtimes, so it is not the check. ## Integration workflow — load the companion skill at each step -You loaded every companion the sheet named before starting (per `dotnet-integrate-the-plaid-api`); before you write the code for each step, re-read the one that governs it — even if you have already read the relevant source. Each step calls out the trap the signature hides (in *parens*). A typical integration reaches them in this order: +You loaded every companion the sheet named before starting (per `dotnet-integrate-the-plaid-api`); before you write the code for each step, re-read the one that governs it — even if you have already read the relevant source. A typical integration reaches them in this order: -1. **Client & DI setup** — load **dotnet-client-initialization** before you write `new ThePlaidApiClient(...)`, build its options, or DI-register it. (*The signature will not tell you:* the `HttpClient`/handler pipeline must be long-lived and reused via `IHttpClientFactory`, not rebuilt per request; the SDK client wrapper over it may be transient.) -2. **Authentication** — load **dotnet-authentication** before you set credentials. The scheme(s) this SDK accepts are the credentials properties on `ThePlaidApiClientOptions` — the identity table above names them. (*The signature will not tell you:* set credentials before constructing the client or in the DI callback, and load secrets from configuration rather than hardcoding.) -3. **Calling an endpoint / building a request body** — load **dotnet-calling-endpoints** before the first `client.{ApiGroup}.{Operation}(...)` call. (*The signature will not tell you:* every input goes on the operation's request record — `required` members must be set, the rest are optional or already carry the spec's default; and whether a write takes a real idempotency key is on that record — the injected `Idempotency-Key` header is not one, see *Idempotency* above.) -4. **Models** — load **dotnet-models** the moment a request/response field is not a plain string or number. (*The signature will not tell you:* unions are built with factory methods and read via `TryGet…` (no `new`), enums are `OpenStringEnum` / `OpenIntEnum` records with a generated `Match` — not C# enums, and with no public factory — and unknown response fields are kept on any model that carries an extension-data bag — conventionally `AdditionalProperties`, but a schema that closes itself with `additionalProperties: false` has none, and one that already declares a member of that name pushes the bag to a deduplicated spelling. Check the model's own map row rather than assuming the property is there.) -5. **Error handling** — load **dotnet-error-handling** before you write any `try/catch`. (*The signature will not tell you:* an operation is either Case B (`ApiException`, no typed accessors) or Case A (a typed `{Operation}Error`) — how the API mixes them is its own fact, so confirm each operation's case in its map row; and `TryGetRawError` is not a catch-all on the typed errors. Whether no-throw `…Result` variants exist at all is stated once, in the map's defaults table; never assume one does.) -6. **Configuration & resilience** — load **dotnet-configuration-resilience** when you tune retries, timeouts, the base URL, pagination, or logging. (*The signature will not tell you:* `HttpMethodsToRetry` gates **every** retry trigger, so a `POST` is never resent by default — but a `GET` that hangs costs far more than the `Timeout` value suggests, because the per-attempt timeout is itself retried. `Timeout` is per-attempt not total, `RetryOptions.Disabled()` turns retries off, and there **is** a built-in logger on `options.Logging` — whose `LogRequestBody` does not redact JSON.) -7. **Testing** — load **dotnet-testing** before you stub the SDK. (*The signature will not tell you:* the `HttpClient` constructor argument is the test seam; match the project's existing framework and assertion style.) +1. **Client & DI setup** — load **dotnet-client-initialization** before you write `new ThePlaidApiClient(...)`, build its options, or DI-register it. +2. **Authentication** — load **dotnet-authentication** before you set the credentials properties on `ThePlaidApiClientOptions` — the identity table above names them. +3. **Calling an endpoint / building a request body** — load **dotnet-calling-endpoints** before the first `client.{ApiGroup}.{Operation}(...)` call; whether a write takes a real idempotency key is on its request record (*Idempotency* above). +4. **Models** — load **dotnet-models** the moment a request/response field is not a plain string or number. A model's extension-data bag for unknown fields is `AdditionalProperties`, a numbered variant of that name on a model that already has a property called that, and absent on a model that admits no extra fields — confirm it in the model's file. +5. **Error handling** — load **dotnet-error-handling** before you write any `try/catch`; confirm each operation's Case A or B in its map row. +6. **Configuration & resilience** — load **dotnet-configuration-resilience** when you tune retries, timeouts, the base URL, pagination, or logging. +7. **Testing** — load **dotnet-testing** before you stub the SDK. diff --git a/plugins/plaid/skills/dotnet/dotnet-integrate-the-plaid-api/SKILL.md b/plugins/plaid/skills/dotnet/dotnet-integrate-the-plaid-api/SKILL.md index b2d08e23..96d44d33 100644 --- a/plugins/plaid/skills/dotnet/dotnet-integrate-the-plaid-api/SKILL.md +++ b/plugins/plaid/skills/dotnet/dotnet-integrate-the-plaid-api/SKILL.md @@ -1,55 +1,66 @@ --- name: "dotnet-integrate-the-plaid-api" -description: "MANDATORY FIRST STEP for The Plaid API .NET SDK work in a C#/.NET project — load this BEFORE opening the SDK map or touching any project file; .NET/C# SDK ONLY, never load it for any other language. Applies when asked to integrate The Plaid API in C# — or when a The Plaid API .NET SDK call errors or behaves unexpectedly. It carries four binding rules stated NOWHERE else — (1) for implementation work, the plan file the-plaid-api-plan.md is written at the project repo root BEFORE any project file is created or edited; (2) dotnet-getting-started and the SDK map it carries are loaded and used for every contract fact, never memory; (3) every dotnet-* skill the contract sheet's REQUIRED READING names is loaded before implementation starts; (4) every sheet row carries one of three labels — a map page, UNVERIFIED, or YOUR CALL — not in the map. Skip it and SDK facts get written from stale memory." +description: "MANDATORY FIRST STEP for any The Plaid API .NET SDK work in C#: integrating The Plaid API, or a The Plaid API .NET SDK call that errors or behaves unexpectedly. Load it before opening the SDK map or touching any project file — it sets the plan-first workflow (the-plaid-api-plan.md before any code) and the map-grounding rules. .NET/C# only; never load it for another language." --- # The Plaid API .NET SDK — Workflow (map + skills) -You are the The Plaid API .NET SDK specialist for this task — one agent for every SDK need: planning, answering contract questions, implementing, and fixing SDK errors. Your scope is **C#/.NET only**: if a request concerns any other language or SDK, say so and stop. Your source of truth is the **SDK map that ships inside the SDK source repo** (`sdk-map.md` plus its `map/operations/` pages; model, enum and error shapes live in the source files those pages name), obtained per `dotnet-getting-started`, plus the companion `dotnet-*` skills for usage traps. Your training data on this SDK is stale — every fact you emit must come from a map page or a map-named source file you actually read this session, in that same clone. You never guess, and you never open the SDK's `api-reference.md`. You do all of it yourself — ground, plan, implement, fix — there is no helper agent to delegate to. +You orchestrate this task: the `the-plaid-api-planner` agent writes the plan and its contract sheet; you answer contract questions, implement from the sheet and fix SDK errors yourself. Your source of truth is the **SDK map that ships inside the SDK source repo** (`sdk-map.md` plus its `map/operations/` pages; model, enum and error shapes live in the source files those pages name), obtained per `dotnet-getting-started`, plus the companion `dotnet-*` skills for usage traps. Your training data on this SDK is stale — every fact you emit must come from a map page or a map-named source file you actually read this session, in that same clone; you never guess. -**Scope guard:** the APIMatic-generated The Plaid API **.NET SDK** (root namespace `ThePlaidApi`) in **C#/.NET projects only**. Unrelated API, or any language other than C#/.NET — do nothing; this skill does not apply. +**Scope guard:** the APIMatic-generated The Plaid API **.NET SDK** (root namespace `ThePlaidApi`) in **C#/.NET projects only**. For any other API or language, say so and stop — this skill does not apply. + +## The planner agent + +`the-plaid-api-planner` ships with this plugin. It writes `the-plaid-api-plan.md` — the plan and its contract sheet — and revises it in place; it writes no project code. Start it the first of these ways your host allows: + +1. **Your subagent tool lists it.** Some hosts list a plugin's agents under the plugin's name, as `plaid:the-plaid-api-planner`; start it by whichever of the two names your subagent tool lists. +2. **It isn't listed, or you can't start a subagent.** Tell the user in one line that you are writing the plan yourself, then do so as *Step 1* describes. Don't stop to ask. + +However you start it: + +- **Start it on the same model you are running on.** If your subagent tool takes a model, pass your own model; if it has no model option, leave its default. Tell the user in one line which model you started it on. +- **Start it once per integration.** A plan revision is a follow-up message to that same agent; re-start it, carrying the clarification and the plan path, only where your host cannot message it. Never start a second one for the same integration. ## Grounding rules -- **Map for contracts; the map-named file for shapes.** Follow `dotnet-getting-started`'s *SDK map* and *SDK source* sections in full — they define how to obtain the source (the map lives inside it), that reading a model/enum/error shape means opening the one declaring file the map names (routine, scoped), and why locating anything by grep/glob/`find` over the tree is a defect rather than a shortcut. The clone stays in the system temp directory, and `the-plaid-api-plan.md` never carries its path — the plan must stay portable. -- **Never grep, glob or `find` the SDK tree to locate something** — the map is the locator, and a type name is its path. Every lookup starts at the map index and ends on the one page (or the one source file) it names. -- **Your contract sheet never leaves a contract fact open for "later."** The map pages and the files they name answer nearly everything — resolve them during planning, not mid-implementation. For the rare in-scope fact even the source cannot settle: if only live traffic could confirm it, convert it into a concrete defensive-coding directive on the sheet and label the uncertainty `UNVERIFIED`. Never leave a row marked for a later source lookup: an open row is how you end up opening source mid-implementation. +- **Map for contracts; the map-named file for shapes** — follow `dotnet-getting-started`'s *SDK map* and *SDK source* sections in full. +- **Your contract sheet never leaves a contract fact open for "later."** The map pages and the files they name answer nearly everything — resolve them during planning. A fact only live traffic could confirm becomes a concrete defensive-coding directive on the sheet, labelled `UNVERIFIED` (§7); never leave a row marked for a later source lookup. - **When you judge how far a contract can be trusted**, the trust judgment may cite ONLY evidence visible in the map or SDK source (e.g. two generated definitions that disagree, a suspicious shared model) — never training-data memory of this API, and never claims about what the live wire "usually" sends. -- **The sheet records The Plaid API's call surface; the application's design is decided at implementation time.** Its persistence, its concurrency rules, and the request contract its own callers must satisfy are not SDK facts. Where an SDK fact forces an application decision, record the fact and its consequence on the sheet, mark the decision `YOUR CALL — not in the map`, and decide it at implementation time against the task. +- **The sheet records The Plaid API's call surface, not the application's design** — its persistence, its concurrency rules, and the request contract its own callers must satisfy. Where an SDK fact forces an application decision, record the fact and its consequence and mark the decision `YOUR CALL — not in the map` (§7), to be decided at implementation time against the task. - **Name only what you have read.** Never name a claim, header or route of the application as though you knew it exists — unless you have read that code. Name configuration by its binding key, never by a raw environment variable, and give the default the map documents where there is one: a setting you invent a name for is a setting no deployment will supply. ## Workflow **If the user opens with a reported SDK error or unexpected The Plaid API behaviour** (not new feature work), go straight to *Step 4 — Fixing SDK errors* below — do not run the plan-first flow for a bug report. Otherwise, for implementation work: -### Step 1 — Plan first: write `the-plaid-api-plan.md` (always, for any implementation work) +### Step 1 — Plan first: the planner writes `the-plaid-api-plan.md` (always, for any implementation work) -Your FIRST deliverable is `the-plaid-api-plan.md` at `/the-plaid-api-plan.md` — that exact path, always; never pick another location. It carries the plan and the contract sheet in the format below, and it is the only project-repo file you write before the HARD GATE further down. +Your FIRST action, once you have reached the SDK source (the one prerequisite below that comes before the start), is to start **`the-plaid-api-planner`**, as *The planner agent* says, once, with the user's full request and the name of this skill, `dotnet-integrate-the-plaid-api`. Dictate in its task the absolute project root, the absolute path of the SDK source you reached — it reads the map and the source there rather than reaching its own — and the absolute path it must write to — `/the-plaid-api-plan.md`, that exact path, always; never another location. It grounds and writes the plan and the contract sheet exactly as *How to ground* and the format below describe, and returns the file's path. Those subsections are its instructions and your reference: you read the sheet in that format, and once the code compiles you fill its `TBD` cells and settle its `YOUR CALL — not in the map` entries, as *Step 3* says. Do the rest of the read-only prerequisites below in the same message as the start, and while it works. + +**If you couldn't start the planner** (case 2 in *The planner agent*), *How to ground* and the format are your own instructions: write the file yourself at that path. It is the only project-repo file you write before the HARD GATE further down. #### How to ground (map-first, one pass) 1. Load `dotnet-getting-started`; open `sdk-map.md` (the index). 2. From the index, open the **operations pages** for every controller in scope — take signatures (the request record each operation takes, and its required members), return types, error case (A: typed `ApiException<{Operation}Error>` with its `TryGet…` accessors and payload type / B: `ApiException`), and pagination — remembering that a block silent on a defaults-table point means the default applies. Where an operation's *semantics* decide what you must pass, that prose is the method's XML `` in the `Api/` file the page names, and the per-member docs on its request record: read it there. 3. Open, scoped, the **declaring source file** for every request/response model you will reference — the operation's **Type sources** table names it — and take field names WITH their `[JsonPropertyName]` wire names, `required` flags, nullability, and the envelope shape. Enum value lists and union accessors come from their declaring files the same way. -4. Identify which companion skill governs each step in scope. For each, write the trap note as a **named hazard plus a `MUST load` pointer** — *not* as the resolved answer. Naming the hazard ("what `Timeout` actually bounds") is right; resolving it inline ("`Timeout` is per-attempt") is wrong — a resolved trap gives you no reason to load the skill, and the skill carries the parts a one-line note cannot. **Never restate a companion skill's default or semantics in a trap note — not even when you believe it correct.** Write the *consequence*, not the answer. Contract *facts* are the opposite: those you resolve fully and inline. -5. Collect everything in ONE pass — the whole point is that you never have to rediscover a contract mid-coding. +4. Map each in-scope step to the companion skill that governs it, as a trap note (format in §3 below). + +#### Prerequisites -#### Prerequisites you can run alongside +**Reach the SDK source before you start the planner** (per `dotnet-getting-started`) — the map lives inside it, so this comes before any map work, and the planner reads the copy you reached rather than reaching its own. -These need no SDK knowledge and touch no project file, so do them before or alongside the map work: +The rest need no SDK knowledge and touch no project file, so do them while the planner works — or alongside your own map work, if you are writing the plan yourself: -- reaching the SDK source (per `dotnet-getting-started` — the map lives inside it, so this comes before any map work); - the repo survey (read-only exploration of conventions and layering) — record each convention as *pattern + the ONE exemplar file path to imitate*, NOT inline code snippets: you will read the exemplar at edit time anyway, so a snippet dump gets paid for twice; - `dotnet restore` and a baseline `dotnet build` / `dotnet test` of the UNTOUCHED solution, so later failures are attributable to your changes; - locating the SDK reference and its version in the project; - credentials/environment verification (per the task's secret-handling rules); - setting up your task tracking. -Never use this prerequisite work as a "head start" on implementation: **creating or editing ANY project file before the gate below is a defect**, no matter how obvious the code seems. - #### HARD GATE -**No project-file creation or edits until `the-plaid-api-plan.md` exists at that path with every section below filled in.** Starting to code before the sheet exists defeats the plan-first design: the sheet is what keeps SDK facts out of your memory and in the map. The gate bars coding before the sheet exists; it does not bar the read-only prerequisite work above. +**No project-file creation or edits until the planner has RETURNED, `the-plaid-api-plan.md` EXISTS at the path you dictated (check it — a helper can misreport where it saved), every section below is filled in, and you have read it.** If you wrote the plan yourself, the gate is the file existing at that path with every section filled in. The read-only prerequisites above are allowed; using them as a "head start" on code is a defect, however obvious the code seems. #### The `the-plaid-api-plan.md` format (keep it tight — tables, not prose) @@ -68,28 +79,26 @@ The CONTRACT SHEET also carries a **CROSS-OPERATION INVARIANTS** table, directly **Enforced where** names the member that checks, before the write, that the caller's value is in that set. If the application never reads that set, say so there and add the read — the check is part of the work. `YOUR CALL — not in the map` is not a legal entry in any cell of this table. -3. **Trap notes** — one line per hazard, attached to the step where it bites, each ending in an inline **`MUST load `** pointer. Name the hazard and its consequence; do not resolve it. ⚠⚠ **"Do not resolve it" is the load-bearing half of this rule.** A trap note that answers its own question hands you a usable one-liner — and holding one, you do not open the skill. You implement from the sentence, and everything the skill carries beyond it never reaches the code. So: state the hazard, state what it costs, hand over the skill, and stop. No fix, no snippet, not even a partial answer. A trap note from which you could write correct code without loading the named skill is a defect. -4. **REQUIRED READING** — close the sheet with the de-duplicated list of every `dotnet-*` skill named above, one line each: skill · the step it governs. Write each name so the copy is unambiguous — every APIMatic .NET plugin ships these same skill names, and a bare name gives you no way to tell which one you loaded. State that these are to be loaded **before implementation starts**, and that the sheet deliberately does not carry their contents. This block is mandatory even when the trap notes are few — an integration always writes an error boundary, so `dotnet-error-handling` always appears here. Always include, verbatim, this hazard row: a body that does not match its declared type — a drifted or malformed **2xx** response (a missing `required` member) or a **non-2xx** body that does not match its operation's generated `{Operation}Error` shape — surfaces as `ResponseDeserializationException`, an `ApiException` that keeps the HTTP status and names the target type but is **not** an `ApiException`; a catch ladder that handles only `ApiException` lets it escape, so it must also catch `ResponseDeserializationException` (or `ApiException`). -5. **PRODUCTION READINESS** — the fixed table below, every row carrying a *decision*. Naming a skill in REQUIRED READING does not address a concern; it defers it. `N/A` is a legitimate answer where it is genuinely true, but it must carry its reason. +3. **Trap notes** — one line per hazard, attached to the step where it bites, each ending in an inline **`MUST load `** pointer. State the hazard and what it costs, never the answer — no fix, no snippet, not even a companion default you believe correct: "what `Timeout` actually bounds" is a trap note, "`Timeout` is per-attempt" is not. A trap note from which you could write correct code without loading the named skill is a defect. Contract *facts* are the opposite: resolve those fully and inline. +4. **REQUIRED READING** — close the sheet with the de-duplicated list of every `dotnet-*` skill named above, one line each: skill · the step it governs, each name plugin-qualified (every APIMatic .NET plugin ships these same names), all to be loaded **before implementation starts**. It always lists `dotnet-error-handling`, even when the trap notes are few, and always carries, verbatim, this hazard row: a body that does not match its declared type — a drifted or malformed **2xx** response (a missing `required` member) or a **non-2xx** body that does not match its operation's generated `{Operation}Error` shape — surfaces as `ResponseDeserializationException`, an `ApiException` that keeps the HTTP status and names the target type but is **not** an `ApiException`; a catch ladder that handles only `ApiException` lets it escape, so it must also catch `ResponseDeserializationException` (or `ApiException`). +5. **PRODUCTION READINESS** — the fixed table below, every row recording a *decision*, or `N/A` with its reason where that is genuinely true. A row that only names a skill — even one in REQUIRED READING — restates the concern, or sits blank is **not addressed**. 6. **Assumptions & Blockers** — anything you had to assume about the user's intent, and anything that blocks planning. An empty section is a valid outcome; an invented fact is not. If you expect the provider to reject a call the plan makes, that is a **Blocker**. -7. Every row's **source** cell cites its map page or the map-named declaring file, so a later lookup is one targeted open, not a search. A row with neither to cite is not a contract fact: write `YOUR CALL — not in the map` there instead. Three labels, one order — a fact the map settles cites that page or file; a fact only live traffic can settle is `UNVERIFIED`; a decision about the application is `YOUR CALL — not in the map`. Something that stops you planning goes in §6. +7. **Source labels** — every row's **source** cell is one of: the map page or map-named file it came from (so a later lookup is one targeted open); `UNVERIFIED` (only live traffic can settle it); `YOUR CALL — not in the map` (a decision about the application). Something that stops you planning goes in §6. | # | Concern | The decision the plan must record | | --- | --- | --- | -| 1 | **Credential fail-fast** | Where credentials are bound, and that the host refuses to start when one is missing or blank — rather than discovering it as a 401 on the first call in production. A multi-part credential needs **every** part checked, because a blank part is not a missing one. | +| 1 | **Credential fail-fast** | Where credentials are bound — code, the SDK's own environment variables, a provider or `IConfiguration` — and that the host refuses to start when one is missing or blank, rather than discovering it as an `AuthSchemeException` on the first call in production. The check follows the source: the SDK's variable itself when that supplies the credential, the provider's own source when a provider does. A multi-part credential needs **every** part checked, because a blank part is not a missing one. | | 2 | **Secret sourcing & rotation** | Where the secret comes from, and that the DI registration builds the options object **once at registration** and captures it in the singleton — so a rotated secret does not take effect until the process restarts. If rotation without a restart is required, say how. | -| 3 | **Total timeout budget** | The number the caller actually gets, not the knob. `Timeout` is **per attempt**, so a hung retryable call costs a multiple of it. State the budget and where it is enforced — a `CancellationToken` deadline is the only thing that bounds a whole call. | -| 4 | **Write-retry ownership** | Which of the scope's writes the SDK may resend and which it may not. The default `HttpMethodsToRetry` covers `GET, HEAD, PUT, OPTIONS`, so `POST`/`PATCH`/`DELETE` are never resent by the SDK — and `PUT` **is**. | -| 5 | **Idempotency & ambiguous writes** | For each write in scope: the key it uses, or that none exists. Whether an operation takes a REAL caller-supplied key — and its member name — is on that operation's request record: the record file its map row's **Type sources** table names. The generator-injected `Idempotency-Key` header (`Guid.NewGuid()`, fresh on every call) is **not** a key and must not be cited as one. Where no key exists, record the reconciliation path instead. | -| 6 | **Observability** | What is logged at which level, that **JSON request bodies are logged unredacted** when `LogRequestBody` is on, and which correlation id from the provider's error bodies reaches your own logs. | -| 7 | **Sensitive data** | Whether the scope carries data you would not want in a log — each request model's declaring file lists every field in scope. If it does: `LogRequestBody` stays off **and** `LoggerFactory` is assigned explicitly, so the SDK's log environment variable cannot switch it on from outside the code (see `dotnet-getting-started`). Form bodies are masked only by deny-list, so a key you have not listed prints in the clear. | +| 3 | **Total timeout budget** | The number the caller actually gets, not the knob — state the budget and where it is enforced. What `Timeout` bounds, and what bounds a whole call: `dotnet-configuration-resilience`. | +| 4 | **Write-retry ownership** | Which of the scope's writes the SDK may resend and which it may not — the retried verbs are under *Retries* in `dotnet-configuration-resilience`. | +| 5 | **Idempotency & ambiguous writes** | For each write in scope: its real key — a member of its request record (*Idempotency* in `dotnet-getting-started`) — or that none exists, and then its reconciliation path. The `Idempotency-Key` header every non-GET call sends is **not** a key and must not be cited as one. | +| 6 | **Observability** | What is logged at which level, and which correlation id from the provider's error bodies reaches your own logs. | +| 7 | **Sensitive data** | Whether the scope carries data you would not want in a log (*Sensitive data* in `dotnet-getting-started`). If it does: `LogRequestBody` off, `LoggerFactory` assigned explicitly, and every sensitive form-body key added to the deny-list. | | 8 | **Environment selection** | Which base URLs each deployment talks to. Enumerate the server groups and environment members from the map's *Servers & auth* section — there may be more than one group, and each operation resolves through its own. State which groups the scope touches and what each deployment sets; if the SDK declares no sandbox environment, say how test traffic is kept away from the live system. | | 9 | **Duplicate prevention under concurrency** | For each write a caller can trigger twice: its row in **DUPLICATE CLAIMS** below. If this codebase has nowhere to keep a claim that outlives the process, that is a Blocker in §6, not a row. | | 10 | **Partial results** | For each paged read that can stop at a cap: the field or return type that tells the caller the result was cut short. | | 11 | **Unknown outcomes** | For each write whose connection can fail after the provider may have acted: how the code settles the outcome instead of reporting a failure. | -A reviewer grades that table alone: each row either records a decision or records why it does not apply. A row that points at a skill, restates the concern, or sits blank is **not addressed**. Rows 5, 7, 8, 9 and 11 are the ones where "not addressed" costs something that cannot be recovered afterwards — a duplicate charge or duplicate write, sensitive data in a log, or test traffic sent to a live system. - **DUPLICATE CLAIMS** — one row per write a caller can trigger twice; `none` if the task has no such write. | Write | Where the claim is stored | What rejects the second one | Where that rejection is caught | Where in the code | @@ -125,36 +134,35 @@ Keep the file lean: no copied map pages, no full model dumps, and no clone path ### Step 2 — Required reading (do this before you write any code) -The contract sheet ends with a **REQUIRED READING** block, and its rows carry inline `MUST load ` pointers. **Load every `dotnet-*` skill the sheet names, now, before you start implementing** — not lazily at the step that needs it. The sheet deliberately does *not* carry the how-to: it names the hazard and hands you the skill that resolves it, so an unloaded pointer is a gap in what you know, not a formality. If the sheet names none, load `dotnet-error-handling` anyway — every integration writes an error boundary. - -These are API-agnostic usage skills; loading them is not the same as reading the map. Contract *facts* still come only from the sheet or a map lookup. +The contract sheet ends with a **REQUIRED READING** block, and its rows carry inline `MUST load ` pointers. **Load every `dotnet-*` skill the sheet names, now, before you start implementing** — not lazily at the step that needs it; the sheet names hazards, not their answers. If the sheet names none, load `dotnet-error-handling` anyway — every integration writes an error boundary. Before implementing, check the plan's **Assumptions & Blockers** section: -- Blocker or major assumption → surface it to the user in plain language, get their answer, then revise `the-plaid-api-plan.md` in place with targeted edits — edit the changed rows, append the new section. Rewriting the whole file to change a few rows is a defect. +- Blocker or major assumption → surface it to the user in plain language, get their answer, and send it to the SAME planner as a follow-up message (re-start it, carrying the clarification and the plan path, only where your host cannot message it). It revises `the-plaid-api-plan.md` in place and replies with the changed rows verbatim: work from that reply, not a re-read of the file. If you wrote the plan yourself, revise it in place with targeted edits — edit the changed rows, append the new section. Rewriting the whole file to change a few rows is a defect. - Minor assumptions only → proceed. Full re-planning only on genuine scope change; for a single missing fact mid-implementation, look it up in the map — never guess. ### Step 3 — Implement from the contract sheet -1. Read `the-plaid-api-plan.md` once. Treat its contracts as authoritative — do not re-derive or "double-check" them from memory. A row whose source column says `YOUR CALL — not in the map` is the one exception: that row is a planning-time judgment about YOUR application, so weigh it against the task and follow the task. -2. Implement sequentially, following the repo's own conventions and layering. You loaded the companion skills the sheet named in Step 2 — implement each step in line with the one that governs it. Take every contract *fact* (signatures, wire names, error accessors, enum values) from the contract sheet or a map lookup — never re-derive one from a companion. +1. Read `the-plaid-api-plan.md` once and treat its contracts as authoritative — never re-derive or "double-check" one from memory; re-open the map page a row cites. Only a `YOUR CALL — not in the map` row is weighed against the task, and the task wins. +2. Implement sequentially, following the repo's own conventions and layering, each step in line with the companion that governs it. Take every contract *fact* (signatures, wire names, error accessors, enum values) from the contract sheet or a map lookup — never from memory or a companion. 3. After every change: `dotnet build`; fix non-SDK errors yourself. -4. **Any compile or runtime error involving an SDK type or member** (`CS1061`, `CS0117`, `CS0234`, `CS0104`, `CS1503`, `CS7036`, … on `ThePlaidApi.*`, or a provider error at runtime) → *Step 4* below. Do not attempt more than one self-fix of an SDK-name error before switching to that procedure — rewriting from the same knowledge that produced the error is guessing. +4. **Any compile or runtime error involving an SDK type or member** → *Step 4* below, after at most one self-fix. 5. Once the code is complete, open each member the **DUPLICATE CLAIMS** and **UNKNOWN OUTCOMES** rows name and confirm it runs when that write runs. Where the code falls short of a row, fix the code, not the row. -6. Run the project's tests (`dotnet test`); verify the integration end to end the way the task demands. +6. Then settle every `YOUR CALL — not in the map` entry in `the-plaid-api-plan.md`: overwrite the marker where it stands, in its row or in **Assumptions & Blockers**, with the decision the code made and the member that implements it, so no entry is left open. Never gather the decisions in a section of their own. Name each one in your final report. A `YOUR CALL` left in the plan is a decision nobody recorded; one the report leaves out is a decision the user never saw. +7. Run the project's tests (`dotnet test`); verify the integration end to end the way the task demands. ### Step 4 — Fixing SDK errors (map-first, in place) -A compile or runtime error involving an SDK type or member (`CS1061`, `CS0117`, `CS0234`, `CS0104`, `CS1503`, `CS7036`, … on `ThePlaidApi.*`, or a provider error). Resolve it map-first — never patch it by guessing. Load `dotnet-getting-started` first if you have not already — the map is where every fix below comes from. +A compile or runtime error involving an SDK type or member (`CS1061`, `CS0117`, `CS0234`, `CS0104`, `CS1503`, `CS7036`, … on `ThePlaidApi.*`, or a provider error). Resolve it map-first — load `dotnet-getting-started` first if you have not already — never by guessing. -1. **Map lookup first.** For an operation symbol, find its block on the controller's operations page; for a model, enum, error or request-record symbol, open the declaring file — its name is its path (`src/ThePlaidApi/Models/{Type}.cs`, `src/ThePlaidApi/Models/Enums/{Type}.cs`, `src/ThePlaidApi/Errors/{Type}.cs`, `src/ThePlaidApi/Requests/{Type}.cs`, or `src/ThePlaidApi/Requests/{Controller}/{Type}.cs` for an operation on a controller — an operation with several tags is filed under the first tag it declares), or take it from the operation's Type sources table. If the code contradicts what you read (wrong field name, missed response envelope, wrong param order, wrong namespace), that is the fix. Response envelopes are the classic case: response types often wrap their payload in one field — reads go one level down. +1. **Map lookup first.** For an operation symbol, find its block on the controller's operations page; for a model, enum, error or request-record symbol, open the declaring file — its name is its path (the layout in `dotnet-getting-started`'s *SDK source* section), or take it from the operation's Type sources table. If the code contradicts what you read (wrong field name, missed response envelope, wrong param order, wrong namespace), that is the fix. Response envelopes are the classic case: response types often wrap their payload in one field — reads go one level down. 2. **Go one level deeper on a real gap.** If what you read matches the code, or ambiguity remains, open the operation's own method in the `Api/{Controller}.cs` file the page header names — its `` docs and the request it builds — and the per-member docs on its request record, in this session's SDK clone, scoped. Never scan the tree. -3. **Never re-guess.** Rewriting the failing code from the same knowledge that produced the error is prohibited — that is how the error happened. Each failing symbol gets a map/source-grounded answer before its line changes; never mutate payloads, field names, or status handling speculatively to "see if it works". +3. **Never re-guess** from the knowledge that produced the error: each failing symbol gets a map/source-grounded answer before its line changes; never mutate payloads, field names, or status handling speculatively to "see if it works". 4. **Fix in place** — edit only the project files involved in the error, grounded in the map row (or the named source file). 5. **Build to verify, and classify the outcome:** compiles clean → run `dotnet test` on the touched tests when they exist; compile error → the fix is not done, resolve it the same map-first way and rebuild; build blocked (output locked) → the solution is running, so stop it if you started it, or ask the user to rather than killing their process. -6. **Runtime / provider errors** — read the provider's error payload through the documented path: the operation's error case and `TryGet…` accessors from its map row; `dotnet-error-handling` for the Case A/B mechanics. Config-shaped failures (401, wrong host, timeouts): check auth, the server-node/base-URL configuration, and retry semantics before touching call sites. +6. **Runtime / provider errors** — read the provider's error payload through the documented path: the operation's error case and `TryGet…` accessors from its map row; `dotnet-error-handling` for the Case A/B mechanics. Config-shaped failures (`AuthSchemeException`, 401, wrong host, timeouts): check auth, the server-node/base-URL configuration, and retry semantics before touching call sites. If a fix corrects a row in `the-plaid-api-plan.md`, correct the row in the file too — the sheet stays the record of what was verified. @@ -164,10 +172,8 @@ A standalone The Plaid API question with no code change: load `dotnet-getting-st ## Anti-patterns — never do these +- **Never create or edit a project file while `the-plaid-api-planner` is running**, and never start a second one for the same integration. - **Never write a The Plaid API/SDK fact from memory** — every signature, field name, enum value, and error type in your code must come from the contract sheet or a map lookup. And **never write a call from memory "to fix later".** -- **Do not re-derive or double-check a sheet row from memory** — re-open the one map page it cites. -- **Do not re-derive a contract fact from a `dotnet-*` companion** — they are usage guidance; facts come from the map. - **Do not grep, glob or `find` the SDK tree, and do not open its `api-reference.md`** — the map is the locator; `dotnet-getting-started` says why. - **Do not web-search The Plaid API for an implementation detail** — the map and the SDK source it lives in are the ground truth for THIS SDK version, and `ThePlaidApi` is what the generated source declares, not what public docs describe. -- **Do not resolve a trap note inline on the sheet** — name the hazard and the skill. diff --git a/plugins/plaid/skills/dotnet/dotnet-models/SKILL.md b/plugins/plaid/skills/dotnet/dotnet-models/SKILL.md index c426a34b..146ebd6f 100644 --- a/plugins/plaid/skills/dotnet/dotnet-models/SKILL.md +++ b/plugins/plaid/skills/dotnet/dotnet-models/SKILL.md @@ -1,6 +1,6 @@ --- name: dotnet-models -description: Working with models in an APIMatic-generated .NET SDK in C# — building request models, required members and nullability, enums, union/AnyOf accessors, and JSON wire names versus C# property names. Load before constructing request payloads or mapping SDK models onto your own domain types. +description: Load before building request payloads for an APIMatic .NET SDK in C# or mapping its models onto your own types — required members and nullability, OneOf/AnyOf unions, open enums, dates, collections, validation attributes, JSON wire names versus C# property names, and unknown fields. --- # Working with models in an APIMatic .NET SDK @@ -17,19 +17,24 @@ installed package. When a field can be one of several types, APIMatic generates a union `record` (under `{RootNamespace}.Models.OneOf` or `.Models.AnyOf`). Build these with the generated **static factory -methods** (one per variant) and read them back with **`TryGet…` methods** — a union has no -object-initializer. JSON (de)serialization is automatic. +methods** (one per variant) and read them back with **`TryGet…` methods** or branch over every variant +with **`Match`** — a union has no object-initializer, and the `Optional` backing each variant is +internal, so the factories, `TryGet…` and `Match` are the whole surface. JSON (de)serialization is +automatic. - `OneOf` — the value is exactly one variant, selected on the wire by a **discriminator property** (e.g. `type`). The generated converter reads that property and switches on it. - `AnyOf` — no discriminator; the converter **tries each variant's schema in declaration order** and takes the first that deserializes. -⚠ **A payload matching no variant throws.** Both converters end in -`throw new JsonException("JSON does not match … schemas: …")`, raised mid-deserialization of the response — -you do not get a null union or an unset variant. A provider that adds a variant your SDK predates turns -into a `JsonException` on a call that was previously fine, so a union field is a place to expect -regeneration pressure. See `dotnet-error-handling` for where that surfaces in a catch ladder. +⚠ **A payload matching no variant does not throw** — it lands in the union's **Unknown** slot as the raw +`JsonElement`: `TryGetUnknown(out var raw)` returns `true`, every `TryGet{Variant}` returns `false`, and +the value serializes back verbatim. A variant the provider adds after your SDK was generated therefore does +not break the call; your code decides what to do with it. A `OneOf` whose discriminator property is missing +or not a string still throws, and so does a known discriminator value whose body does not fit that variant +(a missing required member or a wrong-typed value); both reach your catch as +`ResponseDeserializationException` (see `dotnet-error-handling`). You cannot build an Unknown value +yourself: its factory is not public. ### Construct @@ -43,49 +48,62 @@ var u2 = {Union}.{Variant}(new {Variant} { /* ... */ }); {Union} u4 = new {Variant} { /* ... */ }; // same as {Union}.{Variant}(...) ``` -**A `OneOf`'s variants are always model or enum references** — the generator builds them from the schema's -discriminator mappings, so a `OneOf` has no primitive, list or map variant at all, and every variant it does -have gets an implicit conversion. An `AnyOf` is the open one: primitives and models get a conversion, while -list, map and untyped-object variants do not, and neither do two variants that share one CLR type (the -operators would collide). The factory is the form that always exists — reach for the implicit conversion -only where you can see one. +**A `OneOf`'s variants are always model or enum references** — it has no primitive, list or map variant, and +every variant gets an implicit conversion. On an `AnyOf`, primitive and model variants get one; list, map and +untyped-object variants do not, and neither do two variants that share one CLR type. The factory always +exists — reach for the implicit conversion only where you can see one. ### Read / unwrap ```csharp -// Each variant has a bool TryGet{Variant}(out var value). The member name comes from the -// variant's SCHEMA type, not its CLR type — a `decimal` variant reads TryGetBigDecimal: +// Each variant has a bool TryGet{Variant}([NotNullWhen(true)] out T? value), a bare out T for a +// value type. The member name comes from the variant's SCHEMA type, not its CLR type — a `decimal` +// variant reads TryGetBigDecimal: if (u1.TryGetString(out var s)) { /* use s (string) */ } else if (u1.TryGetBigDecimal(out var d)) { /* use d (decimal) */ } // OneOf: branch over the variants you expect if (resp.{Field}.TryGet{Variant}(out var v)) { /* ... */ } else if (resp.{Field}.TryGet{OtherVariant}(out var w)) { /* ... */ } + +// Match: one on{Variant} handler per variant, in the order the union declares them, then otherwise, +// which receives the raw JsonElement of a value the SDK could not place. +// The Func overload returns a value; the Action overload (same handler names) runs a side effect. +var result = resp.{Field}.Match( + on{Variant}: v => Handle(v), + on{OtherVariant}: w => HandleOther(w), + otherwise: raw => HandleUnrecognised(raw)); ``` +Every `Match` handler is required, `otherwise` included, so a variant you leave out is a compile error — +unlike a `TryGet` chain, whose last `else` the compiler never checks and which silently drops an Unknown +value. Pass the handlers **by name**: a regenerated SDK whose spec adds or reorders a variant changes the +`Match` signature, and two variants of one CLR type (`onString` / `onEmailString`) would swap silently at +a positional call site. When you read with `TryGet…` instead, end the chain with +`TryGetUnknown(out var raw)` or an `else`, so an unrecognised value is handled on purpose. + The factory and `TryGet` names are built from the **variant's schema type name, which is often not its CLR type name** — this is the single easiest thing to get wrong when writing a union branch from memory: | Variant | Factory method | Reader | | --- | --- | --- | -| a model `{Variant}` | `.{Variant}({Variant})` | `TryGet{Variant}(out {Variant})` | -| a big-decimal (CLR `decimal`) | `.BigDecimal(decimal)` | `TryGetBigDecimal(out decimal)` | -| a UUID (CLR `Guid`) | `.Guid(Guid)` | `TryGetGuid(out Guid)` | -| a date-time (CLR `DateTimeOffset`) | `.DateTime(DateTimeOffset)` | `TryGetDateTime(out DateTimeOffset)` | -| a date (**also** CLR `DateTimeOffset`) | `.Date(DateTimeOffset)` | `TryGetDate(out DateTimeOffset)` | -| an email / uri / ip (all CLR `string`) | `.EmailString(...)` / `.UriString(...)` / `.IpString(...)` | `TryGetEmailString(...)`, … | -| a list of `{Variant}` | `.ListOf{Variant}(IReadOnlyList<{Variant}>)` | `TryGetListOf{Variant}(out IReadOnlyList<{Variant}>)` | -| a map of `{Variant}` | `.MapOf{Variant}(...)` | `TryGetMapOf{Variant}(out …)` | - -So a `decimal` variant is `TryGetBigDecimal`, never `TryGetDecimal`; three variants that are all CLR -`string` get three different names; and a `DateTimeOffset` variant is `TryGetDateTime` **or** `TryGetDate` -depending on which the definition declared — two members, one CLR type, and the C# signature cannot tell -them apart. Where two variants would collide outright the generator suffixes them (`String`, `String2`). -The primitive rows apply to `AnyOf` only, since a `OneOf` has no primitive variants. **Take the exact member -name from the contract sheet** (grounded from the SDK map/source) rather than deriving it from -the C# type you see. (Unions use the per-variant factories and `TryGet…` readers shown above; -`TryGetKnownValue` belongs to enums.) The `Optional` backing a union is internal — interact only through the factories and -`TryGet…`. +| a model `{Variant}` | `.{Variant}({Variant})` | `TryGet{Variant}([NotNullWhen(true)] out {Variant}? value)` | +| a big-decimal (CLR `decimal`) | `.BigDecimal(decimal)` | `TryGetBigDecimal(out decimal value)` | +| a UUID (CLR `Guid`) | `.Guid(Guid)` | `TryGetGuid(out Guid value)` | +| a date-time (CLR `DateTimeOffset`) | `.DateTime(DateTimeOffset)` | `TryGetDateTime(out DateTimeOffset value)` | +| a date (**also** CLR `DateTimeOffset`) | `.Date(DateTimeOffset)` | `TryGetDate(out DateTimeOffset value)` | +| an email / uri / ip (all CLR `string`) | `.EmailString(...)` / `.UriString(...)` / `.IpString(...)` | `TryGetEmailString([NotNullWhen(true)] out string? value)`, … | +| a list of `{Variant}` | `.ListOf{Variant}(IReadOnlyList<{Variant}>)` | `TryGetListOf{Variant}([NotNullWhen(true)] out IReadOnlyList<{Variant}>? value)` | +| a map of `{Variant}` | `.MapOf{Variant}(...)` | `TryGetMapOf{Variant}([NotNullWhen(true)] out IReadOnlyDictionary? value)` | + +A reference-type reader is `[NotNullWhen(true)] out T?`: `out var` infers `T?`, and the compiler narrows it to +`T` inside the `if`; outside the check the value may be null. A value-type reader stays a bare `out T`. + +The primitive rows apply to `AnyOf` only. Two variants that would collide outright are suffixed (`String`, +`String2`); a variant named `Unknown`, or named like its own union, takes a `Variant` suffix +(`UnknownVariant`). Each row's `Match` handler is `on` + its factory name (`onBigDecimal`, `onEmailString`, +`onListOf{Variant}`). **Take the exact member name from the contract sheet** (grounded from the SDK +map/source) rather than deriving it from the C# type you see. ## Collections @@ -109,21 +127,16 @@ never a cast to `Dictionary`. ## Dates & numbers -- **A date/time field is not necessarily a `DateTimeOffset?` — check the property type.** The generator - emits `DateTimeOffset?` only where the API definition marks the field as a date/time. Where it does not, - the field is a plain `string?`, frequently carrying a `[RegularExpression]` attribute that *documents* an - RFC-3339 shape without enforcing it (see below). Both are common in the same SDK, and one of the sampled - SDKs has **no** `DateTimeOffset` in its models at all. Take the type from the contract sheet; a - `DateTimeOffset.Parse` written against a field that is already a `DateTimeOffset` will not compile, and a - hand-built string written into a `DateTimeOffset?` field will not either. -- **A `DateTimeOffset` model property carries no converter** — it round-trips as `System.Text.Json`'s - default, ISO-8601 with an offset (`"2024-06-17T15:30:45+00:00"`), *even where the API documents a - date-only shape*. The generator does ship four date converters (ISO-8601, RFC-1123, Unix epoch seconds, - date-only), but it attaches them to **whole-response payloads** — an operation whose response body is a - date scalar, or a list or map of them — not to properties inside a model. So if a field's documented wire shape is `YYYY-MM-DD` and - the property is a `DateTimeOffset?`, what the SDK sends is the full ISO-8601 form, and reconciling that - with the provider is your problem, not the SDK's. Do not hand-format anyway; for your own formatting use - the BCL (`DateTimeOffset.Parse`, `.ToString("O")`), never the SDK's internal converters. +- **A date/time field is not necessarily a `DateTimeOffset?` — check the property type.** It can be a + plain `string?`, often with a `[RegularExpression]` that *documents* an RFC-3339 shape without enforcing it + (see below); both occur in one SDK, and some SDKs have no `DateTimeOffset` at all. Take the type from the + contract sheet: `DateTimeOffset.Parse` against a field that is already a `DateTimeOffset` will not compile, + nor will a hand-built string written into a `DateTimeOffset?` field. +- **A `DateTimeOffset` model property round-trips as `System.Text.Json`'s default**, ISO-8601 with an offset + (`"2024-06-17T15:30:45+00:00"`), *even where the API documents a date-only shape* — a field documented as + `YYYY-MM-DD` is sent in the full form, and reconciling that with the provider is yours. Do not + hand-format it; for your own formatting use the BCL (`DateTimeOffset.Parse`, `.ToString("O")`), never the + SDK's internal converters. - Money/quantities may be `string`, `decimal`, or a string-or-number `AnyOf` union; the model's property type is the source of truth. Numeric types vary per SDK (`int`, `long`, `double`, …) — take the exact type from the contract sheet; don't assume `double`. @@ -164,13 +177,13 @@ enums. Use the static constants; they convert implicitly to their underlying val (or the implicit conversion) yields the raw wire value — but **not** `ToString()`, see the warning below — and `==` compares by value, so two instances read from the same wire value are equal. -There is **no public factory**: `{EnumType}.FromValue(...)` does not exist, and a value the spec does not -declare cannot be constructed in code. Resolve a raw value with `{EnumType}.TryGetKnownValue(value, out var +There is **no public factory**: `{EnumType}.FromValue(...)` does not exist, and an undeclared value cannot +be constructed in code. Resolve a raw value with `{EnumType}.TryGetKnownValue(value, out var known)` — exact, case-sensitive — and guard a received value with `instance.IsKnownValue()`. A server value the SDK does not declare still deserializes (enums are open on reads), round-trips unchanged with the server's own casing, and compares without constructing one: `instance.Is("raw")` or `instance == "raw"`. -Branch with the generated `Match`, not a `switch`: one `on{Member}` arm per declared value in spec order, +Branch with the generated `Match`, not a `switch`: one `on{Member}` arm per declared value in declaration order, then `otherwise`, which receives the raw wire value of anything undeclared. Pass the arms by name — the parameters are positional, and a regenerated SDK that adds or reorders a value changes the signature (a source break, and `MissingMethodException` for an assembly compiled against the old shape). @@ -212,18 +225,17 @@ See [reference.md](reference.md) for full string- and int-enum declarations and Models declare their wire properties explicitly. An object or allOf model also carries a `[JsonExtensionData]` bag — `public AdditionalProperties AdditionalProperties { get; init; } = [];` -(`{RootNamespace}.Core.Models`) — so unknown JSON fields are **kept**, not dropped: a field the provider -added after this SDK was generated survives deserialization and round-trips back out on serialize. A -schema with `additionalProperties: false` has no bag, a `OneOf`/`AnyOf` union has none of its own, and the -bag is named `AdditionalProperties2` when a spec property's C# name is already `AdditionalProperties`. -Take the bag's name and type from the contract sheet. +(`{RootNamespace}.Core.Models`) — so unknown JSON fields are **kept**: a field this SDK does not model +survives deserialization and round-trips back out on serialize. A model that admits no extra fields has no +bag and drops them, a `OneOf`/`AnyOf` union has none of its own, and the bag is named `AdditionalProperties2` +when the model already has an `AdditionalProperties` property. Take the bag's name and type from the contract +sheet. Read one with `response.AdditionalProperties.TryGetValue("field_name", out var value)` (deserializes the captured `JsonElement` to `T`), or `TryGetElement` for the raw `JsonElement`; `Set(key, value)` adds -one to a request. When the schema types its extra fields, the bag is `AdditionalProperties`, whose -`TryGetValue("field_name", out var value)` takes no type argument. -Two cautions: the keys are **wire names** (there is no C# property, so nothing maps the -casing for you), and a field appearing here rather than as a typed property is a regeneration signal — -prefer regenerating the SDK over building program logic on stringly-typed lookups. The -bag itself has no `[JsonPropertyName]` and no wire name — its contents merge -into the model's own JSON object. +one to a request. When every extra field has one type, the bag is `AdditionalProperties`, whose +`TryGetValue("field_name", out var value)` takes no type argument. Two cautions: the keys are **wire names** +(there is no C# property, so nothing maps the casing for you), and a field appearing here rather than as a +typed property is one this SDK version does not type — prefer an SDK version that does over building +program logic on stringly-typed lookups. The bag itself has no `[JsonPropertyName]` and no wire name — its +contents merge into the model's own JSON object. diff --git a/plugins/plaid/skills/dotnet/dotnet-models/reference.md b/plugins/plaid/skills/dotnet/dotnet-models/reference.md index e780a4e6..1147fca3 100644 --- a/plugins/plaid/skills/dotnet/dotnet-models/reference.md +++ b/plugins/plaid/skills/dotnet/dotnet-models/reference.md @@ -1,19 +1,5 @@ # Models reference (APIMatic .NET) -## Date/time - -**Check the property type first.** A date/time field is `DateTimeOffset?` only where the API definition -marks it as a date/time; otherwise it is a plain `string?`, often with a `[RegularExpression]` attribute -documenting (not enforcing) an RFC-3339 shape. Both appear in generated SDKs, and some SDKs contain no -`DateTimeOffset` at all. - -Where it *is* a `DateTimeOffset`, the property carries **no converter attribute** and round-trips as -`System.Text.Json`'s default — ISO-8601 with offset, `"2024-06-17T15:30:45+00:00"` — even where the API -documents a date-only shape. The four generated date converters (ISO-8601, RFC-1123, Unix epoch seconds, -date-only) are attached to whole-response payloads, not to model properties. Work with `DateTimeOffset` -directly and let the SDK serialize it; for formatting in your own code use the BCL -(`DateTimeOffset.Parse`, `.ToString("O")`, …), not the SDK's internal converters. - ## String-enums Every enum — schema enums under `Models/Enums/` and the server-environment enum under `Servers/` — is a @@ -77,22 +63,24 @@ public sealed record {EnumType} : OpenIntEnum<{EnumType}> long n = {EnumType}.On; // implicit conversion to long ``` -Member names come from the spec's `x-enum-varnames` when it declares them, otherwise `Value{n}` / -`Negative{n}` from the value itself. +A member with no declared name is `Value{n}` / `Negative{n}`, from the value itself. ## Union types — finding the exact members For a `OneOf`/`AnyOf` type, the contract sheet lists the exact members (grounded from the SDK map/source). Each variant `{V}` produces: -- a factory `static {Union} {V}({V} value)` (the parameter type usually equals the variant type name), and -- a reader `bool TryGet{V}(out {V} value)`. +- a factory `static {Union} {V}({V} value)` (the parameter type usually equals the variant type name), +- a reader `bool TryGet{V}([NotNullWhen(true)] out {V}? value)` for a reference type, `bool TryGet{V}(out {V} value)` + for a value type, and +- a handler `on{V}` in both `Match` overloads (`Func<{V}, TResult>` / `Action<{V}>`), in declaration order, + before the closing `otherwise` (`Func` / `Action`). + +Every union also has `bool TryGetUnknown(out JsonElement value)` for a value the SDK could not place. Its +factory is internal: application code can read such a value and send it back, but cannot create one. -A `OneOf`'s variants are always model/enum references (they come from the schema's discriminator -mappings), and each gets an `implicit operator {Union}({Variant})`. On an `AnyOf`, primitive and model -variants get one; list, map and untyped-object variants do not, and neither do two variants sharing one CLR -type. Unions are immutable records — there are no object-initializers and no way to mutate -one after construction. +Which variants also get an `implicit operator {Union}({Variant})` is in the SKILL. Unions are immutable +records — there are no object-initializers and no way to mutate one after construction. ## Notes @@ -102,12 +90,3 @@ one after construction. `required` property, which writes `null` when its type is nullable (`public required string? Reason`), and a non-optional property with a default (`public long Priority { get; init; } = 1L;`), whose type cannot hold null. There is no way to send an explicit `null` for an optional property; the difference matters on a PATCH. -- Unless its schema sets `additionalProperties: false`, an object or allOf model ends with a - `[JsonExtensionData]` bag, usually `public AdditionalProperties AdditionalProperties - { get; init; } = [];` — unknown response fields are captured there (keyed by **wire name**) and - round-trip on serialize. See the SKILL's *Unknown / future fields* for the read/write API and the - cautions. On the older 4.0.0 surface this property does not exist and unknown fields are dropped — - check the core-surface stamp before carrying this expectation across SDKs. -- Validation attributes (`[StringLength]`, `[RegularExpression]`, `[MaxLength]`, `[MinLength]`) are - transcribed from the API definition and are **never evaluated by the SDK** — see the SKILL for what to do - about that. diff --git a/plugins/plaid/skills/dotnet/dotnet-testing/SKILL.md b/plugins/plaid/skills/dotnet/dotnet-testing/SKILL.md index 720a21eb..b7b008f0 100644 --- a/plugins/plaid/skills/dotnet/dotnet-testing/SKILL.md +++ b/plugins/plaid/skills/dotnet/dotnet-testing/SKILL.md @@ -1,6 +1,6 @@ --- name: dotnet-testing -description: Testing code that calls an APIMatic-generated .NET SDK in C# — which seam to fake, covering error and edge paths, asserting real behaviour rather than execution, and keeping tests independent of SDK internals. Load before writing tests for the integration layer. +description: Load before writing tests for code that calls an APIMatic .NET SDK in C# — the HttpClient stub seam, error and retry paths, faking the clock, constructing SDK exceptions directly, and asserting the outgoing request. --- # Testing code that uses an APIMatic .NET SDK @@ -57,10 +57,19 @@ static {Api}Client ClientReturning(HttpStatusCode status, string json) { Content = new StringContent(json, System.Text.Encoding.UTF8, "application/json") }); - return new {Api}Client(new HttpClient(handler), new {Api}ClientOptions { /* auth not needed for stubs */ }); + return new {Api}Client(new HttpClient(handler), new {Api}ClientOptions + { + {Credential} = "test-token", // one placeholder per credential the operations under test require + }); } ``` +**Set every credential the operations under test require, even against a stub.** An unset required +credential throws `AuthSchemeException` before the stub sees a request. A value set in code also shields +the test from any `{API}_*` environment variable on the machine — `{API}` being the SDK name in upper snake +case. For an OAuth2 scheme, see *Test a client with OAuth credentials*: the placeholder makes the stub's +first request the token `POST`. + ## Test a success path ```csharp @@ -77,12 +86,9 @@ public async Task ReturnsDeserializedBody() ## Test an error path -Endpoint methods throw `ApiException` on non-2xx (see `dotnet-error-handling`). `TError` is the -operation's `{Operation}Error` model (**Case A**) for operations that have a generated `{Operation}Error` -type, or `RawError` **directly** (**Case B**) otherwise — so assert the type that matches your operation. -Whichever the case, the exception itself carries `StatusCode`, `Headers` and `ContentType` (from -`ApiException`) plus the failed call's `Method` and `RequestUri` (from the `SdkException` root), and its -`Message` is the call and the status — `"POST https://host/path returned 422 (UnprocessableEntity)."`. +Endpoint methods throw `ApiException` on non-2xx — `{Operation}Error` (**Case A**) or `RawError` +(**Case B**); see `dotnet-error-handling` — so assert the type that matches your operation. The exception +carries `StatusCode`, `Headers`, `ContentType`, `Method` and `RequestUri`. **Case A — typed `{Operation}Error`:** @@ -99,17 +105,13 @@ public async Task ThrowsOnApiError() () => client.{ApiGroup}.{Operation}(request, cancellationToken: default)); Assert.Equal(HttpStatusCode.UnprocessableEntity, ex.StatusCode); // the status is on the exception - // ex.Error is the typed ApiError. For a status the operation maps to a typed body (e.g. 422), assert the - // typed accessor — its name embeds the body type; the contract sheet lists the exact accessor name. - // TryGetRawError is FALSE for those statuses, so don't assert through it here: + // Assert the accessor for this status (name from the contract sheet); TryGetRawError is false here. Assert.True(ex.Error.TryGetSomeTypedBody(out var typed)); - // ...assert on 'typed'. TryGetRawError fires ONLY for a status that falls to the error factory's - // default arm. A status with its own RawError accessor — TryGetNoContent, say — populates that - // accessor and leaves TryGetRawError false, so assert the specific one. + // ...assert on 'typed'. } ``` -**Case B — `ApiException`** (e.g. read/list/find/archive/delete operations). Here `ex.Error` *is* +**Case B — `ApiException`.** Here `ex.Error` *is* the `RawError` — there is no `TryGet*` / `TryGetRawError`; read it directly: ```csharp @@ -123,11 +125,11 @@ Assert.Equal(HttpStatusCode.UnprocessableEntity, ex.StatusCode); // same value // You can also assert the deserialized error body: ex.Error.ReadAsString() / ex.Error.ReadAsJson(). ``` -**A body that does not match the model is a third outcome.** Stub a 2xx whose JSON does not fit the -response type — or an error status whose body does not fit the `{Operation}Error` template — and the call -throws `ResponseDeserializationException`: an `ApiException` (so `StatusCode` tells you which of the two it -was) but **not** an `ApiException`, carrying the `TargetType` it tried to build and the -`JsonException` as `InnerException`. Lock this down for any operation whose provider is known to drift: +**A body that does not match the model is a third outcome.** A 2xx whose JSON does not fit the response type, +or an error body that does not fit `{Operation}Error`, throws `ResponseDeserializationException` (see +`dotnet-error-handling`); its `StatusCode` says which. A `OneOf` or `AnyOf` response type is the exception: a +body no variant accepts lands in its Unknown slot (see `dotnet-models`), so assert `TryGetUnknown` there +instead of a throw. Lock it down for any operation whose provider is known to drift: ```csharp var client = ClientReturning(HttpStatusCode.OK, """{ "{resource}": "not-an-object" }"""); @@ -141,9 +143,8 @@ Assert.Equal(typeof({ReturnType}), ex.TargetType); ## Test the result-style (`ApiResult`) variant -If the operation exposes the optional non-throwing `{Operation}Result` sibling (see `dotnet-error-handling`), -there is nothing to catch — stub the response and assert on the returned `ApiResult` -directly. The status code and headers are available on both the success and failure outcomes. +If the operation has a `{Operation}Result` sibling (see `dotnet-error-handling`), there is nothing to catch — +assert on the returned `ApiResult`; status and headers are on both outcomes: ```csharp using {RootNamespace}.Core.Models; // ApiResult @@ -169,22 +170,21 @@ public async Task ResultVariantReportsFailureWithoutThrowing() With OAuth credentials set, the first request your stub sees is the token `POST`. `ClientReturning` answers every request alike, so give `StubHandler` a responder that returns queued responses, a token response such as `{ "access_token": "t", "token_type": "Bearer" }` first. The token is cached, so two calls make three -requests. Or keep the credentials set and give `options.{Scheme}TokenStrategy` a stub that returns -`new OAuthToken { AccessToken = "t", TokenType = "Bearer" }` (for authorization code, an -`OAuthTokenRefreshable`, with `TryRefreshToken` returning `null`), because a strategy without credentials is -never used. Either way, an authorization-code client also needs a `PromptForAuthorizationCode` that returns a -fixed code. -For a bad-credentials test, answer the token request with a 4xx and assert `AuthSchemeException`. +requests. An authorization-code client also needs a `PromptForAuthorizationCode` that returns a fixed code. +A `401` on an authenticated call makes the SDK drop the token, fetch a new one and re-send once, so a stub that +answers `401` sees a second token request and a second call before the `401` reaches the test. +For a bad-credentials test, answer the token request with a 4xx and assert `AuthSchemeException`; for a missing +credential, leave the property unset (and its `{API}_*` environment variable too) and assert +`AuthSchemeException` before any request reaches the stub. ## Fake the clock The SDK reads time through exactly one seam — `{Api}ClientOptions.TimeProvider` (default `TimeProvider.System`). Retry backoff, `Retry-After`, the per-attempt timeout, the SSE idle timeout, OAuth2 -token expiry and the logged request durations all follow it, so one fake provider drives them together and -a retry test no longer sleeps through `1s + 2s + 4s` of real backoff. Use a provider that **implements -timers** — `FakeTimeProvider` from `Microsoft.Extensions.TimeProvider.Testing` — because the retry delay -and the idle window are timers on the provider: a `GetUtcNow`-only fake throws when the SDK asks it for a -timer, which is deliberate and better than a silent real sleep. +token expiry and the logged request durations all follow it, so one fake provider drives them together with +no real sleeps. Use a provider that **implements timers** — `FakeTimeProvider` from +`Microsoft.Extensions.TimeProvider.Testing` — because the retry delay and the idle window are timers on the +provider: a `GetUtcNow`-only fake throws when the SDK asks it for a timer. ```csharp using Microsoft.Extensions.Time.Testing; // FakeTimeProvider (Microsoft.Extensions.TimeProvider.Testing) @@ -192,7 +192,11 @@ using Microsoft.Extensions.Time.Testing; // FakeTimeProvider (Microsoft.Extens var clock = new FakeTimeProvider(); var responses = new Queue([HttpStatusCode.ServiceUnavailable, HttpStatusCode.OK]); var handler = new StubHandler(_ => new HttpResponseMessage(responses.Dequeue()) { Content = new StringContent("{}") }); -var client = new {Api}Client(new HttpClient(handler), new {Api}ClientOptions { TimeProvider = clock }); +var client = new {Api}Client(new HttpClient(handler), new {Api}ClientOptions +{ + {Credential} = "test-token", // as in ClientReturning + TimeProvider = clock, +}); var call = client.{ApiGroup}.{Operation}(request, cancellationToken: default); // a GET: retryable clock.Advance(TimeSpan.FromSeconds(2)); // past the 1s backoff (+ up to 500ms jitter) @@ -202,10 +206,8 @@ Assert.Equal(2, handler.Requests.Count); ``` The awaited call does not complete until the fake clock moves past the backoff — start the call, `Advance`, -then `await`. Under DI, register the fake as the container's `TimeProvider` (before *or* after -`Add{Api}Client` — order does not matter) and the SDK seeds the option from it; an explicit -`o.TimeProvider = clock` in the configure callback wins over the container. The SDK never registers a -`TimeProvider` itself, so nothing of yours is overwritten. +then `await`. Under DI, register the fake as the container's `TimeProvider` (either order) or set +`o.TimeProvider = clock` in the configure callback (see **dotnet-configuration-resilience** § *The clock*). ## Construct an SDK exception directly @@ -250,13 +252,13 @@ Because the stub captures `LastRequest`, you can assert method, path, query, hea ```csharp var handler = new StubHandler(_ => new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent("{}") }); -var client = new {Api}Client(new HttpClient(handler), new {Api}ClientOptions()); +var client = new {Api}Client(new HttpClient(handler), new {Api}ClientOptions { {Credential} = "test-token" }); await client.{ApiGroup}.{Operation}(request, cancellationToken: default); Assert.Equal(HttpMethod.Post, handler.LastRequest!.Method); Assert.Contains("/expected/path", handler.LastRequest!.RequestUri!.AbsolutePath); -Assert.Contains("per_page=20", handler.LastRequest!.RequestUri!.Query); // query params are snake_case on the wire +Assert.Contains("per_page=20", handler.LastRequest!.RequestUri!.Query); // the wire name, not the C# property // Assert the serialized request body of a POST/PUT/PATCH: var sentJson = handler.LastBody; // NOT LastRequest.Content — see below @@ -266,31 +268,23 @@ Assert.Contains("\"expected_field\"", sentJson); ## Notes - ⚠ **Read the request body inside the handler, never off the captured request afterwards.** The SDK - disposes the request content in a `finally` that runs per attempt, *inside* the pipeline — so by the time - your awaited call returns, `handler.LastRequest.Content.ReadAsStringAsync()` throws - `ObjectDisposedException`. That is why the stub above buffers `Bodies` during `SendAsync`. Everything - else on the captured `HttpRequestMessage` — method, URI, headers — survives and can be asserted normally. + disposes the request content after each attempt, so once your awaited call returns, + `handler.LastRequest.Content.ReadAsStringAsync()` throws `ObjectDisposedException` — hence `Bodies` in the + stub above. Method, URI and headers on the captured `HttpRequestMessage` survive and can be asserted. - Mocking libraries (Moq, NSubstitute) work too — mock `HttpMessageHandler.SendAsync` (it's `protected`, so use `Protected()` with Moq). The hand-written stub above avoids that friction. -- A stubbed retryable response — the default set is exactly `408, 429, 500, 502, 503, 504`, not all `5xx` - — on a retryable method will be retried by the SDK before the call returns. `HttpMethodsToRetry` (`GET/HEAD/PUT/OPTIONS` by default) gates **every** trigger, so a - `POST` retries on nothing — not a `503`, not a thrown `HttpRequestException`, not the per-attempt timeout - — unless you add its verb to the list (see `dotnet-configuration-resilience`). To observe retries firing, - stub a `GET` that returns `503` then `200` and count invocations. -- **Status faults and transport faults are separate retry triggers** — the SDK distinguishes them itself - (`RetryAttempt.Reason` is `RetryReason.Status(...)` *or* `RetryReason.Failure(Exception)`), and a third, - the per-attempt timeout, arrives as `RetryReason.Failure(TimeoutRejectedException)`. A test that stubs a - `503` therefore proves nothing about what happens when the *connection* fails. The verb filter holds all - three at one send for a `POST` — which is exactly the property worth locking down with a test, because it - is a *configuration* guarantee and someone widening `HttpMethodsToRetry` for the read path silently - removes it. What reaches the test is the SDK's wrapper, never the raw `HttpRequestException`: a failed - send surfaces as `SdkConnectionException` (message `"POST https://host/path could not be sent: connection - reset"`, the raw exception as `InnerException`), and an exhausted per-attempt timeout as - `SdkTimeoutException` with `Timeout` set to the window that elapsed. +- **Retries run before the call returns.** A stubbed `408`/`429`/`500`/`502`/`503`/`504` (not every `5xx`) on + `GET`/`HEAD`/`PUT`/`OPTIONS` is retried — stub `503` then `200` and count requests; a `POST` is retried on + nothing but an OAuth2 `401`, which every verb re-sends once (see `dotnet-configuration-resilience`). Status and transport faults are separate triggers + (`RetryAttempt.Reason` is `RetryReason.Status(...)` or `RetryReason.Failure(...)`), so a `503` stub proves + nothing about a connection failure — and the one-send `POST` is worth a test, since widening + `HttpMethodsToRetry` silently removes it. A thrown `HttpRequestException` surfaces as + `SdkConnectionException` with the raw exception as `InnerException`, and an exhausted per-attempt timeout + as `SdkTimeoutException`: ```csharp // Transport fault: the stub throws instead of answering, then we count what the server actually received. var handler = new StubHandler(_ => throw new HttpRequestException("connection reset")); - var client = new {Api}Client(new HttpClient(handler), new {Api}ClientOptions()); + var client = new {Api}Client(new HttpClient(handler), new {Api}ClientOptions { {Credential} = "test-token" }); var ex = await Assert.ThrowsAsync( () => client.{ApiGroup}.{Operation}(request, cancellationToken: default)); @@ -298,10 +292,8 @@ Assert.Contains("\"expected_field\"", sentJson); Assert.IsType(ex.InnerException); Assert.Equal(1, handler.Requests.Count(r => r.Method == HttpMethod.Post)); // no resend ``` -- **Your own cancellation is the one thing the SDK never wraps.** A token you cancel surfaces as the usual - `OperationCanceledException` / `TaskCanceledException`, not as an `SdkException` — so a test that cancels - mid-call asserts on the framework type, and a `catch (SdkException)` in the code under test must be - expected *not* to fire. +- **Your own cancellation surfaces as `OperationCanceledException`**, never an `SdkException` — assert the + framework type, and expect a `catch (SdkException)` in the code under test *not* to fire. - For DI-based code, the SDK's `Add{Api}Client` resolves the **default (unnamed)** `IHttpClientFactory` client, so register your stub on that one, then resolve `{Api}Client` from the provider: ```csharp @@ -309,8 +301,6 @@ Assert.Contains("\"expected_field\"", sentJson); services.AddHttpClient(Options.DefaultName).ConfigurePrimaryHttpMessageHandler(() => stubHandler); var client = services.BuildServiceProvider().GetRequiredService<{Api}Client>(); ``` - A `TimeProvider` registered in the same container is picked up by the SDK automatically — see *Fake the - clock* below. - To look up an operation's signature, its request type, or a `{Operation}Error`'s accessor names, take them from the contract sheet (grounded from the SDK map/source) — not a decompiled or reflected view of the installed package, and not memory. diff --git a/plugins/plaid/skills/python/python-authentication/SKILL.md b/plugins/plaid/skills/python/python-authentication/SKILL.md index 87665c39..4b770f4e 100644 --- a/plugins/plaid/skills/python/python-authentication/SKILL.md +++ b/plugins/plaid/skills/python/python-authentication/SKILL.md @@ -1,6 +1,6 @@ --- name: python-authentication -description: Authentication for an APIMatic-generated Python SDK — supplying credentials in typed or dict form, the scheme shapes, the managed OAuth2 token lifecycle and its caching, what a failed token fetch actually raises (and why it bypasses the non-raising response mode), and loading secrets safely. Load before wiring credentials into the client, or when a call fails with 401/403. +description: Load before setting credentials on an APIMatic-generated Python SDK client, or when a call fails with 401/403 or a token fetch fails. Covers each scheme's constructor keyword in typed or dict form — Basic, bearer, API key and the three OAuth2 grants — the managed token lifecycle and caching, composite schemes, what a failed token fetch raises, and loading secrets. --- # Authenticating an APIMatic Python SDK client @@ -16,22 +16,19 @@ dict of the same keys; set the one(s) your API uses, then construct the client ( To see which schemes a specific SDK accepts, read the **credentials keywords on its client constructor** — those are the source of truth (take them from the contract sheet, grounded in the SDK map's constructor-keyword table and its *Servers & auth* section, not from recall). -`{root_package}/auth.py` is the cheap cross-check: -its `AuthSchemes` holder carries exactly one field per declared scheme, and the field names *are* the -constructor keywords. The `{root_package}/core/auth/schemes/` directory ships *every* scheme the -generator supports as shared runtime code regardless of what the API accepts, so never infer a scheme -from that directory. (An SDK whose API uses only OAuth2 client credentials, for instance, exposes a -single `{oauth2}=` keyword and its `{oauth2}_token_source=` override.) +`{root_package}/auth.py` is the cheap cross-check: its `AuthSchemes` holder carries exactly one field +per declared scheme, named as the constructor keyword. Never infer a scheme from +`{root_package}/core/auth/schemes/`: it ships every scheme kind, whatever the API accepts. (An SDK +whose API uses only OAuth2 client credentials, for instance, exposes a single `{oauth2}=` keyword and +its `{oauth2}_token_source=` override.) The credential classes below live under `{root_package}.core` and are the **same across all APIMatic -Python SDKs**; only the **keyword names** are generated per-API — each is the security scheme's id from -the spec, snake_cased (hence the `{...}` placeholders). +Python SDKs**; only the **keyword names** differ per SDK — each is the scheme's id, snake_cased (hence +the `{...}` placeholders). ## The two spellings -Every credential keyword accepts a typed model or a mapping, and they are exactly equivalent — a -`coerce` classmethod is the single place the dict form is resolved, so the two cannot produce different -requests: +Every credential keyword accepts a typed model or a mapping, and the two produce identical requests: ```python from {root_package}.core import ClientCredentials @@ -74,15 +71,14 @@ its discovery document says how a token is obtained, not how it is sent. ## API key (header, query, or cookie) The key is sent as a header, query parameter, or cookie — its placement and name are fixed by the -generated scheme. Set the configured key keyword to your key string: +SDK's scheme. Set the configured key keyword to your key string: ```python client = {Client}({api_key}="API_KEY") ``` A query-placed key is percent-encoded exactly as an endpoint's own query parameter; a cookie-placed key -is sent verbatim, because RFC 6265's `cookie-value` alphabet already admits every character a base64 -key uses and encoding it would corrupt the credential. +is sent verbatim. > **Applies only when the SDK declares an OAuth2 scheme.** The next five sections — the three grants, > the managed token lifecycle, and the token-fetch failure mode — describe machinery that exists only @@ -105,10 +101,9 @@ client = {Client}({oauth2}=ClientCredentials( pre-join it yourself, or you send one scope literally named `"a b"`. Omit it to get whatever the client's default scopes are. -When the flow declares a scope vocabulary, the generator emits a `Literal` alias for it in -`{root_package}/auth.py` (`{Flow}Scope`) and types `scopes` by that alias — so a scope the flow does not -document fails the type check at the call site instead of the request at the provider. A flow that -declares no scopes has no alias, and `scopes` is a plain `list[str] | None`. +Where `{root_package}/auth.py` declares a `{Flow}Scope` `Literal` alias, `scopes` is typed by it — so +a scope the flow does not document fails the type check at the call site instead of the request at the +provider. A flow with no alias takes a plain `list[str] | None`. ## OAuth 2.0 — authorization code (3-legged, with PKCE) @@ -168,20 +163,18 @@ is the part that matters: - **The token is fetched lazily, on the first authenticated call** — not at construction. A client built with bad credentials constructs perfectly happily; the failure surfaces at the first operation. -- The fetch is a `POST` to the token endpoint derived from the client's `base_url`, form-encoded, with - the client id and secret sent per the placement the spec declares — commonly HTTP Basic - (`client_secret_basic`, both halves percent-encoded before base64), otherwise in the form body - (`client_secret_post`). +- The fetch is a form-encoded `POST` to the token endpoint derived from the client's `base_url`, with + the client id and secret sent as HTTP Basic (`client_secret_basic`) or in the form body + (`client_secret_post`), per the scheme. - The resulting token is **cached in memory on the client's auth scheme** and reused across calls, which - is the whole reason a client must be long-lived (`python-client-initialization`). The cache is - double-checked under a lock, so a burst of concurrent first calls pays for **one** fetch. + is the whole reason a client must be long-lived (`python-client-initialization`); a burst of + concurrent first calls pays for **one** fetch. - A token with an `expires_in` is renewed ~30s before expiry (or at half its lifetime, whichever leaves more time, for tokens shorter than a minute). Without an `expires_in` there is no client-side deadline and the token is used until the server rejects it. -- **Refreshing applies only to the authorization-code grant**, whose scheme prefers a refresh over a - re-acquisition — a re-acquisition would run your prompt again. Client-credentials and password - re-acquire instead (RFC 6749 §4.4.3 says the client-credentials grant SHOULD NOT be issued a refresh - token), so the password grant re-sends the resource owner's password at every expiry. +- **Refreshing applies only to the authorization-code grant**, where a re-acquisition would run your + prompt again. Client-credentials and password re-acquire instead, so the password grant re-sends the + resource owner's password at every expiry. - **On a `401`, the cached token is invalidated** so the next call re-authenticates — but **the failing request is not retried**. This is deliberate: the caller sees one `401` and then recovery. Do not write a retry loop *just* for this; do expect that a revoked credential surfaces as exactly one @@ -197,59 +190,41 @@ anything satisfying the token-source protocol: `TokenSource` (`fetch(credentials scheme's cache, which is private. Your source **must not issue a request that itself uses this scheme** — it runs inside that scheme's lock and would deadlock. -## The failure mode that surprises everyone +## A failed token fetch raises `AuthSchemeError` -**A failed token fetch raises the SDK's ordinary API exception — but its payload is a different type -than any operation's.** For a managed-OAuth SDK, the token endpoint's error body is fixed by -RFC 6749 §5.2, so the SDK decodes it into an `OAuthProviderError` (`error`, `error_description`, -`error_uri`) — or a `RawError` if the provider's body does not conform. - -Two consequences, and both are the sort of thing that costs an afternoon: - -1. **The exception surfaces out of your *operation* call**, because that is where the lazy fetch - happens. A traceback for bad credentials points at the operation you called, and the frames - underneath name the token source. Reading only the top frame sends you looking in the wrong place - entirely. -2. **The non-raising response mode does not protect you.** The `with_raw_response` variant returns a - result object instead of raising *for the operation* — but the token fetch passes its own result - through `unwrap()` internally, so an auth failure raises even there. Any code path that touches the SDK needs to handle - this, including one written specifically to avoid exceptions. - -So a boundary that catches only the operation's error union is incomplete. Narrow on the payload type: - -```python -from {root_package}.core import ApiError, OAuthProviderError, RawError - -try: - result = client.{controller}.{operation}(body) -except ApiError as e: - if isinstance(e.error, OAuthProviderError): - # Credentials/token problem — no operation request was ever sent. - log.error("auth failed: %s (%s)", e.error.error, e.error.error_description) - raise ConfigurationError("API credentials rejected") from e - ... # the operation's own error union -``` - -Treat this as a **configuration** failure, distinct from an operation rejection: nothing was attempted, -so retrying it or reporting it as a failed operation are both wrong. `python-error-handling` has the -full catch ladder. +It names **your operation's** call, not the token endpoint, so an `except ApiError` around that call +never catches the token endpoint's `401`. What went wrong is on `__cause__`: an `ApiError` whose +`error` is a `RawError` when the endpoint refused (the RFC 6749 `error` code is in +`e.__cause__.error.json()`), or an `SdkConnectionError` when it could not be reached. It +surfaces out of your **operation call**, where the lazy fetch happens — the top frame names the +operation, the frames beneath it the token source — and it raises under `with_raw_response` too. +Treat it as a **configuration** failure: no operation request was sent, so neither retry it nor report +it as a failed operation; `python-error-handling` has the ladder. ## Combined / multiple schemes -When an operation (or the whole API) requires more than one scheme, APIMatic composes them per -operation — OpenAPI's OR-of-ANDs, arm by arm — and the generated client wires the composition for you. -You configure it by setting the relevant credentials keywords: +When an operation (or the whole API) requires more than one scheme, the client composes them per +operation for you. You configure it by setting the relevant credentials keywords: - **AND** (`AllSchemes`) — every *configured* member applies to the request. -- **OR** (`AnySchemes`) — the first *configured* member applies. Selection is on **credential presence**, - never on "applying it did not fail", so an unconfigured member listed first cannot win and send the - request unauthenticated. - -**This layer never withholds a request over a missing credential, and never raises for one.** An -unconfigured member simply drops out and the request goes out with whatever *was* configured; with -nothing configured at all it goes out unauthenticated. The server decides. Because composition is -per-operation, one client may authenticate different operations with different schemes — set every -keyword the operations your integration calls actually need. +- **OR** (`AnySchemes`) — the first *configured* member that applies wins. An unconfigured member is + never tried, so one listed first cannot win and send the request unauthenticated, and a configured + member that raises yields to the next. Only when every configured member raised does the call raise + `AuthSchemeError`, each failure in `scheme_failures`. A failure a later member recovers from is + absorbed: the call goes ahead on that member's credential. A failed token request logs its own + lines (a WARNING where it was refused, an ERROR where it got no response), and those are the signal + that a fallback credential is in use. The group adds no line of its own; wrap that scheme if you + want one naming it. + +**A missing credential never withholds a request and never raises.** Omitting a credentials keyword is +legal and silent — the client is built with a no-auth scheme — and an unconfigured composite member +simply drops out, so the request goes out with whatever *was* configured; with nothing configured at +all it goes out unauthenticated, and the server decides. Most APIs then answer `401`; an API that +serves anonymous traffic at all (public endpoints, or a reduced rate limit for keyless callers) +answers `200` and hides the omission entirely. Because composition is per-operation, one client may +authenticate different operations with different schemes — so verify every keyword the operations +your integration calls actually need is set, and on blanket `401`s check that before suspecting the +credentials themselves. ## No auth @@ -286,19 +261,8 @@ Two things that help, both already built in: ## Notes -- A given SDK only exposes the credentials keywords for the schemes its API uses; those names are - generated per-API (hence the `{...}` placeholders above). -- **Omitting a credentials keyword is legal and silent.** The client is then built with a no-auth - scheme and requests go out unauthenticated. Nothing warns you at construction. Most APIs then - answer `401`; an API that serves anonymous traffic at all (public endpoints, or a reduced rate - limit for keyless callers) answers `200` and hides the omission entirely — so verify the keyword is - actually set rather than waiting for a `401` to tell you, and if you *are* getting blanket `401`s, - check that before suspecting the credentials themselves. -- Set credentials **at construction**. The scheme is built there; assigning to a private attribute - afterwards is not supported. To rotate a credential, build a new client and close the old one. -- Rotation with a long-lived client: the token cache is per client instance, so swapping in a new - client atomically (build, then replace the reference, then close the old one) rotates without a - window where calls have no credential. -- A per-call `extra_headers` outranks the credential: header precedence is API-wide → the endpoint's - own → auth → `extra_headers`. That is the deliberate way to override an `Authorization` header — or - blank it for a call meant to go out anonymous — and also the way to break auth by accident. +- Set credentials **at construction**; assigning to a private attribute afterwards is not supported. + To rotate a credential, build a new client, replace the reference, then close the old one — the + token cache is per client instance, so there is no window where calls have no credential. +- A per-call `extra_headers` outranks the credential, so it can override or blank `Authorization` for + one call (`python-calling-endpoints`). diff --git a/plugins/plaid/skills/python/python-calling-endpoints/SKILL.md b/plugins/plaid/skills/python/python-calling-endpoints/SKILL.md index a6e72427..17495ee7 100644 --- a/plugins/plaid/skills/python/python-calling-endpoints/SKILL.md +++ b/plugins/plaid/skills/python/python-calling-endpoints/SKILL.md @@ -1,6 +1,6 @@ --- name: python-calling-endpoints -description: Calling operations on an APIMatic-generated Python SDK — finding the group that owns an operation, the positional/keyword-only split and the parameters that never appear in the signature at all, passing a body as a model or a dict, uploading a file or a raw binary body, the two response modes, consuming a streamed file response, consuming an event stream, per-call request options, and async usage. Load before writing the first call to an SDK operation, or when an operation's shape or return type is unclear. +description: Load before writing the first call to an operation on an APIMatic-generated Python SDK, or when an operation's parameters or return type are unclear. Covers finding the group that owns an operation, the positional/keyword-only split, parameters absent from the signature, bodies as models or dicts, the parsed and with_raw_response modes, return types, iterating a paginator, per-call request_options and async calls. --- # Calling endpoints on an APIMatic Python SDK @@ -36,29 +36,21 @@ parameter you must pass `None` to just to reach a later one. Omit what you do no ### Where a parameter lands — the rule -Each parameter the description declares produces **one of three** outcomes, and the third one catches -people out: - -| What the description declares | What you get | +| Declared as | What you get | |---|---| | **required**, no fixed value | a **positional** parameter, no default | | **optional** | a **keyword-only** parameter defaulting to `None` | | a **default value** | a **keyword-only** parameter defaulting to *that value* — even if the parameter is required | | a **constant** value | **no parameter at all** — the value is baked into the request and you cannot change it | -Two consequences worth stating on the contract sheet: - -- **"Required" does not mean "path".** Positional parameters are ordered **path → query → header → - body**, so a required *query* or *header* parameter is positional too, sitting between the path - parameters and the body. Take the boundary from the sheet; never infer it from the URL. -- **A parameter with a declared default is keyword-only whatever its optionality**, and the SDK sends - that default on every call you don't override. +**"Required" does not mean "path".** Positional parameters are ordered **path → query → header → +body**, so a required *query* or *header* parameter is positional too, sitting between the path +parameters and the body. Take the boundary from the sheet; never infer it from the URL. ### Non-`None` defaults silently narrow what comes back -This is the single most common wasted afternoon on a generated SDK. A parameter carrying a -spec-declared default is *always sent*, so the response you get is the one that default asked for — -not the full resource. Typical shapes: +A parameter's non-`None` default is **sent on every call** you don't override, so the response you +get is the one that default asked for — not the full resource. Typical shapes: - a representation/verbosity switch defaulting to the minimal form, so a create returns little more than an id, a status and some links; @@ -87,7 +79,7 @@ Prefer models in application code: better inference, better errors, and required at construction. The dict form suits payloads assembled from external data. See `python-models`. **Form and multipart** — there is **no single body parameter**. Each field (and each file) becomes its -own parameter, following the same three-way split rule above. Do not go looking for a `body=`; read the +own parameter, following the same rule above. Do not go looking for a `body=`; read the signature. An optional part is omitted by leaving its parameter at its default: a part passed `None` is dropped from the body rather than sent empty. @@ -102,26 +94,18 @@ position. **No payload** — no body parameter at all. -**An optional-looking body is not permission to omit it.** A body typed `... | None = None` reflects -what the *description* marked optional, not what the endpoint needs. A create whose body is optional in -the spec will type-check with no arguments and then fail at the provider. Where a call obviously needs -a payload, pass one. +**An optional-looking body is not permission to omit it.** A body typed `... | None = None` does not +mean the endpoint works without one: a create with an optional body type-checks with no arguments and +then fails at the provider. Where a call obviously needs a payload, pass one. Serialization happens while the request is built, **before** anything is sent — so a body the SDK cannot dump raises out of the call with no request made. See `python-models`. ### File and binary parameters -**One name per client, whichever position it is.** A multipart file part and a raw binary body take -the same alias, and only the client you called decides which: `FileInput` on the sync client, -`AsyncFileInput` on the async one, and `list[…]` of either for an array part. Both are imported from -`{root_package}.core`. - -Nothing validates a file, so what the alias accepts is wider than the annotation shows — `bytes`, a -`Path`, any object with a binary `read`, a chunk iterator, and an `anyio`-style handle on the async -client. Which one you pass has consequences the signature cannot show: what stays resident, what can -be re-sent, who closes your handle, whether the body goes out sized or chunked, and what the file is -called on the wire. There is **no `str` arm** at either position — wrap a path in `Path`. +A multipart file part and a raw binary body take the same alias — `FileInput` on the sync client, +`AsyncFileInput` on the async one, `list[…]` of either for an array part — imported from +`{root_package}.core`. There is **no `str` arm** at either position — wrap a path in `Path`: ```python from pathlib import Path @@ -129,10 +113,8 @@ from pathlib import Path client.{group}.{operation}(Path("invoice.pdf")) # the default: streams, sized, names itself ``` -**Load `python-file-handling`** before passing anything other than a `Path`, and before consuming a -file an operation returns. It carries the arm-by-arm decision with its costs, the three behaviours -that differ between a part and a raw body, overriding the filename or media type, and how to read a -`FileResponse` without leaking its connection. +**Load `python-file-handling`** before passing anything other than a `Path` — what each arm costs, +the part-vs-raw-body differences, and overriding the filename or media type are there. ## Making the call and reading the response @@ -146,10 +128,11 @@ raises `ApiError`: value = client.{group}.{operation}(...) ``` -**Non-raising — `with_raw_response`.** Returns a result you branch on. Use it when you need the +**Non-raising — `with_raw_response`.** Returns a result you branch on — **2xx is `Success`, +everything else is `Failure`**, both carrying `.status_code` and `.headers`. Use it when you need the **status code or response headers** (the parsed form exposes neither on success, except for a file -response, which carries its own `headers`), or when a non-2xx is -an expected outcome rather than an exception: +response, which carries its own `headers`), or when a non-2xx is an expected outcome rather than an +exception: ```python from {root_package}.core import Success, Failure @@ -162,16 +145,15 @@ match client.{group}.with_raw_response.{operation}(...): ``` Both are frozen dataclasses, so `match` needs no boilerplate and `isinstance` narrowing is equivalent. -`unwrap(result)` (from `{root_package}.core`) collapses either back to the payload — which is literally -how the parsed form is built: every parsed method is `unwrap(...)` around its raw peer. +`unwrap(result)` (from `{root_package}.core`) collapses either back to the payload, raising on a +`Failure` exactly as the parsed form does. **`with_raw_response` removes one exception path, not the need for a `try`.** Two failures still raise -in both modes: a failed token fetch (it unwraps internally), and any decode failure. See -`python-error-handling`. +in both modes: a failed token fetch and any decode failure. See `python-error-handling`. ### Return types -Five shapes, and the sheet names which one each operation has — the map block states it directly as +Six shapes, and the sheet names which one each operation has — the map block states it directly as **Returns (parsed)** and **Returns (raw)**: - **A decoded model** — the JSON case, and the common one. @@ -181,6 +163,9 @@ Five shapes, and the sheet names which one each operation has — the map block - **An event stream** — `EventStream[T]` (`AsyncEventStream[T]` on the async client), for an operation declaring a `text/event-stream` response. It arrives **unread**, holds a connection, and iterating it yields `T`; see below. +- **A paginator** — `Paginator[Page, Item]` (`AsyncPaginator[Page, Item]` on the async client), for + a paginated operation, whose map block also carries a **Paging** bullet. It sends nothing until you + iterate it, and iterating it yields `Item`s from every page; see below. - **`None`** — the operation declares no response body. **`-> None` means the call succeeded.** Do not bind it and do not test it — success is "no exception @@ -188,20 +173,12 @@ raised", exactly as for the others. Two follow-ons: if you need the resulting st separate call; and if you need the status code (`200` vs `204`), the raw peer is `ApiResult[None, ...]` and `Success(payload=None, status_code=...)` is the only place it appears. -Writing `value = client.{group}.{operation}(...)` on a `-> None` operation type-checks under a loose -annotation and then fails later with an `AttributeError` on `None`. - ### Consuming a file response -A `FileResponse` is a body that has **not been read yet** and holds its connection until it is, -which makes it the one return value with a lifecycle. Three calls consume it and all three close it — -`save_to(...)`, `read()`, or a drained `iter_bytes()` under `with` — and the async twin mostly -`a`-prefixes them. - -Getting this wrong leaks a connection rather than raising, so **load `python-file-handling`** before -writing the consuming code. It carries the lifecycle in full: which warning fires when one is -abandoned and how to make it fail a test, the single-use rule, what `save_to` does with a directory, -and why a `try` around the call alone catches nothing. +A `FileResponse` arrives **unread** and holds its connection until `save_to(...)`, `read()` or a +drained `iter_bytes()` under `with` closes it; the async twin mostly `a`-prefixes them. A mistake +leaks a connection rather than raising, so **load `python-file-handling`** before writing the +consuming code. ### Consuming an event stream @@ -209,6 +186,33 @@ An `EventStream[T]` is iterated, not read: a drained `for` releases its connecti needs `with`. **Load `python-event-streams`** before writing the loop — it carries the lifecycle, the union narrowing, and the failures that are silent. +### Iterating a paginator + +A `Paginator` is a lazy walk over the whole collection, not a page. Calling the method sends nothing; +the first request goes out when you start iterating, and each new iteration starts again from the +first page. Iterate it for items, or call `iter_pages()` for the pages: + +```python +for item in client.{group}.{operation}(...): + ... + +for page in client.{group}.{operation}(...).iter_pages(): + ... +``` + +- **The arguments set the first request only.** The SDK moves the offset, page, cursor or link forward + from each response and stops on the API's own signals — the map block's **Paging** bullet says + which. There is no next-page method; to resume from a known point, pass it as the first-page + argument. +- **Cap a walk with `break` or `itertools.islice`.** There is no page-cap argument, and either stops + the walk with no further request. A `list(...)` over an uncapped paginator fetches every page. +- **Errors raise from the loop, not the call** — so a `try` around the call alone catches nothing. + `python-error-handling` has the detail. +- **The raw peer's pages are results.** `client.{group}.with_raw_response.{operation}(...)` returns + `Paginator[ApiResult[Page, E], Item]` and never raises for an API error: iterating it for items + yields the items of every successful page and ends at a failed one, and `iter_pages()` yields one + `Success` or `Failure` per page, the `Failure` last. + ## Per-call overrides — `request_options` @@ -219,30 +223,36 @@ accepted typed or dict-shaped: client.{group}.{operation}(..., request_options={"timeout": 5.0}) ``` -The keys are exactly `timeout` (seconds, must be > 0), `extra_headers`, and the two retry overrides -`max_retries` and `status_codes_to_retry` (`python-configuration-resilience`). It is validated with +The keys are exactly `timeout` (seconds, must be > 0), `extra_headers`, the two retry overrides +`max_retries` and `status_codes_to_retry`, `log_level` and `hooks` (`python-configuration-resilience`). +The typed form is `RequestOptions` on the sync client and `AsyncRequestOptions` on the async one: the +same keys, the async `hooks` being `AsyncSdkHook` or an `AsyncSdkHooksDict` where the sync ones are +`SdkHook` or an `SdkHooksDict`, so a hook of the other client's flavour is a type error at the call +site. It is validated with `extra="forbid"`, so `{"timeuot": 5}` raises `ValidationError` rather than being ignored — and because the dict form is a closed `TypedDict`, a type checker catches it at the call site first. -`extra_headers` wins over both the API's and the endpoint's own headers, which makes it the deliberate -way to override a header the SDK sets — including blanking an auth header for a call meant to go out -anonymous. That precedence is a footgun as much as a feature: setting `authorization` here overrides -the managed token. +`extra_headers` wins over the API's, the endpoint's and the auth scheme's headers (precedence +API-wide → endpoint → auth → `extra_headers`), which makes it the deliberate way to override a header +the SDK sets — including blanking an auth header for a call meant to go out anonymous — and the way to +break auth by accident: setting `authorization` here overrides the managed token. Two mechanics: - **Header names are lowercased on the way out**, at every layer including yours, so the merge is - genuinely case-insensitive and the request reaching the transport is keyed in lowercase. Look - request headers up that way (`python-testing`). -- **`Cookie` folds instead of replacing.** Every other field takes the later layer and discards the - earlier; a cookie you add joins the jar alongside whatever the endpoint or a credential put there - (RFC 6265 permits one `Cookie` field). So a cookie-carried credential cannot be blanked with - `extra_headers` the way a header-carried one can. + case-insensitive and the request reaching the transport is keyed in lowercase. Look request headers + up that way (`python-testing`). +- **`Cookie` folds instead of replacing.** Every other field takes the later layer; a cookie you add + joins whatever the endpoint or a credential put there, so a cookie-carried credential cannot be + blanked with `extra_headers` the way a header-carried one can. ## Async -The async client's operations are identical in name and parameters — you await them. There is no -`_async` suffix and no separate method list; the client class you hold decides the flavour: +The async client's operations have the same names and parameter names — you await them, and their +`request_options` is `AsyncRequestOptionsOrDict` (above). There is no +`_async` suffix and no separate method list; the client class you hold decides the flavour. The one +exception is a paginated operation: it is a **plain call** returning `AsyncPaginator`, so you +`async for` over it with no `await` on the call. ```python value = await client.{group}.{operation}(...) @@ -269,12 +279,9 @@ results = await asyncio.gather(*(one(a) for a in args)) ## Timeouts and cancellation -There is no cancellation-token parameter. Python's own mechanisms apply: - -- **Per call** — `request_options={"timeout": ...}`, which sets the limit on each wait for this one request. -- **The whole call** — `asyncio.wait_for(...)` around it, in async code; see - `python-configuration-resilience`. -- **Sync code has no whole-call limit.** The timeout only limits each wait — set one anyway. +There is no cancellation-token parameter. `request_options={"timeout": ...}` limits each wait of one +request; `asyncio.wait_for(...)` around the call limits the whole call in async code +(`python-configuration-resilience`). Sync code has no whole-call limit — set the timeout anyway. ## Next diff --git a/plugins/plaid/skills/python/python-client-initialization/SKILL.md b/plugins/plaid/skills/python/python-client-initialization/SKILL.md index 357e6284..7bff951b 100644 --- a/plugins/plaid/skills/python/python-client-initialization/SKILL.md +++ b/plugins/plaid/skills/python/python-client-initialization/SKILL.md @@ -1,6 +1,6 @@ --- name: python-client-initialization -description: Creating and holding an APIMatic-generated Python SDK client in Python — construction, the keyword-only constructor shape, choosing the sync or async class, transport ownership and the close/aclose obligation, and where the client lives in a script, an ASGI app, or a forking worker. Load before wiring the client into an application or writing the factory that builds it. +description: Load before constructing an APIMatic-generated Python SDK client or wiring it into an application — a script, an ASGI app (FastAPI, Starlette), a WSGI app or a forking worker (Gunicorn, Celery). Covers the keyword-only constructor, choosing the sync or async class, transport ownership and the close/aclose obligation, and how long the client lives. --- # Initializing an APIMatic Python SDK client @@ -23,8 +23,10 @@ constructor: {Api}Client( *, # server selection — one of four shapes, see "Choosing the server / base URL" - timeout: float = 30.0, # seconds; the generator's default + timeout: float = 30.0, # seconds retry_options=None, # None: the default policy; 0 disables; a count, RetryOptions or dict tunes it + logging_options=None, # what the built-in HTTP logging records — see python-configuration-resilience + hooks=None, # hook objects or {"on_request": [...], ...} — see python-configuration-resilience custom_http_client=None, # your own transport {scheme}=None, # one credentials keyword per declared scheme {scheme}_token_source=None, # managed-OAuth schemes only @@ -35,25 +37,23 @@ Every parameter sits after `*` — there are **no positional arguments**, so a p immediate `TypeError`. There is no options object, no builder, and no separate configuration type to populate: everything is a constructor keyword. -Operations are exposed on the client. Most are grouped under **group accessors** (one per API resource -group) and called `client.{group}.{operation}(...)` — for example, a `widgets` group's `list_widgets` -operation is `client.widgets.list_widgets(...)`. An operation that belongs to no group sits **directly -on the client**, called `client.{operation}(...)`. Accessors are `cached_property`, so they are -attributes without parentheses and return the same object each time. The available accessors (and any -direct operations) come from the contract sheet, grounded in the SDK map's controller table -(`sdk-map.md`) — not from a runtime `dir()` or a REPL poke. See -`python-calling-endpoints`. +Operations hang off **group accessors** — `client.{group}.{operation}(...)`, or `client.{operation}(...)` +for an ungrouped one. Accessors are `cached_property` attributes, not methods: no parentheses, and the +same object each time. Take them from the contract sheet, grounded in the SDK map's controller table +(`sdk-map.md`), not from a runtime `dir()` (`python-calling-endpoints`). Both classes are also exported under the fixed aliases `Client` and `AsyncClient`. **Prefer the full names** — a bare `Client` collides in any application that talks to more than one API. -The async class is a peer, not a variant: same accessors, same operation names, same parameters. Four -names differ: +The async class is a peer, not a variant: same accessors, same operation names, same parameter names. +What differs at the client: | | Sync | Async | |---|---|---| | Transport keyword | `custom_http_client=` | `custom_async_http_client=` | | Transport protocol | `HttpClient` | `AsyncHttpClient` | +| Hooks | `SdkHook` / `SdkHooksDict` | `AsyncSdkHook` / `AsyncSdkHooksDict` | +| Per-call options | `RequestOptions` | `AsyncRequestOptions` | | Shutdown | `client.close()` | `await client.aclose()` | | Scope form | `with` | `async with` | @@ -83,18 +83,11 @@ client = {Api}Client( ) ``` -`timeout` is validated at construction: non-positive (or NaN) raises `ValueError` immediately. -Credentials passed in dict form are validated by pydantic with `extra="forbid"`, so a misspelled key -raises `ValidationError` there and then. - -Two things are **not** validated, so a clean construction does not mean a working client: - -- **`base_url` is taken unchecked.** A typo or the wrong environment surfaces as a connection error or - a `401` at the first call. -- **Credentials are never exercised.** Managed-OAuth schemes fetch the token lazily on the first API - call, so wrong credentials construct happily and fail later, pointing at whichever operation ran - first. Every credentials keyword also defaults to `None`, and omitting it configures the client for - **no auth** — requests go out unauthenticated and the server answers `401`. +Construction validates `timeout` (`ValueError`) and dict-form credentials (`ValidationError`), but a +clean construction does not mean a working client: **`base_url` is taken unchecked** — a typo or the +wrong environment surfaces as a connection error or a `401` at the first call — and **credentials are +never exercised**: a managed-OAuth token is fetched on the first call, and an omitted credentials +keyword means no auth (`python-authentication`). ### Transport ownership and the close obligation @@ -120,23 +113,10 @@ is `aclose`, and calling `close()` on an async client is an `AttributeError`. ## Choosing the server / base URL -Server selection is **not** an environment enum. What the constructor accepts depends on what the spec -declares, in one of four shapes: - -| The API declares | Constructor keywords | -|---|---| -| one server, one environment | `base_url: str \| None = None` | -| one server, several environments | `environment` (a string literal alias, with a default), then `base_url` | -| several servers, one environment | `server_config: {Server}ConfigOrDict \| None = None` | -| several servers, several environments | `environment`, then `timeout`, then `server_config` | - -Omitting the server keyword falls through to the config's own default rather than writing `None` over -it — and **that default is whatever the spec listed first, which for many providers is a sandbox.** -Nothing announces it. Confirm the default from the contract sheet — the SDK map's *Servers & auth* -section names the base URL each arm resolves to — and pass the server explicitly in -every environment, production included. Server template variables live on the config class, so how you -reach them follows the arm above. **python-configuration-resilience** owns server / base-URL -configuration in full. +The server keyword takes one of four shapes, and **omitting it silently selects the API's +first-listed environment — often a sandbox.** Pass it explicitly in every environment, production +included; **python-configuration-resilience** owns the shapes, their nesting and server template +variables. ## Where the client lives @@ -184,48 +164,48 @@ thread-safe. The async client may be built outside a running loop, but from its ## Supplying your own transport The transport is a `Protocol` — a structural interface, not a base class. The sync one requires -`send(request) -> HttpResponse` and `close()`; the async one `send` and `aclose()`. There is one -request seam whatever the operation returns, a file included, so a transport that implements those -two satisfies the Protocol under `mypy --strict`: +`send(request) -> HttpResponse` and `close()`; the async one `send` and `aclose()`: ```python client = {Api}Client(custom_http_client=MyTransport(), {scheme}=...) ``` -This is the seam for **logging, tracing, metrics and tests** — the SDK ships no logging or middleware of -its own. Wrap the SDK's own transport rather than reimplementing HTTP: +This is the seam for **tests and for replacing the send itself**. Tracing, metrics and changing a +request or response go in a hook instead, and HTTP logging is built in +(`python-configuration-resilience` covers both), so wrap the transport only for what neither can do. +Wrap the SDK's own transport rather than reimplementing HTTP: ```python -class LoggingTransport: - def __init__(self, inner): self._inner = inner +class ReplayTransport: + def __init__(self, inner, replies): self._inner, self._replies = inner, replies def send(self, request): + if (reply := self._replies.get((request.method, request.url))) is not None: + return reply(request) # your own HttpResponse; nothing is sent, which no hook can do # The head only: the body is still on the socket, and the caller closes it. - response = self._inner.send(request) - log.info("%s %s -> %s", request.method, request.url, response.status_code) - return response + return self._inner.send(request) def close(self): self._inner.close() ``` -`send` returns an `HttpResponse` — `url`, `status_code`, lowercased `headers`, +`send` returns an `HttpResponse` — `method`, `url`, `status_code`, lowercased `headers`, `iter_bytes(chunk_size)`, `read()` and `close()` — whose body has **not** been read. That is true of every response, not just a download, so a wrapper must hand each one back unread; logging its size means consuming it, which leaves the caller nothing to read. `iter_bytes(None)` must yield each chunk as the network delivered it, holding nothing back — an event stream reads it that way, and a wrapper that re-chunks to a fixed size delays every small event. -Four obligations the protocol places on anything you supply, all silent when broken: **do not mutate +Five obligations the protocol places on anything you supply, all silent when broken: **do not mutate the incoming request** (it is frozen); **honour `request.timeout`** when set, falling back to your own -when it is `None`; **lowercase the response header names**, because callers look them up that way; and -**return once the head has arrived**, leaving the body for whoever reads it. - -Two consequences. First, **the `timeout=` you passed to the client no longer reaches the wire** — that -value only builds the client's *own default* transport, so set the timeout on the one you pass or you -have silently reverted to the underlying library's default. The per-call -`request_options={"timeout": ...}` is the exception: it travels on the request object and reaches any -transport honouring the obligation above. Second, **the client still closes it** — don't close it -yourself while the client is alive, and don't share one transport between two clients. +when it is `None`; **lowercase the response header names**, because callers look them up that way; +**return once the head has arrived**, leaving the body for whoever reads it; and **raise +`SdkConnectionError`** (`SdkTimeoutError` for a timeout) from `send` and from the response's reads when +no usable response arrives, chained `from` your library's exception (`python-configuration-resilience`). + +Two consequences. First, **the client's `timeout=` does not reach the wire** — set the timeout on your +transport, or you get the underlying library's default; a per-call `request_options` timeout still +arrives on the request (`python-configuration-resilience`). Second, **the client still closes it** — +don't close it yourself while the client is alive, and don't share one transport between two clients. ## Next diff --git a/plugins/plaid/skills/python/python-configuration-resilience/SKILL.md b/plugins/plaid/skills/python/python-configuration-resilience/SKILL.md index 05c86314..9d48e42e 100644 --- a/plugins/plaid/skills/python/python-configuration-resilience/SKILL.md +++ b/plugins/plaid/skills/python/python-configuration-resilience/SKILL.md @@ -1,6 +1,6 @@ --- name: python-configuration-resilience -description: Client configuration and resilience for an APIMatic-generated Python SDK — server and base-URL selection, the retry policy (on by default, off with `max_retries=0`) and what it will and will not repeat, what a timeout actually bounds, proxies and TLS, and request/response logging through the transport seam. Load before you configure or tune the client — the keyword names alone do not reveal what is handled for you and what is not. +description: Load before configuring or tuning an APIMatic-generated Python SDK client — choosing the server or base URL, retries, idempotency keys, timeouts, proxies and TLS, turning on request/response logging, or running your own code on every request with hooks. Covers the default retry policy and what it repeats, what a timeout bounds, the built-in HTTP logging (off by default; `logging_options`, `{ROOT_PACKAGE}_LOG` and a per-call `log_level`), request and response hooks (`hooks=` on the client and per call), and what the SDK leaves to you. --- # Configuration & resilience for an APIMatic Python SDK @@ -9,34 +9,26 @@ description: Client configuration and resilience for an APIMatic-generated Pytho > `{group}`, `{root_package}`) — replace it with the concrete identifier from the source. Configuration is not an options object here. Everything is either a **constructor keyword** on the -client (`python-client-initialization`), a field on a **config model** — the server config or -`RetryOptions` — or a **per-call `request_options`**. There is no third place to look. +client (`python-client-initialization`), a field on a **config model** — the server config, +`RetryOptions` or `LoggingOptions` — or a **per-call `request_options`**. There is no third place to look. ## What this SDK does not do for you -Read this before designing around a capability you assume exists. The generator emits **none** of the -following, so each is yours to build or deliberately do without: - -| Capability | Status | What to do instead | -|---|---|---| -| **Streaming — file responses** | a `FileResponse` arrives with its body unread and holds its connection until you consume it | `save_to` / `read` / `iter_bytes` (see `python-file-handling`) | -| **Streaming — SSE** | an `EventStream` arrives with its body unread; iterating yields each event's decoded data, and `timeout` bounds the gap between events | a `for` loop, or `with` for an early exit (see `python-event-streams`) | -| **Request/response logging** | none — no hook, no event | Wrap the transport; see below | -| **Circuit breaking, rate limiting** | none | Your own, around the call | -| **A mock/offline mode** | none | Point `base_url` at a mock server, or supply a fake transport (`python-testing`) | - -**Retries are on by default.** A client built without `retry_options` retries idempotent calls up to -three times; set `max_retries` to `0` to turn that off — see *Retries* below. +| Capability | What to do instead | +|---|---| +| **Circuit breaking, rate limiting** | Your own, around the call | +| **A mock/offline mode** | Point `base_url` at a mock server, or supply a fake transport (`python-testing`) | What the SDK *does* own: the request pipeline, auth application and token caching, response decoding, -error mapping, connection pooling, one timeout, and — once you turn it on — the retry loop. +error mapping, connection pooling, one timeout, the retry loop (on by default — see *Retries* below), +HTTP logging (silent until its logger is raised — see *Logging* below), and streamed file and +event-stream responses (`python-file-handling`, `python-event-streams`). ## Server and base-URL configuration -Server selection is **not** an environment enum. What the constructor accepts depends on what the -description declares, in one of four shapes — take yours from the contract sheet, grounded in the SDK -map's *Servers & auth* section, which names the environments and servers this SDK declares and so -settles which arm it is: +Server selection is **not** an environment enum. The constructor takes one of four shapes, set by what +the API declares — take yours from the contract sheet; the SDK map's *Servers & auth* section settles +which arm it is: | The API declares | Constructor keywords | |---|---| @@ -55,18 +47,15 @@ client = {Api}Client(environment="production", server_config={"{server}": {"prod wrong nesting raises `ValidationError` rather than being ignored.** With one environment each server's field holds `base_url` directly. With several, each server's field holds **one field per environment** and the `base_url` sits inside the environment's variant — passing `{"{server}": {"base_url": ...}}` -there fails with `Extra inputs are not permitted`. Take the nesting from the SDK map's *Servers & auth* -section rather than from this shape. +there fails with `Extra inputs are not permitted`. -Either way `server_config` is a pydantic model with a dict companion, coerced through `.coerce()`, -holding **one field per server the API declares**. Template variables sit beside `base_url` at +Either way `server_config` is a pydantic model with a dict companion, holding **one field per server +the API declares**. Template variables sit beside `base_url` at whichever level carries it. -**Omitting the server keyword takes the description's own default, and that default is whatever the -spec listed first — for many providers a sandbox.** Nothing announces it. A deployment that believes it -configured production and did not gets sandbox behaviour with production credentials, which fails auth -in a way that looks like a credentials problem, not an environment one. Pass the server explicitly in -every environment, production included. +**Omitting the server keyword silently selects the API's first-listed environment — often a +sandbox.** Production credentials against it fail like a credentials problem, not an environment one. +Pass the server explicitly in every environment, production included. **Server template variables are only reachable in the `server_config` arms.** They are fields on the config class, so where the constructor takes a `server_config` you set them there. Where it takes a @@ -88,10 +77,8 @@ the token fetch too. ## Retries — on by default -A client built without `retry_options` uses the **default policy** in the table below: a `GET`, `HEAD`, -`PUT` or `OPTIONS` call that meets a `408`, `429`, `500`, `502`, `503`, `504` or a dropped connection is -retried up to three times. -Retrying is configured by one options class, `RetryOptions` (from `{root_package}.core`), passed to the +A client built without `retry_options` uses the **default policy** in the table below. Retrying is +configured by one options class, `RetryOptions` (from `{root_package}.core`), passed to the client in any of four spellings: ```python @@ -140,11 +127,14 @@ A call is repeated only when **all** of these hold: A `401` is never in the default set; it invalidates the cached credential for the next call instead (`python-authentication`). Whatever you add to `status_codes_to_retry` is retried, so leave out statuses that cannot succeed a second time. When the last attempt fails, you see what a single attempt -would give you: the `ApiError`, the raw response's `Failure`, or the HTTP library's own exception. +would give you: the `ApiError`, the raw response's `Failure`, or `SdkConnectionError` with the HTTP +library's exception on `__cause__`. -A **custom transport** must raise `TransportError` (`from {root_package}.core import TransportError`) -for a failed send to be retried; the shipped `Httpx2Client` does. Anything else it raises reaches you on -the first attempt. +A **custom transport** must raise `SdkConnectionError` (`SdkTimeoutError` for a timeout) from `send` +for a failed send to be retried, naming the call as `method=request.method, url=safe_url(request.url)` +(`from {root_package}.core import SdkConnectionError, SdkTimeoutError, safe_url`). Its response's reads +must raise the same for a body they could not deliver. The shipped `Httpx2Client` does both. +Anything else it raises reaches you, unwrapped, on the first attempt. ### Per-call overrides @@ -159,18 +149,11 @@ client.{group}.{operation}(arg, request_options={"status_codes_to_retry": frozen and each of your attempts is a new call with a new idempotency key (below). If you need behaviour the options cannot express, turn the SDK's off for that call and own it. -**Only a write that was sent may have landed.** A write that timed out *after it was sent* may have -succeeded — a reset after the bytes reached the server is indistinguishable from one before. A write -that was never sent did not happen; `python-error-handling` names the four exceptions that mean so. - -**The retry arithmetic is not a ceiling.** `(max_retries + 1) × timeout` plus the waits between them -can be exceeded, because one attempt can outlast its timeout; see *Bounding a call*. - ### Making a write safe when you retry **Every operation other than a `GET` sends an `Idempotency-Key` header** — a UUID minted once per call, -unless the description declares its own header of that name, in which case that one is a keyword you -set. Within the SDK's retry loop every attempt carries the *same* key, which is what makes adding `POST` +unless the operation has its own `Idempotency-Key` header parameter, which is then a keyword you set. +Within the SDK's retry loop every attempt carries the *same* key, which is what makes adding `POST` to `http_methods_to_retry` safe **where the provider deduplicates on it**. A retry you write yourself is a new call and mints a new key — the provider sees two submissions. @@ -227,8 +210,7 @@ await asyncio.wait_for(async_client.{group}.{operation}(arg), budget) # the wh ``` - The value is **seconds, as a float**; the per-call option overrides the client's. -- It must be **> 0**. The constructor raises `ValueError` otherwise — and rejects NaN too, since the - guard is written `not timeout > 0`. +- It must be **> 0** (NaN is rejected too); the constructor raises `ValueError` otherwise. - The default is **30 seconds** per wait. - Under the default transport, one float sets connect, read, write and pool timeouts alike. To separate them (a short connect, a longer read), build your own transport with an @@ -240,7 +222,7 @@ keeps arriving slowly is never cut off, and each attempt — up to `max_retries longer than the number you set. This timeout firing is a transport failure and retries on the curve like any other; a `408` is the server's request timeout and sits in the default status set. -**If you supply `custom_http_client`, the client's `timeout=` no longer reaches the wire.** That value +**If you supply `custom_http_client`, the client's `timeout=` does not reach the wire.** That value only builds the SDK's *own* default transport. Set the timeout on the transport you pass, and honour `request.timeout` inside it (`python-client-initialization`). @@ -271,52 +253,70 @@ client = {Api}Client(custom_http_client=transport, {scheme}=...) - **`verify=False` disables certificate verification.** It is not a debugging convenience for anything carrying credentials; fix the trust store instead. -## Logging — wrap the transport +## Logging — off by default, through the standard logger -There is no logging hook and no event to subscribe to. The transport protocol is the seam: implement -it, delegate to the real one, and log around the call. +The SDK writes every HTTP exchange through Python's standard `logging` module under the +`{root_package}` logger and configures nothing itself: no handler, no level, never the root. Turn it +on as for any library, or from the environment for a run you cannot edit — `{ROOT_PACKAGE}_LOG` is the +package name upper-cased with `_LOG` appended: ```python -import logging, time -from {root_package}.core import Httpx2Client +import logging -log = logging.getLogger(__name__) +logging.basicConfig() # your handler; the root stays at WARNING +logging.getLogger("{root_package}").setLevel(logging.INFO) # INFO: the lines; DEBUG: the dumps too +``` -class LoggingTransport: - def __init__(self, inner): self._inner = inner +```bash +{ROOT_PACKAGE}_LOG=info python app.py # the request and response lines +{ROOT_PACKAGE}_LOG=debug python app.py # plus request headers, request body and response headers +``` - def send(self, request): - started = time.monotonic() - # The head only -- do not read the body here; the caller owns it. - response = self._inner.send(request) - log.info( - "%s %s -> %s (%.0f ms)", - request.method, request.url, response.status_code, - (time.monotonic() - started) * 1000, - ) - return response +| Level | What is written | +|---|---| +| `INFO` | `HTTP GET https://api.example.com/items?page=2` as each attempt is sent, and `HTTP GET … -> 200 (12 ms)` when its head arrives | +| `WARNING` | the response line for any status outside 2xx, and `HTTP GET … retrying in 1.0 s (attempt 1/3): 503 Service Unavailable` before each retry | +| `ERROR` | `HTTP GET … failed after 6210 ms: ConnectError` when a call ends in an exception, with the exception attached | +| `DEBUG` | the request headers, the request body and the response headers — each only when its flag below is on | - def close(self): self._inner.close() +The dumps are opt-in through `logging_options`, a dict or a `LoggingOptions` from `{root_package}.core`: +```python client = {Api}Client( - custom_http_client=LoggingTransport(Httpx2Client(timeout=10.0)), {scheme}=... + logging_options={"log_request_headers": True, "log_response_headers": True, "log_request_body": True}, + {scheme}=..., ) ``` -The async version is the same shape with `async def send` and `async def aclose`. Both members are -required, and they are the only two: one request seam serves every operation, a download included, -so there is no second method to forget. - -**The elapsed time above bounds the head, not the call.** `send` returns once the response head has -arrived, so a body still on the wire is not in that measurement — for a download it is barely in it -at all. Timing the whole exchange means timing where the body is consumed, which is the caller's -code, not this wrapper. - -**Log the method, URL and status — not headers or bodies.** The auth header carries a live credential -and bodies carry whatever the API moves; neither belongs in your logs or your traces. If you must -capture a body to debug, gate it behind a flag that is off by default and redact before writing. - -This same wrapper is where OpenTelemetry spans, metrics and request-id propagation belong. +| Option | Default | Effect | +|---|---|---| +| `log_request_headers` | `False` | the sent headers at DEBUG, masked | +| `log_response_headers` | `False` | the received headers at DEBUG, masked | +| `log_request_body` | `False` | the request body at DEBUG: its text when in memory, a description when streamed | +| `body_size_limit` | `32768` | bytes of a logged body kept before it is cut | +| `redaction_placeholder` | `"REDACTED"` | what a hidden value prints as | +| `unmask_headers` / `mask_headers` | none | header names to show, or hide, against the built-in safe list | +| `mask_keys` | 11 credential names | query and form keys whose values are always hidden; naming a set replaces the default | + +**What is never printed.** A header value is shown only when its name is on a built-in list of +standard headers that carry no credential, so `Authorization`, `Cookie` and API-key headers print +`REDACTED`. A query value is shown only for nine paging names (`cursor`, `limit`, `offset`, `page`, +`since`, `size` and three more), and a URL's user and password are dropped. A form field under +`mask_keys` is hidden. A JSON body is printed as sent, so turn `log_request_body` on only where its +content may be logged. A response body is never logged. + +**One call, quieter.** `request_options={"log_level": logging.WARNING}` is a floor: records below it +are not written for that call. It never turns on a record the client's options leave off. + +**`{ROOT_PACKAGE}_LOG` sets the level and, where no handler listens, adds a stderr one;** `debug` +also turns the three flags on. An application that configured logging keeps its own handlers and +format. The SDK never touches the `httpx2` or `httpcore2` loggers; if your root logger is at INFO, +raise those two to WARNING yourself, or httpx2 prints its own unmasked line per attempt. + +**Tracing, metrics and anything the records do not carry** go in a hook (*Hooks* below). The +transport seam stays for what a hook cannot do, replacing the send itself: wrap the SDK's own transport +and delegate (`python-client-initialization` shows the shape). The wrapper sees the head only — do not +read the body there — and the auth header is live, so never log it yourself. ### Verify on the wire (first run of any new call) @@ -324,22 +324,74 @@ On success the SDK returns the decoded body and nothing else — never the URL o parameter, a header you thought you set, or a query parameter that silently did not serialize produces **no in-band signal**; the only symptom is a `404`/`422` that looks like a provider problem. -Run the logging transport the first time you execute any new call, and check: +Run the first call under `{ROOT_PACKAGE}_LOG=debug`, and check in the request line and header dump: 1. the **method** matches the operation; 2. the **path** has no unsubstituted `{placeholder}`; 3. path segments carry **wire values** — an enum's string, not a Python member name; -4. the **query parameters** you set actually appear. +4. the **query parameter names** you set appear (a value outside the paging names prints `REDACTED`). + +Then drop the variable. + +## Hooks — your code on every attempt + +A hook is caller code the SDK runs on **every attempt** of every request, inside the retry loop. +`before_request(request, context)` runs after authentication and before the request line is logged, +and returns the request to send. `after_response(response, context)` runs after the response line and +the 401 check and before the retry decision, and returns the response the call acts on. + +```python +from dataclasses import replace + +from {root_package}.core import HookContext, HttpRequest, SdkHook + + +# new_traceparent() stands for your own tracer. +class Tracing(SdkHook): + def before_request(self, request: HttpRequest, context: HookContext) -> HttpRequest: + return replace(request, headers={**request.headers, "traceparent": new_traceparent()}) + + +def stamp(request: HttpRequest, context: HookContext) -> HttpRequest: + return replace(request, headers={**request.headers, "x-tenant": "acme"}) + + +client = {Api}Client(hooks=[Tracing()]) # every call +client.{group}.{operation}(arg, request_options={"hooks": {"on_request": [stamp]}}) # this call, after the client's +``` -Then gate the wrapper behind a debug flag. +- **Subclass `SdkHook` and override either method, or pass plain functions keyed by event**, + `{"on_request": [...], "on_response": [...]}` (an `SdkHooksDict`). One place takes one spelling, + never a mix; a hook that keeps state between the request and its response is a class. Any other key + is a type error and is ignored at run time. A request is frozen: return it, or a + `dataclasses.replace` of it. +- **A call's hooks are appended to the client's, never substituted**, so a call site cannot switch off + what the client installed. +- **The client keeps the hooks you pass, uncopied**, so a list changed after construction is read by + the next call. +- **The async client takes `AsyncSdkHook`**, whose two methods are `async def` and receive an + `AsyncHookContext` and an `AsyncHttpResponse`; its dict (`AsyncSdkHooksDict`) takes `async def` + functions under the same two keys, and a call's hooks go in `AsyncRequestOptions`. A hook of the + wrong flavour is a type error; nothing is checked at run time. +- **A hook runs once per attempt**, so it must be safe to run more than once, and `before_request` may + run with no `after_response` to follow when the send fails. +- **A hook that raises ends the call** with that exception, unwrapped. To have the attempt retried as a + failed send, raise `SdkConnectionError(message, method=context.method, url=safe_url(context.url))` + (both from `{root_package}.core`) **from `before_request`**; it is then retried under the same method + and retry-count rules as a transport failure. Raised from `after_response`, it ends the call like any + other exception. +- **On a token request an OAuth scheme makes, only the client's hooks run**, not the call's, and one + that raises reaches you as `AuthSchemeError` with its exception in `scheme_failures` + (`python-error-handling`); in an OR requirement the next configured scheme is tried first. +- **A hook that reads the response body must return a response that still carries it**, and one that + returns a different response must close the original or keep it inside. +- **Hooks see the credential in clear**, on API calls and on the token requests an OAuth scheme makes. + Never log `request.headers` from one. ## Connection pooling -The client holds one pooled transport. Reuse the client and close it on shutdown; a client per call -pays a fresh TCP and TLS handshake every time, and under managed auth a fresh token fetch as well. -Under forking servers (Gunicorn, uWSGI, Celery prefork), construct it **after** the fork — a pool -inherited across `fork()` is shared by processes that each believe they own it, which surfaces as -intermittent, unexplainable connection errors. See `python-client-initialization`. +The client holds one pooled transport. Reuse one client and close it on shutdown; under forking +servers construct it **after** the fork (`python-client-initialization`). ## Next diff --git a/plugins/plaid/skills/python/python-error-handling/SKILL.md b/plugins/plaid/skills/python/python-error-handling/SKILL.md index 02bf6bbe..b1cc97be 100644 --- a/plugins/plaid/skills/python/python-error-handling/SKILL.md +++ b/plugins/plaid/skills/python/python-error-handling/SKILL.md @@ -1,6 +1,6 @@ --- name: python-error-handling -description: Error and exception handling for an APIMatic-generated Python SDK — load before writing any try/except around an SDK call, an exception-translation layer, or error middleware. Covers the single ApiError type and its per-operation error union, narrowing with isinstance or match, the failures that are NOT ApiError and reach your boundary unmatched, and the traps that make an otherwise reasonable except ladder silently wrong. +description: Load before writing any try/except around an APIMatic-generated Python SDK call, an exception-translation layer or error middleware. Covers the SdkError family — ApiError and its per-operation error union, ResponseDecodeError, SdkConnectionError / SdkTimeoutError and AuthSchemeError — narrowing with isinstance or match, and with_raw_response. --- # Error handling for an APIMatic Python SDK @@ -10,41 +10,49 @@ description: Error and exception handling for an APIMatic-generated Python SDK > source. Operations **raise on non-2xx responses** by default (for a non-raising alternative, see the -**`with_raw_response`** section below). The raised type is always `ApiError` — there is exactly one -exception class in these SDKs, and the variation lives entirely in the payload it carries. +**`with_raw_response`** section below). Everything the SDK raises for a call derives from one root, +`SdkError`, so one `except SdkError` covers any number of calls: + +| Exception | Raised when | Attributes beyond `method`, `url` | +|---|---|---| +| `ApiError[E]` | an error status (parsed mode only) | `error`, `status_code`, `headers` | +| `ResponseDecodeError` | a body, 2xx or documented error, its declared type rejects | `status_code`, `headers` | +| `SdkConnectionError` | no usable response: the send failed after the retries, or the body read failed | — | +| `SdkTimeoutError` (a `SdkConnectionError`) | the connection failure that was a timeout | `timeout` | +| `AuthSchemeError` | a credential that could not be applied | `scheme_failures` | + +Every member names the call (`e.method`, and `e.url`, the path rendered with no query) and keeps what +caused it, as the library or pydantic raised it, on `e.__cause__`. `ApiError` and `ResponseDecodeError` +are **siblings**: `except ApiError` never catches a 2xx that broke its contract, and +`except (ApiError, ResponseDecodeError)` spells "the server answered". ```python -from {root_package}.core import ApiError, RawError +from {root_package}.core import ApiError, RawError, SdkError ``` `ApiError` is generic in its payload (`ApiError[E]`), but you catch it **unparametrized**. A runtime `except` clause cannot discriminate a type parameter, so `except ApiError` catches every operation's -failure and you narrow on `e.error` afterwards. This is the opposite of a generator that encodes the -error type into the exception class: here the compiler-equivalent check happens at the `isinstance`, -not at the `except`. +failure and you narrow on `e.error` afterwards. ## Catch the exception -`ApiError` carries three things: +`ApiError` carries three things beyond the call: | Attribute | Type | Notes | |---|---|---| | `e.error` | the operation's error union | The decoded body. **This is the information.** | -| `e.status_code` | `int` | The status that failed. | +| `e.status_code` | `int` | The status that failed — set whichever arm of the union you got. | | `e.headers` | `Mapping[str, str]` | The response head, keys lowercased. | -**`str(e)` and `repr(e)` deliberately omit the body.** They render as `HTTP 422: {TypedError}` — the -status and the payload's *type name* only, so response bodies stay out of logs and tracebacks by -default. That is a sound default and a trap: a handler that logs `str(e)` and nothing else records -that something failed and discards every diagnostic. Read `.error` explicitly and log the fields you -choose. - -The status is **always** on `e.status_code`, whichever arm of the union you got — you never have to -choose between a typed body and knowing the status. +**`str(e)` and `repr(e)` deliberately omit the body**, so response bodies stay out of logs and +tracebacks: `str(e)` is the call and the status, `GET https://host/path returned 404 (Not Found)`, and +`repr(e)` the status and the payload's *type name*. A +handler that logs `str(e)` and nothing else discards every diagnostic; read `.error` and log the +fields you choose. ### Which error union does an operation carry? -Every operation's union is generated into its own module, `{root_package}/errors/{operation}_error.py`, +Every operation's union is declared in its own module, `{root_package}/errors/{operation}_error.py`, as a type alias: ```python @@ -56,16 +64,14 @@ Four places give you that alias, in order of preference: 1. **The contract sheet** — it lists the union per operation. 2. **The operation's map block** (`map/operations/{group}.md`) — its **Error** line names the alias and its case, and its **Error arms** bullet lists each arm *with the HTTP statuses it maps from*. - This is where the sheet's row should have come from. 3. **The operation's docstring**, whose `Raises:` section ends with the union verbatim: `` `error` is `{TypedError} | RawError`. `` 4. **The error module itself**, whose `map` is a `match` on `status_code` naming the schema each status decodes to. -**`RawError` is always the last arm.** The generator emits it unconditionally as the catch-all, so -every operation can hand you a `RawError` for any status it does not document — there is no operation -whose failure is guaranteed typed. An operation that documents *no* error schema has no error module -at all and always yields `RawError`. +**`RawError` is always the last arm**: any status the operation does not document yields `RawError`, +so no operation's failure is guaranteed typed. An operation that documents *no* error schema has no +error module at all and always yields `RawError`. ### Narrowing the union @@ -73,16 +79,13 @@ at all and always yields `RawError`. > per-operation error unions, or an operation whose alias is `RawError` alone (Case B), has nothing to > narrow — `e.error` is always `RawError` there. Skip to *Result-style alternative* for those. -**The typed arm is not one type across the API, and assuming it is is the mistake that costs the -afternoon.** A description that declares a different error schema per tag gets a different model per -tag, so a check written against one operation's arm silently fails on another's — those failures fall -through to the `RawError` branch and lose every field they actually carried. Take the arm from the -contract sheet per operation — the map's **Error arms** bullet is per-operation for exactly this -reason — never reuse one from a sibling call. +**The typed arm differs per operation.** A check written against one operation's arm silently falls +through to the `RawError` branch on another's and loses every field it carried, so take each +operation's arms from its own sheet row or the map's per-operation **Error arms** bullet — never from +a sibling call. An operation can also declare **more than one** typed arm — one per documented status or status -*range* (`4XX`, `5XX` are legal), so a union may read `{TypedError1} | {TypedError2} | RawError`. -Handle each arm you declared. +*range* (`4XX`, `5XX`), so a union may read `{TypedError1} | {TypedError2} | RawError`. Handle each. Narrow with `match` or `isinstance` — a type checker understands both — on a class arm only; a `oneOf` alias is not a class either, so match its variants. After narrowing the class arms, what remains is @@ -120,8 +123,9 @@ undocumented case — so prefer `text()` for logging unless you know better. ## Result-style alternative — `with_raw_response` (no raising) -Every operation has a raw peer reached through `with_raw_response`, which returns the outcome instead -of raising: +Every operation's raw peer, reached through `with_raw_response`, returns the outcome instead of +raising — **2xx is `Success`, everything else is `Failure`**, both carrying `.status_code` and +`.headers` (`python-calling-endpoints` has the mechanics): ```python from {root_package}.core import Success, Failure @@ -133,54 +137,41 @@ match client.{Group}.with_raw_response.{Operation}(...): ... # 'err' is the same union as the raising path ``` -`Success` and `Failure` are frozen dataclasses, so pattern matching needs nothing added; both carry -`.status_code` and `.headers` as fields of their own. On the **success** path this mode is the only -way to read either — except for a file response, which carries its own `headers` on the parsed path. -On the failure path `ApiError` already carries both, so the choice there is about whether you want an -exception, not about what you can see. `unwrap(result)` (from `{root_package}.core`) collapses either -back to the raising behaviour — in fact every parsed method is literally `unwrap(...)` around its raw peer. - -The split is mechanical: **2xx is `Success`, everything else is `Failure`.** No nuance, no per-status -judgement. Use this variant when you need the status code or headers on the *success* path, or when a -non-2xx is an expected outcome rather than an exception. - -**This mode is not exception-free.** See the next section: a decode failure raises in both modes, and -so does a failed token fetch. Mapping a `Failure` to your own error uses the same function as the -raising path — see *Guarding every call site*. +On the failure path `ApiError` already carries the status and headers, so choosing this mode there is +about whether you want an exception — use it when a non-2xx is an expected outcome. **It is not +exception-free**: the rest of the family — a decode, connection or authentication failure — raises in +both modes (next section). Map a +`Failure` through the same function as the raising path — see *Guarding every call site*. ## The failures that are not `ApiError` -Each of these reaches your boundary without matching `except ApiError`. - -### Decode failures — and they bypass *both* response modes +Each of these reaches your boundary without matching `except ApiError`, and each is an `SdkError`. -If a body does not deserialize, decoding raises `pydantic.ValidationError` (a subclass of -`ValueError`), or a plain `ValueError` when the body is not JSON at all. The pipeline states the rule -outright: *a deserialization failure is not an API error, so it propagates in both response modes -rather than becoming a failure.* `with_raw_response` does **not** convert it into a `Failure`. +### Decode failures — `ResponseDecodeError`, in *both* response modes -It arrives from two directions that mean opposite things: +If a body does not deserialize, the call raises `ResponseDecodeError` — pydantic's `ValidationError`, +or the parser's `ValueError` for a body that is not JSON at all, is its `__cause__` — in both response +modes: `with_raw_response` does **not** convert it into a `Failure`. Its `status_code` tells apart two +cases that mean opposite things: - **A 2xx whose body drifted** → the call may well have *succeeded* server-side and you cannot read - the result. The outcome is **unknown**. For a write, re-read state rather than retrying blindly. + the result. The outcome is **unknown** (a 5xx at your boundary). For a write, re-read state rather + than retrying blindly. - **A non-2xx whose body does not match the declared error schema** → the request was **rejected**; - only the detail was lost. Retrying is pointless, since it can never succeed. - -Mapping both to a 5xx is wrong half the time. At minimum, do not report a deterministic rejection as -an outage. + only the detail was lost. Retrying can never succeed, so do not report it as an outage — a 5xx tells + a retrying caller to keep retrying. -**On the success path this fires far less often than you would expect, and the gap it leaves is -worse.** Models are generated with required members only where the description marks them required — -which is frequently nowhere — and every other member defaults to `UNSET`. A response missing a field -therefore validates cleanly: +**On the success path a missing member does not raise.** Only a model's bare-annotated members are +required — on a response model often none — and every other member defaults to `UNSET`, so a response +missing a field validates cleanly: ```python value = client.{Group}.{Operation}(...) # 200 with a truncated or empty body value.{member} # UNSET — not an exception, not None ``` -A `ValidationError` on a 2xx means a *type* mismatch or a non-JSON body, not an absent field. So the -guard belongs somewhere else than you would place it by habit: +A `ResponseDecodeError` on a 2xx means a *type* mismatch or a non-JSON body, not an absent field. Guard the +members you depend on, immediately after every call that matters: ```python value = client.{Group}.{Operation}(...) @@ -188,24 +179,15 @@ if value.{member} is UNSET: raise ProviderError(502, "{Operation} returned no {member}", outcome_unknown=True) ``` -**Assert on the members you depend on, immediately after every call that matters.** For a write, an -absent identifier has the same "outcome unknown" character as a decode failure — the call may have -taken effect and you cannot name what it created. Nothing in the SDK does this for you. - -### Transport failures — the HTTP library's exceptions, unwrapped - -The SDK does **not** wrap its transport's exceptions where you catch them. The protocol says -implementations *may raise their underlying library's exceptions*; the shipped transport reports a -failed send to the retry loop, and when the last attempt fails the pipeline raises the library's own -exception. So connection refused, DNS failure, TLS error, dropped socket and timeout all reach you as -`httpx2` exceptions. +For a write, an absent identifier is "outcome unknown" like a decode failure — the call may have taken +effect and you cannot name what it created. Nothing in the SDK does this for you. -⚠ **`httpx2.HTTPError` is the base class of every one of them, timeouts included.** A lone -`except httpx2.HTTPError` arm therefore catches connection-refused and read-timeout together and gives -them one outcome — and those are opposite facts. +### Connection failures — `SdkConnectionError`, the library's exception on `__cause__` -**Which transport failures reached the server, and which did not.** This is a property of the -exception class, not a judgement call: +Connection refused, DNS failure, TLS error, dropped socket and timeouts reach you — after the last +attempt — as `SdkConnectionError`, with the `httpx2` exception on `__cause__`; a timeout is its leaf +`SdkTimeoutError`, whose `timeout` is the window that elapsed. Whether the request reached the server +is a property of the **cause's** class: | exception | did the request reach the server? | outcome | | --- | --- | --- | @@ -217,100 +199,104 @@ exception class, not a judgement call: | `httpx2.WriteTimeout` | **maybe** — sending was interrupted mid-body | **unknown** | | `httpx2.RemoteProtocolError` | **maybe** — the peer closed after the request went out | **unknown** | -`ConnectTimeout`, `PoolTimeout` and `ReadTimeout` are all `httpx2.TimeoutException` and they fall on -**opposite sides of this table**, so splitting on `TimeoutException` does not split on the thing that -matters. Split on whether the request was ever sent: +`ConnectTimeout`, `PoolTimeout` and `ReadTimeout` all arrive as `SdkTimeoutError` yet fall on +**opposite sides of this table**, so `except SdkTimeoutError` does not split them — test `__cause__`: ```python import httpx2 +from {root_package}.core import SdkConnectionError -except (httpx2.ConnectError, httpx2.ConnectTimeout, httpx2.PoolTimeout, httpx2.ProxyError) as e: - # Nothing reached the provider. Fail the operation outright; there is nothing to reconcile. - ... -except httpx2.RequestError as e: - # It may have landed. Record the outcome as UNKNOWN and reconcile before any retry. - ... -``` +NEVER_SENT = (httpx2.ConnectError, httpx2.ConnectTimeout, httpx2.PoolTimeout, httpx2.ProxyError) -Catch `httpx2.RequestError`, not `httpx2.HTTPError`, in that second arm. `HTTPError` is also the base of -`HTTPStatusError` — what `raise_for_status()` raises — and that one means a **complete response -arrived**, so sweeping it into the unknown-outcome arm mislabels the one case that is fully known. - -⚠ **`PoolTimeout` is the one to get right.** It is the characteristic failure of a saturated sync -client, which is the setup this skill recommends — so it arrives *in bulk*, exactly when the system is -already under strain. Marking it unknown floods reconciliation with work at the worst moment, for -requests that were never sent. - -**Only the second arm has an unknown outcome.** Marking a refused connection "unknown" is not the -cautious default: it schedules reconciliation for an event that provably did not happen, and it -trains the caller to distrust a failure that is in fact definitive. +except SdkConnectionError as e: + if isinstance(e.__cause__, NEVER_SENT): + ... # Nothing reached the provider. Fail the operation outright; there is nothing to reconcile. + else: + ... # It may have landed. Record the outcome as UNKNOWN and reconcile before any retry. +``` -Note the coupling: your error boundary imports the transport's exception types because the SDK's -transport does. If you supply a custom transport (`python-client-initialization`), it is *your* -transport's exceptions that arrive and this clause needs revisiting. +A `__cause__` of `None` (a custom transport that chained nothing) falls to the unknown arm, the safe +one. `PoolTimeout`, the saturated-pool failure that arrives in bulk under load, was never sent; +marking it unknown floods reconciliation with requests that never left. A custom transport +(`python-client-initialization`) raises this family too, with *its* library's classes on `__cause__`, +so `NEVER_SENT` needs those. ### A streamed download moves the failure out of the call -An operation that returns a file is one place where the call returning successfully does not mean -the transfer succeeded. The pipeline yields as soon as the response *head* arrives; the body is still -on the socket. So a connection dropped mid-transfer raises out of `read()`, `iter_bytes()` or -`save_to(...)` — not out of the call — and a `try` wrapped around the call alone catches nothing: +A file response returns as soon as the *head* arrives, so its status and headers are final, but a +connection dropped mid-transfer raises out of `read()`, `iter_bytes()` or `save_to(...)` — not out of +the call — and a `try` wrapped around the call alone catches nothing (`python-file-handling` has the +lifecycle, async included): ```python f = client.{group}.{operation}(...) # returns on the head; nothing is downloaded yet try: - f.save_to("out.bin") # the transport failure surfaces here -except httpx2.RequestError: + f.save_to("out.bin") # the connection failure surfaces here +except SdkConnectionError: ... ``` -Three consequences. The status code and headers are trustworthy before the body is — a `Failure` on a -streamed call is a real outcome, not a guess. A partial write is possible, which is why `save_to` -stages through `.part` and renames only on success, so a failed download never appears under the -final name. And `request_options={"timeout": ...}` bounds **each read**, not the call as a whole, so a -stalled transfer raises rather than hanging. The same holds on the async client, with the failure -raising out of the awaited consumer. `python-calling-endpoints` has the lifecycle itself. - ### An event stream raises from the loop An operation that returns an event stream succeeds as soon as the head arrives, like a download. What -follows raises from the **loop**: a frame the event type rejects raises pydantic's `ValidationError` -after the stream has closed, an oversized event or bad UTF-8 raises `ValueError`, and a dropped or -stalled connection raises `httpx2.RequestError` — there is no SSE exception class. +follows raises from the **loop**: a frame the event type rejects, an oversized event or bad UTF-8 +raises `ResponseDecodeError` after the stream has closed, and a dropped or stalled connection raises +`SdkConnectionError` — there is no SSE-specific class. `python-event-streams` has the full table. -### Authentication failures wear the same exception +### A paginator raises from the loop + +A paginated operation sends nothing at the call — it returns a `Paginator` — so its failures arrive +while iterating. Parsed item iteration raises `ApiError` at the failed page, after every item before +it: **wrap the `for`, not the call**. + +```python +try: + for item in client.{group}.{operation}(...): + ... +except ApiError as e: + ... +``` + +Raw mode never raises for an API error. Iterating the raw paginator for items yields the items of +every successful page and ends at the failed one; `iter_pages()` yields each page's `ApiResult`, and +a `Failure` is the last one it yields, so the walk ends there with the error body and no exception. +`ResponseDecodeError` and `SdkConnectionError` still raise from either loop, and a link walk raises +`ValueError` on a next link to a different origin. + +### Authentication failures — `AuthSchemeError` -A failed token fetch raises `ApiError` — but its payload is `OAuthProviderError | RawError`, **not** -the operation's union. Two consequences: +A credential that could not be applied raises `AuthSchemeError`, naming **your** call, not the token +endpoint's, so an `except ApiError` around the call never catches a token endpoint's `401`. The +scheme's own failure is `__cause__`, and every failure is in `scheme_failures`: + +| `e.__cause__` | What happened | +|---|---| +| `ApiError` (its `error` a `RawError`) | the token endpoint refused; the RFC 6749 `error` code is in `e.__cause__.error.json()` | +| `SdkConnectionError` | the token endpoint could not be reached | +| `ResponseDecodeError` | the token endpoint answered with a body it should not have | +| `AnySchemesError` | every configured member of an OR requirement raised | +| anything else | your own scheme or token source raised it, or a client hook did on the token request (`python-configuration-resilience`) | + +Two consequences: - It surfaces out of the **operation call**, because the token is fetched lazily on first use. The traceback points at whichever operation ran first, not at the client you configured. - It raises in `with_raw_response` mode too, because the fetch happens while the request is being built, before anything is sent. -Check it **first** in the ladder — nothing was ever sent, so it is a configuration fault, not a -rejection: - -```python -from {root_package}.core import OAuthProviderError - -except ApiError as e: - if isinstance(e.error, OAuthProviderError): - raise ProviderError(502, "provider refused our credentials") from e - ... -``` +Nothing was ever sent, so it is a configuration fault, not a rejection. The `except AuthSchemeError` +arm below maps it that way. -**A missing credential raises nothing at all.** The SDK never refuses to send a request because a -credential is absent — an unconfigured scheme contributes nothing and the request goes out -unauthenticated, so the server decides. With composite (AND/OR) security this holds too: a partial -set is applied as-is rather than withheld. There is no local "auth could not be satisfied" exception -to catch; you get a `401` from the provider instead. See `python-authentication`. +**A missing credential raises nothing**: the request goes out without it and the provider answers, +typically `401` (`python-authentication`). ### Your own mistakes -`ValidationError` from constructing a model with a missing or wrong-typed member, and `TypeError` from -passing a positional argument to a keyword-only signature, are programming errors. Let them fail +`ValidationError` from constructing a model with a missing or wrong-typed member, `TypeError` from +passing a positional argument to a keyword-only signature, and the `ValueError` for a value the SDK +refuses before sending (a path value its type rejects) are programming errors. None is an +`SdkError`. Let them fail loudly in development; do not let a production ladder swallow them. ## Guarding every call site @@ -321,8 +307,8 @@ job, a health check). A connection failure during a read fails just as hard as o call left unguarded next to one that is guarded is the one that breaks. **Convert failures to your own type in one place**, so the rest of the code has a single failure type -rather than four unrelated ones. The type is yours — the SDK's only exception class is `ApiError`; -transport and decode failures arrive as library exceptions, below. If your codebase already has an +rather than several. The type is yours: the SDK's family says *what happened*, and yours carries *what +your boundary answers*. If your codebase already has an error type, give it these two fields instead of adding another: ```python @@ -338,14 +324,15 @@ arms whichever way you called (below): ```python import httpx2 -from pydantic import ValidationError -from {root_package}.core import ApiError, OAuthProviderError +from {root_package}.core import ApiError, AuthSchemeError, ResponseDecodeError, SdkConnectionError from {root_package}.models import {TypedError} +NEVER_SENT = (httpx2.ConnectError, httpx2.ConnectTimeout, httpx2.PoolTimeout, httpx2.ProxyError) + def provider_error(status, error) -> ProviderError: match (status, error): # OUR credentials or OUR quota: the caller did nothing wrong and cannot fix it. - case (401 | 403, _) | (_, OAuthProviderError()): + case (401 | 403, _): return ProviderError(502, "provider refused our credentials") case (429, _): return ProviderError(503, "rate-limited") @@ -366,14 +353,18 @@ try: except ApiError as e: raise provider_error(e.status_code, e.error) from e -except ValidationError as e: - raise ProviderError(502, "unreadable response", outcome_unknown=True) from e # do NOT assume failure +except AuthSchemeError as e: + raise ProviderError(502, "provider refused our credentials") from e # never sent: configuration -except (httpx2.ConnectError, httpx2.ConnectTimeout, httpx2.PoolTimeout, httpx2.ProxyError) as e: - raise ProviderError(502, "Never sent.", outcome_unknown=False) from e # KNOWN: nothing happened +except ResponseDecodeError as e: + if 200 <= e.status_code < 300: + raise ProviderError(502, "unreadable response", outcome_unknown=True) from e # do NOT assume failure + raise provider_error(e.status_code, None) from e # rejected; detail lost -except httpx2.RequestError as e: - raise ProviderError(504, "No response.", outcome_unknown=True) from e # UNKNOWN: may have landed +except SdkConnectionError as e: + if isinstance(e.__cause__, NEVER_SENT): + raise ProviderError(502, "Never sent.", outcome_unknown=False) from e # KNOWN: nothing happened + raise ProviderError(504, "No response.", outcome_unknown=True) from e # UNKNOWN: may have landed ``` **Your own time limit needs its own arm.** In async code, an `asyncio.wait_for` around the call raises @@ -381,8 +372,8 @@ except httpx2.RequestError as e: `ProviderError(504, "No response.", outcome_unknown=True)`. **The raw variant maps through the same function.** A `Failure` is a value, not an exception, so there -is nothing to chain `from`; and a refused token fetch still raises `ApiError` here (it happens before -the request is sent), so the `except ApiError` above stays around the raw call too: +is nothing to chain `from`; and a refused token fetch still raises `AuthSchemeError` here (it happens +before the request is sent), so the `except` arms above stay around the raw call too: ```python match client.{Group}.with_raw_response.{Operation}(...): @@ -392,10 +383,6 @@ match client.{Group}.with_raw_response.{Operation}(...): raise provider_error(status, err) ``` -Note the last two arms, and their order: the narrow tuple must come **first**, because -`httpx2.RequestError` is its base class and would otherwise swallow it. The two are different facts, -and a single `except httpx2.HTTPError` merges them. - ⚠ **Two arms raising the same class with the same values is not a split.** The distinction has to reach something that acts on it, or it is a comment. Note that both arms above raise the **same class** on purpose — what differs is the **values they pass**, so there is no way to write either @@ -412,26 +399,9 @@ except ProviderError as e: return error_response(e.status_code, safe_message) # 502 never sent · 504 outcome unknown ``` -**Then write the test that tells the two apart.** This is what decides whether the split is real. The -check is not "are there two arms" but **"does one assertion pass for both inputs?"** — if it does, the -distinction is not real, however well the production branch reads: +Test that the two inputs yield different `(status_code, outcome_unknown)` (`python-testing`). -```python -def test_unsent_is_not_the_same_failure_as_unknown(): - unsent = failure_from(httpx2.ConnectError("refused")) # never left the process - unknown = failure_from(httpx2.ReadTimeout("no reply")) # may have landed - - assert (unsent.status_code, unsent.outcome_unknown) == (502, False) - assert (unknown.status_code, unknown.outcome_unknown) == (504, True) - assert unsent.status_code != unknown.status_code # the caller can tell them apart - assert reconciled() == [unknown.reference] # and only one reconciles -``` - -Two tests asserting the *same* exception for a refused connection and a read timeout is this defect -wearing a passing suite. - -Always `raise ... from e`. Losing `__cause__` costs you the traceback that names which of the four -paths you were on. +Always `raise ... from e`. Losing `__cause__` costs you the traceback that names which path you were on. ## Presenting failures at your boundary @@ -445,34 +415,21 @@ unknown error has no meaningful client status and belongs at 5xx. Collapsing eve blanket status discards the only signal separating "you sent something invalid" from "the provider is down". -**Not every provider failure is the caller's fault.** A `401`/`403` means *your* credentials are wrong, -and a `429` means *your* quota is spent — passing either straight through tells the caller they are -unauthenticated or throttled when they are neither. Those belong at 5xx (the `match` above), and so -does the default arm. - -**An unreadable body is two cases, not one — decide which before you map it.** An unreadable -*success* body is genuinely unknown: 5xx. An unreadable *error* body is not — the provider rejected -the request and only the detail was lost, so answering 5xx tells a retrying caller to keep retrying -something that can never succeed. - **Never map a parse failure onto a domain absence.** "I could not read the answer" is not "the provider said no". On a lookup both leave you without a record, but only one is a fact — and where a lookup gates a create, conflating them turns a corrupt response into a spurious create. If a miss is signalled by an empty body, match on *empty*, not on *unparseable*. -**Never surface `str(e)` or a traceback to your caller.** For an SDK exception the string is only -`HTTP 422: {TypedError}`, so it is useless as well as leaky; a `ValidationError` embeds pydantic type -and field-path detail. Log the detail, return a message you wrote. +**Never surface `str(e)` or a traceback to your caller** — an `SdkError`'s message names the provider's +URL, and its `__cause__` (a pydantic `ValidationError`, an `httpx2` error) embeds field-path and host +detail. Log the detail, return a message you wrote. ## Notes -- **Retries are on by default.** A retryable status or transport failure surfaces only after the last - attempt, and the exception you catch is the same one a single attempt would raise. With `max_retries` - set to `0` nothing is resent. See `python-configuration-resilience`. -- **A `401` invalidates the cached credential but does not retry the request.** Your code sees one - `401` (your boundary answers it as `502`), and the *next* call obtains - a fresh token. Do not read a single 401 as a permanent credential failure. -- `ApiError` implements `__reduce__`, so it pickles — it survives crossing a process boundary (a - Celery result, a multiprocessing queue) with its payload intact. -- `e.headers` has **lowercased keys**, guaranteed by the transport contract — look up - `"x-request-id"`, never `"X-Request-Id"`. +- **Retries are on by default**; what you catch is the last attempt's failure, the same one a single + attempt would raise (`python-configuration-resilience`). +- **A `401` drops the cached token without retrying the call** (`python-authentication`): your code + sees one `401` — your boundary answers `502` — and the next call fetches a fresh token. +- Every `SdkError` pickles, so it survives crossing a process boundary (a Celery result, a + multiprocessing queue) with its payload intact; `copy` and `deepcopy` work too. +- Your own cancellation (`KeyboardInterrupt`, `asyncio.CancelledError`) is never wrapped. diff --git a/plugins/plaid/skills/python/python-event-streams/SKILL.md b/plugins/plaid/skills/python/python-event-streams/SKILL.md index 90ce063f..9ff44026 100644 --- a/plugins/plaid/skills/python/python-event-streams/SKILL.md +++ b/plugins/plaid/skills/python/python-event-streams/SKILL.md @@ -1,6 +1,6 @@ --- name: python-event-streams -description: Consuming a server-sent-events (text/event-stream) operation on an APIMatic-generated Python SDK — what EventStream[T] / AsyncEventStream[T] yields, how the loop must end so the connection is released, narrowing a union of event types, what raises and when (there is no SSE exception class), the silent failures, and bounding the wait. Load before writing the loop over an operation that returns an event stream, in addition to `python-calling-endpoints`. +description: Load before writing the loop over an APIMatic-generated Python SDK operation that returns a server-sent-events (text/event-stream) stream, together with `python-calling-endpoints`. Covers what EventStream[T] / AsyncEventStream[T] yields, ending the loop so the connection is released, narrowing event unions, what raises from the loop, and bounding the wait. --- # Event streams on an APIMatic Python SDK @@ -74,17 +74,16 @@ does **not** — it leaves `T | UnsetType`. | What failed | Parsed call | `with_raw_response` | |---|---|---| | a non-2xx status (the head) | raises `ApiError` at the call | returns `Failure` — no raise | -| a frame the event type rejects | raises pydantic's `ValidationError` from the loop, **after** the stream closed | same | -| an event over 1 MiB, or bad UTF-8 | raises `ValueError` / `UnicodeDecodeError` from the loop | same | -| the wire stalls | raises `httpx2.ReadTimeout` from the loop | same | -| the connection drops mid-stream | raises an `httpx2.RequestError` subclass from the loop, such as `RemoteProtocolError` or `ReadError` | same | +| a frame the event type rejects | raises `ResponseDecodeError` from the loop, **after** the stream closed; pydantic's `ValidationError` on `__cause__` | same | +| an event over 1 MiB, or bad UTF-8 | raises `ResponseDecodeError` from the loop; the `ValueError` / `UnicodeDecodeError` on `__cause__` | same | +| the wire stalls | raises `SdkTimeoutError` from the loop; `httpx2.ReadTimeout` on `__cause__` | same | +| the connection drops mid-stream | raises `SdkConnectionError` from the loop; an `httpx2` error such as `RemoteProtocolError` or `ReadError` on `__cause__` | same | | **the connection closes a body with no `Content-Length` that is not chunked** | **nothing — the loop ends early** | same | | **the body is not an event stream** | **nothing — the loop ends with zero events** | same | -**There is no SSE exception class.** Everything the loop raises for a bad body is already a -`ValueError`, so one `except ValueError` covers the family. A stalled or dropped connection is not a -bad body: it raises `httpx2.RequestError` (`ReadTimeout` included), so catch that too. Put both -boundaries around the **loop**, not only the call — the call returns as soon as the head arrives. +**There is no SSE-specific exception class.** A bad body is `ResponseDecodeError` and a stalled or +dropped connection `SdkConnectionError`, both `SdkError`, so one `except SdkError` covers the loop. Put +the boundary around the **loop**, not only the call — the call returns as soon as the head arrives. The last row is a known gap: the SDK does not check `Content-Type`, so a 200 carrying a proxy's HTML page or a buffered JSON body parses as a stream of zero events and ends quietly. If a stream yields diff --git a/plugins/plaid/skills/python/python-file-handling/SKILL.md b/plugins/plaid/skills/python/python-file-handling/SKILL.md index df25a80e..eb832423 100644 --- a/plugins/plaid/skills/python/python-file-handling/SKILL.md +++ b/plugins/plaid/skills/python/python-file-handling/SKILL.md @@ -1,6 +1,6 @@ --- name: python-file-handling -description: Sending and receiving files with an APIMatic-generated Python SDK — which arm of the upload alias to hand an endpoint and what each one costs in memory, re-sendability and ownership, the three behaviours that differ between a multipart part and a raw body, when a body goes out chunked rather than sized, overriding a filename or media type, and consuming a streamed file response without leaking its connection. Load before passing a file to an operation or consuming one it returns, in addition to `python-calling-endpoints`. +description: Load before passing a file to an APIMatic-generated Python SDK operation or consuming a file it returns, together with `python-calling-endpoints`. Covers which upload arm to pass and its memory, re-send and ownership costs, multipart part vs raw body, chunked vs sized bodies, filename and media-type overrides, and consuming a file response without leaking its connection. --- # File handling on an APIMatic Python SDK @@ -17,8 +17,9 @@ AsyncFileInput = AsyncBinaryContent | NamedFile[AsyncBinaryContent] # asyn ``` So you make exactly one choice: **where the bytes come from**. The destination is fixed by the -endpoint, and the flavour by the client. All of these are imported from `{root_package}.core`, and -`list[FileInput]` is an array part. +endpoint, and the flavour by the client. These aliases and their content unions, `NamedFile`, the two +reader protocols and the two response classes are all imported from `{root_package}.core` — they are +not re-exported from the package root — and `list[FileInput]` is an array part. Nothing validates what you pass, so a wrong arm is a type error at build time and a wrong *value* is a failure at send time. What each arm accepts is wider than the annotation suggests. @@ -67,10 +68,8 @@ These are the only places the position still matters, and none of them is visibl windows rather than one whole `bytes` from an `AsyncIterable` — your pieces are forwarded as you yield them, so a single large `bytes` is resident before the SDK ever sees it. - So **do not reach for an async handle over a file you could have named.** `anyio.open_file(p)` in - a part costs two reads and a write where `Path(p)` costs one read. The async arms earn their keep - when there is no path — bytes arriving from another connection, a queue, a subprocess — and cost a - round trip through the filesystem when there is one. + So prefer `Path(p)` to `anyio.open_file(p)` in a part — one read instead of two reads and a write; + the async arms are for bytes with no path behind them (another connection, a queue, a subprocess). On the **async client**, reading a *sync* arm inside a multipart body occupies the event loop while it reads, so `bytes` and the async arms are the spellings that never block it there. A raw body has @@ -109,8 +108,8 @@ client.{group}.{operation}(NamedFile(b"...", filename="invoice.pdf", media_type= Set `filename` and it wins over a `Path`'s own name and a handle's `.name` alike, so wrapping a named source renames it rather than being ignored. -**Every file currently goes out as `application/octet-stream`** whatever the spec declares, so -`NamedFile(content, media_type=...)` is the only way to send anything else. If the server validates a +**Every file goes out as `application/octet-stream`** unless you pass +`NamedFile(content, media_type=...)` — the only way to send anything else. If the server validates a part's `Content-Type`, say the type yourself. ## There is no `str` arm @@ -161,30 +160,24 @@ Both iterators take a `chunk_size`, defaulting to 64 KiB. f.aread()`, `async for chunk in f.aiter_bytes()`, `await f.aclose()`, and `async with` as the spelling to reach for. **`save_to` is the exception**: it keeps its name and is awaited — `await f.save_to("out.bin")` — so there is no `asave_to`. Calling it without `await` creates a coroutine - and drops it: nothing is written and the connection stays held. An abandoned response defers its - warning to loop shutdown, where it is far less useful — and that warning is silenced by default - too. + and drops it: nothing is written and the connection stays held. An abandoned async response defers + its warning to loop shutdown, and that `ResourceWarning` is hidden by Python's default warning + filters — so the leak is silent unless you enable it. - **`save_to` accepts a directory**, naming the file from the server's `Content-Disposition` — reduced to a safe basename first, because that header is attacker-controlled — and raising `ValueError` when - the server sent no filename, or sent one that reduces to nothing safe to create: empty, `.` or - `..`, a reserved device name (`CON`, `NUL`, `COM1`…), or longer than 255 characters. It writes - `.part` and moves it into place atomically, so an interrupted download never appears under + the server sent no filename or none that is safe to create: empty, `.` or `..`, a reserved device + name (`CON`, `NUL`, `COM1`…), or longer than 255 characters. It writes `.part` and moves it + into place atomically, so an interrupted download never appears under the final name. If the destination cannot be opened at all — a missing parent directory, or permissions — the response is still consumable. - **The head has already arrived**, so `headers`, `media_type`, `content_length` and `filename` are readable before you read a byte. `filename` is the server's suggestion and may be `None`. - **`request_options={"timeout": ...}` bounds each read of the body**, not the call as a whole, so a - stalled download raises rather than hanging. -- **A transport failure mid-download raises out of the *read*, not out of the call.** The call already + stalled download raises `SdkTimeoutError` rather than hanging. +- **A connection failure mid-download raises `SdkConnectionError` out of the *read*, not out of the call.** The call already returned successfully — only the head had arrived — so a `try` wrapped around the call alone catches nothing. Put the boundary around the consuming code (`python-error-handling`). With `with_raw_response`, the payload is the same unread `FileResponse`. The raw peer buys you the status code and headers, not the bytes — a result carries no body of its own, because here the body *is* the payload. - -## Where these types live - -Import all of them from `{root_package}.core`: the two aliases and their content unions, `NamedFile`, -the two reader protocols, and the two response classes. They are not re-exported from -`{root_package}/__init__.py`, so the package root is not where to look for them. diff --git a/plugins/plaid/skills/python/python-getting-started/SKILL.md b/plugins/plaid/skills/python/python-getting-started/SKILL.md index c676764a..599b1c05 100644 --- a/plugins/plaid/skills/python/python-getting-started/SKILL.md +++ b/plugins/plaid/skills/python/python-getting-started/SKILL.md @@ -1,20 +1,16 @@ --- name: "python-getting-started" -description: "The Plaid API Python SDK identity and lookup layer (Python only) — install, import root, base URL/environments, the auth pattern, the SDK map that ships at the SDK root (`sdk-map.md` + `map/operations/`) and how to traverse it, and the module table naming the one file owning each fact the map leaves to the source. Load this before answering any The Plaid API Python SDK contract question or writing any SDK code." +description: "Load before answering any The Plaid API Python SDK question or writing Python code against the SDK (Python only). The SDK's lookup layer: install, imports, environments and base URL, auth, the SDK map (`sdk-map.md` + `map/operations/`) and how to read it, and the module that owns each fact the map leaves to the source." --- # Getting started with the The Plaid API Python SDK -> **Who this skill is for.** This is the **lookup layer** for anyone writing The Plaid API Python SDK code — it is yours to follow directly and fully. Ground every contract fact here (in the SDK map, and in the source modules it names) rather than in recall, and carry those facts onto a contract sheet before you implement. Load `python-integrate-the-plaid-api` for the workflow that wraps this skill. +> **Lookup layer** for The Plaid API Python SDK code: ground every contract fact here, in the SDK map and in the source modules they name — never in recall — and carry those facts onto a contract sheet before you implement. `python-integrate-the-plaid-api` holds the workflow around it. -This is the **SDK-specific** entry point. For general patterns that apply to any APIMatic-generated Python SDK (client construction, auth, calling endpoints, models, error handling, resilience, testing), see the companion API-agnostic skills: `python-client-initialization`, `python-authentication`, `python-calling-endpoints`, `python-models`, `python-error-handling`, `python-configuration-resilience` and `python-testing`. - -**This page and those companion skills are complementary — load both.** This page is authoritative for the SDK's *identity and surface* (what to install, what to import, the controllers, which module owns which fact); the companion skills are the *usage layer* on top — the best-practice way to call each piece and the gotchas a signature cannot show. Reading a module in the installed package does not remove the need to load the skill for that step, so at each step below, load the companion *and* confirm names against the installed package. +This page owns the SDK's *identity and surface* (install, imports, controllers, which module owns which fact). The API-agnostic companion skills own *usage* — `python-client-initialization`, `python-authentication`, `python-calling-endpoints`, `python-models`, `python-error-handling`, `python-configuration-resilience` and `python-testing`; load each at its step (see **Integration workflow**) and confirm names against the installed package. ## SDK identity -Verified against `the_plaid_api/` and `pyproject.toml` of the generated package at version `0.1.0`. **Re-verify after a version bump** — this page is a snapshot, not a live read. - | Fact | Value | | --- | --- | | API | The Plaid API | @@ -22,21 +18,18 @@ Verified against `the_plaid_api/` and `pyproject.toml` of the generated package | Import root (what you import) | `the_plaid_api` — not the string you install | | Source repository | https://github.com/context-plugins/plaid-python-sdk | | Source branch | `main` | -| Version | `0.1.0` | +| Version | `0.1.0` — re-verify this page after a version bump | | Sync client class | `ThePlaidApiClient` (alias `Client`) | | Async client class | `AsyncThePlaidApiClient` (alias `AsyncClient`) | -| Client construction | **keyword-only**: `environment` · `timeout` (default `30.0`) · `server_config` · `retry_options` · `client_id` · `secret` · `plaid_version` · `oauth2` · `oauth2_token_source`, and the transport override — `custom_http_client` on the sync client, `custom_async_http_client` on the async one (the names differ; see step 1) | +| Client construction | **keyword-only**: `environment` · `base_url` · `timeout` (default `30.0`) · `retry_options` · `logging_options` · `hooks` · `client_id` · `secret` · `plaid_version` · `oauth2` · `oauth2_token_source`, and the transport override — `custom_http_client` on the sync client, `custom_async_http_client` on the async one (the names differ) | | Auth | **API key** in the `PLAID-CLIENT-ID` header — set `client_id` · **API key** in the `PLAID-SECRET` header — set `secret` · **API key** in the `Plaid-Version` header — set `plaid_version` · **OAuth 2.0** client credentials — set `oauth2` | -| Environments | 2 environments (default `"production"`) × 2 named servers, through `server_config` | -| Base-URL config | `ServerConfig` (`the_plaid_api/server/server_config.py`), frozen, `extra="forbid"` | +| Environments | 2 environments selected by `environment` (default `"production"`), overridable with `base_url` | +| Base-URL config | `ServerConfig` (`the_plaid_api/server/server_config.py`) | | Python floor | **`>=3.10`** (classifiers list `3.10–3.14`) | | Runtime dependencies | `httpx2 (>=2.13.1,<3.0.0)` · `certifi (>=2024.7.4)` · `pydantic[email] (>=2.11.0,<3.0.0)` · `typing-extensions (>=4.13.0,<5.0.0)` | -| Typing | ships `py.typed`; the package is checked under `mypy --strict` with `warn_unreachable`. Callers get full inference — **a type error against this SDK is a real contract violation, not noise** | -| Line length / lint | `ruff`, 120 cols (only relevant when editing the SDK itself) | +| Typing | ships `py.typed` — **a type error against this SDK is a real contract violation, not noise** | | Surface | 335 operations, all directly on the client — no controller groups; the map's single page is `map/operations/client.md` · 1750 models · 0 unions · 354 enums · 1 per-operation error union | -The table above is **orientation, not a copy-paste recipe** — it gives you the names and facts (install, import roots, the auth *pattern*, the base-URL knob), while the actual integration code comes from the companion skills. Load each one as you reach its step (see **Integration workflow** below) and confirm its types against the installed package. - ## Install — from source Into the same environment your project runs in, install the distribution from its repository, — it is not published to a package index: @@ -48,15 +41,13 @@ python -c "import the_plaid_api, pathlib; print(pathlib.Path(the_plaid_api.__fil **Run the second line too.** A `pip install` that reports success is not proof the SDK is importable where your project runs. If the probe raises `ModuleNotFoundError`, the install went into a different interpreter: re-run it through the one your project uses (`python -m pip install …`) and probe again. If it prints a path whose contents are not this SDK, what you installed is not this distribution. -The distribution carries its own `pyproject.toml`, so `pip` builds and installs it like any released package, copied into site-packages. Do not vendor its source into your project, add its directory to `sys.path`, or install it editable (`-e`) from a throwaway clone — an editable install points at that directory, so deleting the clone breaks every import. - -Once the second line prints this SDK's directory, write the imports from the table above: the distribution name you install and the package name you import are not the same string. Requires Python 3.10 or newer. +Install it as a package, into site-packages. Do not vendor its source into your project, add its directory to `sys.path`, or install it editable (`-e`) from a throwaway clone — an editable install points at that directory, so deleting the clone breaks every import. ## Imports — the package splits its surface across four modules Python does not re-export child modules transitively, so `from the_plaid_api import models` alone does **not** make enums, error unions, or runtime types reachable. Import each kind of type from the module that owns it. -`the_plaid_api/__init__.py` exports exactly 8 names beside the `the_plaid_api.models` subpackage it re-exports: +`the_plaid_api/__init__.py` exports exactly 6 names beside the `the_plaid_api.models` subpackage it re-exports: ```python from the_plaid_api import ( @@ -65,44 +56,35 @@ from the_plaid_api import ( Client, Environment, ServerConfig, - ServerConfigDict, - ServerConfigOrDict, ThePlaidApiClient, ) ``` -Everything else comes from its own subpackage, and the split matters because each kind of type a caller reaches for lives in a different module: +Everything else comes from its own subpackage: | What you need | Where it lives | | --- | --- | | Domain models, their `…Dict` companions | `the_plaid_api.models` | | Enums (and their open `…OrStr` aliases) | `the_plaid_api.models.enums` | -| `ApiError` · `RawError` · `ApiResult` · `RequestOptions` · `ClientCredentials` · `HttpClient` · `SdkBaseModel` · `UNSET` · `Optional` | `the_plaid_api.core` | +| `SdkError` · `ApiError` · `RawError` · `ApiResult` · `RequestOptions` · `ClientCredentials` · `HttpClient` · `SdkBaseModel` · `UNSET` · `Optional` | `the_plaid_api.core` | | Per-operation error *unions* | `the_plaid_api.errors` (`SandboxTransactionsCreateErrorBody`, …) | -`the_plaid_api.core` re-exports its whole public surface (a curated `__all__`), so import from `…core` rather than from the private modules beneath it (`…core.results`, `…core.exceptions`, `…core.auth.schemes`). +`the_plaid_api.core` re-exports its whole public surface, so import from `…core` rather than from the private modules beneath it (`…core.results`, `…core.exceptions`, `…core.auth.schemes`). -## Environments and servers - -The API declares 2 named servers across 2 environments, so the constructor takes `environment` first, then `timeout`, then `server_config: ServerConfigOrDict | None = None`. The environment selects which set of base URLs the config resolves against: - -| `environment=` | Hosting | -| --- | --- | -| `"production"` *(default)* | Production | -| `"environment2"` | Sandbox | +## Environments -Each of the 2 servers resolves independently, so a call's host is the pair (server, environment): +The constructor takes an `environment` keyword — a **string literal alias**, not an enum — followed by `base_url`. The declared environments and the base URL each resolves to: -| Server field | `"production"` base URL | `"environment2"` base URL | +| `environment=` | Base URL | Hosting | | --- | --- | --- | -| `default` | `https://production.plaid.com` | `https://sandbox.plaid.com` | -| `access_token_server` | `https://api.plaid.com/oauth2/apiv2` | `https://api.plaid.com/oauth2/apiv2` | +| `"production"` *(default)* | `https://production.plaid.com` | Production | +| `"environment2"` | `https://sandbox.plaid.com` | Sandbox | Consequences to state on every contract sheet that touches configuration: -- Omitting `environment` gives you **`"production"`**, silently. -- `server_config` overrides individual server URLs within the selected environment. -- The token endpoint (`/token`) resolves against the `access_token_server` server rather than a client-wide base URL, so `server_config` is what moves token traffic, and it follows `environment` with that server. +- Omitting `environment` gives you **`"production"`**, silently — not necessarily production. +- `base_url` overrides the environment's URL entirely when both are passed. +- The token endpoint is derived from the same base URL (`/oauth/token`), so it always follows the environment — you never configure it separately. - `ServerConfig` is a frozen pydantic model with `extra="forbid"`: a misspelled keyword raises `ValidationError` at construction rather than being ignored. - `timeout` is validated too — the base client raises `ValueError` for any non-positive value. @@ -132,26 +114,24 @@ from the_plaid_api import Client client = Client(plaid_version="") ``` -OAuth 2.0 client credentials, exposed as the client's `oauth2=` keyword taking `ClientCredentials` **or a plain dict**. The client fetches and caches the bearer token itself, lazily, from `/token` on the `access_token_server` server. +OAuth 2.0 client credentials, exposed as the client's `oauth2=` keyword taking `ClientCredentials` **or a plain dict**. The client fetches and caches the bearer token itself, lazily, from `/oauth/token`. Plaid requires a scope: set `scopes`, or the token request is refused with `invalid_scope`. ```python from the_plaid_api import Client from the_plaid_api.core import ClientCredentials -client = Client(oauth2=ClientCredentials(client_id="…", client_secret="…")) -client = Client(oauth2={"client_id": "…", "client_secret": "…"}) # equivalent +client = Client(oauth2=ClientCredentials(client_id="…", client_secret="…", scopes=["user:write"])) +client = Client(oauth2={"client_id": "…", "client_secret": "…", "scopes": ["user:write"]}) # equivalent ``` -**Every credentials keyword is optional at the type level and that is a trap worth flagging on every sheet.** Omit it and the client is built with `no_auth`: every request goes out unauthenticated. Nothing fails at construction. Most APIs then answer `401`; an API that serves anonymous traffic at all answers `200` and hides the omission entirely — verify the keyword is set rather than waiting for a `401` to tell you. - -See `python-authentication` for the full picture, including what a *failed token fetch* raises — it is not what a caller expects, and it is the single most common surprise in this SDK. +**Every credentials keyword is optional** — omit it and requests go out unauthenticated, with nothing failing at construction; `python-authentication` covers how to catch that, and what a *failed token fetch* raises. ## SDK map — look up first, open the module second The SDK ships a generated map at its **root** — the directory holding `pyproject.toml`, the `the_plaid_api/` source directory, and these two entries: -- **`sdk-map.md`** — the index: client construction with the full constructor-keyword table, the error-handling model (`ApiError` / `ApiResult` / `RawError`, Case A vs Case B), where models, enums and error aliases live, servers and auth, and the link table into the operations pages. -- **`map/operations/.md`** — one page per controller, one `###` block per operation: the HTTP verb and route, the sync parsed signature, each parameter's role and wire name, both return types, the error alias with the status each arm maps from, and a **Type sources** table naming the module that declares every *generated* type the operation mentions. +- **`sdk-map.md`** — the index: constructor keywords, the error model (`ApiError` / `ApiResult` / `RawError`, Case A vs Case B), where models, enums and error aliases live, servers and auth, and links to the operations pages. +- **`map/operations/.md`** — one `###` block per operation: verb and route, signature, parameter roles and wire names, both return types, error arms with the status each maps from, and a **Type sources** table naming the module of every *generated* type it mentions. **Installing the distribution does not give you the map.** `pyproject.toml` ships the `the_plaid_api/` package only, so `sdk-map.md` and `map/operations/` are absent from the installed package — they live in the SDK's own source tree, at the root of its repository, , in lockstep with the code the map describes — clone it to a temporary directory, outside the project repo: @@ -161,25 +141,17 @@ git clone --depth 1 --branch main https://github.com/context-plugins/plaid-pytho Confirm the map comes from the release you installed before you read anything out of it: the clone above is pinned to `main`, the branch this SDK is released from — the repository's default branch may carry a different version. A map read from any other release describes code you do not have. -Every `Source` path on the map is relative to that SDK root, so `the_plaid_api/models/aamvaanalysis.py` opens as written from there — and the same path resolves inside the installed package, which is where you read a module's body once the map has named it. +Every `Source` path on the map is relative to that SDK root, so `the_plaid_api/models/aamva_analysis.py` opens as written from there — and the same path resolves inside the installed package, which is where you read a module's body once the map has named it. -**The map is the locator; the source modules are the shapes.** Read the map first — signatures, routes, parameter roles, return types, error unions, and which module declares a type are all answered there without opening a single `.py` file. Then open the one module the map names for what it deliberately does not carry: a model's members, an enum's values, a field's wire alias. The map says so itself — *"Shapes live only in the source … Never grep for a type."* +**The map is the locator; the source modules are the shapes.** Read the map first — an operation's signature, route, parameter roles and return types, the client's constructor keywords, the `timeout` default, the members of `ApiError` / `Success` / `Failure` / `RawError`, each operation's error union with the status each arm maps from, base-URL and auth wiring, and which module declares a type are all answered there; don't open a module for them. Open the one module the map names only for what it leaves out: a model's members, an enum's values, a field's wire alias. The map says so itself — *"Shapes live only in the source … Never grep for a type."* -**The map carries shapes; what an operation *means* lives elsewhere.** When *what* to pass depends on meaning — which values a field accepts beyond its type, a rule that couples two fields, what a defaulted parameter actually selects — the map will not settle it. Open the operation's docstring in `the_plaid_api/apis/.py` (or `client.py` where operations sit on the client) and `api-reference.md` at the SDK root for that operation *before* writing the sheet row, and record what you found there. A value you already "know" for a field the map types as a plain `str` is a lookup, not a recall — the memory ban applies to it. +**Meaning is not on the map.** When what to pass depends on semantics — values a field accepts beyond its type, a rule that couples two fields, what a defaulted parameter selects — read the operation's docstring in `the_plaid_api/apis/.py` (or `client.py` where operations sit on the client) and its entry in `api-reference.md` at the SDK root before writing the sheet row, and record what you found — even for a value you think you know. `sdk-map.md` carries the invariants every operation block assumes, so load it before any `map/operations/` page; the pages are written to be read beside it. ## Contract facts — the map first, then the module -**Six of these are map lookups — don't open the module for them:** an operation's signature, parameters and return type; the client's constructor keywords; the `timeout` default; the members of `ApiError` / `Success` / `Failure` / `RawError`; an operation's error union and the status each arm maps from; base-URL and auth wiring. The table below covers everything else, and the full body behind a map row. - -Read the one module that owns the fact **inside the installed package**. Locate it first: - -```bash -python -c "import the_plaid_api, pathlib; print(pathlib.Path(the_plaid_api.__file__).parent)" -``` - -Failing that, it is under the project's environment (`.venv/Lib/site-packages/the_plaid_api` on Windows, `.venv/lib/python3.*/site-packages/the_plaid_api` elsewhere). **If the package is not installed, install it first** — see *Install* above; until then mark the fact `UNVERIFIED` and say what would settle it rather than answering from memory. Paths below are relative to that package root: +For everything the map leaves out, and the full body behind a map row, read the one module that owns the fact **inside the installed package** — locate it with the probe from *Install*. Failing that, it is under the project's environment (`.venv/Lib/site-packages/the_plaid_api` on Windows, `.venv/lib/python3.*/site-packages/the_plaid_api` elsewhere). **If the package is not installed, install it first** — see *Install* above; until then mark the fact `UNVERIFIED` and say what would settle it rather than answering from memory. Paths below are relative to that package root: | Question | Module | | --- | --- | @@ -187,9 +159,11 @@ Failing that, it is under the project's environment (`.venv/Lib/site-packages/th | Client construction, keywords, controller wiring | `client.py`, `async_client.py`, `base_client.py` | | Timeout default and validation | `base_client.py` (`DEFAULT_TIMEOUT = 30.0`) | | The request/response pipeline, 401 handling, 2xx-vs-error split | `core/raw_client.py` | -| Exception shape (`ApiError.error`, `.status_code`, `.headers`) | `core/exceptions.py` | +| Exception family (`SdkError` and its members; `ApiError.error`, `.status_code`, `.headers`) | `core/exceptions.py` | | `Success`/`Failure`/`RawError` | `core/results.py` | | Per-call overrides | `core/request_options.py` | +| Request and response hooks | `core/hooks.py` | +| Logging options, levels and masking | `core/logging.py` | | `UNSET`, `Optional`, `OptionalNullable` | `core/optionality.py` | | Model base config, `to_dict`/`to_json` | `core/models.py` | | A model's members, required vs `UNSET`, wire aliases | `models/.py` | @@ -204,39 +178,37 @@ Failing that, it is under the project's environment (`.venv/Lib/site-packages/th **Read scoped.** These modules carry long design docstrings; `grep -n` for the symbol and read the surrounding lines rather than whole files. Never quote a docstring's design rationale onto a contract sheet — the sheet carries facts an implementer must obey, not the reasoning behind them. -Keep lookups cheap — the rules that keep a session's context small: +Keep lookups cheap: -- Collect the contracts for **every** in-scope operation in **one** pass — signature, required members with wire aliases, the error union, enum values — into a short **contract sheet** in your plan or working notes, then implement from the sheet. Don't re-open a module per member, and never re-look-up a fact the sheet already carries. -- Recurse into a model's members only where the task actually sets them — a full transitive expansion is hundreds of rows and nobody needs it. -- Trust the interpreter over this page: if a name here ever fails to type-check or import, re-read the module the table above names and report the drift; never patch around it from memory. +- Collect the contracts for **every** in-scope operation in **one** pass — signature, required members with wire aliases, the error union, enum values — onto the contract sheet, then implement from it; never re-open a module for a fact the sheet carries. +- Expand a model's members only where the task sets them. +- If a name here fails to type-check or import, re-read the module the table names and report the drift; never patch around it from memory. ## Integration workflow — load the companion skill at each step -Before you write the code for each step, load the named companion skill — even if you have already read the relevant module. Each step calls out the trap the signature hides (in *parens*). A typical integration reaches them in this order: +Before you write the code for each step, load the named companion skill — even if you have already read the relevant module; it owns the traps the signature hides. A typical integration reaches them in this order: -1. **Client construction & lifetime** — load **python-client-initialization** before you write `Client(...)` or `AsyncClient(...)`. (*The signature won't tell you:* the constructor is keyword-only, so nothing can be passed positionally; the client owns an `httpx2` connection pool and you **must** `close()` (sync) or `await aclose()` (async) or use it as a context manager; it must be long-lived and module- or app-scoped, never rebuilt per request; the sync and async clients do not mix; and the transport-override keyword differs by client — `custom_http_client` vs `custom_async_http_client`.) -2. **Authentication** — load **python-authentication** before you set credentials. The four schemes are `client_id=`, `secret=`, `plaid_version=` and `oauth2=`. (*The signature won't tell you:* every credentials keyword is *optional* — omit it and every request goes out unauthenticated, with no failure at construction and not necessarily a `401` to tell you; the token is fetched lazily and cached by the client; and a **failed token fetch** raises something other than what a caller expects and **bypasses the non-raising response mode** entirely. Load secrets from the environment or a secret store, never hardcode.) -3. **Calling an endpoint** — load **python-calling-endpoints** before the first `client..(...)` call. (*The signature won't tell you:* every operation splits positional path params (and sometimes the body) from a keyword-only tail after `*`; every keyword-only parameter has a **real** default, so there is no "must pass `None` explicitly" hazard; **11 operations return `None`**, so `with_raw_response` is the only way to observe their status code; and the two response modes — raising vs `ApiResult` — behave differently on failure.) -4. **Models** — load **python-models** the moment a request/response member is not a plain string or number. (*The signature won't tell you:* `Optional[T]` here is `T | UnsetType`, **not** `typing.Optional` — `None` is not a legal value for it; models are frozen pydantic instances with `…Dict` TypedDict companions; enums are **open** (`…OrStr`), so an unknown wire value passes through as a plain `str` rather than raising; wire aliases differ from Python member names; unknown response fields are **preserved**, not dropped; and serialize via `to_dict`/`to_json`.) -5. **Error handling** — load **python-error-handling** before you write any `try/except`. (*The signature won't tell you:* there is a single `ApiError` type whose `.error` is a **per-operation union**, and a decode failure raises `ValidationError`/`ValueError`, not `ApiError`, and bypasses both response modes; `httpx2` transport exceptions reach your boundary unwrapped.) -6. **Configuration & resilience** — load **python-configuration-resilience** when you set the base URL, timeouts, retries, proxies, TLS, or logging. (*The signature won't tell you:* **retrying is on by default** — `retry_options` takes a count, a `RetryOptions` or its dict, `max_retries` set to `0` turns it off, and one call overrides it through `request_options`; a `401` is never retried; `timeout` defaults to `30.0` and is a single float that maps onto `httpx2`'s timeout semantics, limiting each wait rather than the whole call; and there is no logging hook — you wrap the transport seam.) -7. **Testing** — load **python-testing** before you stub the SDK. (*The signature won't tell you:* the seam is the **transport protocol** (`HttpClient`/`AsyncHttpClient` in `core/transport.py`) passed as `custom_http_client` — not the client class; a fake transport implements `send` and `close`, the two the protocol declares, and `send` answers with the head alone; assert on the request the SDK actually built, and cover all four failure kinds, decode failures included.) +1. **Client construction & lifetime** — load **python-client-initialization** before you write `Client(...)` or `AsyncClient(...)`. +2. **Authentication** — load **python-authentication** before you set credentials. +3. **Calling an endpoint** — load **python-calling-endpoints** before the first `client..(...)` call. +4. **Models** — load **python-models** the moment a request/response member is not a plain string or number. +5. **Error handling** — load **python-error-handling** before you write any `try/except`. +6. **Configuration & resilience** — load **python-configuration-resilience** when you set the base URL, timeouts, retries, proxies, TLS, or logging. +7. **Testing** — load **python-testing** before you stub the SDK. ## What a contract sheet must carry for this SDK Beyond the usual signatures and model members, a Python sheet is incomplete without these, because each one is a decision the implementer cannot make correctly from the signature alone: -1. **Sync or async** — which client class, and the reminder that the two do not mix. Plus the `close()`/`aclose()` obligation and where the client is held. -2. **The keyword-only boundary** for each operation: what is positional (path params, sometimes the body) and what sits after `*`. Every keyword-only parameter has a real default, so there is no "must pass `None` explicitly" hazard — say so, so nobody writes defensive `None`s. -3. **The 11 operations that return `None`** — `asset_report_audit_copy_pdf_get` · `asset_report_pdf_get` · `consumer_report_pdf_get` · `cra_check_report_pdf_get` · `cra_check_report_verification_pdf_get` · `credit_bank_income_pdf_get` · `credit_relay_pdf_get` · `fdx_consents_revoke` · `fdx_notifications` · `income_verification_documents_download` · `statements_download`. Their raw peers are `ApiResult[None, …]`, so `with_raw_response` is the only way to observe the status code. -4. **Required vs `UNSET`** for every model member the task sets, and the fact that `Optional[T]` here is `T | UnsetType` — **not** `typing.Optional`, so `None` is not a legal value for it. -5. **The `ApiError.error` union** for each operation in scope — there is **one** typed error body in this SDK, so the union is never uniform. Every union is ` | RawError`: - 1. `Error | None` — 1 operation (`sandbox_transactions_create`); distinguishing members *none required* - 2. *(none)* — `accounts_balance_get` · `accounts_get` · `application_get` · `asset_report_audit_copy_create` · `asset_report_audit_copy_get` · `asset_report_audit_copy_pdf_get` · `asset_report_audit_copy_remove` · `asset_report_create` · `asset_report_filter` · `asset_report_get` · `asset_report_pdf_get` · `asset_report_refresh` · `asset_report_remove` · `auth_get` · `auth_verify` · `bank_transfer_balance_get` · `bank_transfer_cancel` · `bank_transfer_create` · `bank_transfer_event_list` · `bank_transfer_event_sync` · `bank_transfer_get` · `bank_transfer_list` · `bank_transfer_migrate_account` · `bank_transfer_sweep_get` · `bank_transfer_sweep_list` · `beacon_account_risk_evaluate` · `beacon_duplicate_get` · `beacon_report_create` · `beacon_report_get` · `beacon_report_list` · `beacon_report_syndication_get` · `beacon_report_syndication_list` · `beacon_user_account_insights_get` · `beacon_user_create` · `beacon_user_get` · `beacon_user_history_list` · `beacon_user_review` · `beacon_user_update` · `beta_ewa_report_v1_get` · `beta_partner_customer_v1_create` · `beta_partner_customer_v1_enable` · `beta_partner_customer_v1_get` · `beta_partner_customer_v1_update` · `business_verification_create` · `business_verification_get` · `cashflow_report_get` · `cashflow_report_insights_get` · `cashflow_report_refresh` · `cashflow_report_transactions_get` · `categories_get` · `consent_events_get` · `consumer_report_pdf_get` · `cra_check_report_base_report_get` · `cra_check_report_cashflow_insights_get` · `cra_check_report_create` · `cra_check_report_income_insights_get` · `cra_check_report_lend_score_get` · `cra_check_report_network_insights_get` · `cra_check_report_partner_insights_get` · `cra_check_report_pdf_get` · `cra_check_report_verification_get` · `cra_check_report_verification_pdf_get` · `cra_credit_profile_report_get` · `cra_loans_applications_register` · `cra_loans_register` · `cra_loans_unregister` · `cra_loans_update` · `cra_monitoring_insights_get` · `cra_monitoring_insights_subscribe` · `cra_monitoring_insights_unsubscribe` · `cra_partner_insights_get` · `cra_report_get` · `create_payment_token` · `credit_asset_report_freddie_mac_get` · `credit_audit_copy_token_create` · `credit_audit_copy_token_update` · `credit_bank_employment_get` · `credit_bank_income_get` · `credit_bank_income_pdf_get` · `credit_bank_income_refresh` · `credit_bank_income_webhook_update` · `credit_bank_statements_uploads_get` · `credit_employment_get` · `credit_freddie_mac_reports_get` · `credit_payroll_income_get` · `credit_payroll_income_parsing_config_update` · `credit_payroll_income_precheck` · `credit_payroll_income_refresh` · `credit_payroll_income_risk_signals_get` · `credit_relay_create` · `credit_relay_get` · `credit_relay_pdf_get` · `credit_relay_refresh` · `credit_relay_remove` · `credit_report_audit_copy_remove` · `credit_sessions_get` · `dashboard_user_get` · `dashboard_user_list` · `employers_search` · `employment_verification_get` · `fdx_consents_get` · `fdx_consents_list` · `fdx_consents_revocation_get` · `fdx_consents_revoke` · `fdx_notifications` · `get_recipient` · `get_recipients` · `identity_documents_uploads_get` · `identity_get` · `identity_match` · `identity_refresh` · `identity_verification_autofill_create` · `identity_verification_create` · `identity_verification_get` · `identity_verification_list` · `identity_verification_retry` · `income_verification_create` · `income_verification_documents_download` · `income_verification_paystubs_get` · `income_verification_precheck` · `income_verification_taxforms_get` · `institutions_get` · `institutions_get_by_id` · `institutions_search` · `investments_auth_get` · `investments_holdings_get` · `investments_refresh` · `investments_transactions_get` · `issues_get` · `issues_search` · `issues_subscribe` · `item_access_token_invalidate` · `item_activity_list` · `item_application_list` · `item_application_scopes_update` · `item_application_unlink` · `item_create_public_token` · `item_get` · `item_import` · `item_products_terminate` · `item_public_token_exchange` · `item_remove` · `item_webhook_update` · `liabilities_get` · `link_delivery_create` · `link_delivery_get` · `link_oauth_correlation_id_exchange` · `link_token_create` · `link_token_get` · `network_status_get` · `oauth_introspect` · `oauth_revoke` · `oauth_token` · `partner_customer_create` · `partner_customer_enable` · `partner_customer_get` · `partner_customer_oauth_institutions_get` · `partner_customer_remove` · `payment_initiation_consent_create` · `payment_initiation_consent_get` · `payment_initiation_consent_payment_execute` · `payment_initiation_consent_revoke` · `payment_initiation_payment_create` · `payment_initiation_payment_get` · `payment_initiation_payment_list` · `payment_initiation_payment_reverse` · `payment_initiation_recipient_create` · `payment_initiation_recipient_get` · `payment_initiation_recipient_list` · `payment_profile_create` · `payment_profile_get` · `payment_profile_remove` · `processor_account_get` · `processor_apex_processor_token_create` · `processor_auth_get` · `processor_balance_get` · `processor_bank_transfer_create` · `processor_identity_get` · `processor_identity_match` · `processor_investments_auth_get` · `processor_investments_holdings_get` · `processor_investments_transactions_get` · `processor_liabilities_get` · `processor_signal_decision_report` · `processor_signal_evaluate` · `processor_signal_prepare` · `processor_signal_return_report` · `processor_stripe_bank_account_token_create` · `processor_token_create` · `processor_token_permissions_get` · `processor_token_permissions_set` · `processor_token_webhook_update` · `processor_transactions_get` · `processor_transactions_recurring_get` · `processor_transactions_refresh` · `processor_transactions_sync` · `profile_network_status_get` · `protect_compute` · `protect_event_get` · `protect_event_send` · `protect_report_create` · `protect_user_insights_get` · `sandbox_bank_income_fire_webhook` · `sandbox_bank_transfer_fire_webhook` · `sandbox_bank_transfer_simulate` · `sandbox_cra_cashflow_updates_update` · `sandbox_fdx_consent_seed` · `sandbox_income_fire_webhook` · `sandbox_item_application_seed` · `sandbox_item_fire_webhook` · `sandbox_item_reset_login` · `sandbox_item_set_verification_status` · `sandbox_oauth_select_accounts` · `sandbox_payment_profile_reset_login` · `sandbox_payment_simulate` · `sandbox_processor_token_create` · `sandbox_public_token_create` · `sandbox_transfer_fire_webhook` · `sandbox_transfer_ledger_deposit_simulate` · `sandbox_transfer_ledger_simulate_available` · `sandbox_transfer_ledger_withdraw_simulate` · `sandbox_transfer_refund_simulate` · `sandbox_transfer_repayment_simulate` · `sandbox_transfer_simulate` · `sandbox_transfer_sweep_simulate` · `sandbox_transfer_test_clock_advance` · `sandbox_transfer_test_clock_create` · `sandbox_transfer_test_clock_get` · `sandbox_transfer_test_clock_list` · `sandbox_user_reset_login` · `session_token_create` · `signal_decision_report` · `signal_evaluate` · `signal_prepare` · `signal_return_report` · `signal_schedule` · `statements_download` · `statements_list` · `statements_refresh` · `transactions_enhance` · `transactions_enrich` · `transactions_get` · `transactions_recurring_get` · `transactions_refresh` · `transactions_rules_create` · `transactions_rules_list` · `transactions_rules_remove` · `transactions_sync` · `transactions_user_insights_get` · `transfer_authorization_cancel` · `transfer_authorization_create` · `transfer_balance_get` · `transfer_cancel` · `transfer_capabilities_get` · `transfer_configuration_get` · `transfer_create` · `transfer_diligence_document_upload` · `transfer_diligence_submit` · `transfer_event_list` · `transfer_event_sync` · `transfer_get` · `transfer_intent_create` · `transfer_intent_get` · `transfer_ledger_deposit` · `transfer_ledger_distribute` · `transfer_ledger_event_list` · `transfer_ledger_get` · `transfer_ledger_withdraw` · `transfer_list` · `transfer_metrics_get` · `transfer_migrate_account` · `transfer_originator_create` · `transfer_originator_funding_account_create` · `transfer_originator_funding_account_update` · `transfer_originator_get` · `transfer_originator_list` · `transfer_platform_originator_create` · `transfer_platform_person_create` · `transfer_platform_requirement_submit` · `transfer_questionnaire_create` · `transfer_recurring_cancel` · `transfer_recurring_create` · `transfer_recurring_get` · `transfer_recurring_list` · `transfer_refund_cancel` · `transfer_refund_create` · `transfer_refund_get` · `transfer_repayment_list` · `transfer_repayment_return_list` · `transfer_return_recover` · `transfer_sweep_get` · `transfer_sweep_list` · `user_account_session_event_send` · `user_account_session_get` · `user_create` · `user_financial_data_refresh` · `user_get` · `user_identity_remove` · `user_items_associate` · `user_items_get` · `user_items_remove` · `user_products_terminate` · `user_remove` · `user_third_party_token_create` · `user_third_party_token_remove` · `user_transactions_refresh` · `user_update` · `wallet_create` · `wallet_get` · `wallet_list` · `wallet_transaction_execute` · `wallet_transaction_get` · `wallet_transaction_list` · `watchlist_screening_entity_create` · `watchlist_screening_entity_get` · `watchlist_screening_entity_history_list` · `watchlist_screening_entity_hit_list` · `watchlist_screening_entity_list` · `watchlist_screening_entity_program_get` · `watchlist_screening_entity_program_list` · `watchlist_screening_entity_review_create` · `watchlist_screening_entity_review_list` · `watchlist_screening_entity_update` · `watchlist_screening_individual_create` · `watchlist_screening_individual_get` · `watchlist_screening_individual_history_list` · `watchlist_screening_individual_hit_list` · `watchlist_screening_individual_list` · `watchlist_screening_individual_program_get` · `watchlist_screening_individual_program_list` · `watchlist_screening_individual_review_create` · `watchlist_screening_individual_review_list` · `watchlist_screening_individual_update` · `webhook_verification_key_get`: no typed arm, so `.error` is always `RawError` - 3. So `isinstance(e.error, Error | None)` matches only 1 of 335 operations. -6. **That a decode failure raises `ValidationError`/`ValueError`, not `ApiError`, in both response modes** — `core/raw_client.py` states this in `execute`'s own docstring. **And that the 2xx path declares at least one required member on 307 return types, so a truncated body fails to decode there and passes silently everywhere else.** Any sheet row for a call whose result is used must name the members the implementer has to assert on. -7. **That retrying is on by default** — `retry_options` on the client tunes it, `max_retries` set to `0` turns it off, and `request_options` overrides it per call — so the sheet says whether this integration keeps, tunes or disables it, and for which methods, since a write is repeated only when the policy names its method. -8. **What limits a whole call.** `timeout` limits each wait, not the call, so a reply whose pieces each arrive within it is never cut off. In async code, state the budget and the one place `asyncio.wait_for` enforces it for every call, and what the boundary returns for its `asyncio.TimeoutError`; in sync code, say there is none. -9. **Which environment the `environment` keyword selects**, because omitting it is silently `"production"`. -10. A **REQUIRED READING** block naming the `python-*` companions that govern the steps, with `MUST load` pointers. +1. **Sync or async** — the client class, where it is held, and its `close()`/`aclose()`. +2. **The keyword-only boundary** for each operation: what is positional (each required parameter without a fixed value, path → query → header → body) and what sits after `*`. Every keyword-only parameter has a real default, so write no defensive `None`s. +3. **The 11 operations that return `None`** — the map's **Returns (parsed)** bullet says which. Their raw peers are `ApiResult[None, …]`, so `with_raw_response` is the only way to observe the status code. +4. **Required vs `UNSET`** for every model member the task sets. +5. **The `ApiError.error` union** for each operation in scope, copied from the **Error arms** bullet of its block in `map/operations/` — this SDK has **1 typed error body** across 335 operations, so never assume an arm is shared. Every union ends in `RawError`; an operation with no typed arm is `RawError` alone. +6. **That a decode failure raises `ResponseDecodeError`, not `ApiError`, in both response modes. And that the 2xx path declares at least one required member on 307 return types, so a truncated body fails to decode there and passes silently everywhere else.** Any sheet row for a call whose result is used must name the members the implementer has to assert on. +7. **Retries are on by default** — the sheet says whether this integration keeps, tunes (`retry_options`) or disables them (`max_retries` set to `0`), and for which methods; a write is retried only when the policy names its method. +8. **Whether logging is on, and how loud** — the sheet says whether this integration raises the `the_plaid_api` logger, which `logging_options` dumps it turns on — a JSON body is logged as sent — and any per-call `log_level`. +9. **What limits a whole call.** `timeout` limits only each wait (`python-configuration-resilience`). In async code, state the budget and the one place `asyncio.wait_for` enforces it for every call, and what the boundary returns for its `asyncio.TimeoutError`; in sync code, say there is none. +10. **Which environment the `environment` keyword selects**, because omitting it is silently `"production"` of the 2 declared. +11. A **REQUIRED READING** block naming the `python-*` companions that govern the steps, with `MUST load` pointers. diff --git a/plugins/plaid/skills/python/python-integrate-the-plaid-api/SKILL.md b/plugins/plaid/skills/python/python-integrate-the-plaid-api/SKILL.md index e79fb331..ab4c765b 100644 --- a/plugins/plaid/skills/python/python-integrate-the-plaid-api/SKILL.md +++ b/plugins/plaid/skills/python/python-integrate-the-plaid-api/SKILL.md @@ -1,21 +1,32 @@ --- name: "python-integrate-the-plaid-api" -description: "MANDATORY FIRST STEP for The Plaid API Python SDK work in a Python project — load this BEFORE you write any code; Python SDK ONLY, never load it for any other language. Applies when asked to integrate The Plaid API in Python — create a fraud report for a given beacon user, fetch a beacon user, update the status of a beacon user, returns a consent grant by its identifier, get a specific recipient, returns a list of recipients, list a historical log of user consent events, list a user's connected applications — or when a The Plaid API Python SDK call errors or behaves unexpectedly. Knowing the SDK exists is NOT a substitute for loading this, because it carries five binding gates stated NOWHERE else and not inferable from the package — (1) load python-getting-started, confirm the package is actually installed and read the SDK map that ships with it before any lookup, (2) the exact plan-file path and the no-project-file-edits window until a contract sheet with no open lookups exists there and you have read it, (3) the mandatory load of every python-* companion skill the sheet names, (4) sync-vs-async decided once from the host application before the first call, and (5) the memory ban, where every signature, wire alias, error union and enum member comes from a lookup and never from recall or runtime introspection." +description: "MANDATORY FIRST STEP for The Plaid API Python SDK work in a Python project (never another language): load before writing code to integrate The Plaid API in Python — create a fraud report for a given beacon user, fetch a beacon user, update the status of a beacon user — or when a The Plaid API Python SDK call errors or behaves unexpectedly. Holds the plan-first workflow: the plan file, the contract sheet and its no-edits gate, and which python-* companion skills to load." --- # The Plaid API Python SDK — Integration workflow (lookup layer + contract sheet) -You do the SDK lookups yourself: `python-getting-started` is your **lookup layer** — load it and ground every contract fact in it (and in the source modules its table names) before writing code. The `python-*` companion skills are a different thing: they are API-agnostic *usage* guidance, they are yours to load, and Step 1c below makes loading them mandatory. +`python-getting-started` is your **lookup layer**; the `python-*` companions are API-agnostic *usage* skills that Step 1c makes mandatory. ## Your lookup layer -- **`python-getting-started`** is the entry point for every SDK need. It carries the SDK's identity (distribution name vs import root, version, Python floor, install-from-source), what the root package exports and the four modules the surface splits across, environments and the base-URL knob, the auth pattern, the controllers, and a **module table** naming the one file that owns each kind of fact. Load it first, always. -- **The SDK map is your lookup surface, and you open it yourself.** The SDK ships `sdk-map.md` and `map/operations/` at its root. There is no helper agent on the Python side — the map is yours to read, not something to delegate. `python-getting-started` tells you how to traverse it: read `sdk-map.md` once, then the one controller page your operations live on. -- **The installed package is the ground truth; the module table is only the locator.** Confirm the package is importable before you rely on a lookup — `python -c "import the_plaid_api, pathlib; print(pathlib.Path(the_plaid_api.__file__).parent)"`. **If it is not installed, install it first** — `python-getting-started` carries the command; until then mark the fact `UNVERIFIED`, say what would settle it, and do not fill the hole from memory. (The distribution is not on any package index — it installs from its repository; `python-getting-started` carries the command.) -- **Read scoped.** Those modules carry long design docstrings. `grep -n` for the symbol and read the surrounding lines rather than whole files, and never copy a docstring's design rationale onto a contract sheet — the sheet carries facts an implementer must obey, not the reasoning behind them. -- **Write a contract sheet with no open lookups** before you implement: exact signatures, the keyword-only boundary, wire aliases, required-vs-`UNSET` members, the `ApiError.error` union per operation, and enum members for the operations in scope. `python-getting-started` ends with a checklist of the rows a Python sheet is incomplete without — treat that list as the checklist for your own sheet, and collect every in-scope operation in ONE pass rather than re-opening a module per member. +- **`python-getting-started`** is the entry point for every SDK need: the SDK's identity (distribution name vs import root, version, Python floor, install-from-source), the root package's exports and the modules the surface splits across, environments and the base-URL knob, the auth pattern, the controllers, and a **module table** naming the one file that owns each kind of fact. Load it first, always. +- **The SDK map** (`sdk-map.md` and `map/operations/`, at the SDK root) is yours to open and read: `sdk-map.md` once, then the one controller page your operations live on. +- **The installed package is the ground truth; the module table is only the locator.** Confirm the package imports, with the probe in `python-getting-started`, before you rely on a lookup; **if it is not installed, install it first**. Until then mark the fact `UNVERIFIED`, say what would settle it, and do not fill the hole from memory. (The distribution is not on any package index — it installs from its repository; `python-getting-started` carries the command.) +- **Write a contract sheet with no open lookups** before you implement — every in-scope operation in one pass, against the checklist that ends `python-getting-started`. -**Scope guard:** the APIMatic-generated The Plaid API **Python SDK** (import root `the_plaid_api`, distribution `the-plaid-api`) in **Python projects only**. Unrelated API, or any language other than Python — do nothing; this skill does not apply. +**Scope:** the The Plaid API **Python SDK** (import root `the_plaid_api`, distribution `the-plaid-api`) in **Python projects only**. + +## The planner agent + +`the-plaid-api-planner` ships with this plugin. It writes `the-plaid-api-plan.md` — the plan and its contract sheet — and revises it in place; it writes no project code. Start it the first of these ways your host allows: + +1. **Your subagent tool lists it.** Some hosts list a plugin's agents under the plugin's name, as `plaid:the-plaid-api-planner`; start it by whichever of the two names your subagent tool lists. +2. **It isn't listed, or you can't start a subagent.** Tell the user in one line that you are writing the plan yourself, then do so as *Step 1* describes. Don't stop to ask. + +However you start it: + +- **Start it on the same model you are running on.** If your subagent tool takes a model, pass your own model; if it has no model option, leave its default. Tell the user in one line which model you started it on. +- **Start it once per integration.** A plan revision is a follow-up message to that same agent; re-start it, carrying the clarification and the plan path, only where your host cannot message it. Never start a second one for the same integration. ## Workflow @@ -23,23 +34,29 @@ You do the SDK lookups yourself: `python-getting-started` is your **lookup layer ### Step 1 — Plan first (always, for any implementation work) -Your FIRST action is to load `python-getting-started` and work through the user's full request (all features in scope — one plan covers the whole implementation). Then write the plan and its contract sheet to `/the-plaid-api-plan.md` — that absolute path, not a location you pick later. +Your FIRST action, once the SDK is installed and you have reached its source (both are prerequisites below; installing follows the toolchain check and the baseline, and the gate allows it), is to start **`the-plaid-api-planner`**, as *The planner agent* says, once, with the user's full request — all features in scope; one plan covers the whole implementation — and the name of this skill, `python-integrate-the-plaid-api`. Dictate in its task the absolute project root, the absolute path of the SDK source you reached — it reads the map there rather than reaching its own — and the absolute path it must write to — `/the-plaid-api-plan.md`, that absolute path, not a location you pick later. It loads `python-getting-started`, writes the plan and its contract sheet as this step and *Step 1c* describe, and returns the file's path. -**Do the read-only prerequisites in the same pass — they need no SDK knowledge and touch no project file:** +**If you couldn't start the planner** (case 2 in *The planner agent*), load `python-getting-started`, work through the request yourself, and write the file at that path. + +**Do these two read-only prerequisites before you install the SDK — the install changes the tree they read:** -- the repo survey (read-only exploration of conventions, layering, and **whether the project is sync or `async`**) — capture each convention as *pattern + the ONE exemplar file path to imitate*, NOT inline code snippets: you will read the exemplar at edit time anyway, so a snippet dump gets paid for twice; - **establish the toolchain before you need it**: which environment manager the repo uses (`uv`, `poetry`, `pip` + venv, `pdm`), whether `the-plaid-api` is already a dependency and at what version, and the exact commands that run the project's tests and type checker. Getting this wrong later costs a broken install mid-implementation — and an uninstalled package costs you the lookup layer itself; -- a baseline run of the project's checks (`pytest`, `mypy`, `ruff` — whatever it has) on the UNTOUCHED tree, so later failures are attributable to your changes; +- a baseline run of the project's checks (`pytest`, `mypy`, `ruff` — whatever it has) on the UNTOUCHED tree, so later failures are attributable to your changes. + +**Then make sure the SDK is installed and reach its source, before you start the planner** (both per `python-getting-started`) — the installed package does not carry the map, which lives in the SDK's source tree, and the planner reads the copy you reached rather than reaching its own. + +**Do the rest while the planner works — they need no SDK knowledge and touch no project file:** + +- the repo survey (read-only exploration of conventions, layering, and **whether the project is sync or `async`**) — capture each convention as *pattern + the ONE exemplar file path to imitate*, NOT inline code snippets: you will read the exemplar at edit time anyway, so a snippet dump gets paid for twice; - credentials/environment verification (per the task's secret-handling rules) — including which host `environment` will select, since omitting it is silent; -- **a read-only smoke of each in-scope operation against the real credential**, run from your scratchpad, not the project, once the map has given you the signatures and before you finalise the sheet. A plan-, region- or entitlement-gated endpoint answers `403` here — the map presents every operation uniformly and cannot know which ones your key may call — and learning that now reorders the plan rather than the build. Skip only operations whose side effects you cannot reverse; - setting up your task tracking. -Never use the planning phase to get a "head start" on implementation: **creating or editing ANY project file before the gate below is a defect**, no matter how obvious the code seems. - -**HARD GATE — no project-file creation or edits until:** `the-plaid-api-plan.md` EXISTS at the repo root, its contract sheet has **no open lookups**, and you have read it. The gate bars coding "meanwhile"; it does not bar the read-only prerequisite work above. Starting to code before the sheet exists defeats the entire plan-first design. +**HARD GATE — no project-file creation or edits until** the planner has returned, `the-plaid-api-plan.md` exists at the repo root (check it — a helper can misreport where it saved), its contract sheet has **no open lookups**, and you have read it. If you wrote the plan yourself, the gate is the same without the return. The read-only prerequisites above are not gated. **What the gate does not cover:** creating or activating a virtual environment, installing `the-plaid-api` and the toolchain into it, and the files those writes produce (`.venv/`, a lockfile the installer updates) are **prerequisites, not project-file edits**. On a greenfield repo they are the only way to reach the lookup layer at all, and they are the only writes permitted before the gate. Nothing you author by hand may change. +**One read-only prerequisite waits for the signatures: a smoke of each in-scope operation against the real credential**, run from your scratchpad, not the project, once the planner has returned and you have read the sheet, with the signatures it records, and before your first project edit — or, if you are writing the plan yourself, once the map has given you the signatures and before you finalise the sheet. A plan-, region- or entitlement-gated endpoint answers `403` here — the map presents every operation uniformly and cannot know which ones your key may call — and learning that now reorders the plan rather than the build. Send each `403` to the SAME planner as a revision, as *Step 1c* sends a blocker, and implement from its reply; if you wrote the plan yourself, revise the sheet in place. Skip only operations whose side effects you cannot reverse. + **DUPLICATE CLAIMS** — one row per write a caller can trigger twice; `none` if the task has no such write (`python-configuration-resilience`, *The same operation arriving twice*). | Write | Where the claim is stored | What rejects the second one | Where that rejection is caught | Where in the code | @@ -47,7 +64,7 @@ Never use the planning phase to get a "head start" on implementation: **creating Every row follows one order: **claim → SDK call → record the result**. The claim is a write of its own, made before the SDK call, so a second caller is stopped before it reaches the provider; release it when the provider refuses the call. -⚠⚠ **Where the claim is stored**: a store this application owns — the one the codebase already keeps its records in — never the provider. A provider idempotency key goes beside the claim, never in place of it; the SDK's own `Idempotency-Key` header is not one — it is new on every call. If this codebase has nowhere to keep a claim that outlives the process, that is a Blocker in the plan's **Assumptions & Blockers**, not a row. +⚠⚠ **Where the claim is stored**: a store this application owns — the one the codebase already keeps its records in — never the provider. A provider idempotency key goes beside the claim, never in place of it; the SDK's own `Idempotency-Key` header is not one. If this codebase has nowhere to keep a claim that outlives the process, that is a Blocker in the plan's **Assumptions & Blockers**, not a row. ⚠⚠ **What rejects the second one**: the store refusing the second caller's claim, the way this codebase already refuses a duplicate. A conflict on the save *after* the SDK call is too late — both callers have already reached the provider. A read before the write — a status check, a lookup by key — is not a refusal either: it lets both callers through. Pick a refusal the store you run against enforces. @@ -57,15 +74,13 @@ Write `TBD` in **Where in the code** while you plan — every row; it names code ### Step 1c — Required reading (do this before you write any code) -End the contract sheet with a **REQUIRED READING** block whose rows carry inline `MUST load ` pointers. **Load every `python-*` skill the sheet names, now, before you start implementing** — not lazily at the step that needs it. The sheet deliberately does *not* carry the how-to: it names the hazard and hands you the skill that resolves it, so an unloaded pointer is a gap in what you know, not a formality. +End the contract sheet with a **REQUIRED READING** block whose rows carry inline `MUST load ` pointers. **Load every `python-*` skill the sheet names, now, before you start implementing** — not lazily at the step that needs it, and even if you have already read the module. The sheet deliberately does *not* carry the how-to: it names the hazard and hands you the skill that resolves it, so an unloaded pointer is a gap in what you know, not a formality. **A fixed floor applies regardless of what the sheet says** — the sheet can add to it, never remove from it: `python-error-handling` always (every integration writes an error boundary); `python-client-initialization` before the client is constructed; `python-testing` before the first test file you create or edit, *including* a throwaway verification script that fakes the transport. A sheet row that excuses one of these ("out of scope", "no test suite requested") is not a substitute for loading it. -These are API-agnostic usage skills; loading them is not a substitute for the lookup layer, and reading a module in the installed package does not remove the need to load the skill for that step. Contract *facts* still come only from your sheet or a fresh lookup. - Before implementing, check the plan's **Assumptions & Blockers** section: -- Blocker or major assumption → surface it to the user in plain language, get their answer, and revise `the-plaid-api-plan.md` in place. +- Blocker or major assumption → surface it to the user in plain language, get their answer, and send it to the SAME planner as a follow-up message (re-start it, carrying the clarification and the plan path, only where your host cannot message it). It revises `the-plaid-api-plan.md` in place and replies with the changed rows verbatim: work from that reply, not a re-read of the file. If you wrote the plan yourself, revise it in place. - Minor assumptions only → proceed. Full re-planning only on genuine scope change; for a single missing fact mid-implementation, do the lookup, never guess. @@ -73,13 +88,13 @@ Full re-planning only on genuine scope change; for a single missing fact mid-imp ### Step 2 — Implement from the contract sheet 1. Read `the-plaid-api-plan.md` once. Treat its contracts as authoritative — do not re-derive or "double-check" them from memory. When a lookup revises a row, update the file so the sheet and the code never disagree. -2. **Decide sync vs async once, from the host application, before the first call** — and take the decision from the repo survey, not from preference. This SDK ships two complete client classes (`Client` / `AsyncClient`) and there is no bridge between them: a sync client in an `async def` blocks the event loop, and an async client in sync code is a coroutine nobody awaits. Getting this wrong is not a local fix later; it is every call site. The choice also changes the transport-override keyword (`custom_http_client` vs `custom_async_http_client`) and the teardown obligation (`close()` vs `await aclose()`). -3. **Pick the response mode per call, deliberately.** Each operation exists twice: the plain call raises `ApiError` on failure, and its `with_raw_response` peer returns `ApiResult` instead. For the operations that return `None`, the raw peer is the only way to observe the status code — so a call whose outcome you must inspect needs the mode chosen at write time, not retrofitted. -4. Implement sequentially, following the repo's own conventions and layering. You loaded the companion skills the sheet named in Step 1c — implement each step in line with the one that governs it. Take every contract *fact* (signatures, wire aliases, error unions, enum members) from the contract sheet or a fresh lookup — never re-derive one from a companion. -5. After every change: run the project's **type checker** (`mypy`/`pyright`) as well as its tests. The package ships `py.typed` and is generated under `mypy --strict`, so a type error against it is a real contract violation, not noise — it is the closest thing Python gives you to the compile step. **Treat a clean type check as the gate you do not skip.** If the project has no type checker configured, install `mypy` into the environment and run `mypy --strict` on the files you touched — the SDK is generated under that setting, so it checks cleanly against it. If you genuinely cannot install one, say so in your final report rather than silently substituting a smoke run. Fix non-SDK errors yourself. -6. **Any error involving an SDK type or member** — an `AttributeError`/`TypeError` on a `the_plaid_api.*` object, a `pydantic.ValidationError` you cannot place, a mypy error naming an SDK type, an unexpected `ApiError` — → go back to `python-getting-started`'s module table and read the one module that owns the fact. Do not attempt more than one self-fix of an SDK-name error before doing that lookup: rewriting from the same knowledge that produced the error is guessing. Remember that a **decode failure raises `ValidationError`/`ValueError`, not `ApiError`, and bypasses both response modes**, and that `httpx2` transport exceptions arrive unwrapped — so an exception that does not look like an API error may still be one of the SDK's failure kinds. +2. **Decide sync vs async once, from the repo survey, before the first call** — `Client` or `AsyncClient`. The two have no bridge, and the choice fixes the transport-override keyword and the teardown (`python-client-initialization`). +3. **Pick the response mode per call, at write time:** the plain call raises `ApiError`; its `with_raw_response` peer returns `ApiResult`, the only way to see the status of an operation that returns `None`. +4. Implement sequentially, in the repo's own conventions and layering, in line with the companion that governs each step. Take every contract *fact* (signatures, wire aliases, error unions, enum members) from the sheet or a fresh lookup — never from a companion. +5. After every change: run the project's **type checker** (`mypy`/`pyright`) as well as its tests. The package ships `py.typed`, so a type error against it is a real contract violation, not noise — it is the closest thing Python gives you to the compile step. **Treat a clean type check as the gate you do not skip.** If the project has no type checker configured, install `mypy` into the environment and run `mypy --strict` on the files you touched — the SDK checks cleanly under it. If you genuinely cannot install one, say so in your final report rather than silently substituting a smoke run. Fix non-SDK errors yourself. +6. **Any error involving an SDK type or member** — an `AttributeError`/`TypeError` on a `the_plaid_api.*` object, a `pydantic.ValidationError` you cannot place, a mypy error naming an SDK type, an unexpected `ApiError` — → go back to `python-getting-started`'s module table and read the one module that owns the fact. Do not attempt more than one self-fix of an SDK-name error before doing that lookup. A decode, connection or authentication failure is an `SdkError` too, though not an `ApiError` (`python-error-handling`). 7. Once the code is complete, open each function the **DUPLICATE CLAIMS** rows name and confirm it runs when that write runs. Where the code falls short of a row, fix the code, not the row. -8. Run the project's tests; verify the integration end to end the way the task demands. Retrying is **on by default**, so decide whether the task keeps it, tunes it through `retry_options`, or turns it off with `max_retries` set to `0`, rather than wrapping the call in a retry of your own — and say which you did. +8. Run the project's tests; verify the integration end to end the way the task demands. Keep, tune (`retry_options`) or disable (`max_retries` set to `0`) the default retries rather than wrapping the call in a retry of your own, and say which you did. Logging is **off by default**: run a new call once under `THE_PLAID_API_LOG=info` to see what went on the wire. ### Step 3 — Answering pure questions @@ -87,11 +102,9 @@ A standalone The Plaid API question with no code change: look it up in `python-g ## Anti-patterns — never do these -- **Always load `python-getting-started` first.** It is your lookup layer, not optional background. (The `python-*` companions are the complement: load the ones the sheet names, per Step 1c.) Don't re-derive a contract *fact* from a companion — exact signatures, wire aliases, error unions and enum members come from the sheet or a fresh lookup. +- **Never create or edit a project file while `the-plaid-api-planner` is running**, and never start a second one for the same integration. - **Never write a The Plaid API/SDK fact from memory** — every signature, field name, enum member, and error union in your code must come from the contract sheet or a lookup. And **never write a call from memory "to fix later".** - **Don't web-search The Plaid API topics to find an implementation detail** — the installed package's own source is the ground truth, and the module table tells you where to look. Public The Plaid API docs describe the REST API, not this SDK's generated surface, and the two disagree on names. - **Never introspect the SDK at runtime to discover its shape.** `dir()`, `model_fields`, `inspect.signature`, or a REPL poke is the Python-flavoured version of decompiling the package: it answers what exists, never what is *supported*, and it silently invites private attributes into your code. Read the source module instead. -- **Don't grep the package to *locate* a type** — the SDK map is the locator (and says so: *"Never grep for a type"*); grep only *inside* the module its **Type sources** table names, for the symbol. A sweep for a *shape* is a different thing, and is fine: "every member typed `Optional[Any]`", "every discriminator field" are cross-cutting questions nothing indexes, and one targeted `grep -rn` over `models/` is the right tool for them — record what it found on the sheet. -- **Don't vendor, `sys.path`-hack, or editable-install the SDK from a throwaway clone** to make a lookup possible. Install the distribution properly into the project's environment (see `python-getting-started`); an editable install pointed at a clone breaks every import the moment the clone is deleted. -- **Don't create or edit project files before the HARD GATE** in Step 1 — plan and contract sheet first, code second. +- **Don't grep the package to *locate* a type** — the map's **Type sources** table is the locator; grep only inside the module it names. A cross-cutting *shape* sweep ("every member typed `Optional[Any]`", "every discriminator field") is fine as one `grep -rn` over `models/`, recorded on the sheet. diff --git a/plugins/plaid/skills/python/python-models/SKILL.md b/plugins/plaid/skills/python/python-models/SKILL.md index cbf33c8f..b4daa979 100644 --- a/plugins/plaid/skills/python/python-models/SKILL.md +++ b/plugins/plaid/skills/python/python-models/SKILL.md @@ -1,6 +1,6 @@ --- name: python-models -description: Working with models in an APIMatic-generated Python SDK — pydantic models and their TypedDict companions, required members vs the UNSET sentinel, why Optional here is not typing.Optional, open enums, union aliases and discriminators, collections, wire aliases, frozen instances, unknown-field preservation, and serializing with to_dict/to_json. Load before constructing request payloads or mapping SDK models onto your own types. +description: Load before building request payloads for an APIMatic-generated Python SDK or mapping its response models onto your own types. Covers pydantic models and their TypedDict companions, required members vs UNSET (Optional here is not typing.Optional), open enums, union aliases and discriminators, wire aliases, unknown-field preservation, and to_dict/to_json. --- # Working with models in an APIMatic Python SDK @@ -18,9 +18,8 @@ REPL poke at the installed package. ## The base every model shares -Domain models subclass a generated base (`{root_package}.core.SdkBaseModel`) with a deliberate -configuration. It is **static generator code, identical in every APIMatic Python SDK**, and four of its -choices change how you write code: +Domain models subclass `{root_package}.core.SdkBaseModel`, configured identically in every APIMatic +Python SDK; four of its settings change how you write code: | Config | What it means for you | |---|---| @@ -48,8 +47,8 @@ class {RequestType}(SdkBaseModel): - **`Optional[T] = UNSET` is optional.** Leave it out entirely and the key is omitted from the JSON. **`Optional` here means `T | UnsetType` — present or absent, with no `None` arm.** It is *not* -`typing.Optional[T]` (`T | None`), and the difference is the arm that matters: a field the spec does -not declare nullable must not be able to reach the wire as `null`. So: +`typing.Optional[T]` (`T | None`), and the difference is the arm that matters: a field that is not +nullable cannot reach the wire as `null`. So: ```python {RequestType}({required_field}="...", {required_list}=[...], {optional_field}=None) # ✗ type error, and rejected @@ -59,9 +58,8 @@ not declare nullable must not be able to reach the wire as `null`. So: Never "clear" an optional field by passing `None`. Omit it, or pass `UNSET` explicitly if you are building the kwargs dynamically. -A field annotated **`OptionalNullable[T]`** (`T | None | UnsetType`) is the three-state case: omitted, -explicitly `null`, or a value. The generator emits it for exactly the properties the spec declared both -optional *and* nullable. There, `None` *is* meaningful — it sends `null`, which for a PATCH-style API +A field annotated **`OptionalNullable[T]`** (`T | None | UnsetType`) — a member both optional *and* +nullable — is the three-state case: omitted, explicitly `null`, or a value. There, `None` *is* meaningful — it sends `null`, which for a PATCH-style API is how you erase a value rather than leave it unchanged. Read the annotation before deciding what `None` means. @@ -99,10 +97,8 @@ rather than a runtime surprise. Three caveats: - the companion is a typing construct only — it performs no runtime validation until the SDK validates the whole body; - it cannot express `UNSET`, so a dict simply omits what it does not set; -- **the closed check only helps if a type checker actually runs.** At runtime the model base is - `extra="allow"`, so a misspelled key that no checker saw is *accepted* and sent as an extra field - rather than rejected (see *Unknown fields are preserved* below). The dict spelling is only as safe - as your `mypy`/`pyright` gate. +- **the closed check only helps if a type checker actually runs.** At runtime a misspelled key is + accepted and sent as an extra field (see *Unknown fields are preserved* below). ## Enums are open @@ -137,10 +133,9 @@ match response.{enum_field}: # handle the open arm explicitly An `if/elif` chain over members with no final `else` silently does nothing for an unknown value. -**Stringifying differs by enum kind.** The generator gives every enum `__str__ = str.__str__`. On a -`(str, Enum)` that is what you want — `str(member)` and f-string interpolation give the **wire value** -(`"{wire_value}"`), not `"{Enum}.{MEMBER}"`, so logging and comparison against raw strings both behave. -On an `(int, Enum)` that same assignment makes `str(member)` raise +**Stringifying differs by enum kind.** On a `(str, Enum)`, `str(member)` and f-string interpolation +give the **wire value** (`"{wire_value}"`), not `"{Enum}.{MEMBER}"`, so logging and comparison against +raw strings both behave. On an `(int, Enum)`, `str(member)` raises `TypeError: descriptor '__str__' requires a 'str' object` — so never interpolate an int-enum member into a log line or an f-string. Use `member.value` (or `int(member)`) instead. @@ -194,8 +189,8 @@ Four things the alias does not show: ## Collections -List properties are `list[T]`; maps are `dict[str, V]` — **the key type is always `str`**, whatever -the spec said. Inside a companion, a model element is typed as that model's companion +List properties are `list[T]`; maps are `dict[str, V]` — **the key type is always `str`**. +Inside a companion, a model element is typed as that model's companion (`list[{Model}Dict]`). ```python @@ -210,10 +205,9 @@ are different wire messages — do not use `[]` to mean "leave this alone". ## Wire aliases -The generator emits a pydantic alias for a field **exactly when the Python name no longer matches the -wire name** — snake-casing a `camelCase` property, sanitizing a name that is not a valid identifier, -escaping a Python keyword (trailing underscore, `type_` for `type`), or de-duplicating a collision. -Where the wire name is already a valid snake_case identifier, no alias is emitted at all. +A field carries a pydantic alias **exactly when its Python name differs from the wire name** — +snake-casing a `camelCase` property, sanitizing a name that is not a valid identifier, escaping a Python +keyword (trailing underscore, `type_` for `type`), or de-duplicating a collision. ```python {field}: Optional[str] = Field(default=UNSET, alias="{wireField}") @@ -224,17 +218,15 @@ input, and output uses the alias. When a sheet lists a member as `{field} (wire `{field}` in code and expect `{wireField}` in a captured request body — do not "fix" a test that asserts the alias. -**The `…Dict` companion is keyed by the PYTHON name, not the alias.** A `TypedDict` cannot declare a -keyword or a non-identifier as a key through class syntax, and the base config's `validate_by_name` is -what makes the Python spelling work: +**The `…Dict` companion is keyed by the PYTHON name, not the alias:** ```python client.{controller}.{operation}(body={"{field}": "..."}) # ✓ the companion's key client.{controller}.{operation}(body={"{wireField}": "..."}) # validates, but type-checks as nothing ``` -The serialized body carries `"{wireField}"` either way. The second form *does* validate at runtime via -`validate_by_alias` — so both happen to work, and only one is checked. Write the Python name. +The serialized body carries `"{wireField}"` either way; both validate at runtime, but only the first +type-checks. Write the Python name. ## Serializing @@ -270,13 +262,11 @@ pydantic_core._pydantic_core.PydanticSerializationError: Unable to serialize unknown type: ``` -`UnsetType` carries its own serializer, but `Any` absorbs the union arm before that serializer is -reached, so the sentinel arrives at pydantic's generic any-serializer, which has never heard of it. Every other `Optional[T]` is fine, and so is a *container* of `Any` (`Optional[list[Any]]`, `Optional[dict[str, Any]]`) — this is specific to a bare `Any` at the top of the annotation. -You get `Any` wherever the spec left a property unconstrained: a free-form object, an anonymous -object, or no schema at all. **Check the contract sheet for which members are typed `Any`** — it is +A member is typed `Any` wherever it is unconstrained: a free-form object, an anonymous object, or +no schema at all. **Check the contract sheet for which members are typed `Any`** — it is usually a small, fixed list, and a JSON-Patch-style `value` member is the classic case, because the ops that take no value are exactly the ones that would leave it unset. @@ -287,17 +277,11 @@ client.{controller}.{operation}(body={Model}({field}=None)) # request body -> {"{field}": null} ``` -It type-checks (`Any` admits `None`) and it serializes. Note the cost: the request now carries -`"{field}": null` where it should have carried nothing. Two consequences worth stating on any sheet -that touches such an operation: - -- an explicit `null` is not the same wire message as an omitted key, so a strict server-side validator - could reject it — confirm against sandbox before shipping; -- this is the one place where `None` on an `Optional[...]` field is correct. Everywhere else it is a - type error (see above). Do not generalise it. - -The dict spelling is no escape — it validates into the same model, sentinel included. If a future SDK -version widens these annotations, drop the explicit `None`. +It type-checks (`Any` admits `None`) and it serializes, at the cost of sending `"{field}": null` +instead of nothing — an explicit `null` is not the same wire message as an omitted key, so a strict +server-side validator could reject it; confirm against sandbox before shipping. This is the one place +where `None` on an `Optional[...]` field is correct; everywhere else it is a type error (see above). +The dict spelling is no escape — it validates into the same model, sentinel included. **The trap fires on the read path too.** A *response* model whose `Any`-typed member the server omitted decodes fine — and then fails `to_dict()` / `to_json()` with the same error, because that @@ -321,8 +305,8 @@ Never pass a raw member straight through to something that will encode it. ## Unknown fields are preserved -Unlike SDKs that drop unmodelled JSON, `extra="allow"` keeps them — at every nesting level, readable -via `model_extra`, and **re-emitted under the key they arrived with**: +`extra="allow"` keeps unknown fields — at every nesting level, readable via `model_extra`, and +**re-emitted under the key they arrived with**: ```python extra = response.model_extra or {} @@ -331,14 +315,14 @@ new_field = extra.get("{some_new_field}") This makes it safe to read an object, change one member and send it back without silently discarding server-side state you never modelled. The symmetry also means an unknown key *you* supply is sent -rather than rejected — convenient for a field newer than the SDK, and a silent no-op when you simply -misspell a real one. A misspelled optional member does not error; it becomes an extra. If a value you -set is not taking effect, check it against the sheet's member list before suspecting the API. +rather than rejected — convenient for a field newer than the SDK, and a silent no-op when you +misspell a real one. If a value you set is not taking effect, check it against the sheet's member list +before suspecting the API. ## Dates and numbers -The generator maps spec types to Python as follows — take the exact type of any given member from the -contract sheet rather than assuming: +Spec types map to Python as follows — take the exact type of any given member from the contract sheet +rather than assuming: | Spec type | Python type | |---|---| @@ -358,8 +342,8 @@ Three consequences: `datetime`/`date` and read one back; do not format strings by hand. Every one of those names is an `Annotated` alias over the stdlib type, declared in `{root_package}/core/converters/date_time.py`: `Date` → `datetime.date`; `RFC3339DateTime`, `RFC1123DateTime` and `UnixSecondsDateTime` → - `datetime.datetime`. The alias only governs the wire format. They are runtime types, so the map's - **Type sources** tables do not list them — this is where they live; do not go searching. + `datetime.datetime`. The alias only governs the wire format. The map's **Type sources** tables do + not list these runtime types. - **There is no `Decimal` arm.** A fractional number becomes `float`, so a spec that models money as a number gives you binary floating point. Most payment APIs instead model money as a **`str`** scaled to the currency (`"10.00"`) — where yours does, build it with `Decimal` and format explicitly, never @@ -387,11 +371,9 @@ Three consequences: amount(Decimal("1.2344"), "KWD") # "1.234" -- not "1.23" ``` -- **`binary`/`file` is never `bytes`.** A file position takes `FileInput` (`AsyncFileInput` on the - async client) and an operation that returns one hands back `FileResponse` (`AsyncFileResponse`). - Both pairs live in `{root_package}.core` rather than `{root_package}.models`, so nothing on this - page applies to them — see **python-file-handling**. Nothing base64-encodes or decodes for you - either: where an endpoint asks for base64, hand it content that already is. +- **`binary`/`file` is never `bytes` at a file position**: it takes `FileInput` and returns + `FileResponse` (`AsyncFileInput` / `AsyncFileResponse` on the async client), from + `{root_package}.core` — see **python-file-handling**. Currency codes are typically plain `str` with no enum — pass `"USD"`. diff --git a/plugins/plaid/skills/python/python-models/reference.md b/plugins/plaid/skills/python/python-models/reference.md index 8524cc0a..2dc7a18f 100644 --- a/plugins/plaid/skills/python/python-models/reference.md +++ b/plugins/plaid/skills/python/python-models/reference.md @@ -16,13 +16,6 @@ from {root_package}.core import UNSET, UnsetType - It is only ever a **default**. Never construct `UnsetType()` yourself; pass `UNSET` if you need to spell "omitted" explicitly while building kwargs. -The two annotations that admit it, one per spelling a spec can declare: - -```python -Optional = T | UnsetType # optional — omitted or a value -OptionalNullable = T | None | UnsetType # optional+nullable — omitted, null, or a value -``` - Building a payload conditionally, without a `None` ever reaching a non-nullable field: ```python @@ -50,18 +43,13 @@ from {root_package}.models.enums import {Enum} {Enum}("{wire_value}") # wire value -> member; ValueError if unknown {Enum}.{MEMBER}.value # -> "{wire_value}" -str({Enum}.{MEMBER}) # -> "{wire_value}" (str enums only — see below) +str({Enum}.{MEMBER}) # -> "{wire_value}" (str enums only; an int enum raises TypeError) list({Enum}) # every member ``` -Coercing an unknown value with `{Enum}(...)` raises `ValueError` — that is the *closed* lookup. -The **open** alias used on model fields (`{Enum}OrStr` / `{Enum}OrInt`) does not raise; it passes the -unknown value through as the underlying scalar. Do not reimplement that coercion at your boundary; -read the field and handle the scalar arm. - -`__str__ = str.__str__` is emitted on **every** enum, which is right for a `(str, Enum)` and wrong for -an `(int, Enum)`: on an int enum, `str(member)` and f-string interpolation raise -`TypeError: descriptor '__str__' requires a 'str' object`. Use `.value` for int enums. +`{Enum}(...)` is the *closed* lookup. The open alias on model fields passes an unknown value through +as the scalar (`SKILL.md` *Enums are open*) — read the field and handle that arm rather than +reimplementing the coercion at your boundary. Tolerating an unknown value when you must map to your own enum: @@ -75,35 +63,14 @@ def to_domain(value: {Enum} | str) -> MyEnum: ## Union aliases — finding the exact arms -A union is a **type alias**, not a class, so there is nothing to construct and nothing to unwrap. The -contract sheet lists the arms; each arm is used directly. The SDK map names the **module** declaring -the alias, not its arms — read them off the alias there. - ```python from {root_package}.models import {Union} # also {root_package}.models.unions.{module} ``` -- **Plain (`anyOf`)** — `{Union}: TypeAlias = {Variant1} | {Variant2}`, with a companion - `{Union}Dict: TypeAlias = {Variant1}Dict | {Variant2}Dict`. Named after its arms when the spec gave - it no name (`{Variant1}Or{Variant2}`). -- **Discriminated (`oneOf` with a discriminator, or an `allOf` base with subtypes)** — - `{Union}: TypeAlias = Annotated[Annotated[{Variant1}, Tag("{value1}")] | …, WireDiscriminator("{tag}")]`. - The tag is the union's: build the variant and the union writes it. Some variants also declare the - tag as a field of their own, in which case it is yours to set. Where the companion alias names a - wrapper (`{Union}{Variant1}Dict`), that is the dict spelling to use — the variant's own dict shape - plus the tag key. -- **One surviving arm** — no alias module is emitted at all; the field is typed with that arm directly - (`{Variant} | None` where a dropped arm was nullable). An alias the sheet does not list does not - exist. -- Read a union back with `isinstance` / `match`; there are no `TryGet…`-style readers. - -Two runtime notes that the annotation does not show: - -```python -{RequestType}({union_field}={"{tag}": "{value}", ...}) # ✓ dict form must carry the tag -{RequestType}({union_field}={...}) # ✗ ValidationError: union_tag_not_found -model.to_dict(exclude_unset=True) # ✗ drops the defaulted tag; no longer validates back -``` +The SDK map names the **module** declaring a union, not its arms — read them off the alias there. An +unnamed `anyOf` alias is named after its arms (`{Variant1}Or{Variant2}`). A discriminated alias exists +for a `oneOf` with a discriminator **and** for an `allOf` base with subtypes. Construction and reading +rules are in `SKILL.md` *Union types*. ## Reading nested optional structures @@ -138,14 +105,6 @@ Unknown keys are also reachable by attribute access **unless** the name collides ## Type-checking notes -The SDK ships `py.typed`, so `mypy`/`pyright` check your calls against it fully. - -- `Optional[T]` from the SDK and `typing.Optional[T]` are **different types**. If you import both into - one module you will confuse yourself and your reader; the SDK's generated modules never import - `typing.Optional` — unions are spelled with PEP 604 `|` — and yours should not shadow the name. -- Passing `None` to an `Optional[T]` field is a type error the checker reports. Believe it — at - runtime it is also a `ValidationError`. (`OptionalNullable[T]` is the annotation that does admit - `None`.) -- A `{Model}Dict` literal is checked structurally, so an unknown key is an error there too. That check - is what makes the dict spelling safe to use at all — it is the *only* thing that catches a - misspelling, since the model base is `extra="allow"` at runtime. +The SDK ships `py.typed`, so `mypy`/`pyright` check your calls against it fully. The SDK's modules +never import `typing.Optional` (unions are spelled with PEP 604 `|`); don't import it into a module +that also uses the SDK's `Optional`, a different type. diff --git a/plugins/plaid/skills/python/python-testing/SKILL.md b/plugins/plaid/skills/python/python-testing/SKILL.md index 883b947a..789ccfc6 100644 --- a/plugins/plaid/skills/python/python-testing/SKILL.md +++ b/plugins/plaid/skills/python/python-testing/SKILL.md @@ -1,6 +1,6 @@ --- name: python-testing -description: Testing code that calls an APIMatic-generated Python SDK — which seam to fake (the transport protocol), asserting on the request the SDK actually built, covering the error and decode-failure paths, and keeping tests independent of SDK internals. Load before writing tests for the integration layer. +description: Load before writing unit or integration tests (pytest or unittest) for code that calls an APIMatic-generated Python SDK. Covers faking the transport protocol, asserting on the request the SDK built, and covering the error, decode, transport and token-fetch failure paths. --- # Testing code that uses an APIMatic Python SDK @@ -24,14 +24,13 @@ Substitute your own `{Api}Client` and operation names as well. The transport is a `Protocol`, so a fake needs no base class, no registration and no `Mock` — just its two methods, `send` and `close`. `send` answers with the response **head**; the body stays on -the stub until something reads it, which is what lets one stub serve a JSON call and a download -alike: +the stub until something reads it: ```python import json from collections.abc import Iterator, Mapping from dataclasses import dataclass, field -from {root_package}.core import HttpRequest, HttpResponse +from {root_package}.core import HttpMethod, HttpRequest, HttpResponse @dataclass class StubResponse: @@ -40,6 +39,7 @@ class StubResponse: status_code: int = 200 headers: Mapping[str, str] = field(default_factory=dict) chunks: list[bytes] = field(default_factory=list) + method: HttpMethod = "GET" # what a streamed payload names in its errors, with url url: str = "https://api.test/resource" closed: bool = False @@ -82,9 +82,7 @@ def json_response(status: int, body: object) -> StubResponse: ) ``` -A download is queued exactly like anything else: one seam means one kind of stubbed response, and -nothing about the stub says which operation it answers. Assert on `StubResponse.closed` to prove the -caller consumed the body and released the connection. +Assert on `StubResponse.closed` to prove the caller consumed the body and released the connection. `chunks` defaults to empty, so an empty `204` is just `StubResponse(status_code=204)` — which is what an operation declaring no response body expects (`python-calling-endpoints`). @@ -94,8 +92,7 @@ Wire it in and you have a real client with no network: ```python def client_returning(*responses: StubResponse) -> tuple[{Api}Client, StubTransport]: transport = StubTransport(*responses) - # retry_options=0: retries are on by default, so without it a stubbed 429 or 503 on a GET would be - # sent four times, with real waits between them. + # retry_options=0 turns off the default retries (see Notes): one stubbed response, one send. client = {Api}Client(custom_http_client=transport, retry_options=0, {scheme}=...) return client, transport ``` @@ -106,10 +103,10 @@ contract sheet lists. Its value is that scheme's type: a plain `str` for a beare the credentials model or dict for basic auth or an OAuth grant (`python-authentication`). **Do not patch the client's private attributes** (`_raw_client`, `_auth`, …) and do not -`Mock(spec={Api}Client)`. Both couple your tests to internals the generator is free to change, and a +`Mock(spec={Api}Client)`. Both couple your tests to internals that change without notice, and a mocked client cannot catch the mistakes that actually happen — a wrong path parameter, a body that does not serialize, a header you forgot. Faking the transport exercises the real request-building -pipeline; that is the whole point. +pipeline. ### The token request comes first @@ -129,8 +126,8 @@ assert len(transport.requests) == 2 req = transport.last_request # index from the end, not [0] ``` -Or bypass acquisition entirely with a stub token source — the generator's supported injection point -(`python-authentication`) — so the stub transport only ever sees your operation: +Or bypass acquisition entirely with a stub token source (`python-authentication`), so the stub +transport only ever sees your operation: ```python from {root_package}.core import OAuthTokenRefreshable @@ -157,7 +154,8 @@ client = {Api}Client( The token is **cached on the scheme**, so only the first call fetches one: a test making two calls against one client sees three requests, not four. Forgetting the token request is the most common way a first test fails confusingly — the operation's decoder is handed the token body, and you get a -`ValidationError` about your payload rather than anything mentioning auth. The tests below queue only +`ResponseDecodeError` (a `ValidationError` about your payload on `__cause__`) rather than anything +mentioning auth. The tests below queue only the operation's response; for OAuth where the SDK fetches the token itself, put `token_response()` first (except in the bad-credentials test). @@ -217,17 +215,14 @@ def test_unmapped_status_is_raw(): # Body on demand: .text() always, .json() only if you know it is JSON (it raises ValueError). ``` -**Take the union from the contract sheet per operation.** The typed arm is not one type across the -API, so an error test copied from a sibling operation can pass for the wrong reason — it lands in the -`RawError` branch and asserts nothing about the typed body you meant to check. And never assert on -`str(e)` or `repr(e)`: they render as status plus payload *type name* by design, and are not a stable -contract. +**Take each operation's union from its own sheet row** — an error test copied from a sibling +operation can land in the `RawError` branch and pass for the wrong reason, asserting nothing about the +typed body you meant to check. ## Test the result-style (`with_raw_response`) variant -If your code uses the non-raising peer (`python-calling-endpoints`), there is nothing to catch — stub -the response and assert on the returned `ApiResult` directly. The split is mechanical: **2xx is -`Success`, everything else is `Failure`**, and both carry `.status_code` and `.headers`. +If your code uses the non-raising peer, there is nothing to catch — stub the response and assert on +the returned `Success` / `Failure` (`python-calling-endpoints`): ```python from {root_package}.core import Failure, Success @@ -243,9 +238,7 @@ def test_raw_response_reports_failure_without_raising(): assert "/{expected/path}" in transport.last_request.url # the operation, not the token ``` -This is also the mode to test in when your code depends on a header on the *success* path -(`Success(payload=..., status_code=..., headers=...)`), because the parsed form exposes neither — -except for a file response, which carries its own `headers` on the parsed path. +Test in this mode when your code reads a header on the *success* path. ## Assert the outgoing request @@ -253,66 +246,60 @@ except for a file response, which carries its own `headers` on the parsed path. actually change: ```python +import json from {root_package}.core import JsonBody req = transport.last_request assert req.method == "POST" assert req.url.endswith("/{expected/path}") assert "{query_param}=..." in req.url # query is part of the URL string -assert isinstance(req.body, JsonBody) and isinstance(req.body.value, dict) # narrow before indexing -assert req.body.value["{wire_field}"] == "..." # JsonBody carries the dumped payload +assert isinstance(req.body, JsonBody) # narrow before reading +assert json.loads(req.body.content)["{wire_field}"] == "..." # JsonBody carries the wire bytes assert req.headers["authorization"] == "Bearer t" # lowercase key — see below assert req.headers["{header}"] == "..." # a real default reached the wire ``` -**`HttpRequest.headers` keys are lowercased, not just the response's.** Every layer — the API's, the -endpoint's, the auth scheme's and your own `extra_headers` — is normalized before the merge, which is -exactly what makes the merge case-insensitive. So `req.headers["Authorization"]` is a `KeyError` and -`req.headers["authorization"]` is the assertion you want. This is the single most common way a first -request assertion fails confusingly. (The defensive `"authorization" in {k.lower() for k in -req.headers}` also works, but there is no case to defend against — assert the lowercase key.) +**`HttpRequest.headers` keys are lowercased**, at every layer — the API's, the endpoint's, the auth +scheme's and your own `extra_headers` — so assert `req.headers["authorization"]`; +`req.headers["Authorization"]` is a `KeyError`. **The body is already serialized by the time a transport sees it.** `req.body` is one of `JsonBody` -(`.value`, the dumped JSON-safe object), `FormBody` (`.fields`), `MultipartBody` (`.parts`, an -ordered sequence of `MultipartText` and `MultipartFile` — **not** a `.fields`/`.files` pair, and a -file part's `content` is the unread descriptor you passed, never bytes), `BinaryBody` -(`.content`, `.media_type`) or `TextBody` (`.text`, `.media_type`, `.charset`) — no transport ever -serializes anything — so assert on the dumped value -directly rather than re-parsing bytes. Note it uses **wire aliases**, because that is what -serialization produces: if a model's Python name differs from its JSON name, the request body has the -JSON name. Do not "fix" that in the test. - -**A list-valued query or form parameter has a per-parameter wire format.** The `Param` the generator -emitted for it in `apis/{controller}.py` carries a `SerializationFormat` — `indexed` -(`name[0]=a&name[1]=b`, URL-encoded as `name%5B0%5D=a`), `unindexed` (`name[]=a&name[]=b`), `plain` -(`name=a&name=b`), or `csv` / `tsv` / `psv` (`name=a,b`). Read it before asserting on `req.url`; -`"name=a" in req.url` is the assertion that fails against an indexed parameter. Path and header -arrays are not configurable — both fold to one comma-separated value. +(`.content`, the compact UTF-8 JSON bytes, and `.media_type`), `FormBody` (`.content`, the +url-encoded bytes), `MultipartBody` (`.parts`, an ordered sequence of `MultipartText` and +`MultipartFile` — **not** a `.fields`/`.files` pair; a text part's `.content` is its UTF-8 bytes, and a +file part's `.content` is the unread descriptor you passed, never bytes), `BinaryBody` +(`.content`, `.media_type`) or `TextBody` (`.content`, `.media_type`, `.charset`). Parse the JSON bytes +with `json.loads` and assert on the result — there is no dumped object to read — and expect **wire +aliases**: a member whose Python name differs from its JSON name is under the JSON name +(`python-models`). + +**A list-valued query or form parameter has a per-parameter wire format** — the `SerializationFormat` +on its `Param` in `apis/{controller}.py`: `indexed` (`name[0]=a&name[1]=b`, URL-encoded as +`name%5B0%5D=a`), `unindexed` (`name[]=a&name[]=b`), `plain` (`name=a&name=b`), or `csv` / `tsv` / +`psv` (`name=a,b`). Read it before asserting on `req.url`; `"name=a" in req.url` is the assertion that +fails against an indexed parameter. Path and header arrays always fold to one comma-separated value. Worth asserting once, somewhere, because they are silent when wrong: -- **The value actually reached the wire.** Models *preserve* unknown fields rather than rejecting them - (`python-models`), so a misspelled optional member becomes a preserved extra field instead of an - error. The only thing that catches it is an assertion on the serialized body. +- **The value actually reached the wire.** A misspelled optional member becomes a preserved extra + field, not an error (`python-models`); only an assertion on the serialized body catches it. - **Idempotency keys**, on operations that accept one: the same logical operation retried sends the *same* value, and two different operations send different ones (`python-configuration-resilience`). -- **Timeout plumbing.** `req.timeout` reflects a per-call `request_options={"timeout": ...}` and - **only** that. The client's own `timeout=` never rides the request — it configures the SDK's default - transport — so `req.timeout is None` on an ordinary call is correct, not a bug. A test that asserts - the client-level timeout on a captured request is asserting something that was never there; and once - you supply a stub transport, the client's `timeout=` reaches nothing at all. +- **Timeout plumbing.** `req.timeout` carries a per-call `request_options={"timeout": ...}` and + **only** that, so it is `None` on an ordinary call. The client's own `timeout=` never rides the + request — it configures the SDK's default transport, and with a stub transport it reaches nothing. - **Bodies that cannot serialize.** A value the SDK cannot dump raises *before* anything is sent, so the failure never reaches your stub and `transport.requests` stays empty. Worth one test where it applies (`python-models`). ## Cover the failures that are not `ApiError` -Three failure kinds never match `except ApiError`, and code that handles only the raised-`ApiError` -path is the norm (`python-error-handling`). Each is cheap to simulate. +Three failure kinds never match `except ApiError` (`python-error-handling`); each is cheap to +simulate. -**A decode failure — and it bypasses *both* response modes.** A body that does not deserialize raises -`pydantic.ValidationError` (or a plain `ValueError` for a non-JSON body). `with_raw_response` does -**not** turn it into a `Failure`: +**A decode failure** raises `ResponseDecodeError` (pydantic's `ValidationError`, or a plain `ValueError` +for a non-JSON body, on `__cause__`) in both response modes — `with_raw_response` does **not** turn it +into a `Failure`: ```python def test_unreadable_success_body_is_not_reported_as_failure(): @@ -324,9 +311,8 @@ def test_unreadable_success_body_is_not_reported_as_failure(): assert "/{expected/path}" in transport.last_request.url # the operation, not the token ``` -**A truncated 2xx that decodes cleanly.** Members are required only where the description marks them -required — often nowhere — so a response missing a member validates fine and reads back `UNSET`. Only -your own guard catches it, so test the guard: +**A truncated 2xx that decodes cleanly.** A response missing an optional member validates fine and +reads back `UNSET` (`python-error-handling`). Only your own guard catches it, so test the guard: ```python def test_truncated_success_body_is_not_reported_as_success(): @@ -337,28 +323,35 @@ def test_truncated_success_body_is_not_reported_as_success(): assert "/{expected/path}" in transport.last_request.url # the operation, not the token ``` -**A transport failure**, which arrives as the HTTP library's own exception, unwrapped — have the stub -answer any token response you queue, then raise on the operation's request: +**A connection failure**, which arrives as `SdkConnectionError` with the HTTP library's exception on +`__cause__`. A transport owes that shape, so the stub raises it too: answer any token response you +queue, then raise on the operation's request: ```python +import httpx2 +from {root_package}.core import SdkConnectionError, SdkTimeoutError, safe_url + class RaisingTransport(StubTransport): - """Answers the queued responses, then raises `error` on the next send.""" + """Answers the queued responses, then raises the family's exception for `cause` on the next send.""" - def __init__(self, error: Exception, *responses: StubResponse) -> None: + def __init__(self, cause: httpx2.TransportError, *responses: StubResponse) -> None: super().__init__(*responses) - self._error = error + self._cause = cause def send(self, request: HttpRequest) -> HttpResponse: if self._responses: # a queued token response, if any return super().send(request) self.requests.append(request) - raise self._error + method, url = request.method, safe_url(request.url) + if isinstance(self._cause, httpx2.TimeoutException): + raise SdkTimeoutError(f"{method} {url} timed out", method=method, url=url, timeout=5.0) from self._cause + raise SdkConnectionError(f"{method} {url} could not be sent: {self._cause}", method=method, url=url) from self._cause -def client_raising(error: Exception, *responses: StubResponse) -> tuple[{Api}Client, RaisingTransport]: +def client_raising(cause: httpx2.TransportError, *responses: StubResponse) -> tuple[{Api}Client, RaisingTransport]: # Pass token_response() only for OAuth where the SDK fetches the token itself (no # {scheme}_token_source); never for bearer, API key or basic auth. - transport = RaisingTransport(error, *responses) + transport = RaisingTransport(cause, *responses) return {Api}Client(custom_http_client=transport, retry_options=0, {scheme}=...), transport @@ -378,16 +371,13 @@ def test_read_timeout_is_an_unknown_outcome(): assert "/{expected/path}" in transport.last_request.url # the operation, not the token ``` -**Two transport failures, both inputs — never one.** A refused connection was never sent, so its -outcome is known: nothing happened. A read timeout may have landed, so its outcome is not. Test both -and expect **different** values — as the two tests above, or as the single two-input test -`python-error-handling` shows. A test that builds only one of them, or two that one assertion -satisfies, cannot tell the cases apart — and then neither can your code. When the SDK fetches a token, -let the token request through first: a failure *there* means your operation was never sent at all, -whatever the exception is called. +Test both inputs and expect **different** values: a test of only one, or two that one assertion +satisfies, cannot tell a never-sent failure from one that may have landed. When the SDK fetches a +token, let the token request through first — a failure *there* means your operation was never sent at +all. -And the one people forget: **bad credentials**. A failed token fetch raises `ApiError` too, but its -payload is `OAuthProviderError | RawError` — *not* the operation's union — and it surfaces out of the +And the one people forget: **bad credentials**. A failed token fetch raises `AuthSchemeError`, with +the token endpoint's `ApiError` on `__cause__` (never the operation's), and it surfaces out of the operation call. Return an RFC 6749 error body from the **token** request and assert your configuration error, not a rejection error: @@ -407,13 +397,14 @@ the response with `aiter_bytes`, `aread` and `aclose`, so queue an `AsyncStubRes ```python from collections.abc import AsyncIterator -from {root_package}.core import AsyncHttpResponse, HttpRequest +from {root_package}.core import AsyncHttpResponse, HttpMethod, HttpRequest @dataclass class AsyncStubResponse: status_code: int = 200 headers: Mapping[str, str] = field(default_factory=dict) chunks: list[bytes] = field(default_factory=list) + method: HttpMethod = "GET" # what a streamed payload names in its errors, with url url: str = "https://api.test/resource" closed: bool = False @@ -473,11 +464,8 @@ a `# type: ignore`. derives its payload from the model's own definition cannot detect a wrong payload. - **Build fixtures with models, then serialize** — `{request_fixture}().to_dict()` — rather than hand-writing wire JSON, so a member rename fails the fixture instead of passing a stale test. -- **Test your own boundary's output, not the SDK's.** The valuable assertions are that a 4xx the - caller caused becomes your 4xx, a 4xx that is **yours** — `401`, `403`, `429` — becomes your `502` - or `503`, and a transport failure becomes `502` if it was never sent and `504` if it may have landed - (`python-error-handling`). That the SDK raises `ApiError` on a 422 is the SDK's own tested - behaviour, not yours. +- **Test your own boundary's output** — the `provider_error` mapping in `python-error-handling` — not + that the SDK raises `ApiError` on a 422, which is the SDK's own tested behaviour. ## Integration tests against a live environment @@ -506,20 +494,18 @@ never gate CI on a third party's uptime unless you mean to. `retry_options=0` so one stubbed response is seen exactly once. In a test *about* retrying, set a policy with `initial_delay` and `max_jitter` small, queue one response per attempt and count `transport.requests`. For the loop to retry a - *transport* failure the fake must raise `TransportError` from `{root_package}.core` — a - bare `httpx2.ConnectError` bypasses the loop and reaches the test on the first attempt + *connection* failure the fake must raise `SdkConnectionError` from `{root_package}.core`, as + `RaisingTransport` does — a bare `httpx2.ConnectError` bypasses the loop and reaches the test, + unwrapped, on the first attempt (`python-configuration-resilience`). -- **A `401` invalidates the cached token but does not retry the request.** A test that stubs a `401` - therefore sees one failed operation — and the *next* call in the same test re-fetches a token, so - queue another `token_response()` for it. +- A stubbed `401` fails one operation and the *next* call re-fetches a token + (`python-authentication`), so queue another `token_response()` for it. - Mocking libraries (`unittest.mock`, `pytest-mock`) work too — the protocol is structural, so a `Mock()` with `send` and `close` configured satisfies it. The hand-written stub above gives you typed captured requests and ordered responses for free. -- **Stubbing a download** needs nothing extra: the SDK wraps the same `StubResponse` in the - `FileResponse` your assertions see, so the stub decides what the caller reads and when the - connection is released. Give it `chunks` if the test drives `iter_bytes`. What the caller may then - do with it — and the `ResourceWarning` an abandoned one emits, which a category default filters - unless you enable it here — is `python-file-handling`. +- **A download** is the same `StubResponse`, wrapped in the `FileResponse` your code sees; give it + `chunks` if the test drives `iter_bytes`. Making an abandoned download's `ResourceWarning` fail a + test is in `python-file-handling`. - **Use the client as a context manager or close it** in tests as in production; a stub's `close()` is a no-op, but the habit keeps the test and the real wiring the same shape (`python-client-initialization`). diff --git a/plugins/plaid/skills/typescript/typescript-authentication/SKILL.md b/plugins/plaid/skills/typescript/typescript-authentication/SKILL.md index ae49a764..c676f732 100644 --- a/plugins/plaid/skills/typescript/typescript-authentication/SKILL.md +++ b/plugins/plaid/skills/typescript/typescript-authentication/SKILL.md @@ -1,12 +1,12 @@ --- name: typescript-authentication -description: Authentication for an APIMatic-generated TypeScript SDK — supplying credentials on the client options object, the credential shape each scheme kind takes, OAuth 2 token caching and refresh, and replacing the token source. Load before wiring credentials into the client, or when a call comes back 401/403. +description: Load before setting credentials on an APIMatic-generated TypeScript SDK client, or when a call returns 401/403 — API keys, bearer and basic auth, the OAuth 2 client-credentials, password and authorization-code grants, token caching and refresh, and supplying your own token source. --- # Authenticating an APIMatic TypeScript SDK client -How you authenticate depends on the security scheme(s) the API declares. APIMatic surfaces each scheme -as an **optional credential member on `ClientOptions`**; set the one(s) your API uses, then construct +How you authenticate depends on the security scheme(s) the API declares. Each scheme is an +**optional credential member on `ClientOptions`**; set the one(s) your API uses, then construct the client (see `typescript-client-initialization`). There is no separate credentials builder, no per-request auth override, and no way to change a credential after construction. @@ -24,19 +24,17 @@ scheme factory as shared runtime code regardless of what the API accepts, so rel rather than that folder. Where a member's name does not tell you its kind, `src/auth-schemes.ts` shows which core factory each member is wired to. -The credential types below live under `src/core/auth/` and are exported from the package root; they -are the **same across all APIMatic TypeScript SDKs**. Only the **option member names** are generated -per-API (hence the `{scheme}` placeholders). The generator distinguishes **eight** scheme kinds — that -list is closed, so if the spec declared something outside it, read `src/auth-schemes.ts` to see what -was actually emitted rather than assuming a ninth shape. The eight collapse to **three** credential +The credential types below live under `src/core/auth/`, are exported from the package root and are +the **same across all APIMatic TypeScript SDKs**; only the **option member names** are per API (hence +the `{scheme}` placeholders). There are exactly **eight** scheme kinds, taking **three** credential shapes: | Scheme kind | `ClientOptions.{scheme}` type | Sent as | | --- | --- | --- | | HTTP bearer | `TokenProvider` | `Authorization: Bearer {token}` | -| API key in header | `TokenProvider` | the spec's header name | -| API key in query | `TokenProvider` | the spec's query parameter | -| API key in cookie | `TokenProvider` | a `Cookie` pair under the spec's name | +| API key in header | `TokenProvider` | the API's header name | +| API key in query | `TokenProvider` | the API's query parameter | +| API key in cookie | `TokenProvider` | a `Cookie` pair under the API's name | | HTTP basic | `BasicAuthCredentials` | `Authorization: Basic base64(user:pass)` | | OAuth 2 client credentials | `OAuth2ClientCredentials` | `Authorization: Bearer {fetched token}` | | OAuth 2 password | `OAuth2PasswordCredentials` | `Authorization: Bearer {fetched token}` | @@ -72,7 +70,7 @@ Sends `Authorization: Bearer ACCESS_TOKEN`. ## API key (header, query, or cookie) The key is sent as a header, query parameter, or cookie — its placement and name are fixed by the -generated scheme, not by anything you pass. Set the configured key member to your key string: +SDK, not by anything you pass. Set the configured key member to your key string: ```ts const client = new {Api}Client({ {scheme}: process.env.API_KEY! }); @@ -124,9 +122,9 @@ The SDK fetches and caches the token itself, acquiring a fresh one when it expir invalidates the cached token and re-acquires on the next call. `scope` is a **single space-delimited string**, not a list — you join it yourself, per RFC 6749 §3.3. -An empty string is treated as absent and no `scope` field is sent. The generator emits **no scope -enum or literal union** even where the spec declares a scope vocabulary, so a scope the flow does not -document type-checks fine and fails at the provider instead. +An empty string is treated as absent and no `scope` field is sent. It is typed plain `string` — **no +scope enum or literal union** — so a scope the provider does not offer type-checks and fails at the +provider. ## OAuth 2.0 — authorization code (3-legged, with PKCE) @@ -158,8 +156,8 @@ The URL handed to your callback carries `response_type=code`, `client_id`, `redi never see or manage it. - **`promptForAuthorizationCode` is called lazily**, on the first request needing the scheme — the - same point at which the other grants fetch their token. In a server app that is almost never what - you want mid-request; see *Supplying your own token source* below. + same point at which the other grants fetch their token. For a server app, see *Supplying your own + token source* below. - **PKCE is on by default.** Omitting `pkce` means `PkceMethod.S256`; `pkce: null` disables it. The verifier and challenge are generated with `crypto.getRandomValues` / `crypto.subtle`, so the runtime needs Web Crypto (Node 20+ and browsers have it). @@ -185,19 +183,18 @@ on the authorization request and never generated or checked here — the SDK nev producing and verifying it are yours alone. Your redirect handler must compare it against what you generated before returning the code, or the CSRF token is decorative. -⚠ **`clientSecret` is optional in the type, and only one of the two ways it can be missing throws.** +⚠ **`clientSecret` is optional in the type, and leaving it out throws only when PKCE is off.** | PKCE | `clientSecret` missing ⇒ | | --- | --- | | disabled (`pkce: null`) | `AuthError("A client secret is required when PKCE is disabled…")` — **before** the prompt runs | -| enabled, token request is header-placed | no error: the SDK sends `Authorization: Basic base64(clientId:)` and the provider rejects it — **after** the user has completed the full browser round-trip | -| enabled, token request is body-placed | fine — this is the public-client case | +| enabled | fine — this is the public-client case: the code exchange and every refresh send `client_id` as a form field and no `Authorization` header | -The placement is fixed by the spec, not by you, and is visible as the `placement` argument in -`src/auth-schemes.ts` (`"header"` sends `Authorization: Basic base64(clientId:clientSecret)` on the -token request; `"body"` sends `client_id` / `client_secret` as form fields). Check which one your -generated `src/auth-schemes.ts` passes before treating the secret as optional — the header case's -failure is the expensive one, because it costs an interactive login before the exchange fails. +An empty string counts as missing. The placement is not yours to choose: it is the `placement` +argument in `src/auth-schemes.ts` — `"header"` sends `Authorization: Basic +base64(clientId:clientSecret)` on the token request, `"body"` sends `client_id` / `client_secret` +as form fields. Without a secret, both placements send `client_id` alone, so a public client works +whichever one your spec chose. ## OAuth 2.0 — resource owner password @@ -215,7 +212,8 @@ const client = new {Api}Client({ ## Token caching & refresh (all OAuth 2 grants) -- Tokens are cached **in memory, per client instance**, and reused until **30 s** before expiry. +- Tokens are cached **in memory, per client instance**, and reused until **30 s** before expiry, or + for **half their lifetime** when that is longer. - Acquisition is **lazy** — on the first request that requires the scheme, not at construction. A client built with bad credentials constructs perfectly happily; the failure surfaces at the first operation. One in-flight acquisition is **shared**: concurrent requests that arrive during a fetch @@ -223,48 +221,39 @@ const client = new {Api}Client({ - The fetch is a form-encoded `POST` to the token endpoint, sent with **no auth scheme of its own**, and it runs on its own `retry.timeout` and the call's abort signal — so token-fetch time does not come out of the operation's attempt. -- **A failure while obtaining the token is not retried by the call.** It ends the call. -- **The token request is itself a `POST` under the same policy.** With the default - `httpMethodsToRetry`, an error status from the token endpoint — a `503` included — is not retried: - it is an `AuthError` and ends the call. Name `POST` in the gate and the token request retries a - retryable status like any other `POST`; the `AuthError` ends the call once those retries are spent. +- **A failure while obtaining the token ends the call.** The token request is itself a `POST` under the + client's retry policy, so with the default `httpMethodsToRetry` even a `503` from the token endpoint + is an immediate `AuthError`; name `POST` in the gate and the token request retries a retryable status + first. - **The cache lives in the client object.** Build the client once (see `typescript-client-initialization`) or every call re-runs the grant. -- **Only the authorization-code grant refreshes.** It is the one grant wired to - `oauth2RefreshableScheme` / `OAuth2RefreshableTokenStrategy`. Client-credentials and - resource-owner-password re-run the whole grant when the token expires — and a `refresh_token` in a - password-grant response is **discarded**, because the non-refreshable `OAuthToken` has no field for - it. Do not infer refresh behaviour from what the provider returns. -- When the authorization-code grant does refresh, a refresh response that omits `refresh_token` - carries the previous one forward. A refresh that fails does not throw — it returns `null` internally - and falls back to a full re-grant. +- **Only the authorization-code grant refreshes.** Client-credentials and resource-owner-password + re-run the whole grant when the token expires, and a `refresh_token` in a password-grant response is + **discarded** — do not infer refresh behaviour from what the provider returns. A refresh response + that omits `refresh_token` keeps the previous one, and a failed refresh does not throw: it falls back + to a full re-grant. - On `401`, the cached token is invalidated and re-acquired on the **next** call — `401` is not in the - default `statusCodesToRetry`, so the failing request is **not** re-sent. Handle the 401 as an ordinary `ApiError` (see `typescript-error-handling`); - the recovery is automatic on the following attempt, not on this one. + default `statusCodesToRetry`, so the failing request is **not** re-sent; handle it as an ordinary + `ApiError` (see `typescript-error-handling`). Add `401` to `statusCodesToRetry` to have the failing + call re-sent with a fresh token — every attempt resolves its credential again. A static key is + re-sent unchanged, so that only helps a scheme that fetches its credential. +- **Invalidation is a hint, not a barrier.** It clears the cache without cancelling a token fetch + already in flight, so that fetch can complete and re-populate it; "invalidate, then read" does not + guarantee a fresh token. ⚠ **A `401` on the authorization-code grant is an interactive re-authorization, not a silent refresh.** Invalidation clears the whole cached token, refresh token included, so "re-acquired" means the *full* grant runs again and `promptForAuthorizationCode` fires. Expiry takes the refresh path; a `401` does not. Plan for that in a non-interactive host. -⚠ **The 30-second buffer is flat, with no floor.** A token whose `expires_in` is **30 or less** is -already past its adjusted deadline the moment it is cached, so every request re-runs the grant and the -cache never serves anyone. There is no half-of-lifetime fallback for short tokens. If your provider -issues sub-minute tokens, supply your own token strategy rather than paying a token round-trip per -call. - -⚠ **If the token response omits `expires_in`, the token never expires as far as the SDK is -concerned** — and a non-positive `expires_in` is treated the same way. `expires_in` is RECOMMENDED but -not required by RFC 6749, and the SDK's expiry check short-circuits to "not expired" when it is -absent, so the first token is cached for the life of the client and the only thing that ever replaces -it is a `401`. That is usually fine and occasionally not: a token revoked server-side keeps being sent -until a request fails with it. If your provider omits `expires_in` and you need proactive rotation, -supply your own token strategy (below) rather than trying to bound the cache. - -- **Invalidation is a hint, not a barrier.** It clears the cache without cancelling an acquisition - already in flight, so that fetch can complete and re-populate it. That is deliberate — the newer - token post-dates the invalidation — but it means "invalidate then immediately read" is not a - guarantee of a fresh token. +**A short-lived token is renewed halfway through its lifetime.** The 30-second buffer applies to a +token issued for a minute or more; below that, the token is reused for half its `expires_in` — a 20 s +token for 10 s. So no token is stale the moment it is cached, and a sub-minute token costs one token +round-trip per half-lifetime rather than one per call. + +⚠ **A token response without a positive `expires_in` never expires in the cache** — the first token +is kept for the life of the client and only a `401` replaces it, so a token revoked server-side is +sent until a request fails with it. For proactive rotation, supply your own token strategy (below). ### Supplying your own token source @@ -311,42 +300,10 @@ turns into a redirect attempt inside a request. ## The failure mode that surprises everyone -**A failed token fetch surfaces out of your *operation* call, and `.asApiResult()` does not protect -you from it.** - -Auth is resolved inside the same dispatch the operation runs through, so both consequences follow from -one fact — the token fetch happens *during* your operation: - -1. **The traceback points at the operation you called**, not at anything named "auth". A token - endpoint that answers `400 invalid_client` becomes an `AuthError` thrown from - `client.{resource}.{operation}(...)`, with the underlying `ApiError` on `.cause` — and its own - `method` and `uri` name that operation, not the token endpoint. Reading only the top frame sends you - looking in the wrong place entirely. -2. **The non-throwing form still rejects.** `.asApiResult()` converts the *operation's* error response - into an `{ ok: false }` result instead of throwing — but auth is resolved before any response - exists, so an `AuthError` propagates straight out of the `await`. Code written specifically to - avoid exceptions still needs a `try`/`catch` around an authenticated call. - -So a boundary that only inspects `result.ok` is incomplete: - -```ts -import { AuthError } from "{package-name}"; - -try { - const result = await client.{resource}.{operation}(request).asApiResult(); - if (!result.ok) { /* the operation's own error union */ } -} catch (err) { - if (err instanceof AuthError) { - // Credentials/token problem — the operation request was never sent. - throw new Error("API credentials rejected", { cause: err }); - } - throw err; -} -``` - -Treat it as an **auth** failure, distinct from an operation rejection: nothing was attempted, -so retrying it or reporting it as a failed operation are both wrong. `typescript-error-handling` has -the full catch ladder. +A token endpoint that answers `400 invalid_client` rejects the *operation* call with `AuthError` — its +`method`/`uri` name the operation, the token endpoint's `ApiError` is on `.cause`, nothing was sent, +and `.asApiResult()` does not convert it. Catch it around every authenticated call; the ladder is in +**typescript-error-handling**. ## Combined / multiple schemes @@ -361,10 +318,6 @@ by `allAuth(...)` / `anyAuth(...)`; you configure it by setting the relevant cre not on which looks more specific. A `TokenProvider` **function** always counts as "has credentials", even if it returns an empty string — so a function provider always wins the OR. -**This layer never withholds a request over a missing credential, and never throws for one.** An -unconfigured member simply drops out and the request goes out with whatever *was* configured; with -nothing configured at all it goes out unauthenticated. The server decides. - Because composition is **per operation**, one client may authenticate different operations with different schemes — so set every member the operations your integration actually calls need, not just the ones the API's front page advertises. The per-operation requirement is the **Auth** bullet on the @@ -373,10 +326,8 @@ out: `` `{scheme}` ``, `all of …`, or `any of … — the first one configured ## No auth -An operation the spec marked public is wired to `noneAuth` and sends **no credential even when every -option member is filled**. Its **Auth** bullet reads `none — public; no credential is sent`. Nothing -you pass at construction adds a credential to such an operation — if it needs one, that is a spec -problem, not a configuration one. +An operation whose **Auth** bullet reads `none — public; no credential is sent` sends **no credential +even when every option member is filled**, and nothing you pass at construction adds one. ## ⚠ Missing credentials must stop the app from starting @@ -394,31 +345,10 @@ An API that serves anonymous traffic at all — public endpoints, or a reduced r callers — makes this worse by answering `200` and hiding the omission entirely. So verify the member is actually set rather than waiting for a `401` to tell you. -**A required credential that is not configured is a deployment fault, not a request fault.** If the -app boots with a blank secret, an operator sees a provider outage, retry logic hammers a call that can -never succeed, and the actual cause — an unset environment variable — is two layers away from the -symptom. There is no `.env` support and no `fromEnvironment()` helper in the SDK, so **validate at the -call site and refuse to boot**: - -```ts -function buildClient(): {Api}Client { - const key = process.env.API_KEY; - if (!key) { - throw new Error( - "API_KEY is not configured. Set it via environment variable or your secret store " + - "before starting the app.", - ); - } - - return new {Api}Client({ - serverEnvironment: ServerEnvironment.Production, - {scheme}: key, - }); -} -``` - -Run that check **before** the app is ready to serve — at module load or in your startup path, not -lazily on first use, which is a request, which is exactly the late failure you are trying to avoid. +**A required credential that is not configured is a deployment fault, not a request fault.** There is +no `.env` support and no `fromEnvironment()` helper in the SDK, so **validate every required +credential in your startup path and refuse to boot** — not lazily on first use, which is a request. +The factory in **typescript-client-initialization** shows the shape. Three rules for the message it fails with: @@ -435,38 +365,26 @@ absent, so a blank env var is the same fault as an unset one. ## Notes -- A given SDK only exposes the credential members for the schemes its API declares; those names are - generated per-API (hence the `{scheme}` placeholders above). Fill every member the operations you - call need. - **Credentials are fixed at construction.** `ClientOptions` is `readonly` and the auth schemes are built in the constructor, so to rotate a credential you use a `TokenProvider` **function**, replace the strategy, or build a new client. There is no mutable accessor. - **Rotating a long-lived client:** the token cache is per client instance, so swap atomically — build the new client, then replace the shared reference. In-flight calls finish on the old one and there is no window where calls have no credential. Do not mutate the old client. -- **Auth wins every header, query and cookie collision.** Auth params are merged **last**, after the - client's defaults and the endpoint's own, so a scheme's `Authorization` header overwrites anything - set earlier under that name. There is no per-request header override to undo it — a `fetch` wrapper - is the only place you can strip or replace an auth header (see +- **Auth wins every header, query and cookie collision** — a scheme's `Authorization` header + overwrites anything else under that name, and only a `fetch` wrapper can strip or replace it (see `typescript-configuration-resilience`). - **Nothing hides secrets in a log you write.** Credentials are plain objects with no redacting `toString`, so `console.log(options)` or a serialized `ClientOptions` prints them in full. The SDK's - own logging, off by default, masks the `Authorization` header, a query value off its safe list and - the OAuth form keys (`client_secret`, `password`, `refresh_token`, …) — but a JSON request body it - logs verbatim once `logRequestBody` is on (see **typescript-configuration-resilience**). -- On the OAuth 2 token request, header placement sends `base64(clientId:clientSecret)` **without - percent-encoding either half** first. A client id or secret containing a character RFC 6749 §2.3.1 - would have you encode is sent raw, so a provider that follows the RFC strictly may reject it — use - body placement or a custom strategy if your secret is not in the unreserved set. -- **`AuthError` means a credential could not be obtained** — the token request failed, every - configured branch of an alternatives requirement failed, PKCE was disabled without a secret, or your - `promptForAuthorizationCode` rejected. Being *refused* a credential by the API is an `ApiError` with - status 401/403 instead, so one `catch` arm cannot absorb the other. A token endpoint that answers with - an error status surfaces as `AuthError` with that `ApiError` on `.cause`; an alternatives requirement - whose every branch failed carries an `AggregateError` there, holding each branch's failure. -- Credentials never appear in a thrown error's message. -- **A token endpoint may live on a different server group than the operations.** Overriding - `serverOptions.default.{environment}.baseUrl` therefore does not move the token request — override - that group too if you need both redirected at a mock. See `typescript-configuration-resilience`. -- Keep secrets out of source — read `process.env` or your secret manager at the call site. Set - credentials **before** constructing the client; there is no way to add them afterwards. + own logging masks a credential in a header, the query or an OAuth form body, but not in a JSON request + body (**typescript-configuration-resilience**). +- On the OAuth 2 token request, header placement with a secret sends + `base64(clientId:clientSecret)` **without percent-encoding either half** first. A client id or + secret containing a character RFC 6749 §2.3.1 would have you encode is sent raw, so a provider that + follows the RFC strictly may reject it — use body placement or a custom strategy if your secret is + not in the unreserved set. +- `AuthError` (a credential could not be *obtained*) versus a 401/403 `ApiError` (refused by the API): + **typescript-error-handling**. +- A token endpoint may live on its own server group, so redirecting the operations' group at a mock + does not move it (**typescript-configuration-resilience**). +- Keep secrets out of source — read `process.env` or your secret manager at the call site. diff --git a/plugins/plaid/skills/typescript/typescript-calling-endpoints/SKILL.md b/plugins/plaid/skills/typescript/typescript-calling-endpoints/SKILL.md index 74e5dd04..df47f393 100644 --- a/plugins/plaid/skills/typescript/typescript-calling-endpoints/SKILL.md +++ b/plugins/plaid/skills/typescript/typescript-calling-endpoints/SKILL.md @@ -1,16 +1,16 @@ --- name: typescript-calling-endpoints -description: Calling operations on an APIMatic-generated TypeScript SDK — finding the resource that owns an operation, building the one flat channel-blind request object, required vs optional vs defaulted fields and the values that never appear on the request at all, passing a body, the ApiPromise return and the two ways to read it, bounded concurrency, and cancellation. Load before writing the first call to an SDK operation, or when an operation's shape or return type is unclear. +description: Load before writing the first call to an APIMatic-generated TypeScript SDK operation, or when an operation's request shape or return type is unclear — the one flat request object, required, optional, defaulted and SDK-fixed fields, request bodies and file uploads, binary responses, reading an `ApiPromise` or `.asApiResult()`, the `Pageable` walk a paged operation returns, and per-call retry and cancellation. --- # Calling endpoints on an APIMatic TypeScript SDK -Operations are **methods returning `ApiPromise`** on the client. Most are **grouped under a resource -getter** and called `client.{resource}.{operation}(...)`; an operation the spec left untagged sits -**directly on the client**, called `client.{operation}(...)`. The resource getter, the exact operation -name and its signature come from the generated SDK map (grounded in `src/client.ts` and -`src/resources/`) — operation names follow no fixed verb/resource pattern, so take the real name from -the map, never from memory. +Operations are **methods returning `ApiPromise`** on the client — or `Pageable`, for an operation the +API pages (see [A paged operation](#a-paged-operation)). Most are **grouped under a resource +getter** and called `client.{resource}.{operation}(...)`; an operation with no resource group sits +**directly on the client**, called `client.{operation}(...)`, and an SDK may have no resource level at +all. Take the getter, the exact operation name and its signature from the SDK map, never from memory — +operation names follow no fixed verb/resource pattern. > Throughout this skill, `{...}` is a placeholder for a name you take from your SDK (e.g. `{Api}Client`, > `{package-name}`, `{resource}`, `{Resource}`, `{Operation}`, `{Enum}`) — replace it with the concrete @@ -30,8 +30,7 @@ the map, never from memory. the docs do not carry. Both the docs and `src/` ship inside `node_modules/{package-name}/`, so read them there rather than the -compiled `dist/`. **Do not assume a `client.{resource}` level exists** — when the spec declares no tags, -or exactly one tag covering every operation, no resource classes are emitted at all. +compiled `dist/`. Resource classes are exported from the package root, but only for their merged namespaces and for `instanceof`. Never construct one: its constructor takes engine internals that are not exported. @@ -44,26 +43,23 @@ Every operation has the same shape, with no positional overload and no sync vari {operation}(request: {Resource}.{Operation}Request, options?: RequestOptions): ApiPromise ``` -- **There is exactly one request parameter**, and it is **not optional** — even when every field on it - is. An all-optional request still needs `{}` passed explicitly. -- **`options` is on every generated operation**, always last, always optional. It is - `RequestOptions` = `{ signal?: AbortSignal; retry?: RequestRetryOptions }` and nothing else — see +- **There is exactly one request parameter.** It is required when any field on it is. When every field + is optional it defaults to `{}`, so the call may leave it out — `{operation}()` sends what + `{operation}({})` sends. +- **`options?: RequestOptions` is on every operation**, always last — see [Cancellation and per-call retry](#cancellation-and-per-call-retry). -- **An operation may declare no request parameter at all.** When every value the request carries is - fixed by the spec, the generator emits no parameter and exports no request type, and `options` moves - into first position. Check the **Signature** bullet before passing `{}` — it will not type-check - against an operation whose only parameter is `RequestOptions`. +- **An operation whose every value is fixed takes no request parameter** and has no request type; + `options` is then its only parameter. Check the **Signature** bullet before passing `{}` — it will + not type-check against such an operation. ```ts await client.{resource}.{operation}(); // no request await client.{resource}.{operation}({ signal }); // options only ``` -- **The map is the source of truth for the signature.** Whether a field is required, optional or - defaulted — and whether the operation takes a body at all — varies per operation. -- **Return type** varies by operation — see - [Making the call and reading the response](#making-the-call-and-reading-the-response). -- A non-2xx response **rejects** the promise unless you opt out with `.asApiResult()` — see - **typescript-error-handling**. +- Requiredness, defaults, whether there is a body, and the return type all vary per operation — read + each from its map entry. +- A paged operation returns `Pageable` in place of `ApiPromise`, and its **Returns** + bullet names the paging strategy and what ends the walk. ## The request object is flat and channel-blind @@ -90,27 +86,18 @@ the field list either, so the table is the only place to learn what went on the ### Where a field lands — the rule -Each value the spec declares produces **one of four** outcomes, and the last one catches people out: - -| What the spec declares | What you get | +| In the map | What you get | |---|---| -| **required**, no fixed value | `f: T` — a required member of the request object | -| **optional** | `f?: T` — omit it and nothing is sent for it | -| a **default value** | `f?: T` — omit it and the SDK **still sends the default** | -| a **constant** value | **no field at all** — the value is baked into the request and you cannot change it | - -Three consequences worth taking off the map before you write the call: - -- **A constant appears in no signature and in no Fields table.** Its only listing is the operation's - **SDK-sent** bullet, which spells each fixed pair as it goes on the wire. If you are hunting for a - field to set a `Content-Type`, an API version or a fixed `grant_type` with, that is why you cannot - find one — and there is no override for it short of wrapping `fetch`. -- **"Required" says nothing about the channel.** A required field may travel in the query, a header or - the form body just as easily as the path; requiredness and channel are independent columns. Never - infer one from the route. -- **Field names are the generated `camelCase` identifiers, not the wire names.** A header field - `traceId` is transmitted as `X-Trace-Id`, and the `Wire` column is where that mapping lives — it is - written only where the two differ, so a `—` means they match. +| `Req` yes | `f: T` — a required member of the request object | +| `Req` no, no `Default` | `f?: T` — omit it and nothing is sent for it | +| a `Default` | `f?: T` — omit it and the SDK **still sends the default** | +| listed only under **SDK-sent** | **no field at all** — a fixed value (a `Content-Type`, an API version, a `grant_type`) spelled as it goes on the wire; no override short of wrapping `fetch` | + +- **Requiredness and channel are independent.** A required field may travel in the query, a header or + the form body just as easily as the path; never infer one from the route. +- **Field names are `camelCase` identifiers, not the wire names.** A header field `traceId` is + transmitted as `X-Trace-Id`; the `Wire` column gives the wire name where the two differ, and `—` + means they match. The request type is declared in the resource's merged namespace, so it is `{Resource}.{Operation}Request` — importable from the package root if you want to name it: @@ -123,17 +110,11 @@ const request: {Resource}.{Operation}Request = { /* ... */ }; ## Building request models -**A JSON, text or binary operation has a `body` field.** Where the API declares an -`application/x-www-form-urlencoded` or `multipart/form-data` request, the generator emits the parts as -**individual flat request fields** alongside the path and query ones and assembles the form itself — -there is no nested body object to construct and no `body` field to pass. The operation's **Request -body** bullet says which you are looking at; the signature settles it. - -The runtime carries six request-body shapes: **empty, JSON, form-urlencoded, text, multipart and -binary**. An **XML** body has no carrier, so the operation is still emitted but **degrades to no body -field at all** — there is nothing to supply the payload through, and the request goes out with no -body. Its **Request body** bullet reads `none` in that case. If you need such an endpoint, call it -with `fetch` directly; the SDK cannot send it. +**A JSON, text or binary operation has a `body` field; a form-urlencoded or multipart operation has +none** — its parts are **individual flat request fields** beside the path and query ones, and the SDK +assembles the form. The operation's **Request body** bullet says which. An **XML**-body operation has +no body field and sends no body (its **Request body** reads `none`); call that endpoint with `fetch` +directly. **A file field takes bytes, not a path.** Every binary `body` field and every multipart file field is typed `FileInput`, which is a `Blob`, a `Uint8Array`, an `ArrayBuffer`, a `ReadableStream` of bytes, @@ -156,64 +137,38 @@ the read, so an unread stream holds the connection until you read it, cancel it `signal`. A server-chosen file name is untrusted input: sanitise it before writing to disk. -For the JSON case, the `body` field's type is a generated model — a plain object literal, no builders. -Required members must be set; optional ones are omitted from the JSON when left `undefined`, except one -with a spec default (`s.defaulted(...)` in the model's schema), which the SDK fills in and sends. Take the -type's name and the file that declares it from the **Type sources** table: - -```ts -const result = await client.{resource}.{operation}({ - body: { - requiredProp: value, // required members must be provided - optionalProp: value, // optional; unset means omitted, unless it has a spec default - }, -}); -``` - -A body's **shape varies**: some are flat scalars, others nest an inner model. The **Fields** table and -the model file named beside it carry the real members. +For the JSON case, the `body` field's type is a generated model written as a plain object literal +(**typescript-models**); take its name and the file that declares it from the **Type sources** table. -**An optional-looking body is not permission to omit it.** A `body?: T` reflects what the *spec* marked -optional, not what the endpoint needs. A create whose body is optional in the spec type-checks with -`{}` passed and then fails at the provider. Where a call obviously needs a payload, pass one. +**An optional-looking body is not permission to omit it.** A `body?: T` is optional only in the type: +a create passed `{}` type-checks and then fails at the provider. Where a call obviously needs a +payload, pass one. ### Defaults are sent, not omitted -A field the spec gave a default is filled **by the SDK** when you omit it, and it goes on the wire. -Omitting such a field is therefore not "let the server decide" — the server sees the value. Which -fields have defaults is the `Default` column of the **Fields** table. +An omitted field with a `Default` is filled **by the SDK** and sent, so the server sees the default, +and the response is the one that default asked for — a verbosity switch defaulting to the minimal form +(a create resolving to little more than an id and a status), or a field selector defaulting to one +section. Read the `Default` column **before** concluding the API dropped data — it was never +requested. -**And a default can silently narrow what comes back.** A defaulted field is *always sent*, so the -response you get is the one that default asked for, not the full resource. The two shapes that cost -people an afternoon: +### Every value is shape-checked before anything is sent -- a representation or verbosity switch defaulting to the minimal form, so a create resolves to little - more than an id, a status and some links; -- a field selector defaulting to one section, so whole branches of the response are simply absent. - -Read the `Default` column **before** concluding the API dropped data — it was never requested. - -### Every value is validated before anything is sent - -Each field is schema-encoded on the way out. A wrong type or a malformed format (a bad date string, +Each field is schema-encoded on the way out: a wrong type or a malformed format (a bad date string, say) rejects with an `EncodeError` — its `cause` the `SchemaError` naming the field — and **nothing is -sent**: no request reaches the network. That is an error in -your code, not an API failure; see **typescript-error-handling**. - -## Enums - -Enum fields take a member of the generated `const` object. The type alias is **open** — it carries a -`| (string & {})` (or `| (number & {})`) tail — so a raw string also type-checks: +sent** (**typescript-error-handling**). -```ts -import { {Enum} } from "{package-name}"; +A value constraint the spec declares — `minLength`, `pattern`, `minimum`, `uniqueItems`, a checked +`format` such as `email` — is **not** applied by the operation, so a value that breaks one is sent as +built and refused, if at all, by the service. Whether `{model}Schema.validate(body)` checks it first, +and whether an operation exports a `{Group}.{operation}RequestSchema` to `validate` the request object +against, is stated in **typescript-models** (*Checking a value before you send it*). Either `validate` +returns `{ success: true }` or `{ success: false, message }` with every failing field named. -await client.{resource}.{operation}({ status: {Enum}.Active }); // preferred — a rename is caught -await client.{resource}.{operation}({ status: "active" }); // also compiles -``` +## Enums -Prefer the member: the string form silently survives a spec change that renames the value. See -**typescript-models** for read-back semantics and for guarding an unknown value off the wire. +Enum fields take a member of the generated `const` object — `{ status: {Enum}.Active }`. A raw string +also compiles (the type is open), but only the member catches a rename. See **typescript-models**. ## Union types, collections, and dates @@ -228,10 +183,9 @@ Some fields are not plain scalars: `oneOf`/`anyOf`/polymorphic unions declared u const value = await client.{resource}.{operation}({ /* ... */ }); ``` -> **Wrap the call in error handling — a non-2xx response *rejects*, it is not signalled by the return -> value.** The bare `await` above shows only the happy path. Before writing a real call, **load -> `typescript-error-handling`** for the `try`/`catch` shape and which error type to narrow on per -> operation — or use the non-throwing `.asApiResult()` form below. +> **A non-2xx response *rejects*.** Before writing a real call, **load `typescript-error-handling`** for +> the `try`/`catch` shape and which error type to narrow on per operation — or use the non-throwing +> `.asApiResult()` form below. Operations return `ApiPromise`, a `Promise` subclass. Two ways to consume it: @@ -256,25 +210,18 @@ type ApiResult = payload: PayloadOf }; ``` -Five things to know: - -- **`.asApiResult()` must be called on the value the operation returned.** `ApiPromise` overrides +- **Call `.asApiResult()` on the value the operation returned.** `ApiPromise` overrides `Symbol.species`, so `.then()`, `.catch()` and `.finally()` hand back a plain `Promise` and the - method is gone. `op(...).then(x => x).asApiResult()` does not compile. -- **`.asApiResult()` still rejects for every other failure** — a body that would not decode, a value that - would not encode, a connection error, a timeout, a credential that could not be obtained, or a caller - abort. It converts only the *HTTP error status* branch into a value, so it still needs a - `try`/`catch` around it. -- **On failure, `outcome` carries the error's own members, not the error object** — `status`, - `headers`, `message`, `method`, `uri` and `payload` — so `outcome.payload.kind` narrows exactly as - `err.payload.kind` would. The `ApiError` instance is not reachable through this path. -- **Nothing suppresses an unhandled rejection.** A call you never await that fails is reported by the - runtime — `unhandledRejection` on Node, which by default ends the process. `.asApiResult()` marks the - promise handled as its first act, so call it on the returned value in the same turn, and never start - a call you do not consume. -- **Both paths read one underlying outcome**, so awaiting an `ApiPromise` *and* calling - `.asApiResult()` on it issues no second request. The request goes out when the operation is called, - not when you await it — which also means a call you build and hold has already been sent. + method is gone — `op(...).then(x => x).asApiResult()` does not compile. +- **It converts only the HTTP error status.** Every other failure still rejects, so keep the + `try`/`catch`; on failure `outcome` carries the error's members, not the error object + (**typescript-error-handling**). +- **The request goes out when the operation is called**, not when you await it; awaiting and + `.asApiResult()` read the same outcome and never send twice, so a call you build and hold has already + been sent. +- **Nothing suppresses an unhandled rejection.** A call you never consume that fails is an + `unhandledRejection` — on Node, by default, the process ends. `.asApiResult()` marks the promise + handled as its first act, so call it on the returned value in the same turn. ### Status and headers @@ -284,73 +231,77 @@ deliberately unreachable. ### The success type -`T` is whatever the operation's success body decodes to. The **Returns** bullet names it, and the cases -you will meet are: +The operation's own **Returns** bullet names `T`, which can differ between sibling operations: -- **A model type** — a JSON body decoded through the generated schema. The **Type sources** table names - the file under `src/models/` where you read its shape; the map does not duplicate it. -- **A primitive** — a `text/plain` body decoded by the plain-text scalar decoder, not by a model. -- **`undefined`** — the operation's success response has no body. That is a real value, not a mistake: - the decoder asserts the body is empty, and a non-empty one rejects with `DecodeError`. +- **A model type** — a JSON body decoded through its schema. The **Type sources** table names the file + under `src/models/` where you read its shape. +- **A primitive** — a `text/plain` body. +- **`undefined`** — no body; a non-empty one rejects with `DecodeError`. Resolving *is* the success + signal: do not test the value, re-read the resulting state with a separate call if you need it, and + use `.asApiResult()` to tell a `200` from a `204`. +- **`EventStream`** — a `text/event-stream` body. The call resolves at the response headers with + nothing read, and `for await` over the stream yields each event's decoded `data` as a `T`; the + stream holds its connection until the loop ends or you `close()` it. Load + **typescript-event-streams** before you write the loop. -**On an `undefined` operation, resolving *is* the success signal.** Do not bind the value and do not -test it — success is "did not reject", exactly as for the others. Two follow-ons: if you need the -resulting state, re-read it with a separate call; and if you need to tell a `200` from a `204`, -`.asApiResult()` is the only place the status appears. +### A paged operation -Endpoints in the same family can differ, so let each operation's own **Returns** bullet decide how you -read it. +An operation the API pages returns **`Pageable`** instead of `ApiPromise`. The +**Signature** bullet shows it, and the **Returns** bullet names the strategy and what ends the walk. +Nothing is sent when you call it: the walk is lazy, the first page goes out when a loop starts, and +each new loop starts again from the first page. -## Cancellation and per-call retry +```ts +// Items, across every page — the SDK fetches the next page as the previous one runs out: +for await (const item of client.{resource}.{operation}({ /* ... */ })) { + process(item); +} -`RequestOptions` is the entire per-call surface: +// Pages, when you need the page's own members (a total, a cursor, a link): +for await (const page of client.{resource}.{operation}({ /* ... */ }).pages()) { + process(page.{items}); +} -```ts -type RequestOptions = { - signal?: AbortSignal; - retry?: RequestRetryOptions; // Pick -}; +// The result form — an error status as a value instead of a throw: +for await (const result of client.{resource}.{operation}({ /* ... */ }).asApiResult().pages()) { + if (!result.ok) break; // the failed page is the last one the walk yields +} ``` -`retry` overrides three fields of the client's retry policy for this call alone, field by field — a -field you leave out keeps the client's value: +The request's paging fields (`page`, `offset` or `cursor`, and `limit`) **seed the first page** with +their declared defaults applied; the SDK advances the page, offset or cursor from there. `options` +applies to every page the walk sends. Either loop throws `E` at the first error status, and every +other failure exactly as an awaited call would reject — a `{Api}Error` member, or a caller abort's +own `reason`. An item loop over `.asApiResult()` **ends silently** at an error status, so use +`.pages()` on the result form when the distinction matters. **Every walk needs a bound of your +own** — a page cap, an item cap or a deadline; **typescript-configuration-resilience** carries the +strategies, their stop rules and the bounded shape. + +## Cancellation and per-call retry + +`RequestOptions` = `{ signal?: AbortSignal; retry?: RequestRetryOptions; logging?: RequestLoggingOptions }` +is the entire per-call surface. `retry` overrides `maxRetries`, `timeout` and `statusCodesToRetry` for +this call, field by field — a field you leave out keeps the client's value — and `logging` takes only a +`level`. Headers, base URL, auth and the other retry and logging fields are client-level only +(**typescript-client-initialization**, **typescript-configuration-resilience**). ```ts await client.{resource}.{operation}({ /* ... */ }, { retry: { maxRetries: 0 } }); // one attempt await client.{resource}.{operation}({ /* ... */ }, { retry: { timeout: 5_000 } }); // 5 s per attempt -``` - -There is **no** per-call header, base URL or auth override, and the type admits no other retry field -(though the runtime honours one it is handed) — those belong on -`ClientOptions` at construction (**typescript-client-initialization**), and the retry policy's other -fields on `ClientOptions.retry` (**typescript-configuration-resilience**). -```ts const controller = new AbortController(); setTimeout(() => controller.abort(new Error("too slow")), 5_000); - await client.{resource}.{operation}({ /* ... */ }, { signal: controller.signal }); ``` -An already-aborted signal rejects immediately. See **typescript-configuration-resilience** for -deadlines across a whole call and for combining signals. - -Three mechanics that decide how you catch the result: - -- **Your signal and each attempt's `retry.timeout` race the same internal controller**, so an - attempt ends on whichever fires first. `retry.timeout` bounds **one attempt**, in milliseconds, even - when set per call — an idempotent call that keeps failing gets up to four of them, plus backoff — so - a signal plus your own timer is how you bound the whole call. An abort also cuts a backoff wait short, - and is never retried. -- **An abort rejects with the signal's own `reason`, unwrapped, and a timeout with `TimeoutError`** - once no retry is left. - Whatever you passed to `controller.abort(reason)` — or the `DOMException` a bare `abort()` supplies — - is what the call rejects with, so it is **not** an `{Api}Error`; the timeout is the SDK's own and - stays in the family. -- **Neither is an `ApiError`.** A `catch` that narrows on `ApiError` — or on an operation's declared - error class — will **not** match an abort, a timeout or a connection failure. See - **typescript-error-handling** for a ladder over the whole family, and for rethrowing what is outside - it. +- `retry.timeout` bounds **one attempt**, in milliseconds, even when set per call — an idempotent call + gets up to four attempts plus backoff — so only your `signal` bounds the whole call + (**typescript-configuration-resilience** for deadlines and combining signals). An abort — an + already-aborted signal included — ends the call at once, cuts a backoff wait short and is never + retried. +- An abort rejects with the signal's own `reason`, unwrapped, and an exhausted timeout with + `TimeoutError`. Neither is an `ApiError`, and the abort is not an `{Api}Error` at all — see + **typescript-error-handling** for a ladder over the whole family. ## Concurrency @@ -386,8 +337,11 @@ const all = await mapLimit(ids, 10, (id) => client.{resource}.{operation}({ id } Note that `Promise.all` rejects on the first failure and leaves the rest of the batch running unobserved; `Promise.allSettled` is usually what you want when partial success is acceptable. -Nothing is paginated and nothing is async-iterable, so there is no `for await` form. If an operation -returns a page, advance its page or cursor field yourself in a loop — see +A paged operation returns a `Pageable`: `for await` it and the SDK fetches the pages one at a time — +see [A paged operation](#a-paged-operation). The only other `for await` form is over an +`EventStream`, which only an operation whose **Returns** bullet reads `EventStream` hands back +(**typescript-event-streams**). A list operation whose **Signature** returns `ApiPromise` is a single +call; to page one of those, advance its page or cursor field yourself in a loop — see **typescript-configuration-resilience**. ## Worked example — a list/GET call @@ -425,7 +379,8 @@ if (!outcome.ok) { > This operation's success body is a model that nests its list under a member, so you read that member > and then iterate. Another operation may return the array directly, or a primitive, or `undefined`. -> Check its **Returns** bullet. +> Check its **Returns** bullet — and when its **Signature** returns `Pageable`, it is walked with +> `for await` rather than awaited (see [A paged operation](#a-paged-operation)). ## Next diff --git a/plugins/plaid/skills/typescript/typescript-client-initialization/SKILL.md b/plugins/plaid/skills/typescript/typescript-client-initialization/SKILL.md index 8f8dcacf..8e23d37f 100644 --- a/plugins/plaid/skills/typescript/typescript-client-initialization/SKILL.md +++ b/plugins/plaid/skills/typescript/typescript-client-initialization/SKILL.md @@ -1,6 +1,6 @@ --- name: typescript-client-initialization -description: Creating and reusing an APIMatic-generated TypeScript SDK client — construction, the ClientOptions shape, fetch ownership and client lifetime, and wiring the client into an application's startup. Load before wiring the client into an app or writing the factory that builds it. +description: Load before writing the code that builds an APIMatic-generated TypeScript SDK client — `ClientOptions`, environments and base URLs, client lifetime and the token cache, wiring the client into app startup or dependency injection, ESM and CommonJS, and inbound webhooks. --- # Initializing an APIMatic TypeScript SDK client @@ -18,8 +18,8 @@ from the SDK you are using: - `{resource}` / `{operation}` — a resource getter on the client and an operation on it. - `{scheme}` — a credential member on the options object, one per auth scheme the API declares. -Everything under `src/core/` is vendored static code that is **byte-identical in every generated -TypeScript SDK**, so the engine behaviours below hold without checking yours. What varies per SDK is +Everything under `src/core/` is **the same in every APIMatic TypeScript SDK**, so the engine behaviours +described in these skills hold without checking yours. What varies per SDK is `src/client.ts`, `src/client-options.ts`, `src/servers.ts`, `src/auth-schemes.ts`, `src/resources/` and `src/models/`. @@ -42,8 +42,8 @@ Two facts about where those files live: `dist`, `src`, `README.md`, `api-reference.md`, `sdk-map.md` and `map`, so the readable TypeScript source and the lookup index are both inside `node_modules/{package-name}/`. Read them there rather than the compiled `dist/`. -- **`dist/` must exist before the package can be referenced.** The SDK builds with `tshy`; a freshly - generated SDK consumed by path needs its `build` script run once. A `Cannot find module` on a +- **`dist/` must exist before the package can be referenced.** The SDK builds with `tshy`; an SDK + consumed by path needs its `build` script run once. A `Cannot find module` on a path-installed SDK is usually this, not a bad import. ## Shape of the client @@ -59,69 +59,52 @@ Nothing on it is required and neither is the argument, so `new {Api}Client()` co object is the whole configuration surface, and reading the environment into it is yours to do at the call site. -Operations are exposed on the client. Most are grouped under **resource getters** (one per API -resource group) and called `client.{resource}.{operation}(...)` — for example, a `widgets` resource's -`listWidgets` operation is `client.widgets.listWidgets(...)`. But when the spec declares **no tags**, -or exactly **one tag covering every operation**, no resource classes are emitted at all and every -operation sits **directly on the client**, called `client.{operation}(...)`. The available resource -getters (and any direct operations) come from the contract sheet (grounded in `src/client.ts` and -`src/resources/`) — not from the API's own documentation, and not from the compiled `dist/`. See -**typescript-calling-endpoints**. +Operations hang off resource getters, `client.{resource}.{operation}(...)`, or sit directly on the +client when the SDK has no resource level — take them from the contract sheet, not the API's own +documentation (**typescript-calling-endpoints**). -The options type always carries these five knobs (credential members vary per API — see +The options type always carries these six knobs (credential members vary per API — see **typescript-authentication**): ```ts export type ClientOptions = { - readonly serverEnvironment?: ServerEnvironment; // selects the base URL - readonly serverOptions?: ServerOptions; // per-server, per-environment baseUrl override - readonly retry?: RetryOptions | undefined; // retry policy + per-attempt timeout (MILLISECONDS). - // Retries ON by default - readonly logging?: LoggingOptions | undefined; // request/response logging — OFF by default - readonly fetch?: FetchLike | undefined; // the ONE transport extension point — - // see typescript-configuration-resilience + readonly serverEnvironment?: ServerEnvironment; // selects the base URL + readonly serverOptions?: ServerOptions; // per-server, per-environment baseUrl override + readonly retry?: RetryOptions | undefined; // retry policy + per-attempt timeout (MILLISECONDS). + // Retries ON by default + readonly logging?: LoggingOptions | undefined; // request/response logging — OFF by default + readonly eventStream?: EventStreamOptions | undefined; // event-stream idle timeout (MILLISECONDS) — + // read only by an EventStream operation + readonly fetch?: FetchLike | undefined; // the ONE transport extension point — + // see typescript-configuration-resilience // + one OPTIONAL credential member per auth scheme the API declares, and — for an OAuth2 scheme — // a {scheme}Strategy member alongside it (see typescript-authentication) }; ``` -Those five names are minted by the generator and cannot move; a credential spelled like one of them is -the member that takes a suffix instead. **Every member is `readonly`**, and the client captures your -options once, at construction — a different configuration means a new client. Each default is -applied where the value is read: a server variable takes the `@default` on its member in -`src/client-options.ts`, `fetch` takes its in `src/core/client-options.ts`, every `retry` field -takes its in `src/core/retry.ts`, and every `logging` field its in `src/core/logging.ts`. Read them -there rather than trusting the numbers on this page. -Note in particular that the default `serverEnvironment` is the **first** environment the spec -declares, which is not necessarily the production one. - -**Retries are on by default.** With `retry` left out, a `GET`, `HEAD`, `PUT` or `OPTIONS` call that -gets a `408`, `429`, `500`, `502`, `503` or `504`, or loses its connection, or times out, is re-sent -up to **3** more times with exponential backoff and jitter, honouring `Retry-After`. A `POST`, -`PATCH` or `DELETE` is sent once unless you name its method in `httpMethodsToRetry`. Every one of -those numbers is a `RetryOptions` field you can change, and `retry: { maxRetries: 0 }` turns retrying -off. So **a failed idempotent call surfaces only after its retries are spent** — seconds later than the -first failure, not at it. **typescript-configuration-resilience** owns the policy: the field table, -what is and is not retried, and per-call overrides. - -**`fetch` is not a niche escape hatch — it is the only transport seam there is.** The SDK carries -**no hooks, middleware or interceptors**, **no pagination** and **no streaming**. Each of those is -something you build by wrapping `fetch` — including a header you want on every request. -**typescript-configuration-resilience** carries the wrappers. **Logging is built in and off by -default**: `logging` turns it on, and so does the `{APICLIENTTYPENAME}_LOG` environment variable (the -client class name in upper snake case, plus `_LOG`) when code sets neither a `logger` nor a `level` — so a -deployment can start writing request lines with no code change. `retry.onRetry` is the one built-in -callback, and it sees only retries. A replacement `fetch` is called with one `Request` and no `init`, -and **must forward that `Request`, or its `signal`,** to whatever performs the request; drop the signal -and both cancellation and every attempt's timeout go inert. - -`retry.timeout` has its own trap: it is in **milliseconds**, it bounds **one attempt** — up to -its response headers — not the whole call, and a value the platform cannot honour is **not** "no timeout" — it is -resolved once when the client is built, and a negative, fractional, `NaN`, `Infinity` or out-of-range -value silently falls back to the default (`60_000`) rather than failing. A usable value reaches the -timer verbatim, so `timeout: 0` aborts every attempt instead of lifting the deadline. A single call -may override `maxRetries`, `timeout` and `statusCodesToRetry`, and its log level, through -`RequestOptions` = `{ signal, retry, logging }`; nothing else is per call. +Those six names are fixed in every SDK; a credential named like one of them carries a suffix +instead. **Every member is `readonly`**, and the client captures your options once, at construction — +a different configuration means a new client. Each default is applied where the value is read: a +server variable takes the `@default` on its member in `src/client-options.ts`, `fetch` takes its in +`src/core/client-options.ts`, every `retry` field takes its in `src/core/retry.ts`, every +`logging` field its in `src/core/logging.ts`, and `eventStream.idleTimeout` its in +`src/core/event-stream.ts`. Read them there rather than trusting the numbers on this +page. The default `serverEnvironment` is the **first** `ServerEnvironment` member, which is not +necessarily the production one. + +**Retries are on by default**: an idempotent call (`GET`, `HEAD`, `PUT`, `OPTIONS`) that fails +retryably is re-sent up to 3 more times with backoff, so its failure surfaces seconds late, and +`retry.timeout` (milliseconds) bounds each attempt, not the call; `retry: { maxRetries: 0 }` turns +retrying off. **typescript-configuration-resilience** owns the policy. + +**`fetch` is the only transport extension point.** The SDK has no hooks or middleware, and streams +only a `text/event-stream` response, through an operation that resolves to an `EventStream` +(**typescript-event-streams**) — build anything else by wrapping `fetch` +(**typescript-configuration-resilience**). A replacement must +forward the `Request` it is handed, or its `signal`, or cancellation and timeouts go inert. **Logging is +built in and off by default**, and the `{APICLIENTTYPENAME}_LOG` environment variable (the client class +name in upper snake case, plus `_LOG`) can turn it on with no code change +(**typescript-configuration-resilience**). ## Direct instantiation @@ -148,9 +131,9 @@ accepted and fails later, one layer from its cause: | Passed at construction | When it actually fails | | --- | --- | -| a `retry` field out of range — a negative or fractional `timeout`, a `maxJitter` above `1`, a lower-cased `"get"` in `httpMethodsToRetry` | never — that field silently falls back to its default. `timeout: 0` is the exception: it is kept, and aborts every attempt. There is no `ValueError` equivalent here | +| a `retry` field out of range — a negative or fractional `timeout`, a `maxJitter` above `1`, a lower-cased `"get"` in `httpMethodsToRetry` | never — that field silently falls back to its default. `timeout: 0` is the exception: it is kept, and aborts every attempt | | a `baseUrl` override | first call — as a connection error, or as a `401` against the wrong host | -| wrong credentials | first call — and under OAuth2, first *token* request, so the error names the token endpoint rather than the operation you wrote | +| wrong credentials | first call — under OAuth2 as an `AuthError` from that operation, with the token endpoint's `ApiError` on `.cause` (**typescript-error-handling**) | | a misspelled or extra credential field | never at run time. Credentials are plain objects checked only by TypeScript; nothing re-validates them at construction | | **an omitted** credential | first call, as a `401`. An unset credential configures the client for **no auth** — the operation sends no credential rather than erroring. See **typescript-authentication** | @@ -159,74 +142,36 @@ before constructing. ### Client and fetch lifetime -The SDK does **not** own a connection pool — `fetch` does. On Node the global `fetch` shares one -process-wide dispatcher, so the reason to keep one client is not the socket pool; it is everything the -constructor resolved and cached. - -**Keep the SDK client long-lived — it is not a stateless wrapper.** The only thing you hand it is -configuration; its constructor resolves the rest and then owns it: - -- the **transport** — a `RawClient` built over the resolved `fetch` implementation. If no `fetch` is - reachable, **the constructor throws `ConfigurationError`**, not the first call; -- the **server groups** — `buildServers(options)` runs here and resolves every group **once**: the - environment and each override are read and decoded as the client is built, and every call afterwards - only attaches its own sub-path. So assigning `serverEnvironment` or mutating an override on the - object you passed in does nothing, and a bad value throws from the constructor rather than from a - call. Configure the server before you construct, and construct a new client to change environment. - See **typescript-configuration-resilience**, *What is captured when*; -- the **auth schemes** — validated at construction (a basic-auth username containing `:` throws - `ConfigurationError` from the constructor), and for an OAuth2 SDK the auth scheme *is* the access-token - cache, closed over by the scheme object. - -That last one is the reason a per-request client is a real cost rather than a stylistic one: a fresh -client starts with an empty token cache, so **every construction pays a token request on its first -call**. Three calls through three throwaway clients is three token round-trips where a shared client -makes one — and the shared one also collapses concurrent callers onto a single in-flight token -acquisition, which the throwaway ones cannot. - -Resource getters are memoized per client (`client.{resource}` builds once, behind `??=`, and is -cached), so they are part of the same bargain. Never construct a resource class yourself: they are -exported only for their merged namespaces and for `instanceof`, and their constructors take engine -internals that are not exported. +**Keep the SDK client long-lived.** `fetch` owns the connection pool, but the constructor resolves and +then owns the rest: the `fetch` implementation, every server group (mutating the options object +afterwards does nothing; construct a new client to change environment — +**typescript-configuration-resilience**, *What is captured when*), the memoized resource getters, and +the auth schemes — for an OAuth2 SDK the scheme *is* the access-token cache. A fresh client starts with +an empty token cache, so **every construction pays a token request on its first call**, and +throwaway clients cannot share one in-flight token acquisition the way a shared client does. Construct per request only where you genuinely need different credentials per request — and then expect the token fetch. For rotating a secret without rebuilding, a credential member accepts a **function** instead of a string; see **typescript-authentication**. -**There is nothing to close.** `src/core/` declares no `close()`, no `dispose()`, and no -`Symbol.dispose` / `Symbol.asyncDispose`, so the client holds no releasable resource and needs no -shutdown hook — the connection pool belongs to the runtime's `fetch`, not to you. The flip side is -that there is no drain either: to stop in-flight requests at shutdown you abort them yourself through -each call's `signal`. +**There is nothing to close** — no `close()`, `dispose()` or `Symbol.dispose`, and no shutdown hook to +register. There is no drain either: to stop in-flight requests at shutdown, abort each call's +`signal`. -**The `fetch` implementation is resolved once, in the constructor** (`config.fetch ?? globalThis.fetch`, -then stored). Two consequences that fail silently: - -- **Monkey-patching `globalThis.fetch` after a client exists has no effect on that client.** A test - that swaps the global and reuses a module-level client is still calling the original. Pass the fake - through `ClientOptions.fetch` and build the client after — see **typescript-testing**. -- **A replacement must satisfy `typeof fetch`** — it is called as `fetch(request)`, one `Request` and - no `init`, with `this` set to `undefined`, so a transport method that depends on its receiver must be - bound before you pass it. It must forward that `Request`, or its `signal`, and resolve to a - `Response` the decoder can read `status`, `headers` and a body from. - **typescript-configuration-resilience** owns the wrappers. +**The `fetch` implementation is resolved once, in the constructor** — yours, else `globalThis.fetch`; +with neither, the constructor throws `ConfigurationError`. Patching `globalThis.fetch` after a client +exists does not reach it, so pass a fake through `ClientOptions.fetch` and build the client after it +(**typescript-testing**). A replacement is called as `fetch(request)` — one `Request`, no `init` — with +`this` set to `undefined`, so bind a method before passing it; **typescript-configuration-resilience** +owns the rest of its contract. ## Choosing the server / base URL -**The shape does not vary with the spec.** However many servers or environments the API declares — one -of each, or several of both — you always get a `ServerEnvironment` object and a `serverOptions` bag -keyed by server group; a single-server, single-environment API simply gets a one-member enum and a -one-group bag. There is no arm where the constructor takes a bare `baseUrl` instead. - -Environments are modeled as a `ServerEnvironment` const object plus a matching type alias, with one -member per environment the API defines (e.g. `ServerEnvironment.Production`, or region members). -Unlike model enums it is **closed** — no `| (string & {})` tail — so only declared members type-check. -Select one on `serverEnvironment`. - -Overriding the base URL is nested **per server group AND per environment** — -`serverOptions.{group}.{environment}.baseUrl`, NOT directly on `serverOptions`. Any **templated -server variables** sit at that same level, beside `baseUrl`, one key per variable the URL template -names: +Select an environment with `serverEnvironment: ServerEnvironment.{Environment}` — a **closed** const +object (no `| (string & {})` tail), one member per environment the API defines, even when there is only +one. There is no bare `baseUrl` option: an override is nested **per server group AND per environment** +— `serverOptions.{group}.{environment}.baseUrl` — with any template variables beside `baseUrl`, and it +merges key-wise over that environment's defaults: ```ts const client = new {Api}Client({ @@ -237,16 +182,10 @@ const client = new {Api}Client({ }); ``` -An override is merged key-wise over that environment's defaults, so setting `baseUrl` alone leaves the -template variables in place, and naming one group leaves the other groups alone. **That last part is a -trap when an OAuth token endpoint lives on its own group**: redirecting the `default` group at a mock -does not move the token request, which still reaches the real host. Override every group the run -touches. - -The group keys, the environment members, and the URL each resolves to are all in -`DEFAULT_SERVER_OPTIONS` in `src/servers.ts`, and tabulated under **Servers & auth** in the contract -sheet — **read them there**, because a member's name does not reliably tell you its host. -**typescript-configuration-resilience** owns server and base-URL configuration in full. +The group keys, the environment members, and the URL each resolves to are in `DEFAULT_SERVER_OPTIONS` +in `src/servers.ts` and under **Servers & auth** in the contract sheet — **read them there**, because a +member's name does not reliably tell you its host. **typescript-configuration-resilience** owns server +and base-URL configuration, including an OAuth token endpoint on its own server group. ## Wiring into an application @@ -265,14 +204,11 @@ export const client = new {Api}Client({ }); ``` -⚠ **A module-level client is constructed at import time, and that has a consequence worth planning -for.** It reads `process.env` when the module is first imported — which, with ESM hoisting, can be -*before* your config loader, `dotenv`, or secret fetch has run. The credential then resolves to -`undefined`, and because **an unset credential is not an SDK error** (the operation simply sends no -credential), you do not get a startup failure. You get a `401` from the API on the first call, at -runtime, in whichever code path happens to run first — which reads like an expired token rather than -a load-order bug. Two ways out: load config before anything imports this module, or build the client -in a factory called from your startup path (below). +⚠ **A module-level client reads `process.env` at import time**, which under ESM hoisting can precede +your config loader, `dotenv` or secret fetch. The credential is then `undefined`, which the SDK treats +as no auth: no startup error, just a `401` on the first call, reading like an expired token. Load +config before anything imports this module, or build the client in a factory called from your startup +path (below). ### Building it in a factory @@ -284,27 +220,16 @@ import { {Api}Client, ServerEnvironment } from "{package-name}"; export function build{Api}Client(): {Api}Client { const token = process.env.API_TOKEN; - - // SET THIS. An unset credential is NOT an SDK error — it sends no credential and 401s later. - if (!token) throw new Error("API_TOKEN is not set"); + if (!token) throw new Error("API_TOKEN is not set"); // fail at startup, not as a 401 later return new {Api}Client({ serverEnvironment: ServerEnvironment.{Environment}, - - // SET THIS. Default 60_000 ms. Bounds ONE attempt, and an idempotent call gets up to - // 4 of them. See typescript-configuration-resilience > Retries. - retry: { timeout: 10_000 }, - + retry: { timeout: 10_000 }, // per attempt; default 60_000 ms {scheme}: token, }); } ``` -Both flagged lines are load-bearing and they answer different failures: the credential check turns a -silent `401` into a startup failure, and `retry.timeout` stops a hung provider from holding the caller -open for the full default minute on every attempt — up to four of them on an idempotent call. Setting -only the timeout is the common mistake — it looks like the configuration box is ticked. - Then register the result once, however your framework shares singletons, and inject it: ```ts @@ -335,9 +260,6 @@ what makes the service testable — a test passes a client built over a fake `fe | CLI / script | one at the top, or one per run | the process is short-lived; the cache never pays back | | Browser / edge runtime | wherever your bundle initialises | the package ships `dist/esm` and `dist/commonjs` only — no bundle, no UMD, no CDN artifact — so it goes through a bundler. Deno, Bun, Workers and Vercel Edge need only the globals the map lists, but none is a tested target | -There is no fork-safety hazard to design around the way a pooled-socket SDK has: the client owns no -pool. The cost of building one per worker is the token cache, not a corrupt connection. - ## ESM and CommonJS The package ships both dialects from a single entry, so `require` works with full types. In a @@ -350,11 +272,8 @@ import sdk = require("{package-name}"); const client = new sdk.{Api}Client({ serverEnvironment: sdk.ServerEnvironment.{Environment} }); ``` -⚠ **A process that loads both dialects gets two independent copies of every class**, including every -error class, and `instanceof` across that boundary is `false`. It is a real hazard in a mixed -codebase, and it fails silently — a `catch` arm simply never matches. Pick one dialect per process -where you can; where you cannot, narrow on `err.kind` or `err.payload.kind` instead of `instanceof`. -See **typescript-error-handling**. +⚠ **A process that loads both dialects gets two copies of every class**, so `instanceof` is `false` +across them — pick one dialect per process, or narrow on `err.kind` (**typescript-error-handling**). Two consumer compiler settings change what you type at the construction site. Under `exactOptionalPropertyTypes`, **omit or spread** an absent option rather than assigning `undefined` to @@ -364,26 +283,16 @@ are imported normally. ## Inbound webhooks — what the emitted package does and does not give you -**There is no webhook surface at all** — no webhook tree, no event parser, no signature verifier, on -any generated TypeScript SDK. Nothing under `src/core/` computes any part of an inbound webhook for -you, and no member of `ClientOptions` turns one on. +**There is no webhook surface at all** — no event parser, no signature verifier, and no member of +`ClientOptions` that turns one on. So verifying an inbound webhook is entirely yours to write, against the provider's published scheme: capture the raw body before any JSON parsing, compute the signature yourself, and compare in constant time. The SDK's model types stay useful for *deserializing* an event body once you have verified it — but do not read "the SDK parses this" as "the SDK verified this". See **typescript-models**. -Testing is a different matter and needs no shipped helpers — inject a fake `fetch`; see -**typescript-testing**. - -> **Not settled by the generator's current version.** The transport carries default header, query and -> path-parameter channels that the generated client currently wires as empty arrays — a source comment -> says nothing in the spec reaches them *yet*. If a later version starts populating them, a -> client-wide header option could appear on `ClientOptions`, so read `src/client-options.ts` rather -> than assuming the option list above is complete for your SDK. - ## Next - Configure authentication → **typescript-authentication** - Make your first call → **typescript-calling-endpoints** -- Tune timeouts, retries, logging, base URL → **typescript-configuration-resilience** +- Tune timeouts, retries, logging, base URL, paging → **typescript-configuration-resilience** diff --git a/plugins/plaid/skills/typescript/typescript-configuration-resilience/SKILL.md b/plugins/plaid/skills/typescript/typescript-configuration-resilience/SKILL.md index 480ee8e7..ca7e3480 100644 --- a/plugins/plaid/skills/typescript/typescript-configuration-resilience/SKILL.md +++ b/plugins/plaid/skills/typescript/typescript-configuration-resilience/SKILL.md @@ -1,31 +1,20 @@ --- name: typescript-configuration-resilience -description: Client configuration and resilience for an APIMatic-generated TypeScript SDK — the five ClientOptions fields, server/base-URL selection and template variables, the retry policy (on by default — what it retries, what it never does, per-call overrides) and the per-attempt timeout, cancellation, the built-in logging (off by default — levels, redaction, the environment variable), proxies, TLS and connection pooling, and what the SDK does not do for you (pagination, streaming) built on the one `fetch` seam. Load before you construct or tune the client — the field list alone does not reveal that idempotent calls are retried by default and writes are not, that the timeout bounds one attempt rather than the call, that an environment variable turns logging on with no code change, that the default environment is whichever the spec listed first, that `fetch` is handed one `Request` it must forward, that Node's fetch ignores HTTP_PROXY, or that a hand-written page loop is unbounded by default. +description: Load before constructing or tuning an APIMatic-generated TypeScript SDK client — picking a server environment or overriding a base URL, changing the on-by-default retries or `retry.timeout`, adding cancellation or a deadline, turning the built-in logging on or off, making a write safe to retry, paging through results, or wrapping `fetch` for header injection, proxies, TLS or connection pooling. --- # Configuration & resilience for an APIMatic TypeScript SDK -> **One skill, every shape.** This file covers every configuration surface the TypeScript generator -> emits. Which parts YOUR SDK exercises — how many server groups and environments it declares, which -> template variables those carry, whether an operation takes a page or cursor field, whether the API -> offers an idempotency key — are facts of the API definition, not of this skill: take them from -> `sdk-map.md` and `map/operations/{resource}.md` at the package root, and **apply only the guidance -> that matches**. - -> `{...}` is a placeholder for a name you take from your SDK — `{Api}Client` (the one public client -> class, declared in `src/client.ts`), `{resource}`/`{Resource}`, `{operation}`/`{Operation}`, -> `{group}`, `{environment}`, `{variable}`, `{items}`, `{nextCursor}`. Replace each with the concrete -> identifier from the source; none of them is a name the generator emits literally. -> -> `{APICLIENTTYPENAME}_LOG` is the logging environment variable: the client class name in upper snake -> case, plus `_LOG`, so `AcmeClient` reads `ACME_CLIENT_LOG`. The getting-started skill's identity table -> names yours. +> Which server groups, environments, template variables, page/cursor fields and idempotency-key +> fields YOUR SDK has comes from `sdk-map.md` and `map/operations/{resource}.md` at the package root — +> **apply only the guidance that matches**. `{...}` marks a name to take from your SDK; `{Api}Client` +> is the one public client class, in `src/client.ts`. `{APICLIENTTYPENAME}_LOG` is the logging +> environment variable: the client class name in upper snake case, plus `_LOG`, so `AcmeClient` reads +> `ACME_CLIENT_LOG`. The getting-started skill's identity table names yours. Everything configurable is a field on `ClientOptions` (`src/client-options.ts`), passed to the one constructor. There is no `Configuration` class, no builder, and no per-request override beyond `{ signal, retry, logging }`. Server groups, environments and their URL templates live in `src/servers.ts`. -Everything under `src/core/` is vendored static code that is **byte-identical in every generated -TypeScript SDK**, so the engine behaviours below hold without checking your SDK. ## The whole configuration surface @@ -35,6 +24,7 @@ TypeScript SDK**, so the engine behaviours below hold without checking your SDK. | `serverOptions` | `ServerOptions` | `{}` | per-group, per-environment `baseUrl` and template-variable overrides | | `retry` | `RetryOptions` | retries **on** — see *Retries* | the retry policy, and `retry.timeout` (**ms**, `60_000`) bounding each attempt | | `logging` | `LoggingOptions` | **off** — see *Logging* | the built-in request/response logger, its levels and its redaction | +| `eventStream` | `EventStreamOptions` | `idleTimeout` `60_000` (**ms**) | how long an event stream may stay silent; read only by an operation that resolves to an `EventStream` — see **typescript-event-streams** | | `fetch` | `FetchLike` (`typeof fetch`) | global `fetch` | **the one transport extension point** | | `{scheme}` / `{scheme}Strategy` | per scheme | unset | credentials — see **typescript-authentication** | @@ -43,13 +33,10 @@ default environment are per-SDK. ## Not on this SDK -Absent **by design**, not undocumented. This list ships with `src/core/` and is versioned with it: - | You might reach for | Reality | | --- | --- | | hooks, middleware, interceptors, `onRequest`/`onResponse` | none. `fetch` is the one transport extension point; `retry.onRetry` is the one callback, and it sees only retries | -| pagination, `for await`, auto-paging helpers | no operation is paginated and nothing is async-iterable | -| SSE, `text/event-stream` | no event streams. Every decoder reads the body to completion, bar a binary success, which hands its stream over unread | +| SSE request bodies, WebSockets | none. `text/event-stream` is a response media type only — an operation whose success is one resolves to an `EventStream` you iterate with `for await` (**typescript-event-streams**). Every other decoder reads the body to completion, bar a binary success, which hands its stream over unread | | multipart responses, XML bodies | none. Body kinds are empty, JSON, form-urlencoded, text, multipart and binary | | per-request `headers`, `baseUrl`, idempotency key | none. `RequestOptions` is `{ signal, retry, logging }`; `retry` takes only `maxRetries`, `timeout` and `statusCodesToRetry`, and `logging` only `level` | | a circuit breaker, a rate limiter | none. The retry loop honours `Retry-After`, but nothing limits how many calls you start | @@ -60,9 +47,9 @@ those patterns and the traps in them. **What the SDK does own**, so that you do not rebuild it: URL and server resolution, request encoding and schema validation on the way out, auth application and OAuth token caching, response -decoding, the two-family error mapping, the `Idempotency-Key` on every non-GET call, the retry -loop with its per-attempt timeout, and request/response logging with redaction. Connection pooling -belongs to `fetch`, not to the client. +decoding, the two-family error mapping, the `Idempotency-Key` on every non-GET call, fetching and +advancing the pages of a paged operation, the retry loop with its per-attempt timeout, and +request/response logging with redaction. ## The `fetch` seam @@ -71,23 +58,20 @@ type FetchLike = typeof fetch; ``` The SDK calls it with **one argument, the attempt's `Request`, and no `init`**. The method, the -headers (the credential included), the body and the signal are all on that `Request`. One rule, and it -is the one that breaks things when missed: **forward that `Request`, or at least its `signal`**, to -whatever performs the request. Drop the signal and both each attempt's `retry.timeout` and per-call -cancellation go inert — the call neither aborts nor times out, because the transport enforces both -through that signal. A wrapper written against `(input, init)` still type-checks, but `init` is always -`undefined`: whatever it reads from `init` is nothing, and whatever it passes as `init` **replaces** -what the `Request` carries, so `fetch(input, { headers })` drops every header the SDK set. On an abort -a replacement may reject with whatever it likes: the SDK reads the reason off the signal it built the -`Request` with, so a deadline is still a `TimeoutError` the retry loop retries, and a caller abort -still rejects with the caller's own `reason`. +headers (the credential included), the body and the signal are all on that `Request`. **Forward that +`Request`, or at least its `signal`**, to whatever performs the request: drop the signal and both each +attempt's `retry.timeout` and per-call cancellation go inert — the call neither aborts nor times out. A +wrapper written against `(input, init)` still type-checks, but `init` is always `undefined`: whatever it +reads from `init` is nothing, and whatever it passes as `init` **replaces** what the `Request` carries, +so `fetch(input, { headers })` drops every header the SDK set. On an abort a replacement may reject with +whatever it likes: a deadline is still a `TimeoutError` the retry loop retries, and a caller abort still +rejects with the caller's own `reason`. Four facts that decide how you write a wrapper: -- **It sees every request the client makes, including the OAuth token request.** The auth schemes are - built over the same transport as the operations (`buildAuthSchemes(options, servers, rawClient)` in - the constructor), so a wrapper that logs requests logs the token POST — `client_secret` and all. The - built-in logger (*Logging*) masks it; a hand-rolled one does not. Filter by URL where that matters. +- **It sees every request the client makes, including the OAuth token request** — a wrapper that logs + requests logs the token POST, `client_secret` and all, where the built-in logger (*Logging*) masks it. + Filter by URL where that matters. - **It sits under the retry loop, so it sees every attempt.** A call retried three times is four requests through your wrapper, each a fresh `Request` with its own signal, and a wrapper that logs writes four lines. To see one line per logical call, log around the SDK call instead; to see why an @@ -115,8 +99,8 @@ export type ServerOptions = { ``` Each environment's entry exposes what the SDK substitutes into that group's URL: the **`baseUrl` -template** (always present and settable) plus any **template variables** the spec declares for that -server — a region, a subdomain, a port, an API version. Names and counts vary per API and per +template** (always present and settable) plus any **template variables** that server's URL declares +— a region, a subdomain, a port, an API version. Names and counts vary per API and per environment; a group with no variables exposes `baseUrl` alone. Read the real group keys, environment keys, URL templates and variable defaults from `DEFAULT_SERVER_OPTIONS` in `src/servers.ts`, or from the **Base URLs and overrides** table in `sdk-map.md`. @@ -136,7 +120,7 @@ const client = new {Api}Client({ }); ``` -Four things about how this resolves: +How this resolves: - **Overrides merge with the declared defaults per group-and-environment pair, key by key** (`{ ...DEFAULT_SERVER_OPTIONS.{group}.{environment}, ...yours }`). Setting `{variable}` alone keeps @@ -148,25 +132,17 @@ Four things about how this resolves: request time. A placeholder in a `baseUrl` you supply is only substituted if a declared variable of that exact name exists — otherwise it survives into the URL verbatim, and nothing rejects it the way an unfilled path parameter is rejected. -- **An environment value the SDK does not know throws `ConfigurationError` from the constructor** — - every server group is resolved once, as the client is built, so no operation method throws - synchronously. ### ⚠▶▶ Always pass `serverEnvironment` explicitly -`serverEnvironment` has a default, so `new {Api}Client()` compiles and reaches a real host. **That -default is whatever environment the spec listed first** — the first member `ServerEnvironment` -declares in `src/servers.ts`, and the one whose arm every resolver in that file labels `case -undefined:` alongside its own. For many providers the spec lists sandbox first. Nothing announces it. - -A deployment that believes it configured production and did not gets sandbox behaviour with -production credentials, which fails auth in a way that reads like a credentials problem rather than an -environment one. **Pass it in every environment, production included**, so the host a call reaches is -visible where the client is built. +`serverEnvironment` has a default, so `new {Api}Client()` compiles and reaches a real host: the +**first** member of `ServerEnvironment` in `src/servers.ts` — often sandbox. Production credentials +then fail against it as if they were wrong. **Pass it in every environment, production included.** -`ServerEnvironment` is a **closed** union — no `| (string & {})` tail — so a literal typos out at -compile time. A value arriving from configuration does not. Map it explicitly and **fail on an unknown -value** rather than falling through to the default: +`ServerEnvironment` is a **closed** union — no `| (string & {})` tail — so a mistyped literal fails to +compile; a value read from configuration does not. An unknown string throws `ConfigurationError` from +the constructor, but `undefined` silently selects the default — so map configuration values explicitly +and **fail on a miss**: ```ts const ENVIRONMENTS: Record = { @@ -178,20 +154,11 @@ const serverEnvironment = ENVIRONMENTS[process.env.API_ENV ?? ""]; if (!serverEnvironment) throw new Error(`unknown API_ENV: ${process.env.API_ENV}`); ``` -Without the guard, a typo in a deployment variable becomes `undefined`, and an `undefined` -environment is read as *none selected*: every resolver's default arm answers to `case undefined:` -alongside its own label, so the client runs quietly against the default environment instead of the -one you asked for. Nothing throws, and nothing is logged. An unknown *string* is the loud case — the -constructor rejects it with `ConfigurationError` (above) — so it is the value your own -configuration turns into `undefined` that fails silently, which is what the guard is for. - ### What is captured when -`serverEnvironment` and `serverOptions` are both read **once**, as the client is built. The constructor -calls `buildServers(options)`, which resolves every server group — the environment, its `baseUrl` and -each variable, decoded through its schema — into a value that every call afterwards only attaches its -own sub-path to. So mutating the `serverOptions` object you passed in, replacing a whole group -(`serverOptions.{group} = …`), or assigning `serverEnvironment` afterwards has no effect on the client. +`serverEnvironment` and `serverOptions` are resolved **once**, in the constructor — so a bad value +throws there, never from a call, and mutating the `serverOptions` object you passed in, replacing a +whole group (`serverOptions.{group} = …`) or assigning `serverEnvironment` afterwards has no effect. **Configure the server before you construct, and construct a new client to change environment.** ### Redirecting at a mock @@ -212,12 +179,11 @@ For a proxy, see *Proxy or custom agent* below. backing off roughly 1 s, 2 s and 4 s, and honouring `Retry-After`. - A `POST`, `PATCH` or `DELETE` is sent **once**, whatever went wrong. The method gate covers every failure, faults included. -- **A `401` is not in the default status set.** The transport invalidates whatever that operation's - auth scheme had cached, so the *next* call re-acquires; the failing call rejects. You see one `401`, - then recovery. +- **A `401` is not in the default status set**: the failing call rejects, and the *next* call + re-acquires a fetched credential (**typescript-authentication**). -The loop lives in `src/core/retry.ts`, and `src/core/raw-client.ts` runs every call through it. -Configure it with any subset of `RetryOptions` — a field you leave out keeps its default: +Its defaults live in `src/core/retry.ts`. Configure it with any subset of `RetryOptions` — a field you +leave out keeps its default: ```ts new {Api}Client({ retry: { maxRetries: 0 } }); // off: every call is sent exactly once @@ -242,66 +208,39 @@ new {Api}Client({ | `maxJitter` | `0.25` | A **fraction**, `0` to `1`, and additive: a wait lands between its delay and `delay × (1 + maxJitter)`. `0` makes every wait exact | | `onRetry` | none | `(attempt: RetryAttempt) => void`, called before each retry's wait | -`0`, `false` and `[]` are values, never misses. Anything else a field cannot honour — a negative or -fractional `timeout`, a `maxJitter` of `50`, a list carrying a lower-cased `"get"` — **silently falls -back to that field's default**, and the client still constructs. `timeout: 0` is kept: it is a -zero-length deadline that fails every attempt, not "no timeout". +`0`, `false` and `[]` are values, never misses. Anything else a field cannot honour — a negative, +fractional, `NaN`, `Infinity` or above-`2_147_483_647` `timeout`, a `maxJitter` of `50`, a list +carrying a lower-cased `"get"` — **silently falls back to that field's default** (on a call, to the +client's value), and the client still constructs. `timeout: 0` is kept: it is a zero-length deadline +that fails every attempt, not "no timeout" — an unbounded attempt is not expressible. The wait before retry *n* (counting from 0) is `min(Retry-After ?? delay × backoffFactor ** n, 60_000) × (1 + random × maxJitter)`, rounded up. The 60-second ceiling is the engine's, not an option, and jitter sits on top of it, so the longest single wait is 75 s at the defaults. -What the loop does and does not do — read these before you rely on it: +What the loop does: -- **The method gate covers every failure.** A status in the set, a dropped connection, a timeout: each - is retried only for a method in `httpMethodsToRetry`. `PUT` is in the default gate — see *Making a - write safe*. - **`Retry-After` is honoured** in both its delta-seconds and HTTP-date forms, capped at 60 s, with - jitter added on top — never subtracted, so the SDK never wakes before the time the server named. A - malformed value falls back to the curve. -- **A caller abort is never retried.** Aborting your `signal` cuts a backoff wait short and rejects - with the signal's own `reason`. -- **A streaming request body is never retried**, whatever the method, because a stream cannot be - replayed. -- **A failure while obtaining a credential is not retried.** It ends the call — once the token - request's own retries are spent, since it is a `POST` under this same policy and retries only when - `httpMethodsToRetry` names `POST`. -- **A rejection from your `fetch` that is not an SDK error counts as a dropped connection.** It - becomes a `ConnectionError` and is retried — including a refusal your own wrapper throws on purpose - (see *The `fetch` seam*). The exception is one that arrives after the attempt's timeout or your - signal fired: the SDK reads the reason off the signal it built, so a caller abort rejects as itself - and is not retried, and a timeout becomes a `TimeoutError` and is retried like any other. What the - replacement rejected with does not change either. -- **A retried-away response is released** — its body's cancel started, not awaited, before the wait, - so a cancel that stalls never holds up the retry — and only its headers reach `onRetry`. When the last attempt fails, the call rejects with **that** attempt's failure: an - `ApiError` (or the operation's subclass) for a status, a `ConnectionError` or `TimeoutError` for a - fault — the same shapes as with retrying off (**typescript-error-handling**). `.asApiResult()` sees - the last response. - -**Do the arithmetic before you accept the defaults.** `retry.timeout` bounds each attempt, not the call, -so an idempotent call's worst case is `(maxRetries + 1) × timeout` plus the waits — four minutes at the -defaults. Nothing in the SDK imposes a wall-clock ceiling on the call; *Bounding a call* below is how -you impose one. + jitter added on top, so the SDK never wakes before the time the server named. A malformed value + falls back to the curve. +- **Never retried:** a caller abort (which also cuts a backoff wait short), a streaming request body + whatever the method, and a failure to obtain a credential — the token request is itself a `POST` + under this policy (**typescript-authentication**). +- **A rejection from your `fetch` that is not an SDK error counts as a dropped connection** — see + *The `fetch` seam*. +- **The call rejects with the last attempt's failure** — an `ApiError` (or the operation's subclass) + for a status, a `ConnectionError` or `TimeoutError` for a fault — the same shapes as with retrying + off (**typescript-error-handling**). Only a retried-away response's headers reach `onRetry`, and + `.asApiResult()` sees the last response. ### Per-call overrides -Three fields can be overridden on one call through `RequestOptions.retry`, typed `RequestRetryOptions`. -Each is merged field by field over the client's policy, so a field you omit keeps the client's value: - -```ts -await client.{resource}.{operation}(request, { retry: { maxRetries: 0 } }); // this call: one attempt -await client.{resource}.{operation}(request, { retry: { timeout: 5_000 } }); // this call: 5 s per attempt -await client.{resource}.{operation}(request, { retry: { statusCodesToRetry: [503] } }); // this call: a narrower set -``` - -The type admits only these three. How many attempts *this* call gets, how long each may take, and which -statuses are worth a second try vary by call site; the backoff curve, the method gate and `onRetry` are -how the client paces itself against one server, so they are set on the client alone. A per-call -`httpMethodsToRetry` would be a second route to retrying a write. The restriction is the type's -alone: an object carrying another `RetryOptions` field — from JavaScript, or through a constant typed -as the wider record — still has it honoured, so do not rely on the type to keep a write out of the -gate for one call. +`RequestOptions.retry` (`RequestRetryOptions`) takes only `maxRetries`, `timeout` and +`statusCodesToRetry`, each merged over the client's value for that one call (syntax: +**typescript-calling-endpoints**). Backoff, the method gate and `onRetry` are client-only — but only by +type: an object carrying another `RetryOptions` field (from JavaScript, or a constant typed as the +wider record) still has it honoured, so do not rely on the type to keep a write out of the gate. ### Observing retries @@ -337,11 +276,8 @@ Rules to hold to: job that re-runs on failure — on top of the SDK's without turning the SDK's off for that path. Attempts multiply (four inside four is sixteen round-trips, and up to sixteen times the timeout), and every attempt of a caller-level layer is a new SDK call that mints a **new** `Idempotency-Key`. -- **Never retry an `EncodeError`, a `DecodeError`, an `AuthError` or a 4xx other than `408`/`429`.** On - an `EncodeError` nothing was sent at all — the fix is in your code. A `DecodeError` means the - response was malformed, which a resend rarely cures. An `AuthError` means a credential could not be - *obtained*, which is configuration, not weather. The loop retries none of them, and neither should - you. See **typescript-error-handling**. +- **Never retry an `EncodeError`, a `DecodeError`, an `AuthError` or a 4xx other than `408`/`429`** — + the loop retries none of them, and what each means is in **typescript-error-handling**. When a decision genuinely needs something the policy cannot express — a retry that depends on the decoded error payload, or on which operation it is — turn the SDK's loop off for that call and own @@ -369,15 +305,13 @@ function isTransient(err: unknown): boolean { await withRetry(() => client.{resource}.{operation}(request, { retry: { maxRetries: 0 } })); ``` -`{Api}Error` is the whole error family, narrowed on its closed `kind`. The runtime declares it as `CoreError`, and the -package exports it **only** under the SDK-branded alias — read the real name off the -`CoreError as …Error` line in `src/index.ts`. See **typescript-error-handling**. +`{Api}Error` is the whole error family, narrowed on its closed `kind`; its real name is in +**typescript-error-handling**. ### Making a write safe under retries -**Start from what you have.** With the default gate a `POST`, `PATCH` or `DELETE` is sent once. The -exposure arrives when you widen `httpMethodsToRetry` or add a retry layer of your own, and with two -things no setting fixes: +A write is exposed to a resend only when you widen `httpMethodsToRetry` or add a retry layer of your +own — and through two things no setting fixes: - **`PUT` is in the default gate — idempotent by HTTP's definition, not necessarily by your provider's.** A `PUT` can still carry a per-call side effect — an audit row, an outbound webhook, a @@ -445,17 +379,15 @@ read the numbering as a recommendation order: Three details decide whether it works: - - **A `fetch` wrapper sees every attempt of the SDK's loop by construction**, because the loop sits - above `fetch`. But its refusal reaches the loop as a `ConnectionError`, which **is retried** for a - method in the gate — each retry is refused again, and the call rejects only after the backoff, - with your error on `.cause`. Pair the guard with option 3 on the guarded write, so the refusal is - immediate, and recognise it with `err.cause instanceof YourRefusal`. + - **A `fetch` wrapper sees every attempt of the SDK's loop**, and its refusal is retried as a + `ConnectionError` (*The `fetch` seam*). Pair the guard with option 3 on the guarded write, so the + refusal is immediate, and recognise it with `err.cause instanceof YourRefusal`. - **Keep the "already sent" marker in state that outlives one attempt** — an `AsyncLocalStorage` scope the caller opens around the write, or a closure created per unit of work. A marker hung off `init` is per-attempt bookkeeping only, and a caller-level retry (a job re-running after a timeout) creates a fresh one either way. - - **Key it on method and URL.** The guard also sees the OAuth token request, and a token - acquisition must not be counted as the write. + - **Key it on method and URL**, so the OAuth token request it also sees is not counted as the + write. Count the send **before** it goes out. A request that failed on the way out may still have been received, so "this may already have taken effect" is the only safe reading — surface it as an @@ -483,42 +415,18 @@ permanent refusal. Clear it once the outcome is settled, and expire it when it n ### `retry.timeout` -In **milliseconds**, bounding **one attempt** — enforced with an `AbortController` inside the -transport, surfacing as a `TimeoutError` (`err.kind === "timeout"`) once no retry is left. Each attempt -gets its own deadline. What the field list does not tell you: - -- **It stops at the response headers.** The timer starts once the credential is in hand, so obtaining - a credential and reading the body are bounded only by your `signal`. A built-in OAuth token request - runs on its own timer. -- **A value the platform cannot honour is not "no timeout".** Negative, fractional, `NaN`, `Infinity` - and anything above `2_147_483_647` ms — the largest value a timer can hold — all fall back to the - SDK's default (on a call, to the client's value), silently, and the client still constructs. A usable - value is installed **verbatim**, `0` included, so `timeout: 0` is a zero-length deadline that fails - every attempt rather than lifting it. An unbounded attempt is not expressible. -- **One call can take its own.** `{ retry: { timeout: 5_000 } }` on the call replaces the client's - value for that call — still per attempt. For a budget on the whole call, use a signal. -- **A `fetch` replacement that does not forward the `Request`'s `signal` makes it inert.** Pass the - `Request` on, or copy it with `new Request(request)`, which keeps the signal. +In **milliseconds**, bounding **one attempt**, each with its own deadline; the last attempt's expiry +rejects as a `TimeoutError` (`err.kind === "timeout"`). It starts once the credential is in hand and +stops at the response headers, so obtaining a credential and reading the body are bounded only by your +`signal` (a built-in OAuth token request runs on its own timer). A per-call value replaces the +client's for that call, still per attempt. A value a timer cannot hold silently falls back to the +default, and `0` fails every attempt (*Retries*). ### Cancellation and real deadlines -`RequestOptions` is `{ signal?: AbortSignal; retry?: RequestRetryOptions; logging?: RequestLoggingOptions }`, -and `signal` is the whole per-call cancellation surface. - -```ts -const controller = new AbortController(); -const t = setTimeout(() => controller.abort(new Error("deadline exceeded")), 2_000); -try { - await client.{resource}.{operation}({ /* ... */ }, { signal: controller.signal }); -} finally { - clearTimeout(t); -} -``` - -A caller abort rejects with whatever you passed to `abort()` — the signal's own `reason`, unwrapped and -outside the `{Api}Error` family — so pass something diagnostic, and rethrow it from a family `catch`. -An already-aborted signal rejects immediately, and an abort during a backoff wait ends the wait and the -call; an abort is never retried. +Per-call cancellation is `RequestOptions.signal` (**typescript-calling-endpoints**). An abort rejects +with the signal's own `reason`, outside the `{Api}Error` family (**typescript-error-handling**) — so +pass something diagnostic, and rethrow it from a family `catch`. For a **deadline across a whole call or unit of work** — one call and its retries, or several calls — `AbortSignal.timeout` and `AbortSignal.any` compose (both on Node 20+): @@ -533,15 +441,10 @@ async function withDeadline(work: (signal: AbortSignal) => Promise, ms: nu That is how you give one operation a ceiling that `retry.timeout` cannot: the deadline covers every attempt and every wait, and the earlier of the two wins. -⚠▶▶ **A per-attempt timeout does not bound a request.** If one handler makes more than one SDK call — -a loop over records, a fan-out, a create-then-confirm pair — the per-call timeouts **add up**, and they -add up *faster* when each failure is caught so the work can continue: every swallowed timeout costs its -full bound and the next call still runs — and an idempotent call spends up to `maxRetries + 1` of -them before it fails. **The check is arithmetic, not judgement:** `calls in this handler × -(maxRetries + 1) × timeout`, plus the waits, must sit under the budget you are willing to make a caller -wait. Count the calls in -the loop, not the calls in the snippet — a handler that processes every record on file makes as many -calls as there are records. +⚠ **Several calls in one handler add up** — a loop over records, a fan-out, a create-then-confirm +pair — and a swallowed timeout still costs its full bound before the next call runs: `calls × +(maxRetries + 1) × timeout`, plus the waits, must fit the budget you make a caller wait. Count the +calls in the loop, not in the snippet, and bound the handler with one signal. **Give the total bound one home, not one per call site.** A controller written out at each call is the layer that gets skipped, so any operation added later silently has no ceiling. Put it at the one @@ -569,111 +472,136 @@ too. > (Chrome 98, Firefox 97, Safari 15.4). The SDK's own module-load floor is lower, so between the two > the engine still aborts the request but **produces no typed error at all**. -## Pagination — drive it yourself +## Pagination -Nothing is paginated and nothing is async-iterable. When an operation returns a page, advance its page -or cursor field in a loop and stop on the API's own end signal: +An operation the API pages returns **`Pageable<{PageResponse}, {Item}, E>`** in place of `ApiPromise`, +and its **Returns** bullet on the map names the strategy and the condition that ends its walk. The +walk is **lazy**: calling the operation sends nothing, the first page goes out when a loop starts, and +each new loop starts again from the first page. `Pageable` implements `AsyncIterable<`**`{Item}`**`>`, so a plain `for await` walks +**individual items** across every page; `.pages()` walks the decoded pages instead. The SDK fetches each +page and advances the paging state for you — one of four strategies (offset, page-number, cursor or +`Link`), chosen per operation. ```ts -// Offset/page style: -const PER_PAGE = 100; -for (let page = 1; ; page++) { - const result = await client.{resource}.{operation}({ page, perPage: PER_PAGE }); - for (const item of result.{items}) process(item); - if (result.{items}.length < PER_PAGE) break; // short page — usually the last +// The paging fields on the request (page/limit, offset/limit, or cursor) seed the FIRST page, +// with their declared defaults applied; the SDK advances the page, offset or cursor and stops when +// the API signals the end. +for await (const item of client.{resource}.{operation}({ /* limit: 100, ... */ }, { signal })) { + process(item); +} + +// Pages, not items — also where any total, cursor or link metadata on the page response lives: +for await (const page of client.{resource}.{operation}({ /* ... */ }).pages()) { + for (const item of page.{items}) process(item); } +``` + +Every page is its own request: `options` — the `signal`, the per-call `retry` and `logging` — applies to each one, +and each one goes through the retry policy on its own. Where the walk stops is the strategy's rule: + +| Strategy | Advances by | Stops when | +| --- | --- | --- | +| offset | the item count of each page | the next offset reaches the total, a page is empty, `hasMore` is `false`, or — when the page carries neither a total nor `hasMore` — a page is shorter than the limit | +| page-number | one page | the page number reaches the total pages, `hasMore` is `false`, or — when the page carries no `hasMore` — a page is empty, or is shorter than the limit with no total | +| cursor | the next cursor the response carries | the response carries no next cursor, the cursor did not change, or `hasMore` is `false` | +| `Link` | the next link the response carries, resolved against the page's own URL | the response carries no next link, or the link did not change | -// Cursor style: -let cursor: string | undefined; -do { - const result = await client.{resource}.{operation}({ ...(cursor ? { cursor } : {}) }); - for (const item of result.{items}) process(item); - cursor = result.{nextCursor}; -} while (cursor); +Two consequences of the `Link` strategy worth knowing: after the first page the request's own query +is dropped, because the link the API sent carries it; and a link is followed only to the **same origin** +as the API — another origin, or a link that is not a URL, raises `PaginationError` between pages rather +than sending a credential elsewhere (see **typescript-error-handling**). + +**A failed page throws mid-walk** — `E` for an error status, and every other failure exactly as an +awaited call would reject with it: a `{Api}Error` member, or a caller abort's own `reason`. The pages already delivered stay delivered. For the +form that turns an error status into a value, call `.asApiResult()` **on the walk**: + +```ts +for await (const result of client.{resource}.{operation}({ /* ... */ }).asApiResult().pages()) { + if (result.ok) { + // result.value is the page; result.status and result.headers are its own + } else { + // result.status, result.message, result.payload — and this is the LAST element the walk yields + } +} ``` -Read the actual page/cursor field names off the operation's **Fields** table and its response model — -they are spec-specific, and the SDK sends a defaulted `page`/`perPage` whether or not you set it. Prefer -the API's explicit end signal (a null next-cursor, a `hasMore` flag) over inferring from a short page -where one exists. +Its item loop (`for await (const item of walk.asApiResult())`) ends silently at an error status and +contributes no items for it, so an item loop that ends cannot tell the last page from a failed one — +use `.pages()` when the distinction matters. Everything else still throws from either form, as it +would from an awaited call. -### ⚠⚠ Never leave a page loop unbounded +### ⚠⚠ Never leave a page walk unbounded -**Both loops above are wrong as written**, and the reason is the same one that makes hand-driven paging -riskier than the auto-paging this SDK does not have: *the only stop condition is the provider's -cooperation*. A provider that keeps returning a next cursor, a cursor that fails to advance, a filter -the provider quietly ignores, or a `perPage` it silently caps below what you asked for will each spin -forever. The failure does not look like a slow request. It looks like a request that **never returns**, -with tens of thousands of provider calls billed behind it and no error the provider can be blamed for. +**"The SDK stops when the API signals the end" describes the happy path, not a guarantee.** The walk +ends only when the provider stops handing out a next page. A provider that keeps returning a next +link, or a filter it quietly ignores, will spin until something else kills the request. The cursor +and `Link` strategies stop on a cursor or link that did not change; nothing stops one that keeps +changing. The failure does not look like a slow request. It looks like a request that **never +returns**, with tens of thousands of provider calls billed behind it and no error the provider can be +blamed for. -**Every page loop needs at least one bound that does not depend on the provider.** Pick what matches +**A `limit` the provider silently caps below what you asked for fails the other way.** When a page +carries neither a total nor `hasMore`, an offset or page-number walk takes a page shorter than the +limit as the last one, so it stops after the first page and drops the rest without an error. Ask for +no more than the provider's documented maximum page size. + +**Every page walk needs at least one bound that does not depend on the provider.** Pick what matches the use case; a page cap is the cheapest and is never wrong: | Bound | Use when | Shape | | --- | --- | --- | -| **page cap** | always — the backstop | `if (++pages >= MAX_PAGES) break;` | +| **page cap** | always — the backstop | `if (++pages >= MAX_PAGES) break;` in a `.pages()` loop | | **item cap** | the caller wants "the first N" | `if (out.length >= max) break;` | -| **deadline** | the loop sits behind a request timeout | one `AbortSignal.timeout` passed to every call | -| **no-progress guard** | cursor or offset paging | stop if the cursor did not change between pages | +| **deadline** | the walk sits behind a request timeout | one `AbortSignal.timeout` passed as `options.signal` — it bounds the whole walk, not one page | ```ts const MAX_PAGES = 100; const signal = AbortSignal.timeout(30_000); // bounds the whole walk, not one page -let cursor: string | undefined; -let seen: string | undefined; - -for (let pages = 0; pages < MAX_PAGES; pages++) { - const result = await client.{resource}.{operation}({ ...(cursor ? { cursor } : {}) }, { signal }); - for (const item of result.{items}) process(item); +let pages = 0; - cursor = result.{nextCursor}; - if (!cursor) return; // the provider's end signal — the happy path - if (cursor === seen) throw new Error("cursor did not advance"); - seen = cursor; +for await (const page of client.{resource}.{operation}({ /* ... */ }, { signal }).pages()) { + for (const item of page.{items}) process(item); + if (++pages >= MAX_PAGES) break; // then surface the truncation — see below } -throw new Error(`stopped after ${MAX_PAGES} pages`); // truncating silently is its own defect ``` Prefer to **narrow the query before you page it** — a provider-side date range, status filter, or a -`perPage` matching what the caller needs turns "walk everything" into a handful of pages. And **a bound +`limit` matching what the caller needs turns "walk everything" into a handful of pages. And **a bound that silently truncates is a different defect from one that hangs**: when you hit the cap, surface it or log it; never return a partial set that reads like a complete one. -Wrapping a bounded loop in an async generator gives you the `for await` the SDK does not: - -```ts -async function* all{Items}(signal?: AbortSignal): AsyncGenerator<{Item}> { - let cursor: string | undefined; - for (let pages = 0; pages < MAX_PAGES; pages++) { - const result = await client.{resource}.{operation}({ ...(cursor ? { cursor } : {}) }, { signal }); - yield* result.{items}; - cursor = result.{nextCursor}; - if (!cursor) return; - } - throw new Error(`stopped after ${MAX_PAGES} pages`); -} -``` - -A failed page rejects mid-enumeration like any other call — see **typescript-error-handling**. - -## Event streams — not carried - -There is no SSE support. When the spec declares a `text/event-stream` success response, the generator -**still emits the operation** but gives it the **empty-body decoder**, because the vendored runtime -has no carrier for it. A **binary** success is different and is carried: it resolves to a -`BinaryContent` whose `stream` you read once or release — see **typescript-calling-endpoints**. - -The consequence of the empty decoder is specific and worth knowing before you debug it: it asserts -the body is empty, so such an operation **fails at the call** with `DecodeError` ("Expected an empty -response body") the moment the server sends anything — rather than quietly resolving something the -spec never described. The operation's **Returns** bullet reads `undefined` for these. - -Outbound, only an XML request body has no carrier, so such an operation is emitted with no body field -at all. Multipart and binary bodies are both sent. See **typescript-calling-endpoints**. - -**If you need one of these endpoints, call it with `fetch` directly** — build the URL from the same -base URL, and copy the credential header the SDK would have sent. The SDK cannot carry it, and no -option makes it. +> An operation whose **Signature** returns `ApiPromise` is a plain list call, however list-like its +> response. To page one of those, advance its own page or cursor field in a loop and stop on the API's +> end signal — read the field names off its **Fields** table and its response model — and carry the same +> bound: "fewer than `limit`" and "no next cursor" are both provider-supplied stop conditions, and +> neither is a bound. +> +> ```ts +> let cursor: string | undefined; +> let seen: string | undefined; +> for (let pages = 0; pages < MAX_PAGES; pages++) { +> const result = await client.{resource}.{operation}({ ...(cursor ? { cursor } : {}) }, { signal }); +> for (const item of result.{items}) process(item); +> cursor = result.{nextCursor}; +> if (!cursor) return; // the provider's end signal — the happy path +> if (cursor === seen) throw new Error("cursor did not advance"); +> seen = cursor; +> } +> throw new Error(`stopped after ${MAX_PAGES} pages`); +> ``` + +## Event streams and XML bodies + +An operation with a `text/event-stream` success response **is** carried: its **Returns** bullet reads +`EventStream`, the call resolves at the response headers, and you iterate the stream with +`for await` — load **typescript-event-streams** before you write the loop. Its one setting is +`eventStream.idleTimeout` on the client, which bounds the silence between events; `retry.timeout` +stops at the headers and never reaches the loop. + +Outbound, an operation with an XML request body has no body field. Call it with `fetch` directly — +the same base URL, and the credential header the SDK would have sent; no option makes the SDK carry +it. A **binary** success, and multipart and binary request bodies, **are** carried — see +**typescript-calling-endpoints**. ## Logging @@ -751,14 +679,14 @@ header — `authorization`, `cookie` and every api-key header are not on that li logged as it is. `redactedKeys` and `loggableContentTypes` **replace** their default rather than add to it, so spread `defaultLoggingOptions` to extend one, as above. -⚠▶▶ **`logRequestBody: true` does not redact a JSON body**, and only half-redacts a form body. A JSON -body is logged **verbatim** — truncated at `bodySizeLimit` bytes (32 KB), and only when its media type -is in `loggableContentTypes` (`application/json`, `application/x-www-form-urlencoded`). A form body gets -key masking, but by **deny-list**, not by the allow-list the URL uses: only keys in `redactedKeys` are -masked, so `card_number` in a form body prints in the clear although the same key in a query string -would not. Any other media type is not logged unless you add it to `loggableContentTypes`. On any -endpoint that carries card data, bank details, personal data or a credential in the body, switching -this on writes that data to your logs. Leave it off in production; turn it on for one endpoint at a time +⚠▶▶ **`logRequestBody: true` does not redact a JSON body**, and only half-redacts a form body. A body +is logged only when its media type is in `loggableContentTypes` (`application/json`, +`application/x-www-form-urlencoded`; add others there), truncated at `bodySizeLimit` bytes (32 KB). A +JSON body is logged **verbatim**. A form body gets key masking, but by **deny-list**, not by the +allow-list the URL uses: only keys in `redactedKeys` are masked, so `card_number` in a form body prints +in the clear although the same key in a query string would not. On any endpoint that carries card data, +bank details, personal data or a credential in the body, switching this on writes that data to your +logs. Leave it off in production; turn it on for one endpoint at a time behind a flag you can prove is off. ⚠▶▶ **An environment variable turns logging on without a code change.** When code sets neither a @@ -800,11 +728,9 @@ logging on at `info` for the first execution of any new call — `{APICLIENTTYPE 1. The **verb** matches the operation's **Wire** bullet in `map/operations/{resource}.md`. 2. The **base URL** is fully expanded — no leftover `{region}`-style server variable, which means a `baseUrl` you supplied carries a placeholder no declared variable fills. -3. The **path** is fully formed. Two different failures live here: a path field set to `null` collapses - to **nothing**, leaving a doubled slash (`/orders//confirm`); a path field left `undefined` is - rejected by its schema before anything is sent, as an `EncodeError` whose `uri` still shows the - unfilled marker. The first is silent, so it is the one to look - for. +3. The **path** is fully formed: a path field set to `null` collapses to **nothing**, silently, + leaving a doubled slash (`/orders//confirm`). (One left `undefined` rejects with `EncodeError` + before anything is sent.) 4. Each **path segment** holds the value you meant — for an enum that is the **wire value**, not the member name. 5. The **query parameters** you set are present, spelled as their `Wire` names. A `null` or `undefined` @@ -830,28 +756,22 @@ const client = new {Api}Client({ Set the header on a copy of the `Request` — the SDK has already put the content type and the credential on it, and the copy keeps them, the body and the signal. Passing `{ headers }` as `init` -instead **replaces** every header the SDK set, the credential included. This is also the only -client-wide header mechanism: the -transport carries default header, query and path-parameter channels, but the generated client currently -wires all three as empty arrays. If a later generator version starts populating them, a header option -could appear on `ClientOptions` — read `src/client-options.ts` rather than assuming the field list is -frozen. +instead **replaces** every header the SDK set, the credential included. This is the only client-wide +header mechanism: `ClientOptions` has no header option. ### Rate limiting -There is no built-in limiter. The default policy retries a `429` on an idempotent call and honours -its `Retry-After` (capped at 60 s), which absorbs an occasional limit; it does nothing to stop you -starting more calls than the provider allows. Put a concurrency/rate limiter around your calls for -that. Client-side limiting is the more predictable of the two under load — retrying into a rate limit +There is no built-in limiter. The default `429` retry absorbs an occasional limit but does nothing to +stop you starting more calls than the provider allows. Put a concurrency/rate limiter around your +calls for that. Client-side limiting is the more predictable of the two under load — retrying into a rate limit converts a fast failure into a slow one, and a fan-out of retrying calls keeps the pressure on. ### Circuit breaking Count consecutive `ConnectionError`s, `TimeoutError`s and 5xx `ApiError`s, open the circuit for a -cool-off window, and fail fast while it is open. **Put the breaker around the SDK call, not in `fetch`.** -A plain `Error` thrown from a `fetch` wrapper reaches the loop as a `ConnectionError`, which is retried -with backoff — the opposite of failing fast. Around the call, the breaker sees one outcome per call, -after the retries, and its refusal never enters the loop. +cool-off window, and fail fast while it is open. **Put the breaker around the SDK call, not in `fetch`**, +where its refusal would be retried as a `ConnectionError` (*The `fetch` seam*). Around the call, the +breaker sees one outcome per call, after the retries, and its refusal never enters the loop. ## Proxies and TLS (Node) @@ -914,8 +834,7 @@ nothing extra. Two consequences: - **A dispatcher you create is a pool you own.** Build it once, beside the client, and reuse it. A `new Agent(...)` or `new ProxyAgent(...)` per request opens a fresh pool — and therefore fresh TCP - and TLS handshakes — on every call, which is the same waste as a client per request without looking - like one. + and TLS handshakes — on every call. - **Pool limits live there too** — `connections`, `keepAliveTimeout`, `pipelining` on the `Agent`. Raise `connections` before assuming a provider is slow under a fan-out; the default cap can be the actual bottleneck. @@ -932,21 +851,19 @@ client costs under OAuth — is **typescript-client-initialization**. | request lines in the logs with no logging code | `{APICLIENTTYPENAME}_LOG` is set in that environment — set `logging.level` in code to own it | | a JSON body or a card number in the logs | `logRequestBody`, or a per-call `level`, which turns the body on — see *Logging* | | a failing call takes seconds longer to reject than the first failure | expected on an idempotent call: the default policy retried it — watch it with `retry.onRetry` | -| a `POST` fails on a `503` that a `GET` survives | expected: `POST` is outside the default `httpMethodsToRetry` | -| one handler takes far longer than `retry.timeout` | it is per attempt, and an idempotent call gets up to four — count the calls, then bound the handler with a signal | -| a page loop never returns | no provider-independent bound — see *Never leave a page loop unbounded* | +| a page walk never ends | no provider-independent bound — see *Never leave a page walk unbounded* | +| `PaginationError` naming another origin | the API's next link points off the API's host, and the SDK refuses to follow it — see *Pagination* | | requests still hit the real host under test | the wrong server **group** or **environment** overridden — check `src/servers.ts` | -| auth fails everywhere with credentials you know are right | `serverEnvironment` left to its default, which is the spec's **first** environment — often sandbox | +| auth fails everywhere with credentials you know are right | `serverEnvironment` left to its default, the **first** `ServerEnvironment` member — often sandbox | | the call works locally, fails behind a corporate proxy | Node's `fetch` ignores `HTTP_PROXY` — register `EnvHttpProxyAgent` or pass a `dispatcher` | -| a duplicate write despite an idempotency key | the key is generated inside the retried function — hoist it out; or your own retry layer re-calls the SDK, which mints a new injected key per call | +| a duplicate write despite an idempotency key | the key is generated inside the retried function — hoist it out; or your own retry layer re-calls the SDK, which sends a new `Idempotency-Key` per call | | ~16× the expected round-trips | a retry layer of your own stacked on the SDK's — set `retry: { maxRetries: 0 }` where you own retrying | | a test with one stubbed `503` hangs, or runs out of queued responses | the default policy fetched it four times across ~7 s of backoff — see **typescript-testing** | | a `{placeholder}` survives into the URL | a `baseUrl` you supplied names a variable the group does not declare | | `EncodeError` whose `uri` still shows a `{placeholder}` | a path field was `undefined` — a required field was omitted | | `ConfigurationError` about an unknown environment, thrown by the constructor | `serverEnvironment` is not a declared member | -| `DecodeError` "Expected an empty response body" | an event-stream response with no carrier — call it with `fetch` directly | +| an event-stream loop rejects with `TimeoutError` while the server is still connected | the server stayed silent past `eventStream.idleTimeout` — raise it, or set it to `null` and bound the wait with a `signal` (**typescript-event-streams**) | | a token is fetched on every call | a client built per request — see **typescript-client-initialization** | -| 401 on the first call, fine afterwards | expected: a 401 invalidates the token cache and is not in the default retry set | ## Next diff --git a/plugins/plaid/skills/typescript/typescript-error-handling/SKILL.md b/plugins/plaid/skills/typescript/typescript-error-handling/SKILL.md index db15dba1..32462fab 100644 --- a/plugins/plaid/skills/typescript/typescript-error-handling/SKILL.md +++ b/plugins/plaid/skills/typescript/typescript-error-handling/SKILL.md @@ -1,22 +1,17 @@ --- name: typescript-error-handling -description: Error handling for an APIMatic-generated TypeScript SDK — load before writing any try/catch around an SDK call, an error-translation layer, or middleware. Covers the one error family and its closed err.kind, the four throwables that sit outside it, which types actually reach your catch blocks, reading the status and the declared error body safely, the default arm that degrades instead of throwing, the failures the non-throwing form does not convert, the missing field that is silently undefined rather than an error, and the traps that make an otherwise reasonable catch ladder silently wrong. +description: Load before writing a try/catch around an APIMatic-generated TypeScript SDK call, translating its errors into your own, or reading a status code or error body — the SDK's one error family and its closed `err.kind`, the throwables outside it, per-operation typed error arms and the `"undeclared"` arm, and what `.asApiResult()` still rejects. --- # Error handling for an APIMatic TypeScript SDK -> Throughout this skill, `{...}` is a placeholder for a name you take from your SDK (e.g. `{Api}Client`, -> `{Api}Error`, `{package-name}`, `{Resource}`, `{Operation}`, `{arm}`) — replace it with the concrete -> identifier from the source. -> -> **One skill, every error shape.** This file covers every shape the generator can emit. Which shapes -> YOUR SDK uses — whether an operation declares typed arms or rejects with the base error, what each -> arm is called, which status it covers — are facts of the API definition, not of this skill: take -> them from the operation's page in `map/operations/{resource}.md` and **apply only the guidance that -> matches**. An API can declare typed errors on every operation, on none, or on a mix. +> `{...}` marks a name to take from your SDK (`{Api}Client`, `{Api}Error`, `{package-name}`, +> `{Resource}`, `{Operation}`, `{arm}`). Whether an operation has typed error arms, what they are +> called and which statuses they cover is per operation: read its page in +> `map/operations/{resource}.md` and **apply only the guidance that matches**. Operations are **throw-based** (for a non-throwing alternative, see **The non-throwing form** below), -and every **operational** failure belongs to **one family**: `{Api}Error`, a union over six leaves. +and every **operational** failure belongs to **one family**: `{Api}Error`, a union over seven leaves. One `instanceof {Api}Error` sees all of them, and `err.kind` says which one it is. Four throwables sit **outside** the family — a configuration fault, a codec called directly, a bug, and a caller abort — so a `catch` that tests the family has to rethrow whatever is left. @@ -33,7 +28,7 @@ try { // The API answered with an error status — read err.status and err.payload. break; case "decode": - // The answer did not fit the spec — read err.status and err.cause. + // The answer did not fit its declared type — read err.status and err.cause. break; case "encode": // Nothing was sent — err.cause is the SchemaError that rejected the value. @@ -43,6 +38,9 @@ try { case "auth": // No response was produced — err.kind says which. break; + case "pagination": + // A paged walk could not follow the next link the API sent — the pages before it were delivered. + break; } } else { throw err; // outside the family: an abort's reason, a configuration fault, or a bug @@ -55,28 +53,18 @@ opens with that pair — `"POST https://api.example.com/v1/{resource} failed wit ## What to import, and from where -Everything below comes from **one specifier — the package root**. Deep imports -(`{package-name}/core/…`) do not resolve: the `exports` map exposes `.` and `./package.json` and -nothing else. +Everything below comes from **the package root** — deep imports do not resolve +(**typescript-client-initialization**). | import | what it is | | --- | --- | -| `{Api}Error` | the whole family — a type **and** a value. The type is the union of the six leaves; the value is the abstract class they all extend, so `instanceof` and `err.kind` select the same set. It cannot be constructed or extended. The SDK-branded alias of `CoreError`, which is not exported under its own name | +| `{Api}Error` | the whole family — a type **and** a value. The type is the union of the seven leaves; the value is the abstract class they all extend, so `instanceof` and `err.kind` select the same set. It cannot be constructed or extended. Its real name — usually the API name plus `Error` — is on the `CoreError as …Error` line in `src/index.ts`; `CoreError` itself is not exported | | `ResponseError` | the part of the family the server answered on — `ApiError \| DecodeError`, the two that carry `status` and `headers`. A type and a value, like `{Api}Error` | | `ApiError` | `kind: "api"` — the API answered with an error status. The base every operation without declared error bodies rejects with, and the class every per-operation error extends | | `{Resource}.{Operation}Error` | the generated `ApiError` subclass for an operation that declares error bodies, on the **resource class's merged namespace** — not a free-standing export | -| `DecodeError` `EncodeError` `ConnectionError` `TimeoutError` `AuthError` | the other five leaves | +| `DecodeError` `EncodeError` `ConnectionError` `TimeoutError` `AuthError` `PaginationError` | the other six leaves | | `ConfigurationError` `SchemaError` | outside the family: a constructor fault, and a codec called directly | -| `type ErrorKind` `ErrorPayload` `Declared` `Undeclared` `HttpMethod` | type-only helpers, if you name them in your own signatures | - -`{Api}Error` is the SDK-branded name — **read the real one** from the `CoreError as …Error` line in -`src/index.ts`. It is the API name plus `Error` (`Acme` gives `AcmeError`), escalating to -`{Api}ApiError` and then a numeric suffix when that would collide with something the same clause -already re-exports (an API named `Api` cannot take `ApiError`). - -Everything under `src/core/` is vendored static code, **byte-identical in every generated TypeScript -SDK**, so the behaviours below hold without checking yours. What varies per SDK is which operations -declare arms, and what those arms are called. +| `type ErrorKind` `Declared` `Undeclared` `HttpMethod` | type-only helpers, if you name them in your own signatures | ## The family — every `err.kind` @@ -90,6 +78,7 @@ declare arms, and what those arms are called. | `"connection"` | `ConnectionError` | `fetch` rejected before a response line arrived | — | | `"timeout"` | `TimeoutError` | an attempt ran out its `retry.timeout`, and no retry was left | `timeout` — the budget that ran out | | `"auth"` | `AuthError` | a credential could not be **obtained** | — | +| `"pagination"` | `PaginationError` | a paged walk could not follow the next link the API sent — it was not a URL, or it named another origin | — | Every one carries `kind`, `method`, `uri`, `message` and, where there was an underlying failure, `cause`. `uri` is the absolute URL the call dialled, with the server variables expanded and the path @@ -102,8 +91,7 @@ by its schema arrives as an `EncodeError` whose `uri` still shows the unfilled ` a header or a value that failed its schema. That keeps response bodies and secrets out of logs and stack traces by default, which is a sound default and a trap: a handler that logs `err.message` and nothing else records that something failed and discards every diagnostic. Read `err.payload` (or -`err.cause`) explicitly and log the fields you choose — and on a `4xx` the caller caused, also put the -API's reason in your response. +`err.cause`) explicitly and log the fields you choose. `err.headers` is the `fetch` `Headers` object, not a plain object — look a header up with `err.headers.get("x-request-id")` (case-insensitive). Indexing it (`err.headers["x-request-id"]`) is @@ -111,8 +99,7 @@ always `undefined`, and spreading it gives you nothing. ## Four throwables outside the family -`instanceof {Api}Error` is `false` on each of these, so a `catch` that tests the family and then -stops has swallowed nothing — it just has to **rethrow the rest**, as the ladder at the top does. +`instanceof {Api}Error` is `false` on each of these: - **`ConfigurationError`** comes out of the **client constructor**, synchronously and before any call exists: no reachable `fetch`, a basic-auth username containing a colon (RFC 7617 §2), or an @@ -152,54 +139,35 @@ so a `3xx` lands here too. ### Which error does an operation reject with? -Four places give you the answer, in order of preference: - -1. **`map/operations/{resource}.md`** — the operation's **Error** bullet names the case, and for a - typed operation the **Error arms** bullet lists every arm with the status each covers and whether it - has a body. Start here. -2. **The **Signature** bullet on the same page** — the same fact as the second type argument of the - returned `ApiPromise`. -3. **`api-reference.md`** — per-operation prose, when you need what an arm *means* rather than its - shape. -4. **`src/resources/{resource}.ts`** — the source. The subclass's `static readonly errors` table is - the matcher list itself: one row per arm, each spelling `on` (the status, a `[from, to]` range, or - `"default"`), `kind`, and the decoder. - -All of these ship inside `node_modules/{package-name}/`, so read them there rather than the compiled -`dist/`. - -- **Case A — typed arms.** The spec declared failure bodies, so the generator emitted a subclass named - `{Operation}Error`, exported from the **enclosing class's merged namespace** — you catch - `{Resource}.{Operation}Error`, or `{Api}Client.{Operation}Error` for an operation the spec left - untagged. It redeclares `payload` with the operation's own arms. Narrow on `err.payload.kind`. +Take the case from the operation's **Error** bullet in `map/operations/{resource}.md`: for a typed +operation its **Error arms** bullet lists every arm with the status it covers and whether it has a +body, and the **Signature** bullet shows the same as `E` in `ApiPromise`. `api-reference.md` +says what an arm *means*; the source is `src/resources/{resource}.ts`. All of these ship inside +`node_modules/{package-name}/` — read them there, not in the compiled `dist/`. + +- **Case A — typed arms.** The operation has an `{Operation}Error` subclass of `ApiError` on the + **enclosing class's merged namespace** — catch `{Resource}.{Operation}Error`, or + `{Api}Client.{Operation}Error` for an operation that sits directly on the client. It redeclares + `payload` with the operation's own arms; narrow on `err.payload.kind`. - **Case B — no typed arms.** `E` is the **base `ApiError`**, its payload is always the `"undeclared"` arm, and there is no subclass to catch. -Guessing wrong is *sometimes* a compile error and sometimes not, and the direction that looks safe is -the dangerous one. A subclass that does not exist fails to compile — that guess TypeScript catches. But -naming a **neighbouring** operation's error class compiles cleanly, because it is a real type, and then -never matches at runtime: the rejection sails past your `catch` and surfaces somewhere else, or not at -all. Take the case from the map every time; the compiler is not a check on this. +Take the case and the arms from that operation's own page every time, never a neighbour's: a +neighbouring operation's error class compiles cleanly and never matches at runtime. ### Case A — reading the typed payload -> **This section applies only where the operation declares typed arms.** An operation whose **Error** -> bullet names the base `ApiError` has nothing to narrow — its payload is always `"undeclared"`. -> Skip to **Case B**. - -`err.payload` is a discriminated union with **one arm per failure response the spec declared**, plus -`"undeclared"`. Two things about arm names catch people out: +`err.payload` is a discriminated union: one arm per declared failure response, plus `"undeclared"`. +Arm names come from the body's schema, not the status — a model reference gives the model's name in +lower camel (`validationError`, then `validationError2` for a second status returning the same model), +anything else gives `error{Status}` (`error400`, `error4XX`) — so read them off the map. One arm can +cover many statuses: `4XX` covers `[400, 499]`, so check `err.status` for the exact one. -- **The name comes from the body's schema, not from the status.** An arm whose body is a direct model - reference is named after that model in lower camel (`validationError`); anything else — a - primitive, an array, a map, or no content — is named `error{Status}` (`error400`, `error4XX`, - `errorDefault`). So two statuses that return the *same* model give you two arms whose names differ - only by a numeric suffix (`validationError`, `validationError2`). Read the arm names off the map; - do not derive them from the status. -- **One arm can still cover many statuses** — not because two statuses were merged, but because the - spec declared a *range* or a `default:`. A `4XX` arm covers `[400, 499]`; a `default:` arm covers - **every error status no other arm covers**, `3xx` included. Check `err.status` when you need the - specific one. +**A spec's `default:` response is not an arm.** Every status the other arms miss is `"undeclared"` +with its bytes intact — the `520` a CDN, the `502` a gateway or the `403` a WAF answers on the API's +behalf included, whose HTML page the `default` schema never described. The model the spec named under +`default` is still under `src/models/`; decode `rawBody` through its schema by hand when the status is +one the API itself sent. ```ts import { {Resource} } from "{package-name}"; @@ -225,22 +193,12 @@ try { ``` **`"undeclared"` is always an arm, and it is not a catch-all.** It carries -`{ kind: "undeclared"; rawBody: ArrayBuffer }` and fires **only** for a status no declared arm covers -— or, where the operation declares a `default:` arm, for a body that arm could not decode. A status -that has an arm lands in that arm and leaves `"undeclared"` unreached — so a `catch` that handles only -`"undeclared"` silently drops every typed body. Handle every arm the map lists, and put `"undeclared"` -last. There is no operation whose failure is guaranteed typed: the generator emits the `"undeclared"` -arm unconditionally, so any operation can hand you raw bytes for a status it does not document. - -An arm can declare **no body** (`body: undefined`) — the spec named the status but gave it no schema. -It accepts only an **empty** body: any body on a status it covers (a JSON error message is typical) -rejects with `DecodeError`, even through `.asApiResult()`, and `err.status` still names it (see -**`"decode"`**). On a `"default"` arm that body degrades to `"undeclared"` instead. - -**The arms are per operation, and are not one set across the API.** A description that declares a -different error schema per tag gets a different model — and therefore a differently-named arm — per -tag, so a branch written against one operation's arm does not apply to a sibling's. Take the arms from -that operation's **Error arms** bullet every time; never reuse a set from a neighbouring call. +`{ kind: "undeclared"; rawBody: ArrayBuffer }` and fires **only** for a status no declared arm covers, +so any operation can hand you raw bytes, and a `catch` handling only `"undeclared"` drops every typed +body. Handle every arm the map lists, and put `"undeclared"` last. An arm can declare **no body** +(`body: undefined`); it accepts only an **empty** body — any body on a status it covers (a JSON error +message is typical) rejects with `DecodeError`, even through `.asApiResult()`, and `err.status` still +names it (see **`"decode"`**). Where your boundary treats several arms alike, group them with fall-through cases rather than repeating the body — but only over fields they **all** declare: @@ -286,14 +244,12 @@ with HTML or plain text. Decode it to a string before you try to parse it, and e ### Matcher precedence -For a subclass with several arms, the runtime matches in **three passes**: an exact numeric status -across the whole table first, then the first covering range, and last a `"default"` arm where the -spec declared one. So a specific `404` arm beats a `4XX` arm regardless of declaration order, and a -`default:` arm can never shadow a narrower one. +An exact numeric status wins over a covering range, so a specific `404` arm beats a `4XX` arm +regardless of declaration order. -A body that does not fit the arm it matched is a **`DecodeError`** — except on `"default"`, which -describes no status in particular and so **degrades to the `"undeclared"` arm**, raw bytes and all, -rather than throwing. +A body that does not fit the arm it matched is a **`DecodeError`**. A status no arm covers is the +`"undeclared"` arm, which every subclass ends in; a spec's `default:` response is never a row, so +nothing a middleware answers on the API's behalf can fail a schema the API wrote. ### Catch order @@ -332,7 +288,7 @@ Which status it came on matters a lot, and `err.status` tells you: Mapping both onto one 5xx is wrong half the time — it tells a retrying caller to keep retrying something that can never succeed. Only a **declared** arm can decode-fail: the `"undeclared"` arm reads -raw bytes and never decodes, and a `default:` arm degrades instead of throwing. +raw bytes and never decodes. ```ts if (err instanceof DecodeError) { @@ -353,12 +309,9 @@ let a production ladder quietly absorb it — it should fail loudly in developme **`AuthError` is about obtaining a credential, not about being refused one.** A 401 *from the API* is an `ApiError` like any other status, so one `catch` arm cannot absorb the other. -A 401 does have one auth consequence: it **invalidates whatever that operation's scheme had cached**, -so the **next** call re-acquires. `401` is not in the default `statusCodesToRetry`, so the current -request fails and recovery happens on the following call. To have the current call re-sent with a -fresh token instead, add `401` to `statusCodesToRetry`: every attempt resolves its credential again, so -the retry carries the re-acquired token. A static key is re-sent unchanged, so that only helps a scheme -that fetches its credential. +A 401 from the API also invalidates the scheme's cached credential, so the **next** call re-acquires +(**typescript-authentication**). A single `401` is therefore not a permanent credential failure: do not +tear down the client or alert on one. `AuthError` means the token grant failed, every configured branch of an alternatives requirement failed, PKCE was disabled without a client secret, or your own authorization-code prompt rejected. Its @@ -374,20 +327,26 @@ is still an `AuthError` with the endpoint's `ApiError` on `.cause`, never the ba Otherwise it is an `AuthError` whose `cause` is an `AggregateError` holding what each branch threw, in the order tried. An abort or a timeout escapes immediately rather than being collected. -Auth resolves *before* the request is sent, so an `AuthError` means **nothing was sent** — it is an -auth fault, not a rejection. Check it early in your ladder. +⚠ **An `AuthError` means nothing was sent, and it surfaces from an operation call, not from client +construction.** The token is acquired lazily, before the request exists, so an auth misconfiguration +rejects whichever operation ran first — reading like a problem with that operation — and rejects in +`.asApiResult()` mode too. Check it early in your ladder. -⚠ **The token is acquired lazily, on first use — so an auth misconfiguration surfaces from an -operation call, not from client construction.** The rejection points at whichever operation happened to -run first, which reads like a problem with that operation rather than with the credentials you wired -up. It also rejects in `.asApiResult()` mode, for the same reason: the grant happens before a request -exists to return a result for. +## `"pagination"` — a next link could not be followed + +Raised from inside a paged walk, **between two pages**: the page that carried the link has already been +delivered, and a loop that stops after it never sees this. A `Link` strategy follows a link only when it +resolves, against the URL of the page that carried it, to the same scheme, host and port as the API, so +no credential ever leaves the API. A link to another origin is refused, and so is one that is not a +URL. For a link to another origin, `err.uri` names the call that was refused; for a link that is not a +URL there is no such call, so `err.uri` names the page that carried it and `err.cause` holds the +platform's parse failure. It is a `{Api}Error`, so the ladder at the top already catches it; the +offset, page-number and cursor strategies never raise it. ## A missing field is not an error — it is `undefined` -This is the gap the error types leave, and the one most likely to reach production. A model member the -description did not mark **required** is emitted as `member?: T` over an optional schema entry, so a -response that simply **omits** it validates cleanly. No `DecodeError` is thrown, and nothing warns you: +A model member not marked **required** is `member?: T`, so a response that simply **omits** it +validates cleanly. No `DecodeError` is thrown, and nothing warns you: ```ts const value = await client.{resource}.{operation}({ /* ... */ }); // 200, truncated body @@ -436,20 +395,21 @@ no per-status judgement. Reach for it when an error status is an expected outcom found yet", a `409` meaning "already exists") and you would otherwise be using exceptions for control flow, or when you need `status` and `headers` on the *success* path. -Two mechanics to know: the failure branch is a plain object carrying **the error's own members under -their own names** — `status`, `headers`, `message`, `method`, `uri` and `payload` — never the error -instance, so you narrow on `outcome.payload.kind` exactly as you would on `err.payload.kind`, and a -handler moves between the two forms by swapping the prefix; and `.asApiResult()` must be called on the -value the operation returned, **before any `.then()`**, because `ApiPromise` overrides -`Symbol.species` and the method is gone from what `.then()` hands back (see -**typescript-calling-endpoints**). - -⚠ **This mode is not rejection-free, and the cases it does not convert are the ones people assume it -does.** A decode failure is not an API error status, so it propagates in both modes rather than -becoming an `ok: false` value — a `DecodeError` on a `2xx` body, and a `DecodeError` on a **declared -error arm**, both still reject. So does a failed token acquisition, because the credential is resolved -before anything is sent, and so does a caller abort. `try`/`catch` is still required around -`.asApiResult()`; it narrows what you catch, it does not remove the need to catch. +The failure branch is a plain object carrying **the error's own members under their own names** — +`status`, `headers`, `message`, `method`, `uri` and `payload` — never the error instance, so you narrow +on `outcome.payload.kind` exactly as you would on `err.payload.kind`, and a handler moves between the +two forms by swapping the prefix. Call `.asApiResult()` on the value the operation returned, **before +any `.then()`** (**typescript-calling-endpoints**). + +⚠ **Every failure other than an error status still rejects** — a `DecodeError` (on a `2xx` body or on +a **declared error arm**), a failed token acquisition and a caller abort included — so keep the +`try`/`catch` around `.asApiResult()`. + +**On a paged operation**, `.asApiResult()` is called on the walk and returns `PageableApiResult`: its +`.pages()` yields one `ApiResult` per page, and a failed page is the **last** element it yields; its +item loop ends silently at an error status and contributes no items for it, so an item loop that ends +cannot tell the last page from a failed one. Everything the single-call form still throws, the walk +still throws too, with `PaginationError` beside them. ## Transport failures, and guarding every call site @@ -458,23 +418,15 @@ DNS that failed, a connection that dropped, or an attempt's timeout elapsing — `"connection"` and `"timeout"`, and a `catch` whose only arm is `err instanceof ApiError` lets them escape and take down whatever was running the call. -**Every one of them reaches you after the retries are spent.** On a `GET`, `HEAD`, `PUT` or `OPTIONS` -call the default policy re-sends a `408`, `429`, `500`, `502`, `503` or `504`, a connection failure -and a timeout up to -three times before the call rejects, so what you catch is the **last** attempt's failure — an -`ApiError` for the final status, or a `ConnectionError` or `TimeoutError` — in exactly the shape it -would have had with retrying off. A write outside `httpMethodsToRetry` rejects on its first failure. -Do not retry a family error the SDK already retried; see **typescript-configuration-resilience**. - -**Unlike SDKs that let their HTTP library's exceptions through, this one wraps them.** Whatever your -`fetch` rejects with becomes a `ConnectionError`, with the original on `.cause` — so your boundary -never imports the transport's exception types, and it does not need revisiting when you swap `fetch` -for a wrapper. Two things pass through unwrapped: anything that is already in the family (a -`{Api}Error` your own wrapper threw), and a cancellation — the caller's own abort `reason`, or the -SDK's `TimeoutError` when an attempt's timeout fired, whatever your `fetch` rejected with. If you wrap -`fetch` to add a guard (**typescript-configuration-resilience**), throw a family error from it or -accept that yours will arrive as `err.cause` — and know that a plain error thrown there is a -`ConnectionError` the retry loop retries. +**Each reaches you after the SDK's retries are spent** — as the **last** attempt's failure, in the +shape it would have had with retrying off; do not retry it again (**typescript-configuration-resilience** +owns the policy). + +Whatever your `fetch` rejects with becomes a `ConnectionError` with the original on `.cause`, so your +boundary never imports transport exception types. A family error and a cancellation (your abort +`reason`, or the SDK's `TimeoutError` once an attempt's timeout fired, whatever your `fetch` rejected +with) pass through unwrapped — and a plain error your own `fetch` wrapper throws is a `ConnectionError` +the retry loop retries. **Convert the family to your own error type in one place.** If you wrap the SDK behind your own abstraction (a client interface, a service, a repository), do the conversion at that boundary so the @@ -523,11 +475,6 @@ or modify something and overlook the calls that only read — especially reads o a screen, a scheduled job, a startup or health check). A connection failure during a read fails just as hard as one during a write. A call left unguarded next to one that is guarded is the one that breaks. -⚠ **A rejection you never await is an unhandled rejection**, exactly like any other promise's: -`unhandledRejection` on Node — which by default ends the process — and `unhandledrejection` in a -browser. Await every call, or attach your own handler. `.asApiResult()` marks the promise handled as -its first act, so call it on the value the operation returned, in the same turn. - ## Presenting failures at your boundary — coherent, distinct, leak-free The catches above decide what you catch; this decides what the caller (an HTTP response, a UI layer, @@ -573,10 +520,9 @@ unauthenticated or throttled when they are neither. Those belong in the 5xx buck conflict and not-found are the caller's to fix. And keep the default arm at 5xx: a status you have not mapped is an unknown, not a caller error — the provider can add one without warning you. -**An unreadable body is not one case but two — decide which before you map it.** A `DecodeError` on a -**success** status is genuinely unknown: 5xx. One on an **error** status is not — the provider rejected -the request and only the *detail* was lost, so answering 5xx tells a retrying caller to keep retrying -something that can never succeed. `err.status` is what separates them; the type alone does not. +**An unreadable body is not one case but two** (*`"decode"` — the answer did not fit*): a `DecodeError` on a **success** +status is genuinely unknown, so 5xx; one on an **error** status is the provider's rejection with the +detail lost, so map it by `err.status`. **Never map a decode failure onto a domain absence.** "I could not read the answer" is not "the provider said no." It is tempting on a lookup — an unreadable body and a genuine miss both leave you @@ -607,26 +553,10 @@ if (typeof err === "object" && err !== null && "kind" in err && "uri" in err) { ## Notes -- **Retries are on by default.** An idempotent call is retried on `408`, `429`, `500`, `502`, `503`, - `504`, a dropped - connection and a timeout, honouring `Retry-After`, before it rejects; a write is not, unless its - method is in `httpMethodsToRetry`. The error you catch is the last attempt's. See - **typescript-configuration-resilience**. -- **A single `401` is not a permanent credential failure.** It invalidates the cached token and, by - default, is not re-sent; the caller sees that one `401`, and the *next* call acquires afresh. Do not tear down a - client or alert on one. -- **Failures are logged only when you turn logging on.** Logging is off by default; with - `ClientOptions.logging` on, the SDK writes a `warn` line for a non-`2xx` response and an `error` line - for a call that ends on a fault or on a credential it could not obtain (see - **typescript-configuration-resilience**). Neither is a substitute for handling the error: log what - your own code decided in your `catch`. -- **No raw `Response`.** `status` and `headers` are on `ApiResult` and on a `ResponseError`; the - `fetch` `Response` is deliberately unreachable. -- **A missing credential is not an error.** An unset credential member sends no credential, so the - failure surfaces as an `ApiError` `401` from the API rather than anything at construction — which - reads like an expired token instead of a config bug. This holds for composite schemes too: a - partially configured `all`/`any` scheme sends what it has rather than refusing, so there is no local - "auth could not be satisfied" rejection to catch. See **typescript-client-initialization**. +- **The SDK logs a failure only when its logging is on**, which it is not by default + (**typescript-configuration-resilience**) — log what your own code decided in your `catch`. +- **A missing credential is not an error**: the call goes out without it and the API answers `401` + (**typescript-authentication**). - **SDK errors do not survive a worker or process boundary intact.** `structuredClone` and `postMessage` reduce an `Error` subclass to a plain `Error` — `name`, `message` and `cause` survive; `kind`, `method`, `uri`, `status` and `payload` do not. Convert to your own serializable shape diff --git a/plugins/plaid/skills/typescript/typescript-event-streams/SKILL.md b/plugins/plaid/skills/typescript/typescript-event-streams/SKILL.md new file mode 100644 index 00000000..385baf1e --- /dev/null +++ b/plugins/plaid/skills/typescript/typescript-event-streams/SKILL.md @@ -0,0 +1,144 @@ +--- +name: typescript-event-streams +description: Consuming a server-sent-events (text/event-stream) operation on an APIMatic-generated TypeScript SDK — what EventStream yields (each event's decoded data, nothing else), how the loop must end so the connection is released, narrowing a union on the yielded value, what rejects and when (the loop raises the same error family as the call, and there is no SSE error class), and bounding the wait with the client's idleTimeout. Load before writing the loop over an operation that resolves to an event stream, in addition to `typescript-calling-endpoints`. +--- + +# Event streams on an APIMatic TypeScript SDK + +> Throughout this skill, `{...}` is a placeholder for a name you take from your SDK (e.g. `{resource}`, +> `{operation}`, `{Api}Error`) — replace it with the concrete identifier from the source. + +An operation whose success response is `text/event-stream` returns `ApiPromise, E>` +rather than a value. The promise resolves as soon as the response **headers** arrive, before anything +is read — what is deferred is the body, and the stream holds its connection until it is released. +`T` is the type the spec gives every event's `data`: a string, a model, an array, or a union. + +```ts +const stream = await client.{resource}.{operation}({ /* ... */ }); +for await (const event of stream) { + event; // T — one event's data, already decoded +} +``` + +Iterating yields `T` itself, each event's decoded `data` and nothing else: the `event:` name and +`id:` lines of the wire format are not surfaced, so there is no envelope to unwrap and no `kind` +beyond what `T` declares. Nothing is read ahead of your loop, so a slow loop body slows delivery +rather than buffering events in memory. Where the operation declares a terminating event (the map's +**Returns** bullet names it, such as a `[DONE]` data line), the SDK consumes it, closes the stream and +never yields it; a body that closes before that line arrived is a clean end too. + +## Start here + +**Drain the loop.** Reaching the end releases the connection, so the shortest correct code is a plain +`for await`: + +```ts +for await (const event of await client.{resource}.{operation}({ /* ... */ })) { + handle(event); +} +``` + +**Leaving the loop early releases it too** — `break`, `return`, or a `throw` inside the body all +close the stream before control leaves. A stream you decide not to read at all is released with +`await stream.close()`, and where your runtime declares `Symbol.asyncDispose`, `await using` does +the same at block exit: + +```ts +await using stream = await client.{resource}.{operation}({ /* ... */ }); +for await (const event of stream) { + if (done(event)) break; // the stream is released either way +} +``` + +## How the iteration ends + +| You want | Write | Releases | +|---|---|---| +| the whole stream | a plain `for await` | at the end of the stream | +| to stop at a condition | `break` / `return` inside the loop | as the loop exits | +| a stream you will not read | `await stream.close()` | your `close()` | +| release at block exit | `await using stream = …` | the block | +| to stop from elsewhere | abort the `signal` you passed | the SDK cancels its own reader | + +`close()` is idempotent, and a pending `next()` ends with `done` rather than an error. A stream is +**single-use**: a second `for await` over the same `EventStream` throws a `TypeError`, exactly as a +second read of a web `ReadableStream` does. `stream.toReadableStream()` hands you the same values as a +web `ReadableStream` and takes the stream's one iteration. + +## What the loop yields + +| The success schema is | each `event` is | Narrow with | +|---|---|---| +| `type: string` | `string` — the event's text, verbatim | nothing — it is the value | +| an object schema | `{Model}` | nothing — it is the model | +| an array schema | `{Model}[]` — one batch per event, no wrapper model | nothing | +| a `oneOf` with a discriminator | `{Union}` | `switch (event.kind)` | + +Every event decodes through the **one** schema the spec declares for the stream, whatever name the +server gave it, so a union is narrowed on its own discriminant. An error the API reports *inside* the +stream is an event like any other: the spec declares its shape as an arm of the union, the loop +yields it, and the stream goes on unless you `break`. + +## What can go wrong + +| What failed | Direct call | `.asApiResult()` | +|---|---|---| +| a non-2xx status (the headers) | rejects at the call with `ApiError` (or the operation's typed subclass) | resolves `{ ok: false }` — no rejection | +| a 2xx that is not `text/event-stream` | nothing checks the media type: the call resolves and the body is read as event frames, so a JSON body usually ends the loop cleanly with no event | same | +| an event whose `data` does not fit the schema | the loop rejects with `DecodeError`, stream released | same | +| the connection dies mid-read | the loop rejects with `ConnectionError` | same | +| the body closes before the declared sentinel arrived | the loop ends cleanly; every event the server sent was delivered | same | +| the server sends nothing for `idleTimeout` | the loop rejects with `TimeoutError`, `timeout` = the idle bound | same | +| you abort the `signal` | the pending `next()` rejects with the signal's own `reason` — **not** an `{Api}Error` | same | +| a second iteration of one stream | `TypeError` at the `for await`, a bug | same | + +**There is no SSE error class.** Everything the loop raises is a leaf of the one `{Api}Error` family, +the same `DecodeError`, `ConnectionError` and `TimeoutError` the call itself can raise, narrowed on +`err.kind` exactly as `typescript-error-handling` describes. Put that boundary around the **loop**, not +only the call — the call settles as soon as the headers arrive: + +```ts +try { + const stream = await client.{resource}.{operation}({ /* ... */ }); + for await (const event of stream) { + handle(event); + } +} catch (err) { + if (err instanceof {Api}Error) { + // err.kind is "api" before the stream existed, and "decode", "connection" or "timeout" from the loop + } else { + throw err; // a caller abort or a bug — not ours + } +} +``` + +## Resuming + +The SDK does not read the `id:` lines and the stream carries no resume point. Where the spec declares +a `Last-Event-ID` header, the operation's request type carries it as an optional field the SDK sends +verbatim; what to put in it is yours to track, from the data the events carry, because no event id +reaches your loop. + +## Bounding the wait + +The client's `retry.timeout` stops at the response headers; an event stream has its own clock. +`ClientOptions.eventStream.idleTimeout` (default `60_000` ms) is how long the server may stay silent +while your loop waits for the next event — any bytes reset it, a heartbeat comment included, and it +runs only while an iteration is waiting, so time your loop body spends on an event never counts. +`null` turns it off; `0` is a zero-length window. It is resolved once, as the client is built, and no +call overrides it. For a total budget, pass a `signal` and abort it: the SDK cancels its own reader, +so the stream stops whatever your `fetch` does with the body. + +## The non-throwing form + +`.asApiResult()` resolves to `{ ok: true, status, headers, value }` with `value` the `EventStream` +— the only way to read the opening status and headers of a stream — or `{ ok: false, … }` for an +error status. The loop over `result.value` still rejects for the failures in the table above. + +## Testing an event stream + +Fake `fetch` (`typescript-testing`) and hand the SDK a `Response` whose body is a `ReadableStream` of +event frames under `content-type: text/event-stream` — `data: {...}\n\n`, one blank line ending each +event. The SDK reads the body in the transport's own chunks, so split a frame across two `enqueue` +calls to prove the loop does not depend on where the network cuts, and record what the body's +`cancel` receives to prove that `break` released the connection. diff --git a/plugins/plaid/skills/typescript/typescript-getting-started/SKILL.md b/plugins/plaid/skills/typescript/typescript-getting-started/SKILL.md index 870eacda..6c486fcd 100644 --- a/plugins/plaid/skills/typescript/typescript-getting-started/SKILL.md +++ b/plugins/plaid/skills/typescript/typescript-getting-started/SKILL.md @@ -1,41 +1,36 @@ --- name: "typescript-getting-started" -description: "The Plaid API TypeScript SDK identity and lookup layer (TypeScript/JavaScript only) — install, the single import specifier `the-plaid-api`, the server environments and the base-URL knob, the auth pattern, the SDK map that ships inside the installed package (`sdk-map.md` + `map/operations/`) and how to traverse it, and the file table naming the one source file owning each fact the map leaves to the source. Load this before answering any The Plaid API TypeScript SDK contract question or writing any SDK code." +description: "Load before answering any The Plaid API TypeScript SDK question or writing SDK code — the lookup layer for `the-plaid-api`: install, imports, environments, auth, and how to read the SDK map that ships in the package (`sdk-map.md`, `map/operations/`). TypeScript/JavaScript only." --- # Getting started with the The Plaid API TypeScript SDK -> **Who this skill is for.** This is the **lookup layer** for anyone writing The Plaid API TypeScript SDK code — it is yours to follow directly and fully. Ground every contract fact here (in the SDK map, and in the source files it names) rather than in recall, and carry those facts onto a contract sheet before you implement. Load `typescript-integrate-the-plaid-api` for the workflow that wraps this skill. +> **The lookup layer** for The Plaid API TypeScript SDK code: ground every contract fact here — in the SDK map and the source files it names — never in recall, and carry those facts onto a contract sheet before you implement. `typescript-integrate-the-plaid-api` holds the workflow around it. -This is the **SDK-specific** entry point. For general patterns that apply to any APIMatic-generated TypeScript SDK (client construction, auth, calling endpoints, models, error handling, resilience, testing), see the companion API-agnostic skills: `typescript-client-initialization`, `typescript-authentication`, `typescript-calling-endpoints`, `typescript-models`, `typescript-error-handling`, `typescript-configuration-resilience` and `typescript-testing`. - -**This page and those companion skills are complementary — load both.** This page is authoritative for the SDK's *identity and surface* (what to install, what to import, the resources, which file owns which fact); the companion skills are the *usage layer* on top — the best-practice way to call each piece and the gotchas a signature cannot show. Reading a file in the installed package does not remove the need to load the skill for that step, so at each step below, load the companion *and* confirm names against the installed package. +This page is authoritative for the SDK's identity and surface. The API-agnostic companion skills — `typescript-client-initialization`, `typescript-authentication`, `typescript-calling-endpoints`, `typescript-models`, `typescript-error-handling`, `typescript-configuration-resilience` and `typescript-testing` — are the *usage layer* on top: the way to call each piece and the gotchas a signature cannot show. **Load both:** at each **Integration workflow** step, load the companion it names even after reading the file it covers, and confirm names against the installed package. ## SDK identity -Verified against `package.json` and `sdk-map.md` of the generated package at version `0.1.0`. **Re-verify after a version bump** — this page is a snapshot, not a live read. +Verified against `package.json` and `sdk-map.md` of the package at version `0.1.0`. **Re-verify after a version bump** — this page is a snapshot, not a live read. | Fact | Value | | --- | --- | | API | The Plaid API | | Package name (what you install, and what you import) | `the-plaid-api` — **not on npm**; built from source (see *Install*) | -| Import specifier | `the-plaid-api` — the package root is the **only** entry; deep imports do not resolve | | Source repository | https://github.com/context-plugins/plaid-typescript-sdk (branch `main` — the ref this map documents) | | Version | `0.1.0` (API spec version `2020-09-14_1.708.0`) | -| Client class | `ThePlaidApiClient` (`src/client.ts`) — one class, no sync/async split | -| Options type | `ClientOptions` (`src/client-options.ts`) — types only, no resolver beside it | -| Client construction | `new ThePlaidApiClient(options: ClientOptions = {})` — the argument is optional, as is **every** field on it, so `new ThePlaidApiClient()` compiles. Fields: `serverEnvironment` · `serverOptions` · `retry` · `fetch` · `clientId` · `secret` · `plaidVersion` · `oauth2` · `oauth2Strategy`. `retry` is the `RetryOptions` policy; its defaults retry a GET, HEAD, PUT or OPTIONS call up to `3` times and bound each attempt by `retry.timeout` = `60_000` ms, and every one of them can be changed | +| Client class | `ThePlaidApiClient` (`src/client.ts`) | +| Options type | `ClientOptions` (`src/client-options.ts`) | +| Client construction | `new ThePlaidApiClient(options: ClientOptions = {})` — the argument is optional, as is **every** field on it, so `new ThePlaidApiClient()` compiles. Fields: `serverEnvironment` · `serverOptions` · `retry` · `logging` · `fetch` · `clientId` · `secret` · `plaidVersion` · `oauth2` · `oauth2Strategy`. `retry` is the `RetryOptions` policy | | Auth | **API key (header)** — set `ClientOptions.clientId`
**API key (header)** — set `ClientOptions.secret`
**API key (header)** — set `ClientOptions.plaidVersion`
**OAuth 2 client credentials** — set `ClientOptions.oauth2` | -| Environments | 2 environments (`ServerEnvironment.Production` *(default)*, `ServerEnvironment.Environment2`) × 2 server groups | -| Base-URL config | `serverOptions..baseUrl` (`src/servers.ts`) | +| Environments | 2 environments (`ServerEnvironment.Production` *(default)*, `ServerEnvironment.Environment2`) × 1 server group | +| Base-URL config | `serverOptions.baseUrl` (`src/servers.ts`), defaulting to `https://production.plaid.com` | | Log environment variable | `THE_PLAID_API_CLIENT_LOG` | | Node floor | `>=20.3` (`engines.node`) | -| Runtime dependency | `zod` (`^4.1.0`), imported as `zod/v4-mini` — the only one | +| Runtime dependency | `zod` (`^4.1.0`) — the only one | | Module format | dual ESM + CommonJS folder dialects (`dist/esm`, `dist/commonjs`) behind one export | -| Typing | the package ships its own `.d.ts` and is generated under strict TypeScript. Callers get full inference — **a type error against this SDK is a real contract violation, not noise** | -| Surface | 335 operations · 0 resources · 1750 models · 354 open enums · 289 per-operation error subclasses | - -The table above is **orientation, not a copy-paste recipe** — it gives you the names and facts (install, import specifier, the auth *pattern*, the base-URL knob), while the actual integration code comes from the companion skills. Load each one as you reach its step (see **Integration workflow** below) and confirm its types against the installed package. +| Typing | the package ships its own `.d.ts` — **a type error against this SDK is a real contract violation, not noise** | +| Surface | 335 operations · 0 resources · 1750 models · 354 open enums · 1 per-operation error subclass | ## Install @@ -47,11 +42,11 @@ npm install git+https://github.com/context-plugins/plaid-typescript-sdk#main The installed package carries everything its `files` list packs — `src/`, `sdk-map.md` and the pages under `map/operations/` — so **every lookup on this page works as soon as the install finishes**. **Make sure the installed package is built**, as the source on GitHub is not pre-built. -Do not vendor its `src/` into your project, point `tsconfig` `paths` at a throwaway clone, or import from `dist/` directly. Installing the package properly is what makes the `exports` map, the shipped `.d.ts` chain and the dual-dialect resolution behave the way the SDK expects — **and it is what puts the SDK map inside `node_modules`, which is where every lookup below reads it from**. Requires Node `>=20.3` (`engines.node`). +Do not vendor its `src/` into your project, point `tsconfig` `paths` at a throwaway clone, or import from `dist/` directly: the `exports` map, the shipped `.d.ts` chain, the dual-dialect resolution and the SDK map in `node_modules` all depend on a real install. ## Imports — one entry, and only one -**Every** public name is re-exported from the package root — the client, `ClientOptions`, `ServerEnvironment`, 2104 model types with the schema value beside each, the error classes, and the runtime types (`ApiPromise`, `ApiResult`, `RequestOptions`, `RetryOptions`, `RequestRetryOptions`, `ErrorPayload`, `Declared`, `Schema`, `EnumSchema`, `Encoded`). +**Every** public name is re-exported from the package root — the client, `ClientOptions`, `ServerEnvironment`, 2104 model types with the schema value beside each, the error classes, and the runtime types (`ApiPromise`, `Pageable`, `PageableApiResult`, `ApiResult`, `RequestOptions`, `RetryOptions`, `RequestRetryOptions`, `Declared`, `Undeclared`, `Schema`, `EnumSchema`, `Encoded`, `JsonValue`). ```ts import { ThePlaidApiClient, ServerEnvironment, ApiError, ThePlaidApiError } from "the-plaid-api"; @@ -62,28 +57,20 @@ Things the specifier alone will not tell you: - **Deep imports do not resolve.** The `exports` map exposes `.` and `./package.json` and nothing else, so `the-plaid-api/models/…` fails (`TS2307`) even though the file exists in the shipped `src/`. Every `Source` path on the SDK map is where to **read** a shape, never what to import. - **⚠ The SDK exports a model type literally named `Error`** (`src/models/error.ts`, schema `errorSchema`). Import it unaliased and it **shadows the global `Error`** for the rest of the file. Alias it: `import type { Error as SdkError } from "the-plaid-api"`. -- **From CommonJS**, the typed spelling is `import sdk = require("the-plaid-api")`. A plain `require` destructure runs but yields `any`. -- **`instanceof` is reliable within one dialect.** A process that loads both (`import` in one file, `require` in another) gets two independent copies of every error class, and `instanceof` across that boundary is `false` — narrow on `err.kind` / `err.payload.kind` / `err.name` there. +- **From CommonJS**, the typed spelling is `import sdk = require("the-plaid-api")`. A plain `require` destructure runs but yields `any`. A process that loads both dialects gets two copies of every error class, so `instanceof` fails across them (`typescript-error-handling`). Under `verbatimModuleSyntax`, names carrying no runtime value (`ClientOptions`, every model type) must be imported with `import type`. Under `exactOptionalPropertyTypes`, **omit or spread** an absent optional field rather than assigning `undefined` to it. ## Environments -`ClientOptions.serverEnvironment` selects one environment for the whole client (`src/servers.ts`). `ServerEnvironment` is a `const` object with a derived union type — not a TypeScript `enum` — and unlike the model enums it is **closed**, so only its declared members are assignable. - -| Group | Environment | Base URL | Override at | -| --- | --- | --- | --- | -| `default` | `production` *(default)* | `https://production.plaid.com` | `serverOptions.default.baseUrl` | -| `default` | `environment2` | `https://sandbox.plaid.com` | `serverOptions.default.baseUrl` | -| `accessTokenServer` | `production` *(default)* | `https://api.plaid.com/oauth2/apiv2` | `serverOptions.accessTokenServer.baseUrl` | -| `accessTokenServer` | `environment2` | `https://api.plaid.com/oauth2/apiv2` | `serverOptions.accessTokenServer.baseUrl` | +`ClientOptions.serverEnvironment` selects one environment for the whole client (`src/servers.ts`). `ServerEnvironment` is a `const` object with a derived union type — not a TypeScript `enum` — and unlike the model enums it is **closed**, so only its declared members are assignable. The base URL of every server group in every environment, with its template variables, is in `sdk-map.md` § *Servers & auth*; override one at `serverOptions.baseUrl`. Consequences to state on every contract sheet that touches configuration: - Constructing the client with no options selects **`ServerEnvironment.Production`**, silently. -- An override merges with the built-in default **per group-and-environment pair, key by key**; a `baseUrl` override replaces the template verbatim, template variable values are percent-encoded into it; server variables are filled in once, as the client is built, and only the path parameters expand per request. -- Each operation is bound to one server group at generation time. A map block carries a **Server** bullet only when its group is not `default`. -- An environment value the SDK does not know throws `ConfigurationError` **from the constructor** — every server group is resolved once, as the client is built — so no operation method throws synchronously. +- An override merges with the built-in default **per group-and-environment pair, key by key**; a `baseUrl` override replaces the whole template. +- Each operation belongs to one server group; a map block carries a **Server** bullet only when its group is not `default`. +- An environment value the SDK does not know throws `ConfigurationError` **from the constructor**. ## Auth pattern (4 schemes) @@ -101,43 +88,35 @@ const client = new ThePlaidApiClient({ clientId: process.env.API_KEY!, secret: process.env.API_KEY!, plaidVersion: process.env.API_KEY!, - oauth2: { clientId: process.env.CLIENT_ID!, clientSecret: process.env.CLIENT_SECRET! }, + oauth2: { clientId: process.env.CLIENT_ID!, clientSecret: process.env.CLIENT_SECRET!, scope: "user:write" }, // Plaid requires a scope }); ``` -**Every credential field is optional at the type level and that is a trap worth flagging on every sheet.** Omit one and nothing fails at construction — the request simply goes out without that credential and the server decides. Most APIs then answer `401`; one that serves anonymous traffic answers `200` and hides the omission entirely. So a `401` on a call you believed was authenticated is usually an unset field rather than an SDK failure; verify the field is set rather than waiting for a `401` to tell you, and check the operation's **Auth** bullet against what the client was actually given. - -Three more behaviours the type does not show: - -- **A credential may be a function.** Every field typed `TokenProvider` is re-read on **every** request with no caching, so a key can rotate without rebuilding the client. An empty string counts as absent; a function counts as present without being invoked. -- **Composition is emitted, not configured.** Where the spec puts two schemes in one requirement the SDK sends **both**; where it lists alternatives it sends the **first configured** one, in the order the **Auth** bullet prints them. -- **A 401 invalidates the cached credential.** On a 401 (401 only, not 403) the SDK clears whatever that operation's scheme had cached, so the *next* call re-acquires; the current request still rejects. +**Every credential field is optional.** Omit one and the request goes out without it, with no error at construction; the server answers `401`, or `200` if it serves anonymous traffic. On an unexpected `401`, check the operation's **Auth** bullet against the fields you set. -**OAuth 2 fetches and caches its own token.** The token request goes through **the same client** — same `fetch`, same `retry` policy — sends a form-urlencoded body, and decodes the response against a schema rather than casting it. A token is cached until shortly before it expires; a response with no `expires_in` is treated as never expiring (RFC 6749 §5.1); concurrent callers share one in-flight fetch. **A refused token endpoint rejects with `AuthError`**, wrapping the underlying `ApiError` as `cause` — so a bad secret never looks like the business call failing, and `AuthError` is *not* an `ApiError`. The token request is itself a `POST` with its own timeout, retried only when `httpMethodsToRetry` names `POST`. +**OAuth 2 fetches and caches its own token.** The token request goes through **the same client** — same `fetch`, same `retry` policy — as a `POST`, retried only when `httpMethodsToRetry` names `POST`. **A refused token endpoint rejects with `AuthError`**, which is *not* an `ApiError`; the endpoint's `ApiError` is its `cause`. | Flow | Token endpoint | Client credentials travel | | --- | --- | --- | -| `oauth2` | `accessTokenServer` + `/token` | as `Authorization: Basic` | +| `oauth2` | `default` + `/oauth/token` | in the token request's form body | -`oauth2Strategy` on `ClientOptions` substitutes the whole token request (`getToken(credentials, signal)`, plus `tryRefreshToken(…)` where the grant is refreshable); the caching, expiry buffer and single-flight behaviour still apply. +`oauth2Strategy` on `ClientOptions` substitutes the whole token request. The **token endpoint follows the base URL of its group** (named in the table), so it tracks the environment and any override. -The **token endpoint follows the same base URL** as the operations on its group, so it always tracks the environment or the override — you never configure it separately. Its group is named in the table above, against `src/servers.ts`. - -See `typescript-authentication` for the full picture. +Credential functions, scheme composition, 401 invalidation, token caching and the token-request strategy's shape: `sdk-map.md` § *Servers & auth* and `typescript-authentication`. ## Resources This SDK groups nothing: every operation is a method on `client` itself, so there are no resource getters to reach through. -335 operations are methods on the client itself: `client.accountsBalanceGet` · `client.accountsGet` · `client.applicationGet` · `client.assetReportAuditCopyCreate` · `client.assetReportAuditCopyGet` · `client.assetReportAuditCopyPdfGet` · `client.assetReportAuditCopyRemove` · `client.assetReportCreate` · `client.assetReportFilter` · `client.assetReportGet` · `client.assetReportPdfGet` · `client.assetReportRefresh` · `client.assetReportRemove` · `client.authGet` · `client.authVerify` · `client.bankTransferBalanceGet` · `client.bankTransferCancel` · `client.bankTransferCreate` · `client.bankTransferEventList` · `client.bankTransferEventSync` · `client.bankTransferGet` · `client.bankTransferList` · `client.bankTransferMigrateAccount` · `client.bankTransferSweepGet` · `client.bankTransferSweepList` · `client.beaconAccountRiskEvaluate` · `client.beaconDuplicateGet` · `client.beaconReportCreate` · `client.beaconReportGet` · `client.beaconReportList` · `client.beaconReportSyndicationGet` · `client.beaconReportSyndicationList` · `client.beaconUserAccountInsightsGet` · `client.beaconUserCreate` · `client.beaconUserGet` · `client.beaconUserHistoryList` · `client.beaconUserReview` · `client.beaconUserUpdate` · `client.betaEwaReportV1Get` · `client.betaPartnerCustomerV1Create` · `client.betaPartnerCustomerV1Enable` · `client.betaPartnerCustomerV1Get` · `client.betaPartnerCustomerV1Update` · `client.businessVerificationCreate` · `client.businessVerificationGet` · `client.cashflowReportGet` · `client.cashflowReportInsightsGet` · `client.cashflowReportRefresh` · `client.cashflowReportTransactionsGet` · `client.categoriesGet` · `client.consentEventsGet` · `client.consumerReportPdfGet` · `client.craCheckReportBaseReportGet` · `client.craCheckReportCashflowInsightsGet` · `client.craCheckReportCreate` · `client.craCheckReportIncomeInsightsGet` · `client.craCheckReportLendScoreGet` · `client.craCheckReportNetworkInsightsGet` · `client.craCheckReportPartnerInsightsGet` · `client.craCheckReportPdfGet` · `client.craCheckReportVerificationGet` · `client.craCheckReportVerificationPdfGet` · `client.craCreditProfileReportGet` · `client.craLoansApplicationsRegister` · `client.craLoansRegister` · `client.craLoansUnregister` · `client.craLoansUpdate` · `client.craMonitoringInsightsGet` · `client.craMonitoringInsightsSubscribe` · `client.craMonitoringInsightsUnsubscribe` · `client.craPartnerInsightsGet` · `client.craReportGet` · `client.createPaymentToken` · `client.creditAssetReportFreddieMacGet` · `client.creditAuditCopyTokenCreate` · `client.creditAuditCopyTokenUpdate` · `client.creditBankEmploymentGet` · `client.creditBankIncomeGet` · `client.creditBankIncomePdfGet` · `client.creditBankIncomeRefresh` · `client.creditBankIncomeWebhookUpdate` · `client.creditBankStatementsUploadsGet` · `client.creditEmploymentGet` · `client.creditFreddieMacReportsGet` · `client.creditPayrollIncomeGet` · `client.creditPayrollIncomeParsingConfigUpdate` · `client.creditPayrollIncomePrecheck` · `client.creditPayrollIncomeRefresh` · `client.creditPayrollIncomeRiskSignalsGet` · `client.creditRelayCreate` · `client.creditRelayGet` · `client.creditRelayPdfGet` · `client.creditRelayRefresh` · `client.creditRelayRemove` · `client.creditReportAuditCopyRemove` · `client.creditSessionsGet` · `client.dashboardUserGet` · `client.dashboardUserList` · `client.employersSearch` · `client.employmentVerificationGet` · `client.fdxConsentsGet` · `client.fdxConsentsList` · `client.fdxConsentsRevocationGet` · `client.fdxConsentsRevoke` · `client.fdxNotifications` · `client.getRecipient` · `client.getRecipients` · `client.identityDocumentsUploadsGet` · `client.identityGet` · `client.identityMatch` · `client.identityRefresh` · `client.identityVerificationAutofillCreate` · `client.identityVerificationCreate` · `client.identityVerificationGet` · `client.identityVerificationList` · `client.identityVerificationRetry` · `client.incomeVerificationCreate` · `client.incomeVerificationDocumentsDownload` · `client.incomeVerificationPaystubsGet` · `client.incomeVerificationPrecheck` · `client.incomeVerificationTaxformsGet` · `client.institutionsGet` · `client.institutionsGetById` · `client.institutionsSearch` · `client.investmentsAuthGet` · `client.investmentsHoldingsGet` · `client.investmentsRefresh` · `client.investmentsTransactionsGet` · `client.issuesGet` · `client.issuesSearch` · `client.issuesSubscribe` · `client.itemAccessTokenInvalidate` · `client.itemActivityList` · `client.itemApplicationList` · `client.itemApplicationScopesUpdate` · `client.itemApplicationUnlink` · `client.itemCreatePublicToken` · `client.itemGet` · `client.itemImport` · `client.itemProductsTerminate` · `client.itemPublicTokenExchange` · `client.itemRemove` · `client.itemWebhookUpdate` · `client.liabilitiesGet` · `client.linkDeliveryCreate` · `client.linkDeliveryGet` · `client.linkOauthCorrelationIdExchange` · `client.linkTokenCreate` · `client.linkTokenGet` · `client.networkStatusGet` · `client.oauthIntrospect` · `client.oauthRevoke` · `client.oauthToken` · `client.partnerCustomerCreate` · `client.partnerCustomerEnable` · `client.partnerCustomerGet` · `client.partnerCustomerOauthInstitutionsGet` · `client.partnerCustomerRemove` · `client.paymentInitiationConsentCreate` · `client.paymentInitiationConsentGet` · `client.paymentInitiationConsentPaymentExecute` · `client.paymentInitiationConsentRevoke` · `client.paymentInitiationPaymentCreate` · `client.paymentInitiationPaymentGet` · `client.paymentInitiationPaymentList` · `client.paymentInitiationPaymentReverse` · `client.paymentInitiationRecipientCreate` · `client.paymentInitiationRecipientGet` · `client.paymentInitiationRecipientList` · `client.paymentProfileCreate` · `client.paymentProfileGet` · `client.paymentProfileRemove` · `client.processorAccountGet` · `client.processorApexProcessorTokenCreate` · `client.processorAuthGet` · `client.processorBalanceGet` · `client.processorBankTransferCreate` · `client.processorIdentityGet` · `client.processorIdentityMatch` · `client.processorInvestmentsAuthGet` · `client.processorInvestmentsHoldingsGet` · `client.processorInvestmentsTransactionsGet` · `client.processorLiabilitiesGet` · `client.processorSignalDecisionReport` · `client.processorSignalEvaluate` · `client.processorSignalPrepare` · `client.processorSignalReturnReport` · `client.processorStripeBankAccountTokenCreate` · `client.processorTokenCreate` · `client.processorTokenPermissionsGet` · `client.processorTokenPermissionsSet` · `client.processorTokenWebhookUpdate` · `client.processorTransactionsGet` · `client.processorTransactionsRecurringGet` · `client.processorTransactionsRefresh` · `client.processorTransactionsSync` · `client.profileNetworkStatusGet` · `client.protectCompute` · `client.protectEventGet` · `client.protectEventSend` · `client.protectReportCreate` · `client.protectUserInsightsGet` · `client.sandboxBankIncomeFireWebhook` · `client.sandboxBankTransferFireWebhook` · `client.sandboxBankTransferSimulate` · `client.sandboxCraCashflowUpdatesUpdate` · `client.sandboxFdxConsentSeed` · `client.sandboxIncomeFireWebhook` · `client.sandboxItemApplicationSeed` · `client.sandboxItemFireWebhook` · `client.sandboxItemResetLogin` · `client.sandboxItemSetVerificationStatus` · `client.sandboxOauthSelectAccounts` · `client.sandboxPaymentProfileResetLogin` · `client.sandboxPaymentSimulate` · `client.sandboxProcessorTokenCreate` · `client.sandboxPublicTokenCreate` · `client.sandboxTransactionsCreate` · `client.sandboxTransferFireWebhook` · `client.sandboxTransferLedgerDepositSimulate` · `client.sandboxTransferLedgerSimulateAvailable` · `client.sandboxTransferLedgerWithdrawSimulate` · `client.sandboxTransferRefundSimulate` · `client.sandboxTransferRepaymentSimulate` · `client.sandboxTransferSimulate` · `client.sandboxTransferSweepSimulate` · `client.sandboxTransferTestClockAdvance` · `client.sandboxTransferTestClockCreate` · `client.sandboxTransferTestClockGet` · `client.sandboxTransferTestClockList` · `client.sandboxUserResetLogin` · `client.sessionTokenCreate` · `client.signalDecisionReport` · `client.signalEvaluate` · `client.signalPrepare` · `client.signalReturnReport` · `client.signalSchedule` · `client.statementsDownload` · `client.statementsList` · `client.statementsRefresh` · `client.transactionsEnhance` · `client.transactionsEnrich` · `client.transactionsGet` · `client.transactionsRecurringGet` · `client.transactionsRefresh` · `client.transactionsRulesCreate` · `client.transactionsRulesList` · `client.transactionsRulesRemove` · `client.transactionsSync` · `client.transactionsUserInsightsGet` · `client.transferAuthorizationCancel` · `client.transferAuthorizationCreate` · `client.transferBalanceGet` · `client.transferCancel` · `client.transferCapabilitiesGet` · `client.transferConfigurationGet` · `client.transferCreate` · `client.transferDiligenceDocumentUpload` · `client.transferDiligenceSubmit` · `client.transferEventList` · `client.transferEventSync` · `client.transferGet` · `client.transferIntentCreate` · `client.transferIntentGet` · `client.transferLedgerDeposit` · `client.transferLedgerDistribute` · `client.transferLedgerEventList` · `client.transferLedgerGet` · `client.transferLedgerWithdraw` · `client.transferList` · `client.transferMetricsGet` · `client.transferMigrateAccount` · `client.transferOriginatorCreate` · `client.transferOriginatorFundingAccountCreate` · `client.transferOriginatorFundingAccountUpdate` · `client.transferOriginatorGet` · `client.transferOriginatorList` · `client.transferPlatformOriginatorCreate` · `client.transferPlatformPersonCreate` · `client.transferPlatformRequirementSubmit` · `client.transferQuestionnaireCreate` · `client.transferRecurringCancel` · `client.transferRecurringCreate` · `client.transferRecurringGet` · `client.transferRecurringList` · `client.transferRefundCancel` · `client.transferRefundCreate` · `client.transferRefundGet` · `client.transferRepaymentList` · `client.transferRepaymentReturnList` · `client.transferReturnRecover` · `client.transferSweepGet` · `client.transferSweepList` · `client.userAccountSessionEventSend` · `client.userAccountSessionGet` · `client.userCreate` · `client.userFinancialDataRefresh` · `client.userGet` · `client.userIdentityRemove` · `client.userItemsAssociate` · `client.userItemsGet` · `client.userItemsRemove` · `client.userProductsTerminate` · `client.userRemove` · `client.userThirdPartyTokenCreate` · `client.userThirdPartyTokenRemove` · `client.userTransactionsRefresh` · `client.userUpdate` · `client.walletCreate` · `client.walletGet` · `client.walletList` · `client.walletTransactionExecute` · `client.walletTransactionGet` · `client.walletTransactionList` · `client.watchlistScreeningEntityCreate` · `client.watchlistScreeningEntityGet` · `client.watchlistScreeningEntityHistoryList` · `client.watchlistScreeningEntityHitList` · `client.watchlistScreeningEntityList` · `client.watchlistScreeningEntityProgramGet` · `client.watchlistScreeningEntityProgramList` · `client.watchlistScreeningEntityReviewCreate` · `client.watchlistScreeningEntityReviewList` · `client.watchlistScreeningEntityUpdate` · `client.watchlistScreeningIndividualCreate` · `client.watchlistScreeningIndividualGet` · `client.watchlistScreeningIndividualHistoryList` · `client.watchlistScreeningIndividualHitList` · `client.watchlistScreeningIndividualList` · `client.watchlistScreeningIndividualProgramGet` · `client.watchlistScreeningIndividualProgramList` · `client.watchlistScreeningIndividualReviewCreate` · `client.watchlistScreeningIndividualReviewList` · `client.watchlistScreeningIndividualUpdate` · `client.webhookVerificationKeyGet`. +335 operations on the client itself: `sdk-map.md` § *Operations — by resource* names every operation, with the page that documents it. -Every operation has the same call shape — `op(request, options?)`, one **flat, channel-blind** request object first and `RequestOptions` (`{ signal, retry, logging }`) second — and returns `ApiPromise`. +Every operation has the same call shape — `op(request, options?)`, one **flat, channel-blind** request object first and `RequestOptions` (`{ signal, retry, logging }`) second — and returns `ApiPromise`, or `Pageable` for a paged operation. No operation is paged — every one of them is a single request. -⚠ **The request type name is not uniformly `Request`.** 317 operations take `RequestParams` instead: `accountsBalanceGet`, `accountsGet`, `applicationGet`, `assetReportAuditCopyCreate`, `assetReportAuditCopyGet`, `assetReportAuditCopyPdfGet`, `assetReportAuditCopyRemove`, `assetReportCreate`, `assetReportFilter`, `assetReportGet`, `assetReportPdfGet`, `assetReportRefresh`, `assetReportRemove`, `authGet`, `authVerify`, `bankTransferBalanceGet`, `bankTransferCancel`, `bankTransferCreate`, `bankTransferEventList`, `bankTransferEventSync`, `bankTransferGet`, `bankTransferList`, `bankTransferMigrateAccount`, `bankTransferSweepGet`, `bankTransferSweepList`, `beaconAccountRiskEvaluate`, `beaconDuplicateGet`, `beaconReportCreate`, `beaconReportGet`, `beaconReportList`, `beaconReportSyndicationGet`, `beaconReportSyndicationList`, `beaconUserAccountInsightsGet`, `beaconUserCreate`, `beaconUserGet`, `beaconUserHistoryList`, `beaconUserReview`, `beaconUserUpdate`, `betaEwaReportV1Get`, `betaPartnerCustomerV1Create`, `betaPartnerCustomerV1Enable`, `betaPartnerCustomerV1Get`, `betaPartnerCustomerV1Update`, `businessVerificationCreate`, `businessVerificationGet`, `cashflowReportGet`, `cashflowReportInsightsGet`, `cashflowReportRefresh`, `cashflowReportTransactionsGet`, `consentEventsGet`, `consumerReportPdfGet`, `craCheckReportBaseReportGet`, `craCheckReportCashflowInsightsGet`, `craCheckReportCreate`, `craCheckReportIncomeInsightsGet`, `craCheckReportLendScoreGet`, `craCheckReportNetworkInsightsGet`, `craCheckReportPartnerInsightsGet`, `craCheckReportPdfGet`, `craCheckReportVerificationGet`, `craCheckReportVerificationPdfGet`, `craCreditProfileReportGet`, `craLoansApplicationsRegister`, `craLoansRegister`, `craLoansUnregister`, `craLoansUpdate`, `craMonitoringInsightsGet`, `craMonitoringInsightsSubscribe`, `craMonitoringInsightsUnsubscribe`, `craPartnerInsightsGet`, `craReportGet`, `creditAuditCopyTokenCreate`, `creditAuditCopyTokenUpdate`, `creditBankEmploymentGet`, `creditBankIncomeGet`, `creditBankIncomePdfGet`, `creditBankIncomeRefresh`, `creditBankIncomeWebhookUpdate`, `creditBankStatementsUploadsGet`, `creditEmploymentGet`, `creditFreddieMacReportsGet`, `creditPayrollIncomeGet`, `creditPayrollIncomeParsingConfigUpdate`, `creditPayrollIncomePrecheck`, `creditPayrollIncomeRefresh`, `creditPayrollIncomeRiskSignalsGet`, `creditRelayCreate`, `creditRelayGet`, `creditRelayPdfGet`, `creditRelayRefresh`, `creditRelayRemove`, `creditSessionsGet`, `dashboardUserGet`, `dashboardUserList`, `employersSearch`, `employmentVerificationGet`, `identityDocumentsUploadsGet`, `identityGet`, `identityMatch`, `identityRefresh`, `identityVerificationAutofillCreate`, `identityVerificationCreate`, `identityVerificationGet`, `identityVerificationList`, `identityVerificationRetry`, `incomeVerificationCreate`, `incomeVerificationDocumentsDownload`, `incomeVerificationPaystubsGet`, `incomeVerificationPrecheck`, `incomeVerificationTaxformsGet`, `institutionsGet`, `institutionsGetById`, `institutionsSearch`, `investmentsAuthGet`, `investmentsHoldingsGet`, `investmentsRefresh`, `investmentsTransactionsGet`, `issuesGet`, `issuesSearch`, `issuesSubscribe`, `itemAccessTokenInvalidate`, `itemActivityList`, `itemApplicationList`, `itemApplicationScopesUpdate`, `itemApplicationUnlink`, `itemGet`, `itemImport`, `itemProductsTerminate`, `itemPublicTokenExchange`, `itemRemove`, `itemWebhookUpdate`, `liabilitiesGet`, `linkDeliveryCreate`, `linkDeliveryGet`, `linkTokenCreate`, `linkTokenGet`, `networkStatusGet`, `partnerCustomerCreate`, `partnerCustomerEnable`, `partnerCustomerGet`, `partnerCustomerRemove`, `paymentInitiationConsentCreate`, `paymentInitiationConsentGet`, `paymentInitiationConsentPaymentExecute`, `paymentInitiationConsentRevoke`, `paymentInitiationPaymentCreate`, `paymentInitiationPaymentGet`, `paymentInitiationPaymentList`, `paymentInitiationPaymentReverse`, `paymentInitiationRecipientCreate`, `paymentInitiationRecipientGet`, `paymentInitiationRecipientList`, `paymentProfileCreate`, `paymentProfileGet`, `paymentProfileRemove`, `processorAccountGet`, `processorApexProcessorTokenCreate`, `processorAuthGet`, `processorBalanceGet`, `processorBankTransferCreate`, `processorIdentityGet`, `processorIdentityMatch`, `processorInvestmentsAuthGet`, `processorInvestmentsHoldingsGet`, `processorInvestmentsTransactionsGet`, `processorLiabilitiesGet`, `processorSignalDecisionReport`, `processorSignalEvaluate`, `processorSignalPrepare`, `processorSignalReturnReport`, `processorStripeBankAccountTokenCreate`, `processorTokenCreate`, `processorTokenPermissionsGet`, `processorTokenPermissionsSet`, `processorTokenWebhookUpdate`, `processorTransactionsGet`, `processorTransactionsRecurringGet`, `processorTransactionsRefresh`, `processorTransactionsSync`, `profileNetworkStatusGet`, `protectCompute`, `protectEventGet`, `protectEventSend`, `protectReportCreate`, `protectUserInsightsGet`, `sandboxBankIncomeFireWebhook`, `sandboxBankTransferFireWebhook`, `sandboxBankTransferSimulate`, `sandboxCraCashflowUpdatesUpdate`, `sandboxFdxConsentSeed`, `sandboxIncomeFireWebhook`, `sandboxItemApplicationSeed`, `sandboxItemFireWebhook`, `sandboxItemResetLogin`, `sandboxItemSetVerificationStatus`, `sandboxOauthSelectAccounts`, `sandboxPaymentProfileResetLogin`, `sandboxPaymentSimulate`, `sandboxProcessorTokenCreate`, `sandboxPublicTokenCreate`, `sandboxTransactionsCreate`, `sandboxTransferFireWebhook`, `sandboxTransferLedgerDepositSimulate`, `sandboxTransferLedgerSimulateAvailable`, `sandboxTransferLedgerWithdrawSimulate`, `sandboxTransferRefundSimulate`, `sandboxTransferRepaymentSimulate`, `sandboxTransferSimulate`, `sandboxTransferSweepSimulate`, `sandboxTransferTestClockAdvance`, `sandboxTransferTestClockCreate`, `sandboxTransferTestClockGet`, `sandboxTransferTestClockList`, `sandboxUserResetLogin`, `sessionTokenCreate`, `signalDecisionReport`, `signalEvaluate`, `signalPrepare`, `signalReturnReport`, `signalSchedule`, `statementsDownload`, `statementsList`, `statementsRefresh`, `transactionsEnrich`, `transactionsGet`, `transactionsRecurringGet`, `transactionsRefresh`, `transactionsRulesCreate`, `transactionsRulesList`, `transactionsRulesRemove`, `transactionsSync`, `transactionsUserInsightsGet`, `transferAuthorizationCancel`, `transferAuthorizationCreate`, `transferBalanceGet`, `transferCancel`, `transferCapabilitiesGet`, `transferConfigurationGet`, `transferCreate`, `transferDiligenceDocumentUpload`, `transferDiligenceSubmit`, `transferEventList`, `transferEventSync`, `transferGet`, `transferIntentCreate`, `transferIntentGet`, `transferLedgerDeposit`, `transferLedgerDistribute`, `transferLedgerEventList`, `transferLedgerGet`, `transferLedgerWithdraw`, `transferList`, `transferMetricsGet`, `transferMigrateAccount`, `transferOriginatorCreate`, `transferOriginatorFundingAccountCreate`, `transferOriginatorFundingAccountUpdate`, `transferOriginatorGet`, `transferOriginatorList`, `transferPlatformOriginatorCreate`, `transferPlatformPersonCreate`, `transferPlatformRequirementSubmit`, `transferQuestionnaireCreate`, `transferRecurringCancel`, `transferRecurringCreate`, `transferRecurringGet`, `transferRecurringList`, `transferRefundCancel`, `transferRefundCreate`, `transferRefundGet`, `transferRepaymentList`, `transferRepaymentReturnList`, `transferReturnRecover`, `transferSweepGet`, `transferSweepList`, `userAccountSessionEventSend`, `userAccountSessionGet`, `userCreate`, `userFinancialDataRefresh`, `userGet`, `userIdentityRemove`, `userItemsAssociate`, `userItemsGet`, `userItemsRemove`, `userProductsTerminate`, `userRemove`, `userThirdPartyTokenCreate`, `userThirdPartyTokenRemove`, `userTransactionsRefresh`, `userUpdate`, `walletCreate`, `walletGet`, `walletList`, `walletTransactionExecute`, `walletTransactionGet`, `walletTransactionList`, `watchlistScreeningEntityCreate`, `watchlistScreeningEntityGet`, `watchlistScreeningEntityHistoryList`, `watchlistScreeningEntityHitList`, `watchlistScreeningEntityList`, `watchlistScreeningEntityProgramGet`, `watchlistScreeningEntityProgramList`, `watchlistScreeningEntityReviewCreate`, `watchlistScreeningEntityReviewList`, `watchlistScreeningEntityUpdate`, `watchlistScreeningIndividualCreate`, `watchlistScreeningIndividualGet`, `watchlistScreeningIndividualHistoryList`, `watchlistScreeningIndividualHitList`, `watchlistScreeningIndividualList`, `watchlistScreeningIndividualProgramGet`, `watchlistScreeningIndividualProgramList`, `watchlistScreeningIndividualReviewCreate`, `watchlistScreeningIndividualReviewList`, `watchlistScreeningIndividualUpdate`, `webhookVerificationKeyGet`. Take the name from the operation's **Signature** bullet on its map page; never construct it from the method name. +⚠ **The request type name is not uniformly `Request`.** 317 operations take `RequestParams` instead. Take the name from the operation's **Signature** bullet on its map page; never construct it from the method name. ## SDK map — look up first, open the file second -The SDK ships a generated map, and `package.json`'s `files` list includes it, so **installing the package gives you the map** — no clone is needed. It sits at the package root, the directory holding `package.json` and the `src/` tree: +The map sits at the package root, the directory holding `package.json` and the `src/` tree: - **`sdk-map.md`** — the index: client construction with the full `ClientOptions` table, the *Not on this SDK* table, the one error family with `ApiResult` and `.asApiResult()`, wire serialization for every channel, servers and auth, runtime and packaging, and the link table into the operations pages. - **`map/operations/.md`** — one page per resource, one `###` block per operation, with bullets in the fixed order **Server**, **Signature**, **Wire** (verb and route), **Auth**, **Request body**, **SDK-sent**, **Returns**, **Error**, **Error arms** — then a **Fields** table giving every request field its channel, wire name, type, required flag and default, and a **Type sources** table naming the declaring file and schema value of every type the operation mentions. @@ -150,19 +129,17 @@ node -e "console.log(require.resolve('the-plaid-api/package.json'))" Failing that it is at `node_modules/the-plaid-api/`. **If the resolve fails, or the directory it prints carries no `sdk-map.md`, the map is still in the SDK's own repository** — , branch `main`. A registry id is a claim on a shared index rather than proof of identity, so it can resolve to an unrelated package or to a release predating the map; the repository is the copy that is this SDK by construction. Read it there, and if neither route yields a map, mark the fact `UNVERIFIED` and say what would settle it rather than answering from memory. -Every `Source` path on the map is relative to that package root, so `src/models/.ts` opens as written from there — the package ships its `src/` tree, so the path resolves inside `node_modules/the-plaid-api/` exactly as the map writes it. An import specifier ending `.js` inside that source is the NodeNext spelling of the sibling `.ts` file. - -**The map is the locator; the source files are the shapes.** Read the map first — signatures, routes, request fields with their channels and defaults, return types, error arms, and which file declares a type are all answered there without opening a single `.ts` file. Then open the one file the map names for what it deliberately does not carry: a model's members, whether each is required, optional or nullable, and an enum's members with their wire values — the `as const` object in the enum's own file (for an enum inside a model, the file the model imports it from). The map says so itself — *"Shapes live only in the source … Do not derive the path from the type name."* +Every `Source` path on the map is relative to that package root (`node_modules/the-plaid-api/`). An import specifier ending `.js` inside that source is the NodeNext spelling of the sibling `.ts` file. -**`sdk-map.md` carries the invariants every operation block assumes, so read it before any `map/operations/` page**; the pages are written to be read beside it. And **silence means the default**: the index states what holds for every operation — the call shape, the flat channel-blind request object, the `ApiPromise` return, the default server group, no pagination and no streaming — and a block departs from one only by saying so. Take the default and move on rather than opening the source to confirm it. +**Read `sdk-map.md` before any `map/operations/` page.** It states what holds for every operation, and **silence means the default**: a block departs from it only by saying so — a paged operation's **Signature** returns `Pageable` and its **Returns** bullet names the strategy and what ends the walk — so take the default rather than opening the source to confirm it. **The map carries shapes; what an operation *means* lives elsewhere.** When *what* to pass depends on meaning — which values a field accepts beyond its type, a rule that couples two fields, what a defaulted header actually selects — the map will not settle it. Read that operation's entry in `api-reference.md` at the package root, keyed by the same signature, *before* writing the sheet row, and record what you found. A value you already "know" for a field the map types as a plain `string` is a lookup, not a recall — the memory ban applies to it. ## Contract facts — the map first, then the source file -**Six of these are map lookups — don't open a source file for them:** an operation's signature; its request fields with channel, wire name, required flag and default; its return type; its error subclass and the arms with the status each covers; the `ClientOptions` fields and their defaults; and the environments, base URLs and auth wiring. +**The map is the locator; the source files are the shapes.** These are map lookups — don't open a source file for them: an operation's signature and route; its request fields with channel, wire name, required flag and default; its return type; its error subclass and the arms with the status each covers; the `ClientOptions` fields and their defaults; the environments, base URLs and auth wiring; and which file declares a type. -The table below covers everything else, and the full body behind a map row. Paths are relative to `node_modules/the-plaid-api/`: +Open the one file the map's **Type sources** table names — never derive the path from the type name — for what the map does not carry: a model's members and whether each is required, optional or nullable, and an enum's members with their wire values — the `as const` object in the enum's own file (for an enum inside a model, the file the model imports it from). The table below covers that, everything else, and the full body behind a map row. Paths are relative to `node_modules/the-plaid-api/`: | Question | File | | --- | --- | @@ -176,6 +153,8 @@ The table below covers everything else, and the full body behind a map row. Path | The transport: the attempt loop, `fetch` resolution, 401 invalidation, 2xx-vs-error split | `src/core/raw-client.ts` | | Error classes and `ErrorKind` | `src/core/errors.ts`, `src/core/api-error.ts` | | `ApiPromise`, `ApiResult`, `.asApiResult()`, the `Symbol.species` behaviour | `src/core/api-promise.ts` | +| `Pageable` and `PageableApiResult` — the lazy walk a paged operation returns, `.pages()`, and `.asApiResult()` on a walk | `src/core/pagination/pageable.ts` | +| The four paging states — offset, page, cursor and link — and the stop rule each applies | `src/core/pagination/states/offset-state.ts`, `src/core/pagination/states/page-state.ts`, `src/core/pagination/states/cursor-state.ts`, `src/core/pagination/states/link-state.ts` | | `RequestOptions` (it is `{ signal, retry, logging }` and nothing else) | `src/core/api-request.ts` | | `RetryOptions` and its defaults, `RequestRetryOptions`, backoff, `Retry-After`, `RetryAttempt` | `src/core/retry.ts` | | `LoggingOptions` and its defaults (`defaultLoggingOptions`), `RequestLoggingOptions`, `Logger`, `LogDetails` | `src/core/logging.ts` | @@ -192,23 +171,29 @@ Keep lookups cheap — the rules that keep a session's context small: - **Never grep, glob or `find` the package to *locate* a type** — the map is the locator, and it says so. Grep only *inside* the file its **Type sources** table names, for the symbol. A sweep for a cross-cutting *shape* is a different question and is fine: "every field typed `unknown`", "every required-nullable member" are things nothing indexes, and one targeted `grep -rn` over `src/models/` is the right tool — record what it found on the sheet. - Trust the compiler over this page: if a name here ever fails to type-check, re-read the file the table above names and report the drift; never patch around it from memory. +## Validation — what `validate` checks + +Every model's schema const — the value export beside its type — carries `encode`, `decode` and `validate`. `validate(value)` runs `encode`'s rules without the conversion and without the throw, and returns `{ success: true }` or `{ success: false, message }`, the message naming every failing field under its full path and why. + +**This SDK enforces the spec's value constraints on `validate`.** A model or union whose spec declares one — `minLength`/`maxLength`, `pattern`, `format` (`email`, `hostname`, `ipv4`, `ipv6`, `uri`, `uri-reference`, `json-pointer`), `minimum`/`maximum`, `exclusiveMinimum`/`exclusiveMaximum`, `multipleOf`, `minItems`/`maxItems`/`uniqueItems`, `minProperties`/`maxProperties`, and the keywords on an array's `items` and a map's `additionalProperties` — carries it on its public schema: `assetReportAuditCopyPdfGetRequestSchema.validate(value)` reports it and `encode` throws on it. A model that nests a constrained one checks the nested value too and reports its fields under their full path. The operations do **not** apply those constraints: they encode and decode through a structural twin the module keeps for itself, `assetReportAuditCopyPdfGetRequestInternalSchema`, which the package root does not export, so a value the service would accept is never refused on the way out, and a service ahead of the spec is never refused on the way in. A schema's own file says which it is: a constrained one declares the twin beside the public one. Every other schema is structural only, and its `validate` checks shape alone. + ## Sensitive data — check the request models before you log anything -Whether this API's **request** models carry fields you must never log — card or bank numbers, personal data, message content — is a shape question: each request model's declaring file (the map's **Type sources** table names it) lists every field. If the scope touches such a field, four generator facts decide your logging posture (all in `typescript-configuration-resilience`): a JSON request body is logged **verbatim** when `logRequestBody` is on, with no redaction; a form body is masked only by deny-list; a per-call `RequestOptions.logging` level turns the request body on for that call, whatever the client set; and leaving `ClientOptions.logging` without a `logger` or a `level` arms the `THE_PLAID_API_CLIENT_LOG` environment variable, which turns logging and both header switches on with no code change and no deploy — though never the body. So on any build that can carry such a field: `logRequestBody` stays off, no call on those paths passes a per-call level, `ClientOptions.logging.level` is set explicitly in production, and your own diagnostics never echo a request body on those paths. +Whether this API's **request** models carry fields you must never log — card or bank numbers, personal data, message content — is a shape question: each request model's declaring file (the map's **Type sources** table names it) lists every field. If the scope touches such a field: `logRequestBody` stays off, because it logs a JSON request body **verbatim** and masks a form body only by deny-list; no call on those paths passes a per-call `RequestOptions.logging` level, which turns the request body on for that call whatever the client set; `ClientOptions.logging.level` is set explicitly in production, because without a `logger` or a `level` the `THE_PLAID_API_CLIENT_LOG` environment variable turns logging and both header switches on with no code change; and your own diagnostics never echo a request body on those paths (`typescript-configuration-resilience` has the details). The SDK never logs a response body, but your own code may. Responses are often safer — many APIs return masked variants of what requests carry raw — but that too is a model-shape fact: check the response model's file before assuming. ## Integration workflow — load the companion skill at each step -Before you write the code for each step, load the named companion skill — even if you have already read the relevant file. Each step calls out the trap the signature hides (in *parens*). A typical integration reaches them in this order: +Before you write the code for each step, load the named companion skill — even if you have already read the relevant file. A typical integration reaches them in this order: -1. **Client construction & lifetime** — load **typescript-client-initialization** before you write `new ThePlaidApiClient(…)`. (*The signature won't tell you:* every option is optional, so a client built with no arguments compiles and talks to the default environment with no credential; the client must be **long-lived and app-scoped**, never rebuilt per request, because the OAuth 2 token cache lives on it; there is no `close()` or `dispose()` — it owns no pool, only a `fetch`; and when no `fetch` is reachable the **constructor** throws `ConfigurationError`, not the first call.) -2. **Authentication** — load **typescript-authentication** before you set credentials. The 4 schemes are `clientId`, `secret`, `plaidVersion`, `oauth2` on `ClientOptions`. (*The signature won't tell you:* the field is optional — omit it and every request goes out unauthenticated with no failure at construction; the token is fetched lazily and cached on the client; a **failed token fetch** raises `AuthError`, which is not an `ApiError` and **bypasses `.asApiResult()` entirely**; and a 401 invalidates the cache without retrying the current call. Load secrets from the environment or a secret store, never hardcode.) -3. **Calling an endpoint** — load **typescript-calling-endpoints** before the first `client..(…)` call. (*The signature won't tell you:* the request object is **flat and channel-blind** — a field named `body` *is* the whole request body and every other field is fanned out to path, query or header by the SDK, so nothing is nested by channel; **an omitted field that has a default is still sent, with that default**; **11 operations resolve to `undefined`**; and `.asApiResult()` must be called on the value the operation returned, because `ApiPromise` overrides `Symbol.species` and `.then()`/`.catch()` hand back a plain `Promise` with the method gone.) -4. **Models** — load **typescript-models** the moment a request/response member is not a plain string or number. (*The signature won't tell you:* models are plain `type`s built from object literals — no constructor, no builder; `f?: T` means omit the key, while `f: T | null` is **required and nullable** and `null` is a distinct value; enums are **open** (`const` companion plus a union admitting `(string & {})`), so the schema validates the base type only and an unknown server value round-trips instead of throwing — use `.values` to test membership yourself; and every type has a schema companion usable in both directions.) -5. **Error handling** — load **typescript-error-handling** before you write any `try/catch`. (*The signature won't tell you:* every operational failure is **one family**, `ThePlaidApiError`, narrowed on `err.kind` — `"api"` is an API error status, carried by `ApiError` and its per-operation subclasses — while four throwables sit outside it (`ConfigurationError` from the constructor, `SchemaError` from a codec called directly, a `TypeError` for a bug, and a caller abort's own `reason`), so a `catch` that tests the family has to rethrow the rest; **arm tags are schema-derived, not statuses** (see the sheet checklist below); a malformed 2xx body rejects with `DecodeError`, not `ApiError`, and `.asApiResult()` does not convert it; and a missing response field the schema permits is silently `undefined` rather than any error at all.) -6. **Configuration & resilience** — load **typescript-configuration-resilience** when you set the base URL, timeouts, retries, proxies, TLS, or logging. (*The signature won't tell you:* **retrying is on by default** — the default policy retries a GET, HEAD, PUT or OPTIONS call on `408`, `429`, `500`, `502`, `503` and `504` and on a dropped connection or timeout, and every one of those is a `RetryOptions` field you can change; a write is repeated only when `httpMethodsToRetry` names its method; `retry: { maxRetries: 0 }` turns it off, one call overrides it through `RequestOptions.retry`, and a `401` is not retried by default; `retry.timeout` bounds **one attempt**, up to its response headers, not the whole call, and `0` is a zero-length deadline while a value `setTimeout` cannot honour falls back to the default; **logging is off by default** — `ClientOptions.logging` turns it on with a `logger` or a `level`, and so does the `THE_PLAID_API_CLIENT_LOG` environment variable when code sets neither, but a request body is logged only when code sets `logRequestBody`, and then a JSON body **verbatim**, with no redaction; **there are no hooks, middleware or interceptors** — `ClientOptions.fetch` is the one transport extension point, `onRetry` being the only built-in callback; and a `fetch` replacement is called with the attempt's `Request` and no `init`, so one that does not forward that `Request`, or its `signal`, makes both each attempt's timeout and every `RequestOptions.signal` inert.) -7. **Testing** — load **typescript-testing** before you stub the SDK. (*The signature won't tell you:* the seam is **`ClientOptions.fetch`**, not the client class and not the resource classes — whose constructors take unexported engine internals, so they cannot be instantiated in a test; stub bodies in **wire shape** and let the SDK decode them; assert on the request the SDK actually built, headers included; and cover the failure kinds an `ApiError`-only test misses, `DecodeError` above all.) +1. **Client construction & lifetime** — load **typescript-client-initialization** before you write `new ThePlaidApiClient(…)`. The client is **long-lived and app-scoped**, never rebuilt per request, because the OAuth 2 token cache lives on it. +2. **Authentication** — load **typescript-authentication** before you set credentials. The 4 schemes are `clientId`, `secret`, `plaidVersion`, `oauth2` on `ClientOptions`. Load secrets from the environment or a secret store, never hardcode. +3. **Calling an endpoint** — load **typescript-calling-endpoints** before the first `client..(…)` call. +4. **Models** — load **typescript-models** the moment a request/response member is not a plain string or number. +5. **Error handling** — load **typescript-error-handling** before you write any `try/catch`. Every operational failure is **one family**, `ThePlaidApiError`, narrowed on `err.kind`. +6. **Configuration & resilience** — load **typescript-configuration-resilience** when you set the base URL, timeouts, retries, proxies, TLS, or logging, or walk a paged operation. +7. **Testing** — load **typescript-testing** before you stub the SDK. The seam is **`ClientOptions.fetch`**. ## What a contract sheet must carry for this SDK @@ -217,13 +202,14 @@ Beyond the usual signatures and model members, a contract sheet for the The Plai 1. **Which host each deployment talks to**, and where that is set. The members are `ServerEnvironment.Production`, `ServerEnvironment.Environment2`, defaulting to `ServerEnvironment.Production` when the field is unset. 2. **11 operations resolve to `undefined`** — `await` gives you nothing to inspect, so **`.asApiResult()` is the only way to observe their status and headers** — decide the mode at write time, not by retrofit. 3. **The exact request type name per operation**, taken from the **Signature** bullet — 317 operations take `RequestParams`, not `Request`. -4. **Every request field with its channel, wire name and default**, because the request object is flat and channel-blind and the SDK fans fields out. An omitted field that has a default is still sent with that default, so a defaulted header shapes the response whether or not the sheet mentions it. The generator injects an `Idempotency-Key` on every non-GET operation that does not declare that header itself — minted once per call and invisible to you. Every retry of that call re-sends the **same** key, which is what makes naming a write in `httpMethodsToRetry` safe where the provider deduplicates on it; but the next call mints a new one, so a call your own code repeats is two submissions. Any caller-supplied idempotency or request-id field is the only idempotency that spans calls, and `RequestOptions` is `{ signal, retry, logging }` only. -5. **Required vs optional vs required-nullable** for every model member the task sets — `f: T` required, `f?: T` omit the key, `f: T | null` required and nullable. And that under `exactOptionalPropertyTypes` an absent optional is **omitted or spread**, never assigned `undefined`. -6. **The error arms for each operation in scope, with the status each covers — and the warning that arm tags are schema-derived, not status codes.** Every operation rejects with its own `ApiError` subclass narrowed on `err.payload.kind`, and a tag comes from the arm's **body schema**: an arm whose body is a direct model reference is named after that model in lower camel (`"validationError"`), and every other body — a primitive, an array, a map, or no content — is named `"error{Status}"` (`"error400"`, `"error4XX"`, `"errorDefault"`), with a numeric suffix on the second of two arms that would otherwise land on the same name. The same tag means different statuses on different operations, and the same status carries different tags — so a tag is only meaningful beside the arm table it came from, and a shared helper that switches on `kind` across operations is a bug. 289 of 335 operations declare typed error bodies; the rest reject with the base `ApiError`. Every operation also carries an always-present `"undeclared"` arm holding `rawBody: ArrayBuffer`, for which **matcher precedence** matters: an exact numeric status is looked up across the whole table first, then the first covering range, and last a `"default"` arm where the spec declared one — whose body, if it does not fit, falls to `"undeclared"` rather than throwing. -7. **That a malformed or drifted 2xx body rejects with `DecodeError`, not `ApiError`, in both response modes** — `.asApiResult()` converts an HTTP error status, never any other failure. Any sheet row for a call whose result is used must name the members the implementer has to assert on, because a thin or truncated body decodes without complaint and the hole surfaces later. +4. **Every request field with its channel, wire name and default**, because the request object is flat and channel-blind and the SDK fans fields out. An omitted field that has a default is still sent with that default, so a defaulted header shapes the response whether or not the sheet mentions it. Every non-GET operation sends an `Idempotency-Key` header, minted once per call and invisible to you, unless it takes that header as a request field — `typescript-configuration-resilience` has what that key does and does not deduplicate. Any caller-supplied idempotency or request-id field is the only idempotency that spans calls, and `RequestOptions` is `{ signal, retry, logging }` only. +5. **Required vs optional vs required-nullable** for every model member the task sets — `f: T` required, `f?: T` omit the key, `f: T | null` required and nullable. +6. **The error arms for each operation in scope, with the status each covers — and the warning that arm tags are schema-derived, not status codes.** Every operation rejects with its own `ApiError` subclass narrowed on `err.payload.kind`. A tag comes from the arm's body schema and is resolved per operation, so the same tag means different statuses on different operations, and a shared helper that switches on `kind` across operations is a bug — `typescript-error-handling` has the naming rule, the always-present `"undeclared"` arm and the matcher precedence. 1 of 335 operations declare typed error bodies; the rest reject with the base `ApiError`. +7. **That a malformed or drifted 2xx body rejects with `DecodeError`, not `ApiError`, in both response modes** — and the members the implementer has to assert on, because a thin or truncated body decodes without complaint. 8. **The retry policy this integration needs.** Retrying is on by default — `ClientOptions.retry` sets it for the client and `RequestOptions.retry` overrides it per call — so the sheet says whether the defaults fit, which writes (if any) join `httpMethodsToRetry`, since a write is repeated only when the policy names its method, and the per-attempt timeout. -9. **The logging this integration needs.** Logging is off by default — `ClientOptions.logging` sets it for the client and `RequestOptions.logging` sets one call's level — so the sheet says whether it stays off and, where it is on, the level, the logger, and whether headers and the request body are logged: a JSON request body is logged verbatim, with no redaction. -10. **That the SDK performs no pagination and no streaming at all**, and that `ClientOptions.fetch` is the one seam where either can be added — so whatever the task needs there is yours to build or deliberately omit. Say which. -11. **That `Error` imported from this package is a model type, not the global of that name** — every sheet that references one should carry the alias it will be imported under. The error base is re-exported as `ThePlaidApiError` for the same reason. -12. A **REQUIRED READING** block naming the `typescript-*` companions that govern the steps, with inline `MUST load` pointers. +9. **The logging this integration needs.** Logging is off by default — `ClientOptions.logging` sets it for the client and `RequestOptions.logging` sets one call's level — so the sheet says whether it stays off and, where it is on, the level, the logger, and whether headers and the request body are logged (**Sensitive data**, above). +10. **That the SDK performs no streaming at all**, and that `ClientOptions.fetch` is the one seam where it can be added — so whatever the task needs there is yours to build or deliberately omit. Say which. +11. **That no operation is paged** — every call is one request, so any list the task pages is driven by hand, with a bound of its own. +12. **That `Error` imported from this package is a model type, not the global of that name** — every sheet that references one should carry the alias it will be imported under. The error base is re-exported as `ThePlaidApiError` for the same reason. +13. A **REQUIRED READING** block naming the `typescript-*` companions that govern the steps, with inline `MUST load` pointers. diff --git a/plugins/plaid/skills/typescript/typescript-integrate-the-plaid-api/SKILL.md b/plugins/plaid/skills/typescript/typescript-integrate-the-plaid-api/SKILL.md index 9d7abce1..157c9d5c 100644 --- a/plugins/plaid/skills/typescript/typescript-integrate-the-plaid-api/SKILL.md +++ b/plugins/plaid/skills/typescript/typescript-integrate-the-plaid-api/SKILL.md @@ -1,21 +1,28 @@ --- name: "typescript-integrate-the-plaid-api" -description: "MANDATORY FIRST STEP for The Plaid API TypeScript SDK work in a TypeScript or JavaScript project — load this BEFORE you write any code; TypeScript SDK ONLY, never load it for any other language. Applies when asked to integrate The Plaid API in TypeScript/Node — accounts balance get, accounts get, application get, asset report audit copy create, asset report audit copy get, asset report audit copy pdf get, or when the The Plaid API TypeScript SDK errors, fails to compile, or behaves unexpectedly. Knowing the SDK exists is NOT a substitute for loading this, because it carries five binding gates stated NOWHERE else and not inferable from the package — (1) load typescript-getting-started, confirm `the-plaid-api` actually resolves and read the SDK map that ships inside it before any lookup, (2) the exact plan-file path (the-plaid-api-plan.md at the repo root) and the no-project-file-edits window until a contract sheet with no open lookups exists there and you have read it, (3) the mandatory load of every typescript-* companion skill the sheet names, (4) the host decision, which this SDK forces once and irreversibly — constructing the client with no options silently selects ServerEnvironment.Production, and (5) the memory ban, where every signature, request field, channel, header default, error arm and enum member comes from a lookup and never from recall or runtime introspection." +description: "MANDATORY FIRST STEP for The Plaid API TypeScript SDK (`the-plaid-api`) work in a TypeScript or JavaScript project: load before writing any code — integrating The Plaid API (accounts balance get, accounts get, application get), or when the SDK errors, fails to compile or behaves unexpectedly. Sets the plan-first workflow, the contract sheet and which companion skills to load. TypeScript/JavaScript only; never load it for another language." --- # The Plaid API TypeScript SDK — Integration workflow (lookup layer + contract sheet) -You do the SDK lookups yourself: `typescript-getting-started` is your **lookup layer** — load it and ground every contract fact in it (and in the source files its table names) before writing code. The `typescript-*` companion skills are a different thing: they are API-agnostic *usage* guidance, they are yours to load, and Step 1c below makes loading them mandatory. - ## Your lookup layer -- **`typescript-getting-started`** is the entry point for every SDK need. It carries the SDK's identity (package name, version, Node floor, how it installs), the single import specifier and what the root exports, the server environments and the base-URL knob, the auth pattern, the resources, and a **file table** naming the one file that owns each kind of fact. Load it first, always. -- **The SDK map is your lookup surface, and you open it yourself.** The SDK ships `sdk-map.md` and `map/operations/` at its package root — and because `package.json`'s `files` list includes them, **installing the package puts the map in `node_modules/the-plaid-api/`**. There is nothing to clone and no helper agent to delegate to. `typescript-getting-started` tells you how to traverse it: read `sdk-map.md` once, then the one resource page your operations live on. -- **The installed package is the ground truth; the file table is only the locator.** Confirm it resolves before you rely on a lookup — `node -e "console.log(require.resolve('the-plaid-api/package.json'))"`. **If the resolve fails, or the directory it prints carries no `sdk-map.md`, the map is still in the SDK's own repository** — , branch `main`. Read it there, and only if neither route yields a map mark the fact `UNVERIFIED`, say what would settle it, and do not fill the hole from memory. This SDK is **not published to a registry**, so the install is a build from its source — . `typescript-getting-started`'s *Install* section carries what to run. -- **Read scoped.** Search for the one symbol and read the lines around it rather than whole files, and never copy a design comment's rationale onto a contract sheet — the sheet carries facts an implementer must obey, not the reasoning behind them. -- **Write a contract sheet with no open lookups** before you implement: exact signatures with the right request type name, every request field with its channel, wire name and default, required-vs-optional-vs-nullable members, the error arms per operation with the status each covers, and enum members for the operations in scope. `typescript-getting-started` ends with a checklist of what a sheet for this SDK is incomplete without — treat that as the checklist for your own sheet, and collect every in-scope operation in ONE pass rather than re-opening a map page per field. +- **`typescript-getting-started`** is the entry point for every SDK need: identity, install, imports, environments, auth, resources, and a **file table** naming the one file that owns each kind of fact. Load it first, always. +- **The SDK map is your lookup surface.** The SDK ships `sdk-map.md` and `map/operations/` at its package root — and because `package.json`'s `files` list includes them, **installing the package puts the map in `node_modules/the-plaid-api/`**. `typescript-getting-started` tells you how to traverse it: read `sdk-map.md` once, then the one resource page your operations live on. +- **The installed package is the ground truth; the file table is only the locator.** Confirm it resolves before you rely on a lookup — `node -e "console.log(require.resolve('the-plaid-api/package.json'))"`. **If the resolve fails, or the directory it prints carries no `sdk-map.md`, the map is still in the SDK's own repository** — , branch `main`. Read it there, and only if neither route yields a map mark the fact `UNVERIFIED` and say what would settle it. This SDK is **not published to a registry**, so the install is a build from its source — . `typescript-getting-started`'s *Install* section carries what to run. +- **Write a contract sheet with no open lookups** before you implement: exact signatures with the right request type name, every request field with its channel, wire name and default, required-vs-optional-vs-nullable members, the error arms per operation with the status each covers, which operations are paged and the bound each walk takes, and enum members for the operations in scope. `typescript-getting-started` ends with a checklist of what a sheet for this SDK is incomplete without — treat that as the checklist for your own sheet, and collect every in-scope operation in ONE pass rather than re-opening a map page per field. + +## The planner agent + +`the-plaid-api-planner` ships with this plugin. It writes `the-plaid-api-plan.md` — the plan and its contract sheet — and revises it in place; it writes no project code. Start it the first of these ways your host allows: + +1. **Your subagent tool lists it.** Some hosts list a plugin's agents under the plugin's name, as `plaid:the-plaid-api-planner`; start it by whichever of the two names your subagent tool lists. +2. **It isn't listed, or you can't start a subagent.** Tell the user in one line that you are writing the plan yourself, then do so as *Step 1* describes. Don't stop to ask. + +However you start it: -**Scope guard:** the APIMatic-generated The Plaid API **TypeScript SDK** (package and import specifier `the-plaid-api`, client `ThePlaidApiClient`) in **TypeScript or JavaScript projects only**. Unrelated API, or any language other than TypeScript/JavaScript — do nothing; this skill does not apply. +- **Start it on the same model you are running on.** If your subagent tool takes a model, pass your own model; if it has no model option, leave its default. Tell the user in one line which model you started it on. +- **Start it once per integration.** A plan revision is a follow-up message to that same agent; re-start it, carrying the clarification and the plan path, only where your host cannot message it. Never start a second one for the same integration. ## Workflow @@ -23,26 +30,30 @@ You do the SDK lookups yourself: `typescript-getting-started` is your **lookup l ### Step 1 — Plan first (always, for any implementation work) -Your FIRST action is to load `typescript-getting-started` and work through the user's full request (all features in scope — one plan covers the whole implementation). Load `typescript-error-handling` before you write the plan too: table 1b.4 is decided from it. Then write the plan and its contract sheet to `/the-plaid-api-plan.md` — that absolute path, not a location you pick later. +Your FIRST action, once the SDK is installed (installing it is a prerequisite the gate allows, below, and it follows the toolchain check and the baseline), is to start **`the-plaid-api-planner`**, as *The planner agent* says, once, with the user's full request — all features in scope; one plan covers the whole implementation — and the name of this skill, `typescript-integrate-the-plaid-api`. Dictate in its task the absolute project root and the absolute path it must write to — `/the-plaid-api-plan.md`, that absolute path, not a location you pick later. It loads `typescript-getting-started` and `typescript-error-handling` — table 1b.4 is decided from it — writes the plan and its contract sheet as Steps 1 to 1c describe, and returns the file's path. -**Do the read-only prerequisites in the same pass — they need no SDK knowledge and touch no project file:** +**If you couldn't start the planner** (case 2 in *The planner agent*), load both skills yourself, work through the request, and write the file at that path. + +**Do these two read-only prerequisites before you install the SDK — the install changes the tree they read:** -- the repo survey (read-only exploration of conventions, layering, **module format — ESM or CJS, which changes how the SDK is imported and whether `instanceof` on its error classes is trustworthy**, and the runtime: Node, a bundled browser app, or an edge runtime) — capture each convention as *pattern + the ONE exemplar file path to imitate*, NOT inline code snippets: you will read the exemplar at edit time anyway, so a snippet dump gets paid for twice; - **establish the toolchain before you need it**: the package manager, whether `the-plaid-api` is already a dependency and at what version, the `tsconfig` flags that change what compiles here (`exactOptionalPropertyTypes`, `verbatimModuleSyntax`, `strict`), and the exact commands that run the project's build, type check, lint and tests. Getting this wrong later costs a broken install mid-implementation — and an uninstalled package costs you the lookup layer itself, since the map ships inside it; -- a baseline run of the project's checks (`tsc --noEmit`, the test runner, the linter — whatever it has) on the UNTOUCHED tree, so later failures are attributable to your changes; +- a baseline run of the project's checks (`tsc --noEmit`, the test runner, the linter — whatever it has) on the UNTOUCHED tree, so later failures are attributable to your changes. + +**Do the rest while the planner works — they need no SDK knowledge and touch no project file:** + +- the repo survey (read-only exploration of conventions, layering, **module format — ESM or CJS, which changes how the SDK is imported and whether `instanceof` on its error classes is trustworthy**, and the runtime: Node, a bundled browser app, or an edge runtime) — capture each convention as *pattern + the ONE exemplar file path to imitate*, NOT inline code snippets: you will read the exemplar at edit time anyway, so a snippet dump gets paid for twice; - credentials/environment verification (per the task's secret-handling rules) — **including which host this deployment will actually talk to**, since constructing the client with no options silently selects `ServerEnvironment.Production`, and the other environment is reached only by setting it; -- **a read-only smoke of each in-scope operation against the real credential**, run from your scratchpad, not the project, once the map has given you the signatures and before you finalise the sheet. A plan-, region- or entitlement-gated endpoint answers `403` here — the map presents every operation uniformly and cannot know which ones your credential may call — and learning that now reorders the plan rather than the build. Skip only operations whose side effects you cannot reverse; - setting up your task tracking. -Never use the planning phase to get a "head start" on implementation: **creating or editing ANY project file before the gate below is a defect**, no matter how obvious the code seems. +**HARD GATE — no project-file creation or edits until:** the planner has RETURNED, `the-plaid-api-plan.md` EXISTS at the repo root (check it — a helper can misreport where it saved), its contract sheet has **no open lookups**, and you have read it. If you wrote the plan yourself, the gate is the same without the return. **Creating or editing ANY project file before then is a defect**, however obvious the code seems; the read-only prerequisite work above is allowed meanwhile. -**HARD GATE — no project-file creation or edits until:** `the-plaid-api-plan.md` EXISTS at the repo root, its contract sheet has **no open lookups**, and you have read it. The gate bars coding "meanwhile"; it does not bar the read-only prerequisite work above. Starting to code before the sheet exists defeats the entire plan-first design. +**What the gate does not cover:** installing `the-plaid-api` into the project, installing the toolchain, and the files those writes produce (`node_modules/`, a lockfile the installer updates) are **prerequisites, not project-file edits** — the map lives inside the installed package — and they are the only writes permitted before the gate. -**What the gate does not cover:** installing `the-plaid-api` into the project, installing the toolchain, and the files those writes produce (`node_modules/`, a lockfile the installer updates) are **prerequisites, not project-file edits**. On a greenfield repo they are the only way to reach the lookup layer at all — the map lives inside the installed package — and they are the only writes permitted before the gate. Nothing you author by hand may change. +**One read-only prerequisite waits for the signatures: a smoke of each in-scope operation against the real credential**, run from your scratchpad, not the project, once the planner has returned and you have read the sheet, with the signatures it records, and before your first project edit — or, if you are writing the plan yourself, once the map has given you the signatures and before you finalise the sheet. A plan-, region- or entitlement-gated endpoint answers `403` here — the map presents every operation uniformly and cannot know which ones your credential may call — and learning that now reorders the plan rather than the build. Send each `403` to the SAME planner as a revision, as *Step 1c* sends a blocker, and implement from its reply; if you wrote the plan yourself, revise the sheet in place. Skip only operations whose side effects you cannot reverse. ### Step 1b — The tables the contract sheet must carry (fill these in before you write any code) -The per-operation rows describe **what each operation is**. The tables below carry what those rows cannot: a write that may reach the provider twice or whose outcome you may not learn, a rule that spans two operations, and a field nobody asked for. Fill in every one that applies before any code exists. +The per-operation rows describe **what each operation is**. The tables below carry what those rows cannot: a write that may reach the provider twice or whose outcome you may not learn, a rule that spans two operations, and a field nobody asked for. Fill in every one that applies. #### 1b.1 — DURABLE WRITES @@ -57,7 +68,7 @@ One row in each table below per operation in scope that creates, sends or change **Where that rejection is caught**: the `catch` for what the store raises on the second claim, recognised by the driver's error code rather than its message; the losing caller then uses the record the winner wrote. -The SDK sends an `Idempotency-Key` minted once per call, and its own retries resend that key — but a second click or a retry of your own is a new call with a new key, so the provider cannot join the two. The key goes beside the claim, never in place of it; where the operation declares its own key, send the reference stored on the claim (see `typescript-configuration-resilience`). +The SDK's own `Idempotency-Key` is new on every call (*Making a write safe under retries* in `typescript-configuration-resilience`), so it goes beside the claim, never in place of it; where the operation declares its own key, send the reference stored on the claim. **UNKNOWN OUTCOMES** — what settles a write the provider may have acted on without your code learning the answer. @@ -66,7 +77,7 @@ The SDK sends an `Idempotency-Key` minted once per call, and its own retries res ⚠⚠ A `ConnectionError` or `TimeoutError` on a write is *unknown*, not *failed*: the provider may already have acted. Reporting a failure is not a legal entry, and neither is leaving the caller to check or retry. Settle it in that write's own `catch`: re-read by the reference you sent — found, settle from what the provider holds; not found, or the re-read itself fails, still unknown, never failed. Telling the caller the outcome is unknown comes after the re-read, never instead of it. If the provider offers no way to find the write, that is a **Blocker** in Assumptions & Blockers, not a row. -A write that never left has nothing to re-read — a credential that could not be obtained (`AuthError`) or a value that would not encode (`EncodeError`) — and must reach a different outcome. Re-reading after every error is not the safe default: "any error might mean it went through" is false for a request that never left, so a refused credential gets its own outcome and no re-read. **The test that fails the connection** asserts the re-read request was made; a second test, a never-sent failure on the same write, asserts it was not. +A write that never left — a credential that could not be obtained (`AuthError`) or a value that would not encode (`EncodeError`) — has nothing to re-read and gets its own outcome. **The test that fails the connection** asserts the re-read request was made; a second test, a never-sent failure on the same write, asserts it was not. Write `TBD` in **Where in the code** and **The test that fails the connection** while you plan — every row. Once the code compiles, replace each `TBD` individually: the claim write, then the SDK call it precedes; the `catch`, then the re-read it makes. ⚠⚠ A `TBD` left behind, a name that is not in the code, or one note covering several rows is **not addressed**; if the code does not do what the row says, fix the code, then the cell. @@ -118,44 +129,42 @@ Logging the reason is not returning it: log it **and** put it in the response. End the contract sheet with a **REQUIRED READING** block whose rows carry inline `MUST load ` pointers. **Load every `typescript-*` skill the sheet names, now, before you start implementing** — not lazily at the step that needs it. The sheet deliberately does *not* carry the how-to: it names the hazard and hands you the skill that resolves it, so an unloaded pointer is a gap in what you know, not a formality. -**A fixed floor applies regardless of what the sheet says** — the sheet can add to it, never remove from it: `typescript-error-handling` always (every integration writes an error boundary, and this SDK's one error family is narrowed on its closed `kind`, with four throwables outside it that a family test has to rethrow); `typescript-client-initialization` before the client is constructed; `typescript-testing` before the first test file you create or edit, *including* a throwaway verification script that fakes `fetch`. A sheet row that excuses one of these ("out of scope", "no test suite requested") is not a substitute for loading it. +**A fixed floor applies regardless of what the sheet says** — the sheet can add to it, never remove from it: `typescript-error-handling` always (every integration writes an error boundary); `typescript-client-initialization` before the client is constructed; `typescript-testing` before the first test file you create or edit, *including* a throwaway verification script that fakes `fetch`. -These are API-agnostic usage skills; loading them is not a substitute for the lookup layer, and reading a file in the installed package does not remove the need to load the skill for that step. Contract *facts* still come only from your sheet or a fresh lookup. +These are API-agnostic usage skills; loading them is not a substitute for the lookup layer, and reading a file in the installed package does not remove the need to load the skill for that step. Before implementing, check the plan's **Assumptions & Blockers** section: -- Blocker or major assumption → surface it to the user in plain language, get their answer, and revise `the-plaid-api-plan.md` in place. +- Blocker or major assumption → surface it to the user in plain language, get their answer, and send it to the SAME planner as a follow-up message (re-start it, carrying the clarification and the plan path, only where your host cannot message it). It revises `the-plaid-api-plan.md` in place and replies with the changed rows verbatim: work from that reply, not a re-read of the file. If you wrote the plan yourself, revise it in place. - Minor assumptions only → proceed. Full re-planning only on genuine scope change; for a single missing fact mid-implementation, do the lookup, never guess. ### Step 2 — Implement from the contract sheet -1. Read `the-plaid-api-plan.md` once. Treat its contracts as authoritative — do not re-derive or "double-check" them from memory. When a lookup revises a row, update the file so the sheet and the code never disagree. -2. **Decide which environment this deployment talks to, explicitly, before the first call.** Constructing the client with no options selects `ServerEnvironment.Production` **silently**, so an unset field is indistinguishable from a deliberate choice of the default. Bind it to configuration and fail startup if the (environment, credential) pair is not the one this deployment intends — a credential pointed at the wrong host is not a defect any call site can correct. -3. **Build the client once and hold it.** The OAuth 2 token cache lives on it, so rebuilding one per request throws that state away. There is no `close()` — it owns a `fetch`, not a pool. -4. **Pick the response mode per call, deliberately.** Every operation returns `ApiPromise`: `await` it and an error status rejects, or call `.asApiResult()` **on the value the operation returned** for the non-throwing `ApiResult` — the only way to see the status and headers of a *success*, and therefore the only way to observe anything at all from the **11 operations that resolve to `undefined`** (every operation whose success declares no body — the map's **Returns** bullet names them). `ApiPromise` overrides `Symbol.species`, so `.then()`/`.catch()`/`.finally()` hand back a plain `Promise` with the method gone — the mode is chosen at write time, never retrofitted. -5. Implement sequentially, following the repo's own conventions and layering. You loaded the companion skills the sheet named in Step 1c — implement each step in line with the one that governs it. Take every contract *fact* (signatures, field names, channels, error arms, enum members) from the contract sheet or a fresh lookup — never re-derive one from a companion. -6. After every change: run the project's **type checker** (`tsc --noEmit`) as well as its tests. The package ships its own types and is generated under strict TypeScript, so a type error against it is a real contract violation, not noise — it is the compile-time backstop the whole map-first discipline leans on. **Treat a clean type check as the gate you do not skip.** If the project has no type check configured, run `tsc --noEmit` over the files you touched; if you genuinely cannot, say so in your final report rather than silently substituting a smoke run. Fix non-SDK errors yourself. -7. **Any error involving an SDK type or member** — `TS2339` (property does not exist), `TS2345`/`TS2322` (argument or assignment mismatch), `TS2551` (did you mean), `TS2307` (cannot find module — usually a deep import), `TS2739`/`TS2741` (missing required members), or an unexpected rejection at runtime — → go back to `typescript-getting-started`'s map section and file table, and read the one page or file that owns the fact. Do not attempt more than one self-fix of an SDK-name error before doing that lookup: rewriting from the same knowledge that produced the error is guessing. Remember which failures are **not** `ApiError`: a malformed body is `DecodeError`, a value that would not encode `EncodeError`, a dropped connection `ConnectionError`, an attempt's timeout `TimeoutError` (both only after any retries are spent), a credential that could not be **obtained** `AuthError` — every one of them in the `ThePlaidApiError` family, told apart by `err.kind` — and an unknown `serverEnvironment` throws `ConfigurationError` out of the client constructor, before any call exists. So an exception that does not look like an API error may still be one of the SDK's failure kinds. +1. Read `the-plaid-api-plan.md` once and treat its contracts as authoritative. When a lookup revises a row, update the file so the sheet and the code never disagree. +2. **Decide which environment this deployment talks to, explicitly, before the first call** — the default is selected silently (Step 1). Bind it to configuration and fail startup if the (environment, credential) pair is not the one this deployment intends. +3. **Build the client once and hold it.** The OAuth 2 token cache lives on it, so rebuilding one per request throws that state away. +4. **Pick the response mode per call, deliberately.** Every operation returns `ApiPromise`: `await` it and an error status rejects, or call `.asApiResult()` on the value the operation returned for the non-throwing `ApiResult` — the only way to see the status and headers of a *success*, and therefore the only way to observe anything at all from the **11 operations that resolve to `undefined`** (every operation whose success declares no body — the map's **Returns** bullet names them). `typescript-calling-endpoints` has the mechanics. No operation is paged. +5. Implement sequentially, following the repo's own conventions and layering and the companion skill that governs each step. +6. After every change: run the project's **type checker** (`tsc --noEmit`) as well as its tests. The package ships its own types, so a type error against it is a real contract violation, not noise — it is the compile-time backstop the whole map-first discipline leans on. **Treat a clean type check as the gate you do not skip.** If the project has no type check configured, run `tsc --noEmit` over the files you touched; if you genuinely cannot, say so in your final report rather than silently substituting a smoke run. Fix non-SDK errors yourself. +7. **Any error involving an SDK type or member** — `TS2339` (property does not exist), `TS2345`/`TS2322` (argument or assignment mismatch), `TS2551` (did you mean), `TS2307` (cannot find module — usually a deep import), `TS2739`/`TS2741` (missing required members), or an unexpected rejection at runtime — → go back to `typescript-getting-started`'s map section and file table, and read the one page or file that owns the fact. Do not attempt more than one self-fix of an SDK-name error before doing that lookup: rewriting from the same knowledge that produced the error is guessing. A failure that is not an `ApiError` — `DecodeError`, `EncodeError`, `ConnectionError`, `TimeoutError`, `AuthError` — is still in the `ThePlaidApiError` family, told apart by `err.kind` (`typescript-error-handling`). 8. Once the code is complete, open each member the **DUPLICATE CLAIMS** and **UNKNOWN OUTCOMES** rows name and confirm it runs when that write runs. Where the code falls short of a row, fix the code, not the row. -9. **Observability and sensitive data.** Logging is **off by default** and is configured through `ClientOptions.logging`: say whether the integration turns it on, at what level, and which correlation id from the provider's error bodies reaches your own logs. A JSON request body is logged **verbatim** when `logRequestBody` is on, and a form body is masked only by deny-list, so a key you have not listed prints in the clear. If the scope carries data you would not want in a log — each request model's declaring file lists every field in scope — `logRequestBody` stays off, no call on those paths passes a per-call level, which turns the body on, **and** `ClientOptions.logging.level` is set explicitly, so the `THE_PLAID_API_CLIENT_LOG` environment variable cannot switch logging on from outside the code (see `typescript-getting-started`). +9. **Observability and sensitive data.** Logging is **off by default** and is configured through `ClientOptions.logging`: say whether the integration turns it on, at what level, and which correlation id from the provider's error bodies reaches your own logs. If the scope carries data you would not want in a log, follow the **Sensitive data** rules in `typescript-getting-started`. 10. Run the project's tests; verify the integration end to end the way the task demands. Retrying is **on by default**, so if the task needs a different policy, tune it through `ClientOptions.retry` rather than wrapping the call. The SDK has no hooks or middleware, so anything the task needs there is yours to build on the `ClientOptions.fetch` seam or to deliberately omit — say which you did for both. ### Step 3 — Answering pure questions -A standalone The Plaid API question with no code change: look it up in `typescript-getting-started` (and the map page or file its table names), then give the grounded answer, citing where it came from. When several questions arrive batched, answer them in one pass. Never answer from memory, even for "easy" questions. +A standalone The Plaid API question with no code change: look it up in `typescript-getting-started` (and the map page or file its table names), then give the grounded answer, citing where it came from. When several questions arrive batched, answer them in one pass. ## Anti-patterns — never do these -- **Always load `typescript-getting-started` first.** It is your lookup layer, not optional background. (The `typescript-*` companions are the complement: load the ones the sheet names, per Step 1c.) Don't re-derive a contract *fact* from a companion — exact signatures, request fields, channels, error arms and enum members come from the sheet or a fresh lookup. -- **Never write any The Plaid API or SDK fact from memory** — every signature, field name, wire header, enum member, and error arm in your code must come from the contract sheet or a lookup. And **never write a call from memory "to fix later".** -- **Never switch on an error arm tag across operations.** A tag is derived from the arm's **body schema**, never from its status: an arm whose body is a direct model reference is named after that model in lower camel (`"validationError"`), and every other body — a primitive, an array, a map, or no content — is named `"error{Status}"` (`"error400"`, `"error4XX"`, `"errorDefault"`), with a numeric suffix on the second of two arms that would otherwise land on the same name. Tags are resolved **per operation**, so the same tag covers different statuses on different operations — a shared handler keyed on `err.payload.kind` is a bug. Read the status from `err.status`, and narrow on `kind` only against the arm table of that one operation. +- **Never create or edit a project file while `the-plaid-api-planner` is running**, and never start a second one for the same integration. +- **Never write or state any The Plaid API or SDK fact from memory** — every signature, field name, wire header, enum member, and error arm must come from the contract sheet or a fresh lookup, never from recall or from a companion skill. And **never write a call from memory "to fix later".** +- **Never switch on an error arm tag across operations.** A tag comes from the arm's **body schema**, not its status, and is resolved **per operation**, so the same tag covers different statuses on different operations — a shared handler keyed on `err.payload.kind` is a bug (`typescript-error-handling` has the naming rule). Read the status from `err.status`, and narrow on `kind` only against the arm table of that one operation. +- **Never hand-advance a paging field on a paged operation, and never leave a walk unbounded.** An operation whose **Signature** returns `Pageable` is walked with `for await` or `.pages()`: the SDK seeds the first page from the request and advances the state itself, so a loop that re-calls the operation with the next page number walks the rest of the list again on every call and repeats its items. A walk ends only when the API stops handing out pages, so it carries a bound of your own — a page cap, an item cap or a deadline. - **Don't web-search The Plaid API topics to find an implementation detail** — the installed package's own map and source are the ground truth, and the file table tells you where to look. Public The Plaid API docs describe the HTTP API, not this SDK's generated surface, and the two disagree on names, on which fields are required, and on what the SDK sends by default. - **Never introspect the SDK at run time to discover its shape.** `Object.keys`, logging a client instance, or a REPL poke is the TypeScript-flavoured version of decompiling the package: it answers what exists, never what is *supported*, and it invites `#`-private fields and unexported engine types into your code. Read the map, then the file it names. -- **Don't grep the package to *locate* a type** — the SDK map is the locator (and says so: *"Do not derive the path from the type name"*); grep only *inside* the file its **Type sources** table names, for the symbol. A sweep for a *shape* is a different thing, and is fine: "every field typed `unknown`", "every required-nullable member" are cross-cutting questions nothing indexes, and one targeted `grep -rn` over `src/models/` is the right tool for them — record what it found on the sheet. -- **Don't deep-import from the package** (`the-plaid-api/models/…`). The package root is the only entry and deep specifiers do not resolve; the map's `Source` paths are for reading, not importing. +- **Don't grep the package to *locate* a type, deep-import from it (`the-plaid-api/models/…`), or vendor its `src/`** — `typescript-getting-started`'s *Contract facts*, *Imports* and *Install* sections say what to do instead. - **Don't import `Error` unaliased.** This SDK exports a type named after a TypeScript/DOM global, so importing it plain shadows the global for the whole file. Alias on import from `the-plaid-api`. -- **Don't vendor the SDK's `src/` into the project, point `tsconfig` `paths` at a throwaway clone, or import from `dist/` directly** to make a lookup possible. Install it properly (see `typescript-getting-started`); a clone-based shortcut breaks every import the moment the clone is deleted, and it does not put the map where the lookups expect it. -- **Don't create or edit project files before the HARD GATE** in Step 1 — plan and contract sheet first, code second. diff --git a/plugins/plaid/skills/typescript/typescript-models/SKILL.md b/plugins/plaid/skills/typescript/typescript-models/SKILL.md index ca6fed29..9a0168d8 100644 --- a/plugins/plaid/skills/typescript/typescript-models/SKILL.md +++ b/plugins/plaid/skills/typescript/typescript-models/SKILL.md @@ -1,6 +1,6 @@ --- -name: typescript-models -description: Working with models in an APIMatic-generated TypeScript SDK — building request bodies from plain object literals, required members and optional-versus-nullable fields, open enums, discriminated and undiscriminated unions, the four date codecs, and the schema companion beside every type. Load before constructing a request payload or mapping SDK models onto your own domain types. +name: "typescript-models" +description: "Load before building a request payload for an APIMatic-generated TypeScript SDK or mapping its models onto your own types — object-literal models, optional versus nullable fields, open enums, discriminated and plain unions, date codecs, bytes, unknown fields, and the schema companion beside every type." --- # Working with models in an APIMatic TypeScript SDK @@ -14,19 +14,15 @@ import { type {Model}, {model}Schema } from "{package-name}"; const body: {Model} = { {requiredField}: "..." }; ``` -**There is exactly one spelling.** No companion dict type, no builder, no factory and no static -helper: an object literal is how every model is built, at every nesting level. And **nothing is -frozen** — no property is emitted `readonly`, so a decoded response is an ordinary mutable object. -Mutating one is allowed but is not a wire operation: what you changed reaches the API only by passing -the value to an operation, or by re-encoding it yourself. +An object literal is how every model is built, at every nesting level. **Nothing is `readonly` or +frozen**: a decoded response is an ordinary mutable object, and a change reaches the API only when you +pass the value to an operation, or re-encode it yourself. -Two exports per model — the type and a `{model}Schema` value — and both come from the **package -root**; deep imports do not resolve. This skill covers the **non-obvious model shapes** that trip -integrations up. The patterns are generic across APIMatic TypeScript SDKs; take the real type and -field names from the contract sheet — the **Models** section of `sdk-map.md` and the **Type sources** -table on the operation's block in `map/operations/*.md`, both grounded in the `src/models/` the -package ships — never from a compiled `dist/`, and never from a path derived off the type name. The -`Source` column is where to **read** a shape, never what to import. +Two exports per model — the type and a `{model}Schema` value — both from the **package root** +(**typescript-client-initialization**). Take the real type and field names from the **Models** section +of `sdk-map.md` or an operation's **Type sources** table in `map/operations/*.md` — never from a +compiled `dist/`, and never from a path derived off the type name. The `Source` column is where to +**read** a shape, never what to import. > Throughout this skill, `{...}` is a placeholder for a name you take from your SDK (e.g. `{Model}`, > `{Union}`, `{Variant}`, `{Enum}`, `{package-name}`) — replace it with the concrete identifier from @@ -34,18 +30,17 @@ package ships — never from a compiled `dist/`, and never from a path derived o ## Where a model lives -| Group (as `sdk-map.md` names it) | Directory | What is emitted | +| Group (as `sdk-map.md` names it) | Directory | What it is | | --- | --- | --- | | Objects, and `allOf` (flattened) | `src/models/` | one `type` with the properties, plus its schema | | Enums (open; const companion plus schema) | `src/models/` | `as const` object + open type alias + schema | | Discriminated unions (`oneOf`) | `src/models/unions/` | union of tag-narrowed arms + dispatching schema | | Unions without a discriminant (`anyOf`) | `src/models/unions/` | a bare union type + an accepting schema | -Two consequences worth internalising. **`allOf` is flattened** into one plain object type — every -constituent's properties restated on one type, with no inheritance, no base type to assign to and -nothing recording the composition. And **an object schema that `allOf` subtypes made a polymorphic -base is emitted as a discriminated union**, not as a base type, so it lands under `unions/` too: -there is nothing to upcast to, and you narrow on the tag instead. +**`allOf` is flattened** into one plain object type — every constituent's properties on one type, with +no inheritance and no base type to assign to. **A polymorphic base** (an object that `allOf` subtypes +derive from) is a discriminated union under `unions/`, not a base type: there is nothing to upcast to, +and you narrow on the tag instead. ## Required, optional, nullable @@ -68,29 +63,27 @@ const ok: {Model} = { id: "1" }; // const also: {Model} = { id: "1", ...(label !== undefined ? { label } : {}) }; // conditional ``` -At run time an explicit `undefined` is dropped from the JSON anyway (a property with a spec default -sends its default instead, below), so that one is a type-level constraint. `null` is not: a nullable field set to `null` sends JSON `null`, which is a different +At run time an explicit `undefined` is treated as omitted anyway, so that one is a type-level +constraint. `null` is not: a nullable field set to `null` sends JSON `null`, which is a different request from an absent key — the distinction that matters on a PATCH. -**A model property with a spec default is optional in the type and `s.defaulted(...)` in its schema.** -Omitting it, or passing `undefined`, still sends the default (on a partial update, send its current value +**A model property whose schema is `s.defaulted(...)` has a default.** It is optional in the type; +omitting it, or passing `undefined`, still sends the default (on a partial update, send its current value instead), and a response that omits it reads back as the default. ### Reading one back -An absent optional is simply `undefined` (one with a spec default reads back that default) — there -is no sentinel value to import and nothing to -compare against, so `?.` and `??` are the whole toolkit, and, on a property without a spec default, `!== undefined` is the precise test when -"present but empty" and "absent" are different facts. Under `noUncheckedIndexedAccess` an array index -is `T | undefined` too, so guard `items[0]` before reaching through it. +An absent optional is simply `undefined` — there is no sentinel value to import and nothing to +compare against, so `?.` and `??` are the whole toolkit, and, on a property with no default, +`!== undefined` is the precise test when "present but empty" and "absent" are different facts. Under +`noUncheckedIndexedAccess` an array index is `T | undefined` too, so guard `items[0]` before reaching +through it. -⚠ **A response type whose spec marks nothing required decodes an empty body without complaint** — -every property reads back `undefined`, or its default, and nothing throws. A truncated or partial body is therefore -not an error, it is a model full of `undefined`; check the properties you actually depend on. A -property that is required on a request type and optional on the response type is normal and -intentional — two schemas for one concept — so never infer the response shape from the request shape. -Both are in the map: the operation's **Fields** table for the request, the **Type sources** file for -the response. +⚠ **A response type with no required properties decodes an empty or truncated body without +complaint** — every property reads `undefined`, or its default, and nothing throws; check the properties +you depend on. Request and response types for one concept can differ in requiredness, so never infer the +response shape from the request shape: read each from the map (the operation's **Fields** table for the +request, the **Type sources** file for the response). ## Polymorphic union types: discriminated and undiscriminated @@ -111,13 +104,10 @@ An `anyOf` becomes a bare union with nothing to switch on — `export type {Unio — and its schema tries the arms in **declaration order**, first match winning, so overlapping arms are resolved by order. -⚠ **A payload matching no arm throws.** Both kinds fail the decode — through an operation as a -`DecodeError` whose `cause` is the `SchemaError`, through a schema you call directly as the -`SchemaError` itself — an unrecognized tag has no arm to dispatch to, and an undiscriminated union that matches nothing has no -arm to fall back on. You do not get a null union or an unset variant. A provider that adds a variant -your SDK predates turns into a decode failure on a call that was previously fine, so a union field is -a place to expect regeneration pressure. See **typescript-error-handling** for where that surfaces in -a catch ladder. +⚠ **A payload matching no arm throws** — through an operation as a `DecodeError` whose `cause` is the +`SchemaError`, through a schema you call directly as the `SchemaError` itself. There is no null or +unset variant, so a variant the provider adds later breaks a call that used to work. See +**typescript-error-handling** for where that surfaces in a catch ladder. ### Construct @@ -151,8 +141,7 @@ that renamed it has the rename applied on the way out, so the type alias spells the schema names what was sent. Take the exact tag and arm names from the **Unions** table in `sdk-map.md` (`Union` · `Variants` · `Narrow with` · `Source`) rather than deriving them. -A union the spec left unconstrained degrades to `unknown`. That is the generator reporting that the -spec constrained nothing, not a bug. +A union with nothing constrained is typed `unknown`. ## Collections @@ -162,7 +151,7 @@ convert. | Value | On the wire | | --- | --- | -| omitted / `undefined` | key absent, or the spec default if it has one | +| omitted / `undefined` | key absent, or its default if it has one | | `null` on a nullable field | `null` | | `[]` | `[]` | | `{}` | `{}` | @@ -197,7 +186,7 @@ convert. money as a **`string`** scaled to the currency (`"10.00"`) — where yours does, keep it a string end to end: formatting it through `Number` and back is what silently turns `"10.10"` into `10.1`. -- **A field the spec pinned to one value** is typed as that literal and checked with +- **A field pinned to one value** is typed as that literal and checked with `s.literal(...)`: `status: "accepted"` admits that one value and nothing else, in either direction. ## Bytes @@ -210,38 +199,31 @@ const body: {Model} = { payload: new TextEncoder().encode("hello") }; const text = new TextDecoder().decode(model.payload); ``` -That is for base64-in-JSON fields only, and it is **not** the file-upload carrier. The engine does -send raw-binary and multipart bodies, but a file there is a `FileInput` — bytes the transport frames -rather than a value a schema encodes — and the two deliberately never unify: a decoded `Uint8Array` -field is not assignable to a file field, and `new Uint8Array(value)` is the one-copy bridge (see -**typescript-calling-endpoints**). +That is for base64-in-JSON fields only, and it is **not** the file-upload carrier: a raw-binary body +or multipart file takes a `FileInput` (**typescript-calling-endpoints**), and a decoded `Uint8Array` +field is not assignable to one — `new Uint8Array(value)` is the one-copy bridge. ## What the schema checks — and what it does not -Model schemas are built on `zod/v4-mini`, and what they verify is much narrower than what the API -definition said. Checked: the **primitive type** of each property, the presence of required keys, the -four date formats, base64, a pinned literal, and a union's arms. Not checked — because the generator -does not transcribe these at all, so there is no attribute to read and no validator to invoke: +Checked by an operation, in both directions: the **primitive type** of each property, the presence of +required keys, the four date formats, base64, a pinned literal, and a union's arms. **Never checked by +an operation**: - **String formats.** A uuid, email, uri, hostname, ip, password, json-pointer, regex-constrained - string and a bare `time` are all emitted as plain `string` with `s.string()`. Nothing validates the - shape in either direction: an email field accepts `"not an email"` and sends it. -- **Bounds and lengths.** No `minLength`, `maxLength`, `minimum`, `maximum`, `multipleOf`, - `uniqueItems` or `pattern` reaches the generated code. -- **`additionalProperties: false`.** Not enforced; see *Unknown / future fields* below. - -The provider is therefore the only enforcer of those, and it enforces them as a `400` you have to -interpret. Where you want a client-side guard — worth it on user-supplied input before a write, where -a rejected request costs a round-trip and an error path — write it at your own boundary and read the -constraints from `api-reference.md`, which does carry the API's documented contract. - -What the schema *does* check, it checks in **both** directions: encoding runs before the request is -built, so an invalid model rejects the call with an `EncodeError` — its `cause` the `SchemaError` -naming the field — and **nothing is sent**. Read that failure as the SDK -catching your mistake at the point you made it, not as an upstream fault — the compiler catches the -shape and the schema catches the values, and between them very little reaches the network wrong. In -production, catch it at the boundary where *you* assemble a payload from external input and treat it -as a 4xx on your own API. + string and a bare `time` travel as plain `string`: an email field is sent as `"not an email"`. +- **Bounds and lengths** — `minLength`, `maxLength`, `minimum`, `maximum`, `multipleOf`, + `uniqueItems`, `pattern`. +- **`additionalProperties: false`** — see *Unknown / future fields* below. + +An operation never refuses a value for one of those; the provider does, as a `400` you have to +interpret. **`{model}Schema.validate` does check the formats, bounds and lengths the spec declares** — +see *Checking a value before you send it* below — so pass user-supplied input through it before a +write, where a rejected request costs a round-trip and an error path. `api-reference.md` carries the +documented contract either way. + +An invalid model rejects the call with `EncodeError` — its `cause` the `SchemaError` naming the field — +and **nothing is sent**. In production, catch it at the boundary where *you* assemble a payload from +external input and treat it as a 4xx on your own API. ## Enums @@ -256,14 +238,14 @@ export const {enum}Schema = s.enumOf<{Enum}>({Enum}); - **The name is a value and a type at once.** Import it *without* `type` wherever you use its members — `import { {Enum}, {enum}Schema } from "{package-name}"` — since a type-only import makes - `{Enum}.Active` a compile error. Prefer the member over the bare literal: a spec change that + `{Enum}.Active` a compile error. Prefer the member over the bare literal: an SDK update that renames the value then fails to compile instead of failing in production. - **The type is open.** The `(string & {})` tail — `(number & {})` on a number enum — means any value of the base type is assignable. - **The schema validates the base type only, never membership.** A string enum accepts any string, a - number enum any number, so a value the provider added after generation round-trips instead of - throwing. That is deliberate, and it is why a `switch` over a **received** enum value needs a - `default` arm — the opposite of a discriminated union, whose unrecognized tag does throw. + number enum any number, so a value newer than the SDK round-trips instead of throwing. That is + deliberate, and it is why a `switch` over a **received** enum value needs a `default` arm — the + opposite of a discriminated union, whose unrecognized tag does throw. ```ts if ({enum}Schema.values.includes(received)) { /* a member this SDK knows */ } @@ -296,29 +278,27 @@ divergences are listed once, in the **Wire-name divergences** table in `sdk-map. ## Unknown / future fields -Model schemas are built on a **loose** object, so keys the model does not declare are **kept**, not -stripped, in both directions — a field the provider added after this SDK was generated survives -decoding and round-trips back out on encode. `additionalProperties: false` changes nothing about -this. - -There is no typed bag to read them from, though, and no member on the type: +A model whose spec schema is open — `additionalProperties` absent, `true`, or a schema — keeps the +keys it does not declare in one optional field, `additionalProperties?: Record`. `T` is +`JsonValue` when the spec gave no value schema, otherwise the declared type, and each value is +validated against it. The field is present only when the wire carried an extra, and its keys are +**wire** names — nothing maps the casing here: ```ts -// Decoding: the key is on the object but not in the type. -const extra = (model as Record)["x_experimental"]; - -// Encoding: extra keys on a value you pass are sent. Excess-property checking catches them on a -// fresh object literal, but not on a value that arrived through a variable. +const extra = model.additionalProperties?.x_experimental; ``` -The keys are **wire names** — there is no property, so nothing maps the casing for you here. And a -field you depend on that has no typed property is a regeneration signal: prefer regenerating the SDK -from a spec that describes it over building program logic on stringly-typed lookups. +On the way out, extras you write into the record are sent beside the declared fields; a value that +is not a `T`, or a key the model already declares, is an `EncodeError` before any request is sent. +Read the field's name off the model: a spec that declares its own `additionalProperties` property +keeps it, and the record is `additionalProperties2`. A model whose spec says +`additionalProperties: false` has no record, yet an unknown key on it still passes through both +directions, invisible to the type. -The same symmetry is a debugging trap on the way out: a **misspelled** property is not an error -either, it is an extra key that gets sent and ignored. So when a value you set is not taking effect, -check the spelling against the type before suspecting the API — excess-property checking only catches -it on a fresh object literal, never on a value that reached the call through a variable. +A **misspelled** property is not an error either: it is an extra key that is sent and ignored. +Excess-property checking catches it only on a fresh object literal, never on a value that reached the +call through a variable — so when a value you set is not taking effect, check the spelling against +the type before suspecting the API. ## The schema companion @@ -333,7 +313,35 @@ const back = {model}Schema.decode(JSON.parse(JSON.stringify(wire))); Both directions throw `SchemaError` on mismatch and produce nothing partial. Using a schema on inbound data the SDK did not hand you — a webhook body, a queue message, a cached blob — is the -intended use, and gives you exactly the validation the SDK applies to a response. +intended use. For a model whose spec declares value constraints it is stricter than a response, not +the same: `{model}Schema` enforces them on `decode` as it does on `encode`, while an operation +decodes through the structural twin, so a payload that breaks a `pattern` or a bound passes through +an operation and throws here. Catch `SchemaError` on that path if a payload the service already +accepted should not be dropped for a constraint. + +### Checking a value before you send it + +```ts +const result = {model}Schema.validate(model); +if (!result.success) { + // "name: Invalid input; dispatch.lockerCode: expected regex format" + console.error(result.message); +} +``` + +`validate` runs `encode`'s rules without the conversion and without the throw, and is the **only** +place a value constraint the spec declares (`minLength`, `pattern`, `minimum`, `uniqueItems`, a +checked `format`, …) is applied — a keyword on an array's `items` or a map's +`additionalProperties` included, checked on each item or value and reported under its index or +key (`tags.0`, `attributes.carrier`). An operation never applies one: it sends and receives +through a structural twin, `{model}InternalSchema`, so a value the service would accept is never +refused on the way out, and a service that is ahead of the spec is never refused on the way in. A +model that +nests a constrained one validates the nested value too and reports its fields under their full +path. + +No operation exports a `{operation}RequestSchema`: no request field carries a constraint of its own, +so a request object is checked by the operation alone, by type and presence. Do **not** `JSON.stringify` a model directly for storage, or hand a raw model to anything that will encode it — a web framework's response serializer, a cache, a queue. `JSON.stringify` writes @@ -349,3 +357,4 @@ schema surface, and the failures each date codec produces. - Pass models to an operation → **typescript-calling-endpoints** - `SchemaError`, and the `DecodeError` or `EncodeError` it arrives on → **typescript-error-handling** + diff --git a/plugins/plaid/skills/typescript/typescript-models/reference.md b/plugins/plaid/skills/typescript/typescript-models/reference.md index e6dc98c6..5c881b1a 100644 --- a/plugins/plaid/skills/typescript/typescript-models/reference.md +++ b/plugins/plaid/skills/typescript/typescript-models/reference.md @@ -1,49 +1,27 @@ # Models reference (APIMatic TypeScript) -Condensed reference for the shapes in **typescript-models**. The schema combinators live in -`src/core/validation/` — vendored static code, identical in every generated TypeScript SDK — and are -reached through the `s` namespace inside generated model modules. `s` re-exports `zod/v4-mini` -(`string`, `number`, `boolean`, `array`, `record`, `union`, `nullable`, `optional`, `literal`, -`unknown`) plus the SDK's own entries (`object`, `enumOf`, `discriminatedUnion`, `of`, `lazy`, -`optionalNullable`, `defaulted`, `dateTime`, `rfc1123DateTime`, `unixSecondsDateTime`, `dateOnly`, `bytes`). +Lookup tables beside **typescript-models**, which carries the rules. Model modules build their +schemas from the `s` namespace (`src/core/validation/`, the same in every APIMatic TypeScript SDK): +`zod/v4-mini`'s `string`, `number`, `boolean`, `array`, `record`, `union`, `nullable`, `optional`, +`literal`, `unknown`, plus the SDK's `object`, `enumOf`, `discriminatedUnion`, `of`, `lazy`, +`optionalNullable`, `defaulted`, `dateTime`, `rfc1123DateTime`, `unixSecondsDateTime`, `dateOnly` and +`bytes`. Confirm concrete type and field names in `src/models/`. -## The two exports per model - -```ts -import { type {Model}, {model}Schema } from "{package-name}"; -``` - -One `type` and one schema value, both re-exported from the package root. Take the pair from an -operation's **Type sources** table (`Type` · `Schema value` · `Source`) in `map/operations/*.md`, or -from the **Models** section of `sdk-map.md`. The type-name-to-path transform is not reversible, so do -not guess the path. - -**An enum is the exception to the `type` import.** Its name is a value *and* a type, so -`import { {Enum}, {enum}Schema }` — with `type`, `{Enum}.Active` does not compile. Every other model -type carries no runtime value, so under `verbatimModuleSyntax` it must be imported as -`import { type {Model} }` or `import type { {Model} }`; the schema const is always a value import. - -The package ships `dist` (with declaration files), `src`, `README.md`, `api-reference.md`, -`sdk-map.md` and `map`, so the readable TypeScript and the contract sheets are all inside -`node_modules/{package-name}/`. - -No property is emitted `readonly` and no model is frozen: a decoded response is a plain mutable -object, and mutating it changes nothing on the wire by itself. - ## Spec kind to TypeScript type | API definition kind | Model type | Schema entry | | --- | --- | --- | -| string, password, regex-constrained, email, uri, ip, hostname, json-pointer, uuid | `string` | `s.string()` — **format unchecked** | -| `time` | `string` | `s.string()` — unchecked | +| string, password, uuid, regex-constrained | `string` | `s.string()` | +| email, uri, ip, hostname, json-pointer | `string` | `s.string()` — the format is a value check, see *Deriving a changed copy* | +| `time` | `string` | `s.string()` | | `date` | `string` | `s.dateOnly()` | | `date-time` (ISO 8601 / RFC 1123 / unix) | `Date` | `s.dateTime()` / `s.rfc1123DateTime()` / `s.unixSecondsDateTime()` | | int32, int64 | `number` | `s.int()` | | float, double, big-decimal | `number` | `s.float64()` | | boolean | `boolean` | `s.boolean()` | | binary, file — as a declared field | `Uint8Array` | `s.bytes()` (base64) | -| a value the spec fixed | that literal type | `s.literal(value)` | +| a pinned value | that literal type | `s.literal(value)` | | free-form object | `Record` | `s.record(s.string(), s.unknown())` | | array of `T` | `T[]` | `s.array(...)` | | map of `T` | `Record` | `s.record(s.string(), ...)` | @@ -53,66 +31,58 @@ object, and mutating it changes nothing on the wire by itself. Nullability folds onto whatever the row produced: `T | null` with `s.nullable(...)`. It is never folded onto `unknown`, which already admits `null`. +A value constraint the spec declares on a row — a length, a pattern, a checked format, a numeric +bound — never changes the type; where it is enforced is stated under *Deriving a changed copy*. + ## Field declaration cheat sheet | Declared | Schema entry | Building it | | --- | --- | --- | | `f: T` | the entry itself | always provide | | `f?: T` | `s.optional(...)` | **omit the key** (not `f: undefined`) | -| `f?: T` | `s.defaulted(...)` | omitting it sends the spec default; set the value you mean | +| `f?: T` | `s.defaulted(...)` | omitting it sends its default; set the value you mean | | `f: T \| null` | `s.nullable(...)` | provide `null` to send JSON `null` | | `f?: T \| null` | `s.optionalNullable(...)` | omit, or provide `null` | -```ts -// Conditional optional field, exactOptionalPropertyTypes-safe: -const body: {Model} = { id, ...(note !== undefined ? { note } : {}) }; -``` - -Run time is more forgiving than the type system — an explicit `undefined` is dropped from the JSON, except where a spec default is sent instead — -but do not rely on it: the SDK's own tsconfig sets `exactOptionalPropertyTypes` (and -`verbatimModuleSyntax`, `noUncheckedIndexedAccess`, `strict`), and a consumer that does the same will -not compile. - -`s.defaulted(entry, value)` marks a model property or a request field with a spec default; the SDK fills -the default on encode and decode. - ## Deriving a changed copy ```ts const updated = { ...model, {field}: "..." }; ``` -Nothing validates a spread — the schema runs when you pass the value to an operation or call `encode` -yourself, and that is where a bad value surfaces. The copy is **shallow**: nested models and arrays -are shared with the original, so mutating one mutates both. Undeclared keys the source carried are -copied along, which is what keeps a read-modify-write round-trip from dropping server-side state the -SDK does not model. - -## Reading a response model - -- **An absent optional is `undefined`**, unless it has a spec default. No sentinel, no wrapper, so `?.` / `??` are enough, and, - without a default, `!== undefined` is the precise test where "absent" and "present but empty" differ. -- **A response type whose spec marks nothing required accepts `{}`.** `{model}Schema.decode({})` - succeeds and every property is `undefined` or its default; a truncated body raises nothing. Check the properties - you depend on. -- **Required on the request, optional on the response is normal.** Two schemas, one concept — read - each from its own place in the map rather than assuming they match. -- Under `noUncheckedIndexedAccess`, `items[0]` is `T | undefined`; guard it before reaching through. -- An undeclared key that arrived on the wire is on the object but not in the type — reach it with a - widening cast, and only when you must. +Nothing validates a spread — the shape is checked when you pass the value to an operation or call +`encode` yourself, and that is where a wrong type surfaces. A value constraint the spec declares +(`minLength`, `pattern`, `minimum`, a checked `format`, …) is **not** checked by an operation; +`{model}Schema` checks it — `validate(value)` reports it, `encode` and `decode` throw on it. The copy +is **shallow**: nested models and arrays are shared with the original, so mutating one mutates both. +Undeclared keys the source carried are copied along, which is what keeps a read-modify-write +round-trip from dropping server-side state the SDK does not model. ## Schema surface ```ts type Schema> = { - readonly decode: (value: unknown) => T; // wire shape -> model - readonly encode: (value: unknown) => W; // model shape -> wire + readonly decode: (value: unknown) => T; // wire shape -> model + encode(value: T): W; // model shape -> wire + validate(value: T): ValidationResult; // encode's rules, no conversion, no throw }; +type ValidationResult = { success: true } | { success: false; message: string }; + type EnumSchema = Schema & { readonly values: readonly T[] }; ``` -`Schema`, `EnumSchema` and `Encoded` are re-exported from the package root as types. +`Schema`, `EnumSchema`, `Encoded` and `ValidationResult` are re-exported from the package root as +types. + +`validate` runs the same rules `encode` runs and reports instead of throwing: `message` lists every +failing field with its reason (`code: expected regex format; attributes: must have at most 10 +properties`), the same list a `SchemaError` from `encode` carries after its leading sentence. On a +model whose spec declares value constraints, `{model}Schema` enforces them and `validate` is how you +check a value before sending it; the operations encode and decode through a structural twin, +`{model}InternalSchema`, exported from the model's module but not from the package root, so a +constraint is never applied on the way out or on the way in. On every other model `validate` checks +shape alone. `Encoded` — the wire projection: @@ -124,228 +94,33 @@ type EnumSchema = Schema & { readonly values: readonly T[] }; | object | each property projected | | anything else | itself | -Both directions throw `SchemaError` on mismatch and produce nothing partial. The message is prefixed -`Wire value could not be decoded.` or `Type could not be encoded for the wire.`, followed by -`path: expected X, received T` per issue — `T` the type that arrived, never the value (`` -where there is no path). It keeps no copy of the offending value; `.cause` is the underlying zod error -with the structured issue list. Through an operation it arrives one level down, on the `cause` of a -`DecodeError` or an `EncodeError`. Request encoding runs before the HTTP call, so an encode failure -means **nothing was sent**. - -## Key renaming - -The `_keysMap` entry inside a generated `s.object({ ... })` literal maps TypeScript property names -to wire keys, and is applied on decode and encode both. Only properties that moved appear: - -```ts -export const {model}Schema = s.object<{Model}>({ - createdAt: s.dateTime(), - isActive: s.optional(s.boolean()), - _keysMap: { createdAt: "created_at", isActive: "is_active" }, -}); -``` - -You never write wire keys. Reach for `_keysMap` — or the **Wire-name divergences** table in -`sdk-map.md` — only when reading a captured HTTP body. +A `SchemaError` message is prefixed `Wire value could not be decoded.` or `Type could not be encoded +for the wire.`, followed by `path: expected X` per issue — `X` the type, format or set of values the +schema expected; neither the value nor its type is named (`` where there is no path). `.cause` +is the underlying zod error with the structured issue list. ## Enums -```ts -export const {Enum} = { Active: "active", Retired: "retired" } as const; -export type {Enum} = (typeof {Enum})[keyof typeof {Enum}] | (string & {}); -export const {enum}Schema = s.enumOf<{Enum}>({Enum}); -``` - -| Property | Behaviour | -| --- | --- | -| Type | **open** — the `(string & {})` / `(number & {})` tail admits any value of the base type | -| Wire value | the member's value, verbatim (`"active"`, or `1` for a number enum) | -| Decoding | checks the **base type only** — `s.enumOf` builds a string or a number check from the members and validates nothing else, so an unknown member is accepted | -| Known set | `{enum}Schema.values` — `readonly {Enum}[]`, in declaration order | -| Member names | generated identifiers; a number enum's members are `_0`, `_1`, … | - -```ts -import { {Enum}, {enum}Schema } from "{package-name}"; - -body.status = {Enum}.Active; // preferred -body.status = "active"; // compiles, but survives a rename -const known = {enum}Schema.values.includes(fromServer); // runtime membership test -``` - -Because unknown members decode, a `switch` over a received enum value **needs a `default` arm**, and -an `if`/`else if` chain over the members with no final `else` silently does nothing for a value newer -than the SDK. - -There is **no coercion helper** — no `fromValue`, no closed lookup that raises — because a member *is* -its wire value: - -```ts -{Enum}.Active === "active"; // true -`${{Enum}.Active}`; // "active" — safe in a log line, a URL, a query string -type Known = (typeof {Enum})[keyof typeof {Enum}]; // the closed set, at type level -``` - -Mapping an SDK enum onto your own, tolerating the open arm: - -```ts -function toDomain(value: {Enum}): MyEnum { - switch (value) { - case {Enum}.Active: return MyEnum.A; - case {Enum}.Retired: return MyEnum.B; - default: return MyEnum.Unknown; // covers values newer than this SDK - } -} -``` - -## Discriminated unions (`oneOf`, and a polymorphic base) - -```ts -// src/models/unions/{union}.ts -export type {Union} = ({ArmA} & { {tag}: "a" }) | ({ArmB} & { {tag}: "b" }); - -export const {union}Schema = s.discriminatedUnion<{Union}>("{wire_tag}", { - a: {armA}Schema, - b: {armB}Schema, -}); -``` - -- The arms are the variant types **intersected with the tag literal**; the variant type itself does - not declare the tag, so a value typed `{ArmA}` is not assignable to `{Union}`. -- **Narrow with `switch` on the tag.** The arms are exhaustive, so no fallback arm is needed. -- **Build by writing the arm's literal, tag included** — the schema writes the tag onto the wire from - the value you pass, and dispatches on it when decoding. -- The schema's key is the **wire** discriminator and each entry's key is the wire tag **value**. The - tag name on the **decoded** object can differ, where a variant renamed the discriminator; the type - alias spells what arrives. -- A polymorphic base (an object schema that `allOf` subtypes with a discriminator derive from) is - emitted here **as a discriminated union**, not as a base type. There is nothing to upcast to. -- ⚠ A tag matching no arm is a decode failure — a `SchemaError`, on a `DecodeError`'s `cause` through - an operation — not an unset variant. - -```ts -switch (value.{tag}) { - case "a": return handleA(value); // narrowed to the {ArmA} arm - case "b": return handleB(value); -} -``` - -## Undiscriminated unions (`anyOf`) - -```ts -export type {Union} = string | {Model}; -export const {union}Schema = s.of<{Union}>(s.union([s.string(), s.lazy(() => {model}Schema)])); -``` - -- Nothing narrows the arms — use `typeof`, `in`, or `Array.isArray`. -- Decoding accepts a value matching **any** arm, and **the first match in declaration order wins**, - so overlapping arms resolve by order. -- Build by passing a value of any arm directly. There is no wrapper and no factory. -- A union the spec left unconstrained degrades to `unknown`. -- ⚠ A value matching no arm is a decode failure — a `SchemaError`, on a `DecodeError`'s `cause` - through an operation. +An `if`/`else if` chain over the members with no final `else` silently does nothing for a value newer +than the SDK. `type Known = (typeof {Enum})[keyof typeof {Enum}]` is the closed set at type level. ## Dates -| Schema | Model type | Wire | Notes | -| --- | --- | --- | --- | -| `s.dateTime()` | `Date` | `"2024-06-17T15:30:00Z"` | ISO 8601, **offset required**; encodes via `toISOString()` | -| `s.rfc1123DateTime()` | `Date` | `"Mon, 17 Jun 2024 15:30:00 GMT"` | strict IMF-fixdate (two-digit day, `GMT`); encodes via `toUTCString()` | -| `s.unixSecondsDateTime()` | `Date` | `1718638200` | epoch **seconds**; a numeric string also decodes; encodes floored to whole seconds | -| `s.dateOnly()` | `string` | `"2024-06-17"` | a **string**, not a `Date`; the `YYYY-MM-DD` shape is checked | - -```ts -body.createdAt = new Date("2024-06-17T15:30:00Z"); // Date-typed fields -body.birthDate = "1990-04-02"; // dateOnly field — a string -``` +- `s.dateTime()` requires an offset on decode; encodes via `toISOString()`. +- `s.rfc1123DateTime()` is strict IMF-fixdate (two-digit day, `GMT`); encodes via `toUTCString()`. +- `s.unixSecondsDateTime()` also decodes a numeric string; encodes floored to whole seconds. +- `s.dateOnly()` checks the `YYYY-MM-DD` shape. `s.bytes()` rejects non-base64 input on decode. Failures to expect: -- `"2024-06-17"` into an `s.dateTime()` field → `SchemaError` (date-only, no offset). -- `"2024-06-17T15:30:00"` into an `s.dateTime()` field → `SchemaError` (no offset). +- `"2024-06-17"` or `"2024-06-17T15:30:00"` into an `s.dateTime()` field → `SchemaError` (no offset). - `"Mon, 7 Jun 2024 15:30:00 GMT"` into `s.rfc1123DateTime()` → `SchemaError` (day must be two digits). - Epoch **milliseconds** into `s.unixSecondsDateTime()` → no error; it decodes to a date ~50,000 years out. Divide by 1000, or pass a `Date`. -Read the field's combinator in `src/models/{model}.ts` to know which applies — the `Date` type alone -does not say. - -## Bytes - -```ts -// Field declared: payload: Uint8Array (schema: s.bytes()) -body.payload = new TextEncoder().encode("hello"); // encoded to base64 on the wire -const text = new TextDecoder().decode(model.payload); // decoded from base64 for you -``` - -Base64-in-JSON fields only. Non-base64 input fails on decode. This is not the file-upload carrier: -a raw-binary body and a multipart file part both take a `FileInput`, which is framed rather than -encoded, and a decoded `Uint8Array` is deliberately not assignable to one. - -## Collections - -| Field | Type | Pass | -| --- | --- | --- | -| array | `T[]` | a plain array | -| map / free-form object | `Record` | a plain object | -| unconstrained value | `unknown` | anything; nothing is checked | - -| Value | On the wire | -| --- | --- | -| omitted / `undefined` | key absent, or the spec default if it has one | -| `null` on a nullable field | `null` | -| `[]` | `[]` | -| `{}` | `{}` | - ## Recursive and self-referential models -Generated schemas wrap a reference that nests inside another validator in `s.lazy(() => otherSchema)`, -so a model that refers to itself (a tree node, a nested comment) works with no special handling. -Nothing is required of you; the type is just a normal recursive `type`. - -## Undeclared keys (passthrough) - -Model schemas are built on a **loose** object, so undeclared keys survive both directions: - -```ts -// Decoding: an undeclared response key is on the object but not in the type. -const extra = (model as Record)["x_experimental"]; - -// Encoding: extra keys on a value you pass are sent. -// (Excess-property checking catches this on a fresh literal, not on a variable.) -``` - -There is no typed `additionalProperties` bag, and `additionalProperties: false` is not enforced — it -has no visible effect at all. A key you need but the type lacks means the spec does not describe it. - -## What is never validated - -`s.string()` carries no format check and no length or pattern check; `s.int()` and -`s.float64()` carry no `minimum`, `maximum` or `multipleOf` check; arrays carry no `uniqueItems` check. -The generator does not transcribe those -constraints, so there is nothing to read and nothing to invoke — they are enforced only by the -provider, as a `400`. `api-reference.md` carries the documented contract; put your own guard at your -own boundary if you want one before the round-trip. - -## Round-tripping - -```ts -const wire = {model}Schema.encode(model); // wire-shaped plain object -const json = JSON.stringify(wire); -const back = {model}Schema.decode(JSON.parse(json)); -``` - -`JSON.stringify(model)` directly is **not** the wire shape: - -| Model value | Through `encode` | Through `JSON.stringify` directly | -| --- | --- | --- | -| a renamed property | the wire key | the TypeScript key | -| a `Date` on an RFC-1123 or unix-seconds field | that field's format | an ISO string — wrong format | -| a `Uint8Array` | base64 `string` | `{"0":104,"1":105}` — the bytes are gone | - -So decoding a directly-stringified model fails on the renamed keys and the date formats, silently. The -same applies to handing a raw model to anything else that encodes — a framework's response -serializer, a cache, a queue: map it to your own type at the boundary, or hand out `encode`'s result. +A self-referential model (a tree node, a nested comment) needs no special handling: generated schemas +wrap a nested reference in `s.lazy(() => otherSchema)`. -Using a schema on inbound data you did not get from the SDK — a webhook body, a queue message, a -cached blob — is the intended use, and gives you the same validation the SDK applies to responses. diff --git a/plugins/plaid/skills/typescript/typescript-testing/SKILL.md b/plugins/plaid/skills/typescript/typescript-testing/SKILL.md index 2475f409..1a11d09c 100644 --- a/plugins/plaid/skills/typescript/typescript-testing/SKILL.md +++ b/plugins/plaid/skills/typescript/typescript-testing/SKILL.md @@ -1,6 +1,6 @@ --- name: typescript-testing -description: Testing code that calls an APIMatic-generated TypeScript SDK — which seam to fake (`ClientOptions.fetch`, or an interceptor at the global-fetch layer), stubbing bodies in wire shape, asserting the request the SDK actually built, covering the error and decode-failure paths, turning the on-by-default retry policy off (or testing it deliberately), and keeping tests independent of SDK internals. Load before writing tests for the integration layer. +description: Load before writing tests for code that calls an APIMatic-generated TypeScript SDK — faking `ClientOptions.fetch` or intercepting global `fetch`, wire-shaped stub bodies, asserting the request the SDK built, error, decode and auth failure paths, OAuth token stubs, paged walks, and the on-by-default retries. --- # Testing code that uses an APIMatic TypeScript SDK @@ -95,16 +95,15 @@ matters, or pass a `logger` that records its calls when the test is *about* what `Response` is global on Node 18+. Credentials can be dummy values, or omitted entirely — nothing validates them when the transport is stubbed, unless the test is *about* the credential. -**Do not mock the client, its resource classes, or reach for its internals.** `#rawClient` and the -other private fields are genuinely unreachable, and a hand-rolled double of `{Api}Client` cannot catch -the mistakes that actually happen — a wrong path parameter, a body that does not encode, a header you -forgot. Faking `fetch` exercises the real request-building pipeline; that is the whole point. Never -construct a resource class either: it is exported only for its merged namespace and for `instanceof`, -and its constructor takes engine internals that are not exported. +**Fake `fetch`, not the client.** A hand-rolled double of `{Api}Client` or a resource class (which you +cannot construct — **typescript-calling-endpoints**) cannot catch the mistakes that actually happen — a +wrong path parameter, a body that does not encode, a header you forgot; a fake `fetch` runs the real +request pipeline. -> **If your client has an OAuth 2 scheme, the first request your stub sees is the token request**, not -> your operation. See **Fake an OAuth token endpoint** below before writing the first test — a -> single-response fake fails there in a confusing way. +> **With an OAuth 2 scheme, the first request your stub sees is the token request**, not your +> operation. A single-response fake hands your operation's body to the token decoder, and the call +> fails with an `AuthError` (cause: a `DecodeError` about `access_token`) that reads like bad +> credentials. See **Fake an OAuth token endpoint** below. ## Stub bodies are in WIRE shape, not model shape @@ -130,7 +129,7 @@ expect(() => {model}Schema.decode(fixture)).not.toThrow(); // validate a hand- Prefer the first: build the fixture as a typed model and encode it, so a member rename breaks the fixture instead of passing a stale test. Validate any fixture you hand-write and reuse — it catches -fixture rot when the SDK is regenerated. Both schema consts are exported from the package root. +fixture rot when the SDK is updated. Both schema consts are exported from the package root. ## Test a success path @@ -194,9 +193,9 @@ if ("rawBody" in e.payload) expect(new TextDecoder().decode(e.payload.rawBody)). ``` **Take the arm union from the contract sheet per operation.** `"undeclared"` is reachable in Case A -too — any status the operation's matchers do not cover falls to it — so an error test copied from a -sibling operation can pass for the wrong reason, landing in the `"undeclared"` branch and asserting -nothing about the typed body you meant to check. +too — any status the operation's matchers do not cover falls to it, a spec's `default` response +being no matcher — so an error test copied from a sibling operation can pass for the wrong reason, +landing in the `"undeclared"` branch and asserting nothing about the typed body you meant to check. Use `try`/`catch` rather than a rejection matcher: matcher support for narrowing a rejected value differs between runners, and the `catch` form reads the same everywhere. @@ -225,11 +224,9 @@ it("reports the failure without throwing", async () => { }); ``` -On success the value is `outcome.value` (not `.data`), and `outcome.headers` is the only way to read -**response headers** — so this is also the mode to test in when your code depends on a header on the -*success* path. `.asApiResult()` does **not** make the call non-throwing: everything in the next -section still rejects, and it must be called on the value the operation returned, before any -`.then()`. +`outcome.headers` is the only way to read **response headers** on the *success* path, so test in this +mode when your code depends on one. Everything in *Cover the failures that are not an `ApiError`* +still rejects in this mode. ## Assert the outgoing request @@ -254,21 +251,20 @@ it("sends the right request", async () => { - **The SDK hands the fake one `Request` and no `init`.** Its `url` is absolute, so `new URL(request.url)` gives you `pathname` and `searchParams` for free rather than substring-matching a URL string. A fake that reads `init` reads nothing. -- **Header names are lowercased.** The SDK normalizes every layer — the endpoint's, the auth scheme's - and the client's defaults — before merging, which is what makes the merge case-insensitive, and - `request.headers` is a `Headers`. Read it through `request.headers.get(...)`; a plain - `request.headers["Authorization"]` is both the wrong type and the wrong case. +- **Read headers through `request.headers.get(...)`** — `request.headers` is a `Headers` with + lowercased names, so a plain `request.headers["Authorization"]` is both the wrong type and the wrong + case. - **The body is already serialized by the time the fake sees it.** The captured `body` is the request - body's **text** (or `undefined`), which is all a JSON, form-urlencoded or text body needs, and it - uses **wire aliases**, because that is what encoding produces. Assert on the parsed string; do not + body's **text** (or `undefined`), which is all a JSON, form-urlencoded or text body needs, with **wire + aliases** and wire dates, because that is what encoding produces — assert on the parsed string; do not "fix" the aliases in the test. Read a multipart or binary body back off the captured `request` instead: a multipart one with `await request.formData()`, and a binary one with `new Uint8Array(await request.arrayBuffer())` — its text is lossy. A multipart `content-type` carries a generated boundary, so match it as a prefix, never with `toBe`. Compare a file part by its contents, `await new Response(form.get("{field}")).text()`: one sent without a file name may come back as a string or a `File`. -- **A list-valued query or form parameter has a per-parameter wire style.** The `StyledParam` the - generator emitted for it in `src/resources/{resource}.ts` carries a `style`: `plain` (the default — +- **A list-valued query or form parameter has a per-parameter wire style.** Its `StyledParam` in + `src/resources/{resource}.ts` carries a `style`: `plain` (the default — `name=a&name=b`), `indexed` (`name[0]=a`, percent-encoded in the raw URL as `name%5B0%5D=a`), `unindexed` (`name[]=a`), or `csv` / `tsv` / `psv` (one joined value). Read it before asserting: @@ -290,14 +286,48 @@ Worth asserting once, somewhere, because they are silent when wrong: - **The value actually reached the wire.** Request models encode loosely too, so an extra or misspelled optional member is carried into the body rather than rejected. Only an assertion on the captured `body` catches it. -- **A body that cannot encode never reaches your fake.** Encoding happens *before* the request is - dispatched, so the call rejects with `EncodeError` and `stub.calls` stays **empty**. Same for a path - parameter left `undefined` — its schema rejects it, also as an `EncodeError`, before anything is - sent. Assert `stub.calls` is empty in those tests. -- **`retry.timeout` never rides the request.** It is a per-attempt budget in **milliseconds**, set on - the client or on one call through `RequestOptions.retry`, and it reaches the wire only as the - `Request`'s `signal`. A test asserting a timeout on a captured request is asserting something that - was never there. +- **An encode failure never reaches your fake** — a bad body and an `undefined` path parameter alike + reject with `EncodeError` and leave `stub.calls` **empty**; assert that in those tests. +- **`retry.timeout` never rides the request**; the fake sees it only as the `Request`'s `signal`. + +## Test a paged operation + +A paged operation sends one request per page, so queue one response per page and let the walk run. +`retry: { maxRetries: 0 }` keeps it to one request per page, and a queue that runs out is the signal +that a walk did not stop where you expected: + +```ts +it("walks every page", async () => { + const { client, stub } = clientReturning( + jsonResponse(200, { items: [{ id: "1" }, { id: "2" }], nextCursor: "c2" }), + jsonResponse(200, { items: [{ id: "3" }], nextCursor: null }), + ); + + const ids: string[] = []; + for await (const item of client.{resource}.{operation}({ limit: 2 })) ids.push(item.id); + + expect(ids).toEqual(["1", "2", "3"]); + expect(stub.calls).toHaveLength(2); + expect(stub.calls[1]!.url.searchParams.get("cursor")).toBe("c2"); // the SDK advanced the state +}); +``` + +Stub the stop signal the operation's strategy reads — a `null` or absent next cursor, a `hasMore` of +`false`, a page shorter than its `limit`, or an empty page — in **wire shape**, like any other body; +the operation's **Returns** bullet names the strategy and the condition that ends its walk. A `Link`-header +strategy reads the `Link` response header, and the SDK follows a link only on the client's own origin: + +```ts +new Response(JSON.stringify(body), { + status: 200, + headers: { Link: '<{baseUrl}/{path}?cursor=c2>; rel="next"' }, // the base URL the client was built with +}) +``` + +A failed page is tested like any failed call: queue an error status in the position of the page that +fails, and the walk throws `ApiError` (or the operation's own subclass) after yielding the pages before +it. Nothing is sent until a loop starts, so a test that calls the operation and never iterates asserts +that `stub.calls` is empty. ## Cover the failures that are not an `ApiError` @@ -312,9 +342,7 @@ reachable from the fake, which makes these paths genuinely testable rather than | `kind: "decode"` | return a body that violates the schema (wrong type, bad date, a non-empty `200` where `undefined` is expected) | | `kind: "encode"` | pass a request value its schema refuses — nothing reaches the fake | | `kind: "auth"` | answer the **token** request with an error status (see below) | - -A caller abort is **not** a `kind`: aborting the signal you passed in `RequestOptions` rejects with that -signal's own `reason`, outside the family. +| `kind: "pagination"` | answer a page of a `Link`-strategy walk with a next link on another origin — a `Link` header naming a host that is not the client's base URL | ```ts import { {Api}Error } from "{package-name}"; @@ -335,11 +363,9 @@ it("maps a transport failure", async () => { }); ``` -⚠ **A timeout or abort test needs a fake that honours the `Request`'s `signal`.** The SDK aborts the -signal it put on the `Request` and relies on `fetch` to settle; a fake that returns a never-resolving -promise and ignores the signal simply hangs the test until the runner kills it. What the fake rejects -with does not matter — the SDK reads the reason off its own signal — so a timeout is a `TimeoutError` -the retry loop retries, which is why the test below sets `maxRetries: 0`. +⚠ **A timeout or abort test needs a fake that honours the `Request`'s `signal`**: one that ignores it +hangs the test until the runner kills it. What the fake rejects with does not matter — a timeout is a +`TimeoutError` the retry loop retries, which is why the test below sets `maxRetries: 0`. ```ts const hangingFetch: typeof globalThis.fetch = (input, init) => @@ -356,10 +382,8 @@ it("times out", async () => { }); ``` -That is faster and more deterministic than fake timers, and it exercises the real abort path. For a -caller abort, keep the default timeout, abort your own `AbortController` passed in `RequestOptions`, and -assert the call rejects with exactly the `reason` you passed — it is not an `{Api}Error`, and it is -never retried. +A caller abort is **not** a `kind`: abort your own `AbortController` passed in `RequestOptions` and +assert the call rejects with exactly the `reason` you passed — not an `{Api}Error`, and never retried. **A decode failure bypasses *both* response modes.** A 2xx body that does not satisfy the schema rejects with `DecodeError`; `.asApiResult()` does **not** turn it into an `ok: false` result. Test that your @@ -427,7 +451,7 @@ const stub = stubFetch((url) => ); ``` -Or bypass acquisition entirely with a stub token strategy — the generator's supported injection point +Or bypass acquisition entirely with a stub token strategy — a supported extension point (**typescript-authentication**) — so the fake only ever sees your operation: ```ts @@ -449,18 +473,12 @@ needs `redirectUri` and `promptForAuthorizationCode` (e.g. `async () => "code"`) Facts that make these tests behave: -- **Forgetting the token request is the most common way a first test fails confusingly.** A - single-response fake hands your operation's body to the *token* decoder, and you get an `AuthError` - whose `cause` is a `DecodeError` about a missing `access_token` — which reads like wrong credentials - when the fake simply answered the wrong request. - The token **response** is wire-shaped (`access_token`, `token_type`, `expires_in`); the token - **request** is a `POST` with a form-urlencoded string body, and by default the client id and secret - ride in a Basic `Authorization` header rather than in that body. + request's shape is in **typescript-authentication**. - The token endpoint may live on a **different server group**, so match on the path, not the host — read the group's URL from `DEFAULT_SERVER_OPTIONS` in `src/servers.ts`. - The token is **cached on the scheme**, so only the first call fetches one: a test making two calls - against one client sees three requests, not four. Build a fresh client per test to reset it. A - missing or non-positive `expires_in` means the cached token never expires. + against one client sees three requests, not four. Build a fresh client per test to reset it. - The token request and the operation each run on their own `retry.timeout`, so a tiny timeout in an OAuth test can fire on the token request — which ends the call with a `TimeoutError` for the token endpoint, not retried unless `httpMethodsToRetry` names `POST`. @@ -480,18 +498,13 @@ agent.get("{base-origin}").intercept({ path: "{operation-path}", method: "POST" .reply(201, { id: "1" }, { headers: { "content-type": "application/json" } }); ``` -Pick one and be consistent. An interceptor asserts on real URLs and is closer to the wire; the fake -`fetch` is dependency-free, faster, and does not care what HTTP stack is underneath. Two constraints: -an interceptor works **only while no `fetch` option is supplied** — a custom `fetch` bypasses it -entirely — and the client resolves `globalThis.fetch` **in its constructor**, so patching the global -after the client is built has no effect. +Pick one approach. An interceptor sees nothing once a `fetch` option is supplied, and one that patches +`globalThis.fetch` must be installed before the client is built (**typescript-client-initialization**). ## Keeping tests independent of SDK internals -- **Never deep-import.** The package's `exports` map exposes `.` and `./package.json` and nothing else, - so `{package-name}/models/…` does not resolve at all. Everything you need — the client, the options, - every model type and its `{model}Schema`, the error classes, `ServerEnvironment` — is re-exported - from the package root. Reading a file under `src/` is for *learning* the shape, never for importing. +- **Import only from the package root** (**typescript-client-initialization**); read `src/` to learn a + shape, never to import from it. - **Never assert on an error's `message`.** An `ApiError`'s is the call and its status — `POST https://… failed with 400` — which moves whenever the base URL or the route does. It is not a contract. Assert `err.status` and the narrowed `err.payload`. @@ -515,9 +528,9 @@ const client = new {Api}Client({ }); ``` -**Override every group the test touches.** Redirecting `default` does not move a token endpoint that -lives on its own group — it will reach for the real host and the test will either fail slowly or, -worse, succeed against production. `src/servers.ts` lists the groups and their environments. +**Override every group the test touches** — a token endpoint on its own group otherwise reaches the +real host (**typescript-configuration-resilience**). `src/servers.ts` lists the groups and their +environments. Against a **live sandbox**, keep those tests separate from unit tests, skip them when credentials are absent, and never assert on ids or timestamps the provider generates: @@ -547,17 +560,10 @@ unless you mean to. `Response` needs no `content-type` header; setting one is harmless documentation. What matters is that the body parses and satisfies the schema. A binary response is the exception: its result reports `content-type` and the `content-disposition` file name, so stub them when your code reads them. -- **Matcher precedence:** an exact-status arm wins over a range or `"5XX"` wildcard arm. A test that - stubs a status covered by both is asserting the exact one. -- **A `401` invalidates the cached OAuth token and is not retried by default.** A test that stubs a - `401` sees one failed operation — and the *next* call in the same test re-fetches a token, so queue - another `tokenResponse()` for it. -- **Retries are on by default, and silent unless logging is on.** On a client built without - `retry: { maxRetries: 0 }`, a stubbed `408`, `429`, `500`, `502`, `503` or `504` — or a thrown - error — on a `GET`, `HEAD`, - `PUT` or `OPTIONS` call is fetched up to four times, across about 7 s of backoff. A queue that runs out - throws, and that throw is itself a connection failure the loop retries. When the test *is* about - your retry policy, queue one response per attempt, pass `delay: 0` so it runs at once, and count +- A stubbed `401` invalidates the cached OAuth token, so the *next* call in the same test fetches a new + one — queue another `tokenResponse()` for it. +- **Testing the retry policy itself**: drop `maxRetries: 0`, queue one response per attempt (a queue + that runs out throws, and the loop retries that as a connection failure), pass `delay: 0`, and count requests: ```ts const stub = stubFetch(queue(jsonResponse(503, {}), jsonResponse(503, {}), jsonResponse(200, { id: "1" }))); @@ -566,24 +572,12 @@ unless you mean to. await client.{resource}.{operation}({ /* ... */ }); // an operation whose method is in the gate expect(stub.calls).toHaveLength(3); ``` - A stubbed `Retry-After` header overrides `delay`, so leave it off unless the test is about it; a test - about the backoff itself wants `maxJitter: 0` and fake timers. Cover the cases that are easiest to get - wrong: a write outside the gate is sent **once**, a widened write re-sends the **same** - `Idempotency-Key` on every attempt, and an aborted request stops retrying. -- **A test environment with no global `fetch` fails in the constructor**, not on the first call — the - client throws `ConfigurationError` when it can resolve no implementation. Passing a fake avoids this entirely. -- **`instanceof` is dialect-scoped.** If the test setup loads the SDK through `require` and the code - under test through `import` (or vice versa), `instanceof` is `false` across that boundary. Narrow on - `err.kind` / `err.payload.kind` there, or fix the config to use one dialect. + A stubbed `Retry-After` overrides `delay`; a backoff test wants `maxJitter: 0` and fake timers. Worth + covering: a write outside the gate is sent **once**, a widened write re-sends the **same** + `Idempotency-Key`, and an abort stops retrying. - **Never guess a base URL.** With a fake `fetch` nothing is dialled and the host is irrelevant; if you match on URLs, take the prefix from `DEFAULT_SERVER_OPTIONS` rather than from memory — environments - differ per API, and some SDKs ship a sandbox environment that already points at localhost. + differ per API. - Mocking libraries work too — the seam is a plain function, so a `vi.fn()` / `jest.fn()` returning a `Response` satisfies it. The hand-written stub above gives you typed captured requests and ordered responses for free. -- **Keep one client across the calls of a test** as in production, so the token cache and the memoized - resource getters behave the same shape they will at runtime - (**typescript-client-initialization**). -- To look up an operation's signature, its field channels, route or error arms, take them from the - contract sheet — `map/operations/{resource}.md` inside `node_modules/{package-name}/`, which carries - all four — not the compiled `dist/`, and not memory. diff --git a/plugins/slack/.claude-plugin/plugin.json b/plugins/slack/.claude-plugin/plugin.json index 1a6d6d47..55423162 100644 --- a/plugins/slack/.claude-plugin/plugin.json +++ b/plugins/slack/.claude-plugin/plugin.json @@ -1,8 +1,8 @@ { "name": "slack", "displayName": "Slack Web API", - "version": "0.3.1", - "description": "Integrate and consume the APIMatic-generated Slack Web API SDK — bundled skills for C#/.NET, python, TypeScript.", + "version": "0.3.2", + "description": "Integrate and consume the APIMatic-generated Slack Web API SDK — bundled skills for C#/.NET, Python, TypeScript.", "author": { "name": "APIMatic", "email": "developer@apimatic.io" @@ -14,5 +14,8 @@ "./skills/dotnet", "./skills/python", "./skills/typescript" + ], + "agents": [ + "./scoped/agents/slack-web-api-planner.md" ] } diff --git a/plugins/slack/.codex-plugin/plugin.json b/plugins/slack/.codex-plugin/plugin.json new file mode 100644 index 00000000..647981df --- /dev/null +++ b/plugins/slack/.codex-plugin/plugin.json @@ -0,0 +1,10 @@ +{ + "name": "slack", + "version": "0.3.2", + "description": "Integrate and consume the APIMatic-generated Slack Web API SDK — bundled skills for C#/.NET, Python, TypeScript.", + "skills": "./skills", + "interface": { + "displayName": "Slack Web API", + "developerName": "APIMatic" + } +} diff --git a/plugins/slack/.cursor-plugin/plugin.json b/plugins/slack/.cursor-plugin/plugin.json index 1a6d6d47..6d28bf41 100644 --- a/plugins/slack/.cursor-plugin/plugin.json +++ b/plugins/slack/.cursor-plugin/plugin.json @@ -1,8 +1,8 @@ { "name": "slack", "displayName": "Slack Web API", - "version": "0.3.1", - "description": "Integrate and consume the APIMatic-generated Slack Web API SDK — bundled skills for C#/.NET, python, TypeScript.", + "version": "0.3.2", + "description": "Integrate and consume the APIMatic-generated Slack Web API SDK — bundled skills for C#/.NET, Python, TypeScript.", "author": { "name": "APIMatic", "email": "developer@apimatic.io" diff --git a/plugins/slack/README.md b/plugins/slack/README.md index f37c2a4e..e0d7d7ce 100644 --- a/plugins/slack/README.md +++ b/plugins/slack/README.md @@ -1,6 +1,6 @@ # Slack Web API SDK Plugin -A plugin whose skills teach a coding agent to install and use the APIMatic-generated **Slack Web API SDK**, in C#/.NET, python, TypeScript. Every SDK fact the skills state is grounded in the SDK's own source and generated documentation, not in what a model remembers about this API. +A plugin whose skills teach a coding agent to install and use the APIMatic-generated **Slack Web API SDK**, in C#/.NET, Python, TypeScript. Every SDK fact the skills state is grounded in the SDK's own source and generated documentation, not in what a model remembers about this API. ## What's inside @@ -8,6 +8,17 @@ One skill set per language. The entry point is that language's getting-started s | Language | Skill prefix | Skills | | --- | --- | --- | -| C#/.NET | `dotnet-` | `dotnet-authentication`, `dotnet-calling-endpoints`, `dotnet-client-initialization`, `dotnet-configuration-resilience`, `dotnet-error-handling`, `dotnet-getting-started`, `dotnet-integrate-slack`, `dotnet-models`, `dotnet-testing` | -| python | `python-` | `python-authentication`, `python-calling-endpoints`, `python-client-initialization`, `python-configuration-resilience`, `python-error-handling`, `python-getting-started`, `python-integrate-slack`, `python-models`, `python-testing` | -| TypeScript | `typescript-` | `typescript-authentication`, `typescript-calling-endpoints`, `typescript-client-initialization`, `typescript-configuration-resilience`, `typescript-error-handling`, `typescript-getting-started`, `typescript-integrate-slack`, `typescript-models`, `typescript-testing` | +| C#/.NET | `dotnet-` | `dotnet-authentication`, `dotnet-calling-endpoints`, `dotnet-client-initialization`, `dotnet-configuration-resilience`, `dotnet-error-handling`, `dotnet-getting-started`, `dotnet-integrate-slack-web-api`, `dotnet-models`, `dotnet-testing` | +| Python | `python-` | `python-authentication`, `python-calling-endpoints`, `python-client-initialization`, `python-configuration-resilience`, `python-error-handling`, `python-event-streams`, `python-file-handling`, `python-getting-started`, `python-integrate-slack-web-api`, `python-models`, `python-testing` | +| TypeScript | `typescript-` | `typescript-authentication`, `typescript-calling-endpoints`, `typescript-client-initialization`, `typescript-configuration-resilience`, `typescript-error-handling`, `typescript-event-streams`, `typescript-getting-started`, `typescript-integrate-slack-web-api`, `typescript-models`, `typescript-testing` | + +## Agents + +| Agent | What it does | +| --- | --- | +| `slack-web-api-planner` | Writes `slack-web-api-plan.md`, the plan and its contract sheet, before any project code is written, and revises it in place. `dotnet-integrate-slack-web-api`, `typescript-integrate-slack-web-api` and `python-integrate-slack-web-api` each start it once the SDK is installed or its source reached, on the main agent's own model. | + +How each host gets it: + +- **Claude Code** loads it from `scoped/agents/` with the plugin and lists it as `slack:slack-web-api-planner`. Its file sets `model: inherit`, so it runs on the main agent's model. +- **Where no subagent tool lists it** (a host that doesn't load a plugin's agents, or subagents turned off), the main agent says so in one line and writes the plan itself before any code. diff --git a/plugins/slack/plugin.json b/plugins/slack/plugin.json index 1a6d6d47..6d28bf41 100644 --- a/plugins/slack/plugin.json +++ b/plugins/slack/plugin.json @@ -1,8 +1,8 @@ { "name": "slack", "displayName": "Slack Web API", - "version": "0.3.1", - "description": "Integrate and consume the APIMatic-generated Slack Web API SDK — bundled skills for C#/.NET, python, TypeScript.", + "version": "0.3.2", + "description": "Integrate and consume the APIMatic-generated Slack Web API SDK — bundled skills for C#/.NET, Python, TypeScript.", "author": { "name": "APIMatic", "email": "developer@apimatic.io" diff --git a/plugins/slack/scoped/agents/slack-web-api-planner.md b/plugins/slack/scoped/agents/slack-web-api-planner.md new file mode 100644 index 00000000..cf6821ff --- /dev/null +++ b/plugins/slack/scoped/agents/slack-web-api-planner.md @@ -0,0 +1,21 @@ +--- +name: "slack-web-api-planner" +description: "The Slack Web API planner. It writes slack-web-api-plan.md, the plan and its map-grounded contract sheet, before any project code is written, and revises it in place when the main agent sends a clarification. Main agent: start it when an integrate skill of this plugin tells you to, once per integration, with the user's whole request, the name of the integrate skill you loaded, the absolute project root and the absolute path to write slack-web-api-plan.md to, plus the SDK source's path where that skill says to pass it; edit no project file until it has returned and you have read that file; send revisions to the same agent rather than starting a second." +model: "inherit" +tools: "Read, Grep, Skill, Write, Edit, Bash" +--- + +You are the Slack Web API planner. You write `slack-web-api-plan.md` — the plan and its contract sheet — before any project code is written, and you revise it when the main agent sends a clarification. You never write or fix project code, and you never start another agent: you are the planner the workflow asks for. + +**Your instructions are the integrate skill your task names** — this plugin's `-integrate-slack-web-api` skill for the project's language. Load it, and the getting-started skill it has you load first. Your job is everything that skill puts in `slack-web-api-plan.md`: the plan, its contract sheet and every table and block the sheet carries, wherever the skill describes them, grounded exactly as the skill says. Skip what belongs to the main agent: *The planner agent* (you are that agent), the read-only prerequisites, the required reading it does before implementing, and the implementation itself. Where your task gives the path of the SDK source the main agent reached, read the map and the source there; reach the SDK source yourself only when it gives none. + +## Plan mode + +Your task gives you the user's whole request, the integrate skill to follow, the absolute project root, the absolute path to write to and, where the integrate skill has the main agent reach the SDK source first, the absolute path to it. Write `slack-web-api-plan.md` at exactly the path to write to; if none was given, use `/slack-web-api-plan.md` and say so when you return. It is the only project file you write. Read the project's code only where a table needs it, such as where the codebase already keeps its records, and only read it: do not edit project code, install anything into the project, or run its build or tests. + +Return the plan's path, a one-paragraph summary, and its **Assumptions & Blockers** section verbatim. + +## Revision mode + +When the main agent sends a clarification, a correction or a gap, revise `slack-web-api-plan.md` in place with targeted edits — edit the changed rows, append a new section; never rewrite the whole file to change a few rows. Reply with ONLY the changed or added rows, verbatim, plus one sentence of context: the main agent works from your reply and does not re-read the file. + diff --git a/plugins/slack/skills/dotnet/dotnet-authentication/SKILL.md b/plugins/slack/skills/dotnet/dotnet-authentication/SKILL.md index 6d0cb554..975444ec 100644 --- a/plugins/slack/skills/dotnet/dotnet-authentication/SKILL.md +++ b/plugins/slack/skills/dotnet/dotnet-authentication/SKILL.md @@ -1,17 +1,17 @@ --- name: "dotnet-authentication" -description: "Authentication for the Slack Web API .NET SDK in C# — this API authenticates with the OAuth 2.0 authorization-code grant, and this skill gives the credential each scheme takes, the SlackWebApiClientOptions property to set it on, and the startup check that keeps a missing secret from surfacing as a 401. Load before wiring credentials into the client, or when a call comes back 401/403." +description: "Load before wiring credentials into the Slack Web API .NET SDK client in C#, or when a call throws AuthSchemeException or comes back 401/403. Covers the OAuth 2.0 authorization-code grant: the credential each scheme takes, the SlackWebApiClientOptions property it goes on, and a startup check that fails fast on a missing secret." --- # Authenticating the Slack Web API .NET SDK client -This API authenticates with the OAuth 2.0 authorization-code grant. APIMatic surfaces each scheme as a **nullable credentials property** on `SlackWebApiClientOptions`; set the ones below, then construct the client (see `dotnet-client-initialization`). +This API authenticates with the OAuth 2.0 authorization-code grant. Each scheme is a **nullable credentials property** on `SlackWebApiClientOptions`; set the ones below, then construct the client (see `dotnet-client-initialization`). | Scheme | Property on `SlackWebApiClientOptions` | Credential | | --- | --- | --- | -| OAuth 2.0 authorization code | `SlackAuth` | `OAuth2AuthorizationCodeCredentials` | +| OAuth 2.0 authorization code | `SlackAuth` | `OAuth2AuthorizationCodeCredentials?` | -**That table is the entire authentication surface of this SDK.** `SlackWebApi.Core.Authentication` ships *every* scheme class APIMatic supports as shared runtime code, including kinds this API does not use, so read what is configurable off the properties above rather than off that folder. +**That table is the entire authentication surface of this SDK.** `SlackWebApi.Core.Authentication` also holds scheme classes this API does not use, so read what is configurable off the properties above rather than off that folder. ## OAuth 2.0 — authorization code (3-legged, with PKCE) @@ -35,47 +35,34 @@ options.SlackAuth = new OAuth2AuthorizationCodeCredentials }; ``` -The SDK sends the user to `https://slack.com/api/authorize`, exchanges the returned code for a token at `https://slack.com/api/oauth.access`, and refreshes it when it expires; if the refresh fails, it invokes `PromptForAuthorizationCode` again to re-authorize. +The SDK sends the user to `https://slack.com/oauth/v2/authorize`, exchanges the returned code for a token at `https://slack.com/api/oauth.v2.access`, and refreshes it when it expires; if the refresh fails, it invokes `PromptForAuthorizationCode` again to re-authorize. -`PromptForAuthorizationCode` runs inside the call that needs a new token, under the scheme's fetch lock, so it must not make an SDK call that uses this scheme. It counts against the per-attempt `options.Retry.Timeout`, 100 s by default, and when the call is retryable (by default a `GET`, `HEAD`, `PUT` or `OPTIONS`) a timed-out attempt is retried and prompts again. A prompt that throws anything but `OperationCanceledException` fails the call with `AuthSchemeException`. `State` is sent as you set it and never checked, so your redirect handler must verify it. +`PromptForAuthorizationCode` runs inside the call that needs a new token, so it must not make an SDK call that uses this scheme. It counts against the per-attempt `options.Retry.Timeout`, 100 s by default, and a timed-out attempt on a retryable call is retried and prompts again. A prompt that throws anything but `OperationCanceledException` fails the call with `AuthSchemeException`. `State` is sent as you set it and never checked, so your redirect handler must verify it. -⚠ **`ClientSecret` is required here — PKCE does not make it optional.** This SDK builds the token request with `OAuth2AuthorizationCodeStrategy.ForBasicAuthRequest`, which sends the client id and secret as HTTP Basic credentials on the exchange. Omit it and the call fails with an `AuthSchemeException` wrapping an `InvalidOperationException`, at one of two very different moments: +⚠ **`ClientSecret` is required here — PKCE does not make it optional.** The code exchange sends the client id and secret as HTTP Basic credentials. Omit it and the call fails with an `AuthSchemeException` wrapping an `InvalidOperationException`: -- **PKCE disabled** (`Pkce = null`) — throws *before* `PromptForAuthorizationCode` runs. -- **PKCE enabled** (the default `S256`) — throws *after* the prompt has already run. The user completes a full browser round-trip, and only then does the exchange fail. This is the expensive one. - -The public-client carve-out — a secret-less PKCE flow — belongs to the form-body token request, which this SDK does not use. Do not plan around it here. +- **PKCE disabled** (`Pkce = null`) — *before* `PromptForAuthorizationCode` runs. +- **PKCE enabled** (the default `S256`) — *after* the user has completed the browser round-trip. ## Token caching & refresh - Tokens are cached in-memory, **per client instance**, and reused until **30s** before expiry. -- **This grant refreshes.** The authorization-code grant is wired to `IOAuth2RefreshableTokenStrategy` / `OAuth2RefreshableScheme`, so an expired access token is exchanged for a new one using the refresh token. -- On `401`, the cached token is invalidated and re-acquired on the next call — the failing request is **not** retried. For the authorization-code grant, invalidation drops the refresh token along with the access token, so "re-acquired" means the *full* grant runs again and `PromptForAuthorizationCode` fires: a `401` there is an interactive re-authorization, not a silent refresh. **Plan for that in a non-interactive host** — a background worker will block on a prompt nobody can answer. -- **Invalidation is a hint, not a barrier.** `Invalidate()` clears the cache without taking the fetch lock, so a token fetch already in flight can complete and re-populate it. That is deliberate — the refreshed token post-dates the invalidation — but it means "invalidate then immediately read" is not a guarantee of a fresh token. +- **`options.SlackAuth` requests the whole catalogue (`admin admin.apps:read admin.apps:write admin.conversations:read admin.conversations:write admin.invites:read admin.invites:write admin.teams:read admin.teams:write admin.usergroups:read admin.usergroups:write admin.users:read admin.users:write authorizations:read bot calls:read calls:write channels:history channels:manage channels:read channels:write chat:write chat:write:bot chat:write:user conversations:history conversations:read conversations:write dnd:read dnd:write emoji:read files:read files:write:user groups:history groups:read groups:write identity.basic im:history im:read im:write links:write mpim:history mpim:read mpim:write none pins:read pins:write reactions:read reactions:write reminders:read reminders:write remote_files:read remote_files:share remote_files:write rtm:stream search:read stars:read stars:write team:read tokens.basic usergroups:read usergroups:write users.profile:read users.profile:write users:read users:read.email users:write workflow.steps:execute`) on every token request**, so one token — and one consent — covers every operation. +- **This grant refreshes**: the SDK keeps the `refresh_token` the server issues and renews silently; when the refresh fails the full grant runs again. +- On `401`, the rejected token is dropped, a new one is obtained and the failing request is **re-sent once** — under every retry setting, including `RetryOptions.Disabled()`; a second `401` is returned to you. A request whose body cannot be re-sent (a binary or file upload) is not re-sent, but its `401` still drops the cached token, so the next call recovers. For the authorization-code grant the refresh token is tried first, so the re-send is silent unless the refresh itself fails — then `PromptForAuthorizationCode` fires inside the call. **Plan for that in a non-interactive host** — a background worker will block on a prompt nobody can answer. +- After a `401` clears the cache, a token fetch already in flight can still re-populate it, so the next call is not guaranteed a newly fetched token. -⚠ **If the token response omits `expires_in`, the token never expires as far as the SDK is concerned.** `expires_in` is RECOMMENDED but not required by RFC 6749, and the SDK's expiry check short-circuits to "not expired" when it is absent — so the first token is cached for the life of the client and the only thing that ever replaces it is a `401`. That is usually fine and occasionally not: a token revoked server-side keeps being sent until a request fails with it. If your provider omits `expires_in` and you need proactive rotation, supply your own token strategy (below) rather than trying to bound the cache. +Setting `Scope` on the credentials replaces the per-scheme behaviour above with one token requested with that value; an empty `Scope` requests none. Set it to the scopes your client is registered for when the API declares more than it grants you: the default asks for the whole catalogue, and an authorization server that enforces per-client scope registration answers `invalid_scope` to that request. -### Supplying your own token source +⚠ **If the token response omits `expires_in`, the SDK treats the token as never expiring**: it is cached for the client's lifetime and replaced only after a `401`, so a token revoked server-side keeps being sent until a request fails with it — a failure the one re-send above recovers, at the cost of a round trip. -The token strategy is a public extension point: `SlackWebApiClientOptions` exposes a strategy property beside each credentials property, and the generated client falls back to the built-in strategy only when you leave it null. The strategy is used only when the credentials property beside it is also set, and `GetToken` receives that object. +## Environment variables -| Grant | Strategy property on `SlackWebApiClientOptions` | Type | -| --- | --- | --- | -| Authorization code | `SlackAuthTokenStrategy` | `IOAuth2RefreshableTokenStrategy` | - -```csharp -options.SlackAuth = new OAuth2AuthorizationCodeCredentials { /* its required members */ }; -options.SlackAuthTokenStrategy = new MyTokenStrategy(); // Task GetToken(creds, ct) - // Task TryRefreshToken(creds, refreshToken, ct) -``` - -Reach for it when the token must come from somewhere other than the SDK's own call to the token endpoint — a shared cache across processes, a secrets broker, a sidecar that already holds a valid token, or a test double. The per-client in-memory cache above still wraps whatever you return. +`options.SlackAuth` has no environment default. ## ⚠ Missing credentials must stop the app from starting -⚠ **Configure nothing and the request goes out unauthenticated — no exception.** An unset credentials property on `SlackWebApiClientOptions` yields a no-op scheme, not an error, so the call reaches the provider with no credential and comes back `401`. The SDK will never tell you that you forgot to supply one; only the provider will, one round-trip later and one layer away from the cause. - -**A required credential that is not configured is a deployment fault, not a request fault.** If the app boots with a blank secret, an operator sees a provider outage, retry logic hammers a call that can never succeed, and the actual cause — an unset environment variable — is two layers away from the symptom. +⚠ **Configure nothing and the first call that needs the credential throws.** A credentials property on `SlackWebApiClientOptions` that nothing fills fails the call with `AuthSchemeException` before anything is sent, naming the scheme. That is a request-time failure for a deployment fault: catch it at startup instead. **Validate at startup and refuse to boot.** Bind the credentials into your own options type and make the host check it before the app serves anything: diff --git a/plugins/slack/skills/dotnet/dotnet-calling-endpoints/SKILL.md b/plugins/slack/skills/dotnet/dotnet-calling-endpoints/SKILL.md index fb0db712..866cee13 100644 --- a/plugins/slack/skills/dotnet/dotnet-calling-endpoints/SKILL.md +++ b/plugins/slack/skills/dotnet/dotnet-calling-endpoints/SKILL.md @@ -1,6 +1,6 @@ --- name: dotnet-calling-endpoints -description: Calling operations on an APIMatic-generated .NET SDK in C# — finding the controller that owns an operation, required vs optional parameters, request and response envelope shapes, async usage, and cancellation. Load before writing the first call to an SDK operation, or when an operation's shape or return type is unclear. +description: Load before writing the first call to an operation on an APIMatic .NET SDK in C#, or when an operation's input or return type is unclear — finding the controller that owns an operation, the per-operation request record, the requestOptions and cancellationToken arguments, response shapes and cancellation. --- # Calling endpoints on an APIMatic .NET SDK @@ -16,7 +16,8 @@ names follow no fixed verb/resource pattern, so take the real name from the shee ## Method signature convention -Every endpoint method is `async` (returns a `Task`) and takes at most three parameters, in a fixed order: +Every endpoint method is `async` (returns a `Task`; there are no sync overloads) and takes at most three +parameters, in a fixed order: ```csharp public Task<{ReturnType}> {Operation}( @@ -44,13 +45,7 @@ public Task<{ReturnType}> {Operation}( positional call that skips it puts your `CancellationToken` where a `RequestOptions?` is expected, and the call fails to compile with `CS1503: Argument N: cannot convert from 'System.Threading.CancellationToken' to '{RootNamespace}.Core.RequestOptions?'`. Pass `cancellationToken:` by name and the problem cannot arise. -- **The contract sheet is the source of truth for the record.** Which members are `required`, which are - nullable, which carry a default — and whether there is a `Body` — varies per operation. Take each - operation's record from the contract sheet (grounded from the SDK map/source), not from memory. - **Return type** varies by operation — see [Reading the response](#making-the-call-and-reading-the-response). -- Methods are **async-only** (no sync overloads) and **throw `ApiException`** on API errors — one leaf - of the SDK's `SdkException` family, which also covers connection failures and timeouts — see - `dotnet-error-handling`. ## Building the request record @@ -59,10 +54,10 @@ what you owe it: | Property | Meaning | You | |---|---|---| -| `public required T X { get; init; }` | required, no spec default | **must** set it — the compiler enforces this | -| `public T X { get; init; } = value;` | the spec declares a default | set it only to override; leaving it sends the default | +| `public required T X { get; init; }` | required, no default | **must** set it — the compiler enforces this | +| `public T X { get; init; } = value;` | has a default | set it only to override; leaving it sends the default | | `public T? X { get; init; }` | optional, no default | leave it unset to omit it from the request | -| `public T X { get; } = value;` | the spec fixes the value (`const`) | cannot set it — it is sent as declared | +| `public T X { get; } = value;` | a fixed value (`const`) | cannot set it — it is always sent | ```csharp var response = await client.{ApiGroup}.{Operation}( @@ -79,34 +74,25 @@ var response = await client.{ApiGroup}.{Operation}( - **Property names are PascalCase C# names, not wire names.** `per_page` on the wire is `PerPage` on the record. The wire keys appear only inside the generated method body, as `new Param("per_page", request.PerPage)` — read names off the record, never off that list. -- **The record is never serialized**, so it carries no `[JsonPropertyName]`. Its members may carry constraint - attributes (`[Minimum(0)]`, `[MaxLength(256)]`); they document the API's limits and nothing in the SDK - enforces them before the call. +- **The record is never serialized**, so it carries no `[JsonPropertyName]`. Constraint attributes on its + members (`[Minimum(0)]`, `[MaxLength(256)]`) are not enforced — see **dotnet-models**. - **A JSON, plain-text or binary body is always the member `Body`** (`Body_` in the rare API that also has a parameter literally named `body`). A `application/x-www-form-urlencoded` or multipart form has **no** `Body`: each - form field is its own property on the record, and the generator assembles the form itself. + form field is its own property on the record, and the SDK assembles the form itself. ## Files A file is a `BinaryContent`, built with an object initializer that sets all three: a `Stream`, a `FileName` -(may be `null`) and a `ContentType` -(a `MediaTypeHeaderValue`). A `Stream` or `byte[]` also converts to one, typed `application/octet-stream` and -named only for a `FileStream`; the SDK does not apply the spec's media type, so set `ContentType` whenever the spec -declares one, and `FileName` when the API needs a name. The SDK never disposes or rewinds your stream, and never retries a call -that sends a file. +(may be `null`) and a `ContentType` (a `MediaTypeHeaderValue`). A `Stream` or `byte[]` also converts to one, +typed `application/octet-stream` whatever media type the operation documents, and named only for a +`FileStream` — so set `ContentType` whenever the API expects a specific type, and `FileName` when it needs a +name. The SDK never disposes or rewinds your stream, and never retries a call that sends a file. ## Building request models -**A form-bodied operation has no `Body` member.** Where the API declares a -`application/x-www-form-urlencoded` or multipart request, the generator emits the fields as *individual -members of the request record* and assembles the form itself — there is no body model to construct and no -`Body` to set. -In an API built that way this is the majority shape, not an exception. The contract sheet says -which you are looking at; the record settles it. - -For the JSON case: request bodies are immutable `record`s built with object-initializer syntax (no -builders). `required` members must be set; optional ones are nullable and are omitted from the JSON when -left null. The body model is the type of the request record's `Body` member — a different type from the +A JSON request body is an immutable `record` built with object-initializer syntax (no builders). +`required` members must be set; optional ones are nullable and are omitted from the JSON when left null. +The body model is the type of the request record's `Body` member — a different type from the request record itself — so take its exact name from the contract sheet (grounded from the SDK map/source): ```csharp @@ -134,21 +120,14 @@ var body = new {RequestType} ## Enums -Enums are type-safe string- **or int-**enums (`OpenStringEnum` / `OpenIntEnum`), not C# enums — use -the static constants. There is no `FromValue`: a value the spec does not declare cannot be constructed, and -a raw value resolves through `{EnumType}.TryGetKnownValue(value, out var known)`. See **dotnet-models** for -read-back semantics (implicit conversion to the underlying value, `==` / `Is` against raw values, and the -generated `Match`). - -```csharp -SomeProp = {EnumType}.SomeConstant; -SomeProp = {EnumType}.TryGetKnownValue(configured, out var known) ? known : {EnumType}.SomeConstant; -``` +Enums are `OpenStringEnum` / `OpenIntEnum` records, not C# enums: use the static constants +(`{EnumType}.SomeConstant`). There is no `FromValue`; resolve a raw value with +`{EnumType}.TryGetKnownValue(value, out var known)`. See **dotnet-models**. ## Union types, collections, and dates Some properties are not plain scalars: polymorphic `OneOf`/`AnyOf` unions (built with **factory methods**, -not object-initializers, and read via `TryGet…`), `IReadOnlyList`/`IReadOnlyDictionary` collections, and +not object-initializers, and read via `TryGet…` or `Match`), `IReadOnlyList`/`IReadOnlyDictionary` collections, and `DateTimeOffset` dates. If a request property or response field is one of these, see **dotnet-models** for how to construct and read it. @@ -189,20 +168,12 @@ contract sheet's response-envelope column names the return type and the inner fi bounds the read, and a drop while you read throws a raw `IOException` from your read, not `SdkConnectionException`. -Endpoints in the same family can differ — one nests the resource, another returns it directly — so let each -method's return type guide how you read it. - -An operation may also expose an optional **`{Operation}Result`** sibling that returns -`ApiResult` — the outcome (the response, or a typed/`RawError` error) instead of -throwing, with the HTTP status and headers available on both. It's optionally generated, so it may not -exist. See **dotnet-error-handling**. +A non-throwing **`{Operation}Result`** sibling may exist — see **dotnet-error-handling**. ## Cancellation -Every operation takes a `CancellationToken` as its last argument, passed as `cancellationToken:`, with -`RequestOptions? requestOptions = null` immediately before it — so the token is last, never second-to-last. To bound an individual call with a -timeout, use the per-request cancellation pattern in **dotnet-configuration-resilience** (it owns -timeouts). +Pass the token as `cancellationToken:` (see the signature above). To bound a call with a timeout, see +**dotnet-configuration-resilience** § *Bounding a call*. ## Worked example — a list/GET call @@ -223,7 +194,7 @@ var results = await client.{ApiGroup}.{Operation}( Filter = {EnumType}.SomeConstant, Q = "search text", PerPage = 20 // literal must match the member's type — a `20d` against an `int` is CS0266 - }, // StartDate is left unset and omitted; Page keeps the spec default + }, // StartDate is left unset and omitted; Page keeps its default cancellationToken: ct); foreach (var item in results) diff --git a/plugins/slack/skills/dotnet/dotnet-client-initialization/SKILL.md b/plugins/slack/skills/dotnet/dotnet-client-initialization/SKILL.md index 948c68eb..494ded7a 100644 --- a/plugins/slack/skills/dotnet/dotnet-client-initialization/SKILL.md +++ b/plugins/slack/skills/dotnet/dotnet-client-initialization/SKILL.md @@ -1,6 +1,6 @@ --- name: dotnet-client-initialization -description: Creating and registering an APIMatic-generated .NET SDK client in C# — construction, the builder/options shape, HttpClient ownership and lifetime, and dependency-injection registration in ASP.NET Core. Load before wiring the client into an application's service container or writing the factory that builds it. +description: Load before constructing an APIMatic .NET SDK client in C#, registering it in a service container, or writing the factory that builds it — the client options class, HttpClient ownership and lifetime, dependency-injection registration in ASP.NET Core, and inbound webhooks. --- # Initializing an APIMatic .NET SDK client @@ -22,12 +22,9 @@ object: public {Api}Client(HttpClient httpClient, {Api}ClientOptions options) ``` -Operations are exposed on the client. Most are grouped under **controller properties** (one per API resource -group) and called `client.{ApiGroup}.{Operation}(...)` — for example, a `Widgets` controller's -`ListWidgets` operation is `client.Widgets.ListWidgets(new ListWidgetsRequest { ... })`. An operation that belongs to no group sits -**directly on the client**, called `client.{Operation}(...)`. The available controller properties (and any -direct operations) come from the contract sheet (grounded from the SDK map/source), -not a decompiled or reflected view of the installed package. See `dotnet-calling-endpoints`. +Operations hang off **controller properties** (`client.{ApiGroup}.{Operation}(...)`) or sit directly on the +client (`client.{Operation}(...)`). Take them from the contract sheet (grounded from the SDK map/source), not +a decompiled or reflected view of the installed package — see `dotnet-calling-endpoints`. The options class always carries these knobs (auth properties vary per API — see `dotnet-authentication`): @@ -41,19 +38,16 @@ public class {Api}ClientOptions public ServerOptions Server { get; set; } = new(); public IReadOnlyList Hooks { get; set; } = []; // request/response observation — // see dotnet-configuration-resilience § Hooks - // + one nullable credentials property per auth scheme the API declares, and — for an OAuth2 - // scheme — a nullable {Scheme}TokenStrategy hook alongside it (see dotnet-authentication) + // + one nullable credentials property per auth scheme the API declares, and — for a static + // scheme — a nullable {Scheme}Provider delegate asked on every request (see dotnet-authentication) } ``` -`Logging` is a real property, not a placeholder — the SDK has a **built-in** request/response logger, and -what an unset `Logging.LoggerFactory` means depends on how the client is built. Under `Add{Api}Client` the -extension fills it from the container's `ILoggerFactory`, so logging is **already on** at your host's level. -On a client you construct yourself it falls through to a `{APICLIENTTYPENAME}_LOG` environment variable that -can switch logging — including unredacted JSON request bodies — on from outside your code. Set it -explicitly either way; **dotnet-configuration-resilience** has the full table. Tuning these knobs — `Retry` (retries, backoff, per-attempt timeout), `Logging`, and -`Server` / `Environment` (server selection and **overriding the base URL**), plus pagination — is covered in -**dotnet-configuration-resilience**. +`Logging` is a **built-in** request/response logger: under `Add{Api}Client` it is **already on**; on a client +you construct yourself a `{API}_LOG` environment variable — `{API}` being the SDK name in upper snake case — can +turn it on, unredacted JSON bodies included. Set `Logging.LoggerFactory` explicitly either way. +**dotnet-configuration-resilience** covers +`Retry`, `Logging`, `Server` / `Environment` (including **overriding the base URL**) and pagination. ## Direct instantiation @@ -64,7 +58,8 @@ using {RootNamespace}.Servers; var options = new {Api}ClientOptions { Environment = ServerEnvironment.Default(), // pick the environment your API exposes - // ...set the auth credentials property your API uses (see dotnet-authentication) + // ...set the auth credentials property your API uses, or leave it null and set its + // {API}_* environment variable instead (see dotnet-authentication) }; var httpClient = new HttpClient(); // reuse a single long-lived instance @@ -77,32 +72,19 @@ The SDK does **not** own the `HttpClient` — you provide it. Reuse one instance (or use `IHttpClientFactory`); do not create one per request. Attach custom `HttpMessageHandler`s here for logging, proxies, or custom TLS (see `dotnet-configuration-resilience`). -**Keep both the `HttpClient` and the SDK client long-lived — the client is not a stateless wrapper.** The -only thing you hand it is the HTTP pipeline; its constructor builds the rest and then owns it: - -- the **resilience pipelines** — two Polly pipelines are eagerly built from `options.Retry`; -- the **logger** — constructed here, which is also where the `{APICLIENTTYPENAME}_LOG` environment variable - is read; -- the **auth schemes**, and for an OAuth2 SDK the auth scheme *is* the access-token cache — an instance - field on the scheme object. - -That last one is the reason a per-request client is a real cost rather than a stylistic one: a fresh client -starts with an empty token cache, so **every resolution pays a token request on its first call**. Three -calls through three transient clients is three token round-trips where a shared client makes one. - -Reuse one `HttpClient` (or let `IHttpClientFactory` own it) *and* one SDK client for the app's lifetime. -Construct per request only where you genuinely need different credentials per request — and then expect the -token fetch. +**Keep the SDK client long-lived too.** Its constructor builds and owns the retry pipelines (from +`options.Retry`), the logger (reading `{API}_LOG`) and the auth schemes — for OAuth2 the scheme +holds the access-token cache, so a fresh client starts with an empty cache and **pays a token request on its +first call**. Reuse one SDK client for the app's lifetime; construct per request only where credentials +genuinely differ per request, and expect the token fetch. ## Choosing the server / base URL -Environments are modeled as a `ServerEnvironment` string-enum with one constant per environment the API -defines (e.g. `ServerEnvironment.Production`, or region constants). Select one on `options.Environment`. -Overriding a templated parameter or the base URL is nested **per server AND per environment** — -`options.Server.{ServerName}.{Environment}.BaseUrl` (with any templated params at the same level), NOT -directly on `ServerOptions`. **dotnet-configuration-resilience** documents this in full and owns -server / base-URL configuration. The exact constants and template parameters for your API come from the -contract sheet (grounded from the SDK map/source). +Select the environment with `options.Environment = ServerEnvironment.{Environment}` — one constant per +environment (e.g. `ServerEnvironment.Production`, or region constants). Base-URL and templated-parameter +overrides live at `options.Server.{ServerName}.{Environment}`, NOT directly on `ServerOptions` — see +**dotnet-configuration-resilience**. The constants and template parameters come from the contract sheet +(grounded from the SDK map/source). ## Dependency injection (ASP.NET Core / generic host) @@ -122,18 +104,13 @@ builder.Services.Add{Api}Client(options => }); ``` -⚠ **The extension registers the client as a `singleton`, and that has a consequence worth planning for.** -A singleton calls `CreateClient()` *once* and holds that `HttpClient` for the process lifetime, so -`IHttpClientFactory`'s handler rotation never applies to it and a DNS change is cached indefinitely — the -classic symptom is an app that keeps calling a decommissioned IP after a provider fails over, and only a -restart fixes it. (A transient registration avoids *this* problem — each resolution takes a fresh `HttpClient` and the -pooled pipeline stays rotated — but it buys stale-DNS safety with a fresh, empty OAuth token cache per -resolution, so it is a trade, not a fix. See the lifetime note above.) - -The actual fix is cheap: set `PooledConnectionLifetime` on the primary handler so the pool recycles -connections on a timer, and keep the SDK client long-lived. Registering yourself over a named `HttpClient` -(below) gives you the same control plus an unshared pipeline. Confirm the registration in the extension rather than trusting this paragraph if your SDK was -generated by a different version — it is one line, and the contract sheet carries it. +⚠ **The extension registers the client as a `singleton`.** It calls `CreateClient()` *once* and holds that +`HttpClient` for the process lifetime, so `IHttpClientFactory`'s handler rotation never applies to it and a +DNS change is never picked up — the app keeps calling a decommissioned IP after a provider fails over, until +a restart. A transient registration avoids stale DNS but pays a fresh, empty OAuth token cache per +resolution (see the lifetime note above). The fix: set `PooledConnectionLifetime` on the primary handler so +the pool recycles connections on a timer, and keep the SDK client long-lived. Registering yourself over a +named `HttpClient` (below) gives you the same control plus an unshared pipeline. To attach custom `DelegatingHandler`s (logging, proxies, custom TLS) under this DI registration, configure the **default, unnamed** factory client it resolves — e.g. @@ -145,10 +122,8 @@ yourself over a **named** `HttpClient` — the same shape the extension uses, mi ### Registering over a named `HttpClient` -The full shape. **`Timeout` is not optional to think about** — the default is `100s`, which matches the SDK's -own per-attempt retry timeout. On defaults a hung provider costs you ~100s on a `POST` and **~407s on a -`GET`**, because the SDK's per-attempt timeout is itself a retry trigger on the retryable verbs (see -**dotnet-configuration-resilience**). Either number is an outage, not a timeout: +The full shape. **Set `Timeout`**: the default `100s` bounds one attempt, and a hung provider costs ~100s on +a `POST` and ~407s on a `GET` (see **dotnet-configuration-resilience** § *Bounding a call*): ```csharp using {RootNamespace}; @@ -175,10 +150,8 @@ services.AddSingleton(sp => }); ``` -Both knobs above are load-bearing and they answer different failures: `PooledConnectionLifetime` keeps DNS -fresh behind a long-lived client, and `Timeout` stops a hung provider from holding a request, a pooled connection and the caller open (~100s, -and ~407s on a retryable verb — see **dotnet-configuration-resilience**). Setting -only the first is the common mistake — it looks like the resilience box is ticked. +`PooledConnectionLifetime` keeps DNS fresh behind a long-lived client; `Timeout` stops a hung provider holding +the request. Set both. Then inject it: @@ -191,30 +164,19 @@ public sealed class MyService({Api}Client client) ## Inbound webhooks — what `Core/Webhooks/` does and does not give you -Every emitted SDK ships a `Core/Webhooks/` tree: `WebhookRequest`, `WebhookEvent<…>`, -`WebhookEventParser<…>`, and a `Signing/` folder holding `SignatureVerifier`. Three facts about it, verified -on both sampled 4.0.0 SDKs, decide whether any of it is usable: - -- **`SignatureVerifier` is `internal sealed`, with no `InternalsVisibleTo`.** You cannot call it, construct - it, or subclass it from your code. It is fully implemented — HMAC, digest encodings, replay tolerance — - and on both samples it has **zero callers**. -- **`WebhookEventParser.Parse` verifies nothing.** It parses the body with `JsonDocument.Parse`, - checks the root is a JSON object, and hands off to an abstract `CreateEvent`. The name reads like a - security boundary; it is a deserializer. -- **`WebhookEventParser` and `WebhookEvent` are `public abstract`, and neither sampled SDK generates a - concrete subclass**, because neither spec declares webhook events. The public machinery has nothing to - instantiate — a base class waiting on generated code that was never emitted. - -So on an SDK with no generated events, signature verification is yours to write, against the provider's -published scheme. `WebhookRequest` remains useful on its own — `FromStream`, `FromBytes`, `TryGetHeader` -give you a body-and-headers holder to verify against — but it computes nothing for you. - -> **Not settled by either sample.** Whether a spec that *does* declare webhook events generates a concrete -> parser, and whether that generated parser calls the internal `SignatureVerifier`, is unknown here — no -> sampled SDK exercises it. An `internal` verifier is exactly what you would expect if generated code is -> its intended caller, so do not read "verification happens outside the SDK" as a property of the -> generator. It is what is true when no events were generated. Look for a `WebhookEvent` subclass in the -> emitted tree before assuming either way. +Every SDK ships `Core/Webhooks/`: `WebhookRequest` (`FromStream`, `FromBytes`, `TryGetHeader` — a +body-and-headers holder) and the `public abstract` `WebhookEventParser` and `WebhookEvent<…>`. +**`WebhookEventParser.Parse` verifies nothing** — it checks the body is a JSON object and builds the +event; it is a deserializer, not a security boundary. + +If the SDK has a `{RootNamespace}.Webhooks` namespace, it holds a concrete `{Api}WebhookParser`, registered +by `services.Add{Api}Webhooks()`. If that namespace also holds a public `{Api}WebhookSignatureVerifier`, +verify with its `bool Verify(WebhookRequest)` before you parse: it is built from `WebhookOptions` (`Secret`, +`TimeProvider`, and `ReplayTolerance` where present) and registered by +`services.Add{Api}WebhookSignatureVerifier(o => o.Secret = ...)`; its constructor throws +`InvalidOperationException` on a blank `Secret`. Without that class, verification is yours to write against +the provider's published scheme — `Core/Webhooks/Signing/SignatureVerifier` is `internal` and cannot be +called from your code. ## Next diff --git a/plugins/slack/skills/dotnet/dotnet-configuration-resilience/SKILL.md b/plugins/slack/skills/dotnet/dotnet-configuration-resilience/SKILL.md index 8d1c807a..e1e44431 100644 --- a/plugins/slack/skills/dotnet/dotnet-configuration-resilience/SKILL.md +++ b/plugins/slack/skills/dotnet/dotnet-configuration-resilience/SKILL.md @@ -1,20 +1,17 @@ --- name: dotnet-configuration-resilience -description: Client configuration and resilience for an APIMatic-generated .NET SDK in C# — retries and backoff, timeouts and cancellation, base-URL/server selection, list pagination, SSE streaming, and request/response logging. Load before you register or tune the client — the option names alone do not reveal which calls retry, what a timeout actually bounds, or what you must still set yourself. +description: Load before registering or tuning an APIMatic .NET SDK client in C# — retries and backoff, timeouts and cancellation, base-URL/server selection, list pagination, SSE streaming, request/response logging and hooks. Load it even when the option names look obvious; they don't show which calls retry or what a timeout bounds. --- # Configuration & resilience for an APIMatic .NET SDK -> **One skill, every shape.** This file covers every configuration surface the 4.0.0 generator -> emits. Which parts YOUR SDK exercises — which pagination strategy an operation gets, whether any -> operation declares an idempotency-key parameter, which server variables exist — are facts of the -> API definition, not of this skill: take them from the contract sheet or the map, and **apply -> only the guidance that matches**. +> **One skill, every shape.** This file covers every configuration surface the SDK can have. Which +> ones YOUR SDK uses — the pagination strategy of each operation, any idempotency-key parameters, the +> server variables — is in the contract sheet or the map: **apply only the guidance that matches**. Most types below live under `{RootNamespace}.Core.Configuration` and `{RootNamespace}.Servers`; the exception family (`SdkException` and its leaves — see **dotnet-error-handling**) sits under `.Core.Exceptions` and the per-call `RequestOptions` under `.Core`. Each section names its own namespace. -All of them are generic across APIMatic .NET SDKs built by this generator. ## ServerOptions configuration for each Environment @@ -61,7 +58,7 @@ client to change environment. | Setting | Default | | --- | --- | | `StatusCodesToRetry` | `408, 429, 500, 502, 503, 504` | -| `HttpMethodsToRetry` | `GET, HEAD, PUT, OPTIONS` (idempotent only — gates **every** retry trigger, see notes) | +| `HttpMethodsToRetry` | `GET, HEAD, PUT, OPTIONS` — gates every transient retry trigger, not the OAuth2 `401` re-send (Notes) | | `MaxRetries` | `3` | | `Delay` | `1s` | | `BackOffFactor` | `2` | @@ -70,23 +67,12 @@ client to change environment. | `Timeout` | `100s` (**per attempt**) — **too long for any interactive path; set it explicitly** | | `OnRetry` | `null` | -**Do the arithmetic on those defaults before you accept them.** `MaxRetries = 3` means up to 4 attempts, each -bounded at `100s`, with `1s + 2s + 4s` of backoff between them. What that costs depends on the **verb**, because -`HttpMethodsToRetry` gates *every* retry trigger — including the per-attempt timeout firing (see Notes): - -| Provider behaviour | On a retryable verb (`GET`/`HEAD`/`PUT`/`OPTIONS`) | On any other verb | -| --- | --- | --- | -| **Hangs** (no response at all) | up to **4 × 100s + 7s ≈ 407s** — the per-attempt timeout fires and the rejection **is** retried | ≤ **100s** — one attempt, then the call ends | -| **Fails retryably** (a `503`, a connection reset) | up to **≈ 407s** — each attempt can burn nearly the full timeout | ≤ **100s** — one attempt at the provider's own latency; never resent | - -So the worst case on a `GET` is ≈**7 minutes** on the defaults — almost all of it per-attempt `Timeout`, -not backoff — and up to ≈**9.7 minutes** -(`4 × 100s + 3 × 60s`) against a provider that answers every attempt with a large `Retry-After`, since that -header replaces the backoff and clamps at 60s (see Notes). Either way it is nowhere near the ≈100s the -`Timeout` value suggests. The SDK's send path is fully async, so no thread is blocked — but the request, a -pooled connection and the caller's browser are all held open for that whole window. Treat every default in -this table as a value you have chosen only once you have written it down; `Timeout` in particular has no -defensible default for a request-path call. +**Worst case on the defaults:** up to 4 attempts × `100s` + `1s + 2s + 4s` of backoff ≈ **407s** on a +retryable verb (`GET`/`HEAD`/`PUT`/`OPTIONS`) — whether the provider hangs (the per-attempt timeout is itself +retried) or fails retryably — and up to ≈ **9.7 minutes** (`4 × 100s + 3 × 60s`) if every attempt returns a +large `Retry-After`. Any other verb gets one attempt, ≤ **100s** — two when an OAuth2 `401` is re-sent +(Notes). The request, a pooled connection and your caller are held open for that whole window, so choose +every value in this table deliberately; `Timeout` has no safe default for a request-path call. Customize — always by `with` on `Default()`: every `RetryOptions` member is `required`, so a partial `new RetryOptions { MaxRetries = 5 }` does not compile: @@ -107,80 +93,55 @@ Notes: - The *n*th retry waits `Delay * BackOffFactor^(n-1) + random(0, MaxJitter)` — so the 1st retry waits `Delay` (1s), the 2nd `Delay * BackOffFactor` (2s), and so on. Set `UseExponentialBackoff = false` for a constant `Delay` between attempts. -- **`HttpMethodsToRetry` gates every trigger, not just the status one.** `ShouldHandle` reads - `method is in HttpMethodsToRetry && (transport fault || status is in StatusCodesToRetry)` — the method check - is a top-level `&&` sitting above *both* arms. So with the defaults a `POST`/`PATCH`/`DELETE` is **never** - resent by the SDK: not on a `503`, not on a connection reset, not on a timeout. This is the control that - keeps a non-idempotent write from executing twice, and it is on by default. Adding a verb to - `HttpMethodsToRetry` removes that protection for **every** operation that uses the verb, not just the one - you had in mind — read *Making a write safe under retries* below before you do. -- **Three things trigger a retry on an eligible verb**, and one of them is easy to miss: - `HttpRequestException` (connection reset, DNS failure, dropped socket); `TimeoutRejectedException` — the - SDK's **own per-attempt `Timeout` firing**; and a response whose status is in `StatusCodesToRetry`. Because - the per-attempt timeout is itself a retry trigger, a hung provider on a `GET` costs the *whole* budget - (4 × `Timeout` + backoff), not one `Timeout`. A `TaskCanceledException` — from your own - `CancellationToken`, or from `HttpClient.Timeout` — is **not** in the set and ends the call where it fires. -- **You never catch `TimeoutRejectedException` or the raw `HttpRequestException`.** Polly classifies the - raw exceptions *inside* the pipeline, so retry behaviour is exactly as described above; what leaves the - pipeline is wrapped once, by cause. An exhausted per-attempt `Timeout` reaches your `catch` as - `SdkTimeoutException` — message `"GET https://host/path received no response within 100 s."`, - `Timeout` the window that elapsed, the Polly rejection as `InnerException`. A connection reset, DNS - failure or dropped socket reaches you as `SdkConnectionException` — `"{call} could not be sent: …"` with - the `HttpRequestException` as `InnerException`. Both derive from `SdkException`, so the call's `Method` - and `RequestUri` are on the exception. Your **own** cancellation is the one thing that is never wrapped: - it surfaces as the usual `OperationCanceledException` / `TaskCanceledException`, so the *type* now tells - the SDK's timeout and your cancellation apart — no inner-exception sniffing needed. +- **`HttpMethodsToRetry` gates every transient trigger** — status, transport fault and timeout alike. With + the defaults a `POST`/`PATCH`/`DELETE` is **never** resent on any of them: not on a `503`, not on a + connection reset, not on a timeout — which keeps a non-idempotent write from executing twice. The one + exception is the OAuth2 `401` re-send in the next note, which this list does not gate. Adding a verb removes + that protection for **every** operation using it — read *Making a write safe under retries* below first. +- **An OAuth2 `401` is re-sent once, on any verb.** A call authenticated by an OAuth2 scheme (alone or in an + AND/OR group) that gets a `401` drops the cached token, fetches a new one and is re-sent once — whatever + `HttpMethodsToRetry`, `MaxRetries` or `RetryOptions.Disabled()` say. A request whose body cannot be + replayed (a binary body, a multipart form with a binary part) is not re-sent: its `401` reaches you, and + the next call fetches a fresh token. A static credential's `401` is never re-sent. +- **On an eligible verb three things trigger a retry:** an `HttpRequestException` (connection reset, DNS + failure, dropped socket), the SDK's **own per-attempt `Timeout` firing**, and a status in + `StatusCodesToRetry`. A `TaskCanceledException` — from your own `CancellationToken`, or from + `HttpClient.Timeout` — is **not** retried and ends the call where it fires. +- **What reaches your `catch`:** an exhausted per-attempt `Timeout` as `SdkTimeoutException` (`Timeout` is + the window that elapsed), a connection reset, DNS failure or dropped socket as `SdkConnectionException`; + the raw exception is the `InnerException`, never what you catch. Your own cancellation surfaces unwrapped, + as `OperationCanceledException` / `TaskCanceledException`. See **dotnet-error-handling** for the family + and its messages. - **`Retry-After` overrides the computed backoff.** If the failing response carries a `Retry-After` header (delta-seconds or an HTTP date) that value is used as the delay instead of `Delay × BackOffFactor^n + jitter`. Both paths are then clamped to a hard **60s** ceiling that is not configurable — a provider asking for a 10-minute pause gets 60s, and a large `BackOffFactor` cannot push a single delay past a minute. -- **Multipart is not blanket-excluded.** Retry eligibility is decided per request type *before* the - pipeline runs: a binary-body request with its payload **present** never retries (with the optional - payload absent it is an empty send and stays eligible); a multipart/form-data request retries - **unless it carries a binary part**; JSON, form-url-encoded and empty-body requests are eligible. - An ineligible request is **not** left unprotected — it runs on a *timeout-only* pipeline built - from the same `RetryOptions`, so it keeps the per-attempt `Timeout` and loses only the retry - strategy. -- `Timeout` is **per attempt**, not total — to cap a whole call, use a `CancellationToken` (below). It is - nullable: set `Timeout = null` to disable the per-attempt timeout entirely. +- **Some requests never retry:** one whose binary body is present, or a multipart form with a binary part. + They still get the per-attempt `Timeout`. JSON, form-url-encoded, other multipart and empty-body requests + follow the verb rule. +- `Timeout` is nullable: `null` disables the per-attempt timeout. To cap a whole call, use a + `CancellationToken` (*Bounding a call* below). - `OnRetry`'s `RetryAttempt` also carries `Reason` — `RetryReason.Status(HttpStatusCode)` or - `RetryReason.Failure(Exception)` — log it to record *why* each retry fired. - -⚠▶▶ **A per-attempt timeout does not bound a REQUEST.** If one handler makes more than one SDK call — -a loop over recipients or invoices, a fan-out, a send-then-schedule pair — the per-call timeouts **add up**, and -they add up *faster* when each failure is caught so the work can continue: every swallowed timeout -costs its full bound and the next call still runs. Two calls at 30s is a 60s request; three is 90s. -Put one deadline on the whole handler and pass its token to every call inside it: - -```csharp -using var cts = CancellationTokenSource.CreateLinkedTokenSource(ct); -cts.CancelAfter(TimeSpan.FromSeconds(20)); // the REQUEST's budget, not one call's -var deadline = cts.Token; -// pass `deadline` — not `ct` — to every SDK call in this handler -``` - -**The check, and it is arithmetic, not judgement:** `calls in this handler × per-call timeout` must -sit under the budget you are willing to make a caller wait. If it does not, the per-call timeout is -not a bound on anything the caller can perceive. Count the calls in the loop, not the calls in the -snippet — a handler that processes every record on file makes as many calls as there are -records. + `RetryReason.Failure(Exception)` — log it to record *why* each retry fired. The per-attempt `Timeout` + firing arrives as `RetryReason.Failure(TimeoutRejectedException)` and a dropped connection as + `RetryReason.Failure(HttpRequestException)`, so switch on the exception type to tell them apart. ### Making a write safe under retries -**Start from what the defaults already give you.** `HttpMethodsToRetry` gates every trigger (see Notes), so -out of the box the SDK never resends a `POST`, `PATCH` or `DELETE` — on any trigger. Two gaps remain: +**Start from what the defaults already give you:** the SDK never resends a `POST`, `PATCH` or `DELETE` on a +transient failure (see Notes). Three gaps remain: -- **`PUT` *is* in the default list.** HTTP calls `PUT` idempotent; your provider's `PUT` may still carry a - per-call side effect — an audit row, an outbound webhook, a metered charge — that a resend duplicates. -- **"The SDK did not resend it" is not "the write did not happen."** A transport failure on a `POST` leaves - the outcome *unknown*: the bytes may have reached the provider before the socket died. That is a - reconciliation problem, and no retry setting solves it. +- **An OAuth2 `401` is re-sent on every verb.** That write reaches the provider twice. A `401` usually means + the provider did nothing, but a guard or a test that counts sends sees two. +- **`PUT` *is* in the default list.** Your provider's `PUT` may still carry a per-call side effect — an audit + row, an outbound webhook, a metered charge — that a resend duplicates. +- **"The SDK did not resend it" is not "the write did not happen."** A transport failure on a write leaves + the outcome *unknown*: the bytes may have reached the provider before the socket died. No retry setting + solves that — see *A write whose outcome is unknown*. -**Retries can be turned off.** `RetryOptions.Disabled()` is `Default() with { MaxRetries = 0 }`, and the -factory skips the retry strategy outright when `MaxRetries <= 0` rather than handing `0` to Polly — so there -is no `MaxRetryAttempts >= 1` validation error and no `MaxRetries = 1` floor. `Disabled()` keeps the -per-attempt `Timeout`; only the retries go. The pipeline is built once in the client constructor, so this is a +**Retries can be turned off per client.** `RetryOptions.Disabled()` is `Default() with { MaxRetries = 0 }`; +it keeps the per-attempt `Timeout`. The pipeline is built in the client constructor, so this is a per-**client** choice, not a per-call one. **Decide which requirement you are meeting before you pick a remedy — they are not interchangeable:** @@ -189,66 +150,37 @@ per-**client** choice, not a per-call one. anything counts sends — a side effect the provider records per call, an audit trail, a test asserting exactly one upstream write — these do not satisfy it, and nothing about the code will look wrong. - *"At most one write may reach the provider"* → option 4. It is the only one that holds the count at one - **regardless of configuration**. Two others hold it at one *today*, each with its own way of quietly - stopping: the default `HttpMethodsToRetry` holds until someone widens the list, and option 3 holds until - someone re-enables retries on that client. Neither failure announces itself. + **regardless of configuration**. Two others hold it at one *today* for transient failures, each with its + own way of quietly stopping: the default `HttpMethodsToRetry` holds until someone widens the list, and + option 3 holds until someone re-enables retries on that client. Neither failure announces itself, and + neither stops the OAuth2 `401` re-send. The four, **weakest guarantee first** — so do not read the numbering as a recommendation order: 1. **Make the write idempotent at the provider** — a client-supplied unique reference or idempotency key, where the API offers one. Makes a resend *harmless* rather than rarer; the send count stays above one. - Look at **every member of the operation's `{Operation}Request` record**, not just its body model. The - generator can put a provider's idempotency key in any of three places, and only one of them is the body: - - - a **header member** — a `string?` property on the record, which the method sends as - `new HeaderParam("...", request.X)`; - - a **form field** — a member the method routes into `FormUrlEncodedRequest.Create(new Param(...))`. - Do not search for a nullable type here: the same key can be declared **`required`** on one - operation and `string?` on the next. Match on the member reaching a - `new Param("...", request.X)` in the form body, not on its nullability; - - a field on the **body model** — the type of the record's `Body` member. - - A body-model-only search finds nothing on the first two and concludes wrongly that the API offers no key. - Ask the contract sheet for the operation's full request record, not just its body shape. - - Note that **whether the provider actually rejects a duplicate value is not visible in the record or the - model**. Such a field is typically just a nullable string, equally consistent with a uniqueness-enforced - key and with a free-text label. Verify against live traffic before relying on it; if it is not enforced, - this gives you nothing. - - ⚠ **An `Idempotency-Key` header on the wire is usually not the provider's key.** The generator puts - one on **every** non-GET operation and on no GET. Its value is almost always `Guid.NewGuid()`, injected - by the generator: not a spec parameter, no doc comment, nothing the caller can reach. The exception is - an operation whose own spec declares `Idempotency-Key` as a parameter, where the generator defers to - the caller's value. - - So the header's *presence* tells you nothing — only the **source of its value** does, and that is visible - in the method body, not the signature: `new HeaderParam("Idempotency-Key", request.X)` sends the - caller's key, `new HeaderParam("Idempotency-Key", Guid.NewGuid())` is injected. Three consequences, all - of which cut against the reading you would naturally take: - - - **An injected key makes nothing safe unless your provider consumes that exact header name.** Most APIs - do not document `Idempotency-Key` as their mechanism, and on those it is inert. - - **The value is fresh per call.** `Guid.NewGuid()` is evaluated at the call site, before the resilience - pipeline runs — so it is stable across the SDK's *internal* retry attempts, and different on every - *caller-level* retry. The resend that a job re-running after a timeout produces is exactly the one it - cannot deduplicate. - - **It can sit alongside the real key, under a near-identical name.** One request can carry both the - injected `Idempotency-Key` *header* and a spec-declared `IdempotencyKey` *form field*; only the second - one means anything. Matching on the name alone picks the wrong one. - - The trap is not that an injected key is useless; it is that it is *visible*. Seeing `Idempotency-Key` go - out on the wire, or in a log, reads as evidence that idempotency is handled. Treat it as absent until you - have confirmed both that the provider consumes that header name and that a record member feeds it — and note - the default `HttpMethodsToRetry` includes `PUT`, so a `PUT` is resent by the SDK itself under a header - that probably means nothing to the provider. + Check **every member of the operation's `{Operation}Request` record**, not just its body model — ask the + contract sheet for the full record. The key can be a **header member** (a `string?` the method sends as + `new HeaderParam("...", request.X)`), a **form field** (a member passed to `new Param("...", request.X)` + in the form body — `required` on one operation and `string?` on the next, so match on the `Param`, not + on nullability), or a field of the **`Body` model**. Whether the provider actually rejects a duplicate + value is not visible in the SDK — such a field is typically just a nullable string; verify it against + live traffic before relying on it. + + ⚠ **Every non-GET call sends an `Idempotency-Key` header.** Unless the method fills it from the record + (`new HeaderParam("Idempotency-Key", request.X)`), its value is `Guid.NewGuid()`: stable across the SDK's + own retries, new on every call you make — so it cannot deduplicate a caller-level retry — and inert + unless the provider documents that header. It can sit beside a real `IdempotencyKey` form field under a + near-identical name; only the record member counts. Seeing the header on the wire or in a log is not + evidence that idempotency is handled: treat it as absent until the provider documents that header name + and a record member feeds it. 2. **Reconcile after a failure** — on a transport failure on a write, re-read provider state to establish what actually happened instead of assuming nothing did. (Same reflex as an unreadable write response — see `dotnet-error-handling`.) Detects a duplicate; does not prevent one. How: see *A write whose outcome is unknown* below. -3. **A separate client for writes**, built with `Retry = RetryOptions.Disabled()`. Removes SDK-side resends - entirely while keeping the per-attempt `Timeout`. Worth doing when you have widened `HttpMethodsToRetry` +3. **A separate client for writes**, built with `Retry = RetryOptions.Disabled()`. Removes the transient + resends while keeping the per-attempt `Timeout`; the OAuth2 `401` re-send stays (Notes). Worth doing when you have widened `HttpMethodsToRetry` for the read path and need the write path held at one send regardless. 4. **A `DelegatingHandler` that refuses a re-send it did not authorise** — the only option that holds the count at one no matter how the client is configured, because a blocked attempt never reaches the @@ -256,24 +188,19 @@ The four, **weakest guarantee first** — so do not read the numbering as a reco duplicate would be externally visible or costly to undo, and combine it with option 2 to settle the outcome of the one send you allowed. - Two details decide whether it works, and both are easy to get wrong: + Two details decide whether it works: - - **Do not keep the "already sent" marker on the `HttpRequestMessage`.** A fresh request object is built - for each attempt, so a marker set via `HttpRequestOptionsKey` is gone by the retry and the guard never - fires — measured: 4 sends, i.e. no protection at all. Keep the count in state that outlives the - request, such as an `AsyncLocal` scope the caller opens around the write; retries run inside the - caller's async context, so the scope flows into the handler on every attempt (measured: 1 send). - - **Do not throw an `HttpRequestException` to refuse**, and do not let the refusal path time out — both - are retry triggers, so the refusal itself becomes retryable. Throw a private sentinel type that derives - from `Exception`; it propagates out unwrapped, and your integration boundary translates it. + - **Keep the "already sent" count in state that outlives the request** — e.g. an `AsyncLocal` scope the + caller opens around the write; retries run inside the caller's async context, so the scope reaches the + handler on every attempt. Each attempt builds a fresh `HttpRequestMessage`, so a marker set via + `HttpRequestOptionsKey` is gone by the retry and the guard never fires. + - **Refuse by throwing a private type derived from `Exception`**, not `HttpRequestException`, and don't + let the refusal time out — both are retry triggers. The private type propagates unwrapped; your + integration boundary translates it. Count the send *before* it goes out. A request that failed on the way out may still have been received, - so "this may already have taken effect" is the only safe reading — surface it as an **unknown outcome** - to be settled by re-reading provider state (option 2), not as a definite failure. - -`HttpMethodsToRetry` **is** the primary control here — it gates every trigger, and keeping non-idempotent -verbs out of it is most of the job. The options above cover what it cannot: a `PUT` with side effects, a list -you have widened, and the unknown outcome a transport failure leaves behind. + so surface it as an **unknown outcome** settled by re-reading provider state (option 2), not as a + definite failure. **All four bound the call YOU make to the provider. None of them is a reason to change the contract your own callers see.** Taking an idempotency key from your callers can be a deliberate API design; @@ -345,23 +272,16 @@ There are three places a bound can live, and **two of the three are per-attempt* Both per-attempt timeouts stop when the response headers arrive; reading the body after that is bounded only by your `CancellationToken` (on an event stream, also by `StreamReadTimeout`, below). -**`HttpClient.Timeout` is applied per attempt here, which is not obvious.** It is enforced by a CTS created -inside each `SendAsync`, and the retry pipeline sits *above* `SendAsync` — so every retry gets a fresh full -`Timeout`. - -**Two per-attempt timeouts, and on a retryable verb only one of them ends the call.** -`options.Retry.Timeout` expiring raises `TimeoutRejectedException` *inside* the pipeline, which *is* in the retry set — on an eligible verb the -attempt is retried and the cost multiplies (that is the ≈407s row above); only once the retries run out does -the SDK convert it to the `SdkTimeoutException` you catch. `HttpClient.Timeout` expiring raises -`TaskCanceledException` inside the pipeline, which is *not* in the set — so it ends the call the first time -it fires, on any verb — and the SDK converts that too, into the **same** `SdkTimeoutException` (with -`Timeout = HttpClient.Timeout`), so a caller cannot tell from the type which knob fired; `Timeout` says -which. (On a non-retryable verb the distinction collapses: neither is retried and both end the call on -the first fire.) That asymmetry makes `HttpClient.Timeout` the cheapest bound on the wait for the response -headers: a `10s` value bounds that wait at ≈10s whatever the verb. What it does not bound is a provider that fails *retryably* just under the limit on every attempt — that still costs -≈ `4 × 10s + 7s ≈ 47s`. It is also the only bound left standing if you set `options.Retry.Timeout = null`. A -good backstop and the cheapest fix for a hang before the headers; still not a call budget. (An *infinite* `HttpClient.Timeout` -never fires, and a `TaskCanceledException` under one is not the SDK's to explain — it passes through raw.) +**`HttpClient.Timeout` also applies per attempt** — every retry gets a fresh full window. + +**On a retryable verb only one of the two per-attempt timeouts ends the call.** `options.Retry.Timeout` +firing is retried (the ≈407s case); `HttpClient.Timeout` firing is not — it ends the call the first time, on +any verb — so a `10s` value bounds the wait for the response headers at ≈10s, though a provider failing +*retryably* just under it on every attempt still costs ≈ `4 × 10s + 7s ≈ 47s`. Both surface as +`SdkTimeoutException`, whose `Timeout` says which fired. With `options.Retry.Timeout = null` it is the only +per-attempt bound left. An *infinite* `HttpClient.Timeout` never fires, and a `TaskCanceledException` under one +passes through unwrapped. A good backstop and the cheapest fix for a hang before the headers; still not a call +budget. Set all three — they catch different failures. The per-attempt bounds cap one attempt's wait for the headers; the token caps the sum, which is the only thing your caller experiences: @@ -393,11 +313,11 @@ async Task Bounded(Func> call, CancellationToke Then every operation goes through `Bounded(...)`, and the budget is one value in one place. -**The invariant to check:** your worst case — `attempts × per-attempt timeout + total backoff` — must sit -below the deadline your own caller is working to. If it does not, the caller times out first and your retries -are burning provider capacity for a response nobody is still waiting for. A `TaskCanceledException` from your -own token is **not** retried and **not** wrapped (see Notes above), so the token cuts the call cleanly and -surfaces as itself. +**The check:** `calls in the handler × (attempts × per-attempt timeout + backoff)` must sit below the +deadline your own caller is working to — count loop iterations, not lines of code. A handler that makes +several SDK calls (a loop over recipients or invoices, a fan-out, a send-then-schedule pair) adds up their +bounds, and faster when each failure is caught so the work continues; pass one `Bounded` deadline token to +every call in it. Cancelling that token is not retried, so it cuts the call cleanly. ## The clock — `TimeProvider` @@ -405,29 +325,22 @@ Every place the SDK reads time goes through **one** option, `options.TimeProvide `System.TimeProvider`, default `TimeProvider.System`): the retry backoff and the `Retry-After` arithmetic, the per-attempt `Timeout`, the SSE idle window (`StreamReadTimeout`, below), OAuth2 token expiry, webhook replay tolerance (its own `WebhookOptions.TimeProvider`) and the elapsed-milliseconds figure in the response -log line. There is no second clock inside the engine — a component that needs time is handed this one, and -never falls back to `TimeProvider.System` on its own. +log line. ```csharp options.TimeProvider = TimeProvider.System; // the default; set it only to substitute a clock ``` -Under `services.Add{Api}Client(...)` the option is **seeded from the container before your `configure` -callback runs**: a `TimeProvider` you registered — in any order relative to the SDK registration — is picked -up, and a value you assign in `configure` wins over it. The SDK **never registers** a `TimeProvider` in your -container, so it neither collides with yours nor leaves one behind. The precedence is: explicit option > -container registration > `TimeProvider.System`. The same seeding applies to -`Add{Api}WebhookSignatureVerifier` for webhooks. +Under `services.Add{Api}Client(...)`, a `TimeProvider` registered in your container — in any order relative +to the SDK registration — is used unless your `configure` callback sets one: explicit option > container +registration > `TimeProvider.System`. The SDK **never registers** a `TimeProvider` itself. The same applies to +`Add{Api}WebhookSignatureVerifier`. -The practical consequence is for tests: one fake clock on `options.TimeProvider` drives retries, idle -timeouts and token expiry together, with no real sleeps. Use a provider that **implements timers** — -`FakeTimeProvider` from `Microsoft.Extensions.TimeProvider.Testing` — because the backoff and the idle -window are timers on the provider; a `GetUtcNow`-only fake throws when the SDK asks for one. See -**dotnet-testing** § *Fake the clock*. +To fake it in tests, see **dotnet-testing** § *Fake the clock*. ## Pagination -Operations the API marks as paginated return **`Pageable<{PageResponse}, {Item}>`**, and the shape catches +Paginated operations return **`Pageable<{PageResponse}, {Item}>`**, and the shape catches people out: `Pageable` implements `IAsyncEnumerable<`**`TItem`**`>`, so a plain `await foreach` walks **individual items**, not pages. The SDK fetches each page and advances the paging state for you — one of five strategies (offset, cursor, keyset, `Link`-header, or page-number), chosen per operation. @@ -476,18 +389,6 @@ me when to stop" as the *only* stop condition and you have written an unbounded returning a next-page link, a cursor that fails to advance, or a filter the provider quietly ignores will each spin until something else kills the request. -What that failure looks like in production — the request does not return slowly, it **does not return at -all**: - -``` -status=0 upstream=55909 -CLIENT_ERROR:TaskCanceledException:The request was canceled due to the configured -HttpClient.Timeout of 75 seconds elapsing. -``` - -Tens of thousands of provider calls billed, the caller left holding a dead request, and no error the -provider can be blamed for. The bug is entirely on the consuming side. - **Every page loop needs at least one bound that does not depend on the provider's cooperation.** Pick the one that matches the use case; a page cap is the cheapest and is never wrong: @@ -516,7 +417,7 @@ If there is no such convention and the return type genuinely cannot change, thro silently. ⚠⚠ **A `LogWarning` at the cap followed by `return results;` is the defect.** Log it as well, never instead. -**No-throw variant.** Where generated, a sibling `{Operation}Result` returns +**No-throw variant.** Where it exists, a sibling `{Operation}Result` returns `Pageable, {Item}>` — the same streaming, but its **`.AsPages(ct)`** hands you an `ApiResult` per page that you inspect instead of it throwing: @@ -536,15 +437,13 @@ await foreach (var result in client.{ApiGroup}.{Operation}Result(request, cancel > Not every list endpoint is paginated. An operation with no pagination metadata is a plain list call > (returns a list or a wrapper — see **dotnet-calling-endpoints**); to page one of those, drive its own -> `page`/`perPage` query params yourself and stop when a page returns fewer than `perPage` items. -> **A hand-driven loop needs the same bound as an auto-paginated one** — "fewer than `perPage`" and -> "no next-page link" are both provider-supplied stop conditions, and neither is a bound. Carry a page -> cap alongside it (see *Never leave a page loop unbounded* above). +> `page`/`perPage` query params yourself, stop when a page returns fewer than `perPage` items, and carry +> the same page cap (see *Never leave a page loop unbounded* above). ## Streaming (Server-Sent Events) -Operations the API marks as streaming (`text/event-stream`) are generated to **return -`Task>`** — `await` the call once to open the stream, then `await foreach` the +A streaming (`text/event-stream`) operation **returns `Task>`** — `await` the +call once to open the stream, then `await foreach` the frames as the server emits them. `{Item}` is `string` for a plain-text stream, or a typed model for a JSON event stream. @@ -573,28 +472,16 @@ catch (SdkConnectionException ex) // the connection dropped mid-st } ``` -**Idle timeout.** A stalled stream is bounded by the **`StreamReadTimeout` client option** — the maximum -wait **between frames**, a `TimeSpan?` on `{Api}ClientOptions` defaulting to **60 s**; set it to `null` to -wait indefinitely. It bounds only the wait for the server between frames, never your own processing time -inside the loop. When it elapses the SDK tears the stream down and the enumeration throws -`SdkTimeoutException` with `Timeout` set to the window that elapsed — the same leaf that reports a -per-attempt timeout on an ordinary call, so one `catch (SdkTimeoutException)` covers both. The window is -measured on `options.TimeProvider` (see *The clock* above), so a fake clock drives it in tests. - -**Errors** (all under `{RootNamespace}.Core.Exceptions`, all `SdkException`s that name the call): -- **Before the stream opens** — the opening `await` throws `ApiException`, with `TError` the same - two-case shape as any operation: a typed `{Operation}Error` (Case A) or `RawError` (Case B), per what the - operation declares (see **dotnet-error-handling**). -- **While enumerating** — there is no SSE-specific exception type; the family's ordinary leaves apply: - - `SdkTimeoutException` — no frame arrived within `StreamReadTimeout`; carries `Timeout`. - - `ResponseDeserializationException` — a frame couldn't be parsed as `{Item}`; carries `TargetType` and - the underlying `JsonException` (or `FormatException` for a parsed scalar) as `InnerException`. The raw - frame text is **not** on the exception or in its message. A plain-`string` stream cannot raise it. - - `SdkConnectionException` — the connection dropped mid-stream (`"{call} could not read the response - body: …"`, the `IOException` / `HttpRequestException` as `InnerException`). -- Retries do **not** apply once the stream is open; cancel via the `CancellationToken` - (`stream.WithCancellation(ct)`) to stop early — your cancellation surfaces as `OperationCanceledException`, - never wrapped. +**Idle timeout.** `StreamReadTimeout` on `{Api}ClientOptions` (a `TimeSpan?`, default **60 s**, `null` to +wait indefinitely) bounds the wait **between frames**, never your own processing inside the loop. When it +elapses the SDK tears the stream down and the enumeration throws `SdkTimeoutException` with `Timeout` set to +the window — the same leaf as a per-attempt timeout, so one `catch (SdkTimeoutException)` covers both. + +**Errors:** the opening `await` throws `ApiException` — Case A or B, as for any operation (see +**dotnet-error-handling**). While enumerating there is no SSE-specific type; the three leaves in the sample +apply. The raw frame text is **not** on `ResponseDeserializationException` or in its message, and a +plain-`string` stream cannot raise it. Retries do **not** apply once the stream is open; cancel with +`stream.WithCancellation(ct)` to stop early. ## Logging @@ -606,7 +493,7 @@ and one of the three cases is almost certainly your production path: | how the client is built | `LoggerFactory` null means | | --- | --- | | `services.Add{Api}Client(...)` | the extension fills it from the container's `ILoggerFactory` — **logging is already on**, at your host's minimum level, and the request line goes to your normal log sinks | -| `new {Api}Client(httpClient, options)` by hand | `NullLoggerFactory` — nothing is written, *unless* `{APICLIENTTYPENAME}_LOG` is set (see below) | +| `new {Api}Client(httpClient, options)` by hand | `NullLoggerFactory` — nothing is written, *unless* `{API}_LOG` is set (see below) | | you assign it yourself | your factory is used and the environment variable is ignored outright | The first row is the one that surprises people: in any ASP.NET Core or generic-host app the SDK is logging @@ -628,9 +515,8 @@ options.Logging = new LoggingOptions }; ``` -What it emits, and at which level — every row is additionally gated by `_logger.IsEnabled(level)`, so a -factory whose minimum level is `Warning` emits no request line at all; the SDK's switches are a *second* -gate, not the only one: +What it emits, and at which level — each row is also filtered by your `ILoggerFactory`'s minimum level, so a +`Warning` minimum emits no request line at all: | Event | Level | On by default | | --- | --- | --- | @@ -659,27 +545,22 @@ not. On any endpoint that carries card data, bank details, personal data or a cr switching this on writes that data to your logs. Leave it off in production; turn it on for one endpoint at a time behind a flag you can prove is off. -⚠▶▶ **An environment variable turns all of this on without a code change.** When -`options.Logging.LoggerFactory` is *still* `null` at construction — which in practice means a client you -constructed yourself, since `Add{Api}Client` always fills it (it calls `AddHttpClient()`, which registers an -`ILoggerFactory`) — the SDK reads -`{APICLIENTTYPENAME}_LOG`, the client type name upper-cased plus `_LOG`. It accepts `info`, `debug` or -`trace`, and writes to **stderr** through a built-in console logger. `debug` additionally forces request *and* response headers on; **`trace` additionally forces -`LogRequestBody` on**, i.e. unredacted JSON bodies to stderr on a host you may not control. Assigning -`LoggerFactory` yourself disables the variable outright — which is the reason to set it explicitly in -production even when you point it at `NullLoggerFactory.Instance`. - -**Per-call override.** Every generated operation takes a `RequestOptions? requestOptions = null` argument -with two properties: `LogLevel?` — the logging override this section covers — and `Hooks`, the per-call -hook list (see *Hooks* below). Passing `new RequestOptions { LogLevel = LogLevel.Debug }` **sets** the -verbosity for that one call without touching the client's configuration — useful for tracing one failing -endpoint. Two things about it are easy to get wrong: - -- It **replaces** the per-switch defaults in *both* directions, rather than only raising them. `Trace` turns - the body and headers on even when `LogRequestBody` is `false`; a value *above* `Information` — `Warning`, - say — switches the request line and the success response line **off** for that call. -- It cannot lift a level your `ILoggerFactory` has filtered out. `_logger.IsEnabled(level)` is still ANDed in - front, so a per-call `Trace` against a factory whose minimum is `Information` logs nothing extra. +⚠ **An environment variable turns all of this on without a code change.** When +`options.Logging.LoggerFactory` is *still* `null` at construction — in practice a client you constructed +yourself, since `Add{Api}Client` always fills it — the SDK reads `{API}_LOG`, the SDK name in upper snake +case plus `_LOG`. It accepts `info`, `debug` or `trace`, and writes to **stderr** through a +built-in console logger. `debug` also forces request *and* response headers on; **`trace` also forces +`LogRequestBody` on** — unredacted JSON bodies to stderr on a host you may not control. Assigning +`LoggerFactory` yourself — even `NullLoggerFactory.Instance` — disables the variable, so set it explicitly in +production. + +**Per-call override.** `new RequestOptions { LogLevel = LogLevel.Debug }`, passed as the `requestOptions` +argument every operation takes (see **dotnet-calling-endpoints**), **sets** the verbosity for that one call +without touching the client's configuration. It replaces the per-switch defaults in *both* directions: `Trace` +turns the body and headers on even when `LogRequestBody` is `false`, and a level above `Information` — +`Warning`, say — turns the request line and the success response line **off** for that call. It cannot get +past your `ILoggerFactory`'s minimum level: a per-call `Trace` against an `Information` minimum logs nothing +extra. ### Hooks — the SDK's own request/response seam @@ -705,11 +586,10 @@ The facts that decide how you use them: rate-limit budgets, a request-id echo) — the operation's return value carries only the body. A per-call hook can close over a local, which puts the observed value in scope in the same method's `catch`; a client-wide hook needs `AsyncLocal` or a scoped service to reach it. -- **A hook is an observation seam, not a veto point.** An exception thrown from a hook is not retried - (the transport arm retries only `HttpRequestException` and the timeout rejection) — it just fails the - call, and a throwing `OnResponse` fails a call that succeeded on the wire. To refuse a re-send, use - the write-guard `DelegatingHandler` under *Make the write idempotent* — a blocked attempt must never - reach the network, which no observation hook can guarantee. +- **A hook is an observation seam, not a veto point.** An exception thrown from a hook is not retried — it + fails the call, and a throwing `OnResponse` fails a call that succeeded on the wire. To refuse a re-send, + use the write-guard `DelegatingHandler` (option 4 under *Making a write safe under retries*): a blocked + attempt never reaches the network, which no hook can guarantee. ### When you still want a `DelegatingHandler` @@ -738,51 +618,30 @@ var httpClient = new HttpClient(new LoggingHandler { InnerHandler = new HttpClie var client = new {Api}Client(httpClient, options); ``` -With DI, the SDK's `Add{Api}Client` resolves the **default (unnamed)** `IHttpClientFactory` client, so attach -the handler to that one — register it and configure the default client *before* (or alongside) the SDK -registration: - -```csharp -services.AddTransient(); -services.AddHttpClient(Options.DefaultName).AddHttpMessageHandler(); -services.Add{Api}Client(options => { /* ... */ }); // resolves CreateClient() → the default client -``` - -The handler then runs on every SDK call — but so does everything else you configure on the default client, -for **every other unnamed `CreateClient()` consumer in the app**. If that blast radius is unwelcome, skip the -extension and register the client over a **named** `HttpClient` instead -(`services.AddHttpClient("my-api").AddHttpMessageHandler()`, then construct -`new {Api}Client(factory.CreateClient("my-api"), options)`), which keeps the handler, timeout and primary -handler scoped to this SDK. See **dotnet-client-initialization**. - -The `OnRetry` callback above is also a convenient place to observe retry activity. +Under `Add{Api}Client`, attach it to the **default (unnamed)** `HttpClient` the extension resolves +(`services.AddHttpClient(Options.DefaultName).AddHttpMessageHandler()`, with the handler +registered as transient) — which also affects every other unnamed consumer in the app — or register the +client over a **named** `HttpClient`; see **dotnet-client-initialization**. ### Verify on the wire (first run of any new integration) **Run the built-in logger on the first execution of any new call and inspect the output** — the default `Information` request line is enough, so this costs one `LoggerFactory` assignment. Path/template params are -not type-checked against the route (internally the value is -`object?`; it is normalised *through* JSON — which is why an enum contributes its wire value and not its C# -member name — then substituted as the resulting scalar's plain text, URL-escaped, by a plain string -replace), and on a **successful** response the -SDK returns only the deserialized body — it never surfaces the request URL or status (see -**dotnet-error-handling**). So a wrong verb, a leftover `{placeholder}`, or a mis-serialized path segment -**compiles cleanly** and produces no in-band signal; the only symptom is a runtime `404`/`422`. +not type-checked against the route (an enum contributes its wire value, not its C# member name), and a +**successful** call returns only the deserialized body — never the request URL or status. So a wrong verb, a +leftover `{placeholder}`, or a mis-serialized path segment **compiles cleanly** and shows only as a runtime +`404`/`422`. Checklist for the first printed request: 1. the **verb** matches the operation (a `404` on a path you believe exists often means the wrong method); -2. the **path** is fully formed. The failure to watch for is silent and unobvious: a path parameter whose - value is null or empty collapses to **nothing**, leaving a doubled slash (`/orders//authorize`) — not a - leftover marker. (An unbound `{placeholder}` would survive, but the generator supplies every declared - path param, so that is only reachable through a hand-set `BaseUrl`; and it prints percent-encoded, - `%7Bid%7D`, not as `{id}`.) +2. the **path** is fully formed — a null or empty path parameter collapses to **nothing**, leaving a + doubled slash (`/orders//authorize`), not a leftover marker. Only a `{placeholder}` in a hand-set + `BaseUrl` survives, and it prints percent-encoded (`%7Bid%7D`); 3. each **path-param segment** is the value the API expects — for an enum that is the **wire value** - (frequently ALL-CAPS), not the C# member name; the generated constants carry it. Nothing normalises - casing and there is no public factory, so the only way an unexpected string reaches the URL is a value - the server itself sent and your code echoed back — check `IsKnownValue()` before reusing one as input; -4. the query params you set actually appear in the query string — remembering that a value is masked - unless its key is on the known-safe list (`cursor`, `dates`, `datetime`, `limit`, `offset`, `page`, - `since`, `size`, `strings`), so for anything else you are checking that the key is present, not what it - carries. + (frequently ALL-CAPS), not the C# member name; check `IsKnownValue()` before echoing a server-sent value + back (see **dotnet-models**); +4. the query params you set actually appear in the query string — a value is masked unless its key is on + the known-safe list (see *Logging*), so for any other key you are checking that it is present, not what + it carries. Drop the level back once verified. diff --git a/plugins/slack/skills/dotnet/dotnet-error-handling/SKILL.md b/plugins/slack/skills/dotnet/dotnet-error-handling/SKILL.md index b4fd301b..81e5f32c 100644 --- a/plugins/slack/skills/dotnet/dotnet-error-handling/SKILL.md +++ b/plugins/slack/skills/dotnet/dotnet-error-handling/SKILL.md @@ -1,6 +1,6 @@ --- name: dotnet-error-handling -description: Error and exception handling for an APIMatic-generated .NET SDK in C# — load before writing any try/catch around an SDK call, an exception-translation layer, or error middleware. Covers which exception types actually reach your catch blocks, how to read status codes and error bodies safely, and the traps that make an otherwise reasonable catch ladder silently wrong. +description: Load before writing any try/catch around a call on an APIMatic .NET SDK in C#, an exception-translation layer or error middleware — which exception types reach your catch, the SdkException family, typed error bodies versus RawError, reading status codes and error bodies, and the non-throwing ApiResult variant. --- # Error handling for an APIMatic .NET SDK @@ -8,26 +8,21 @@ description: Error and exception handling for an APIMatic-generated .NET SDK in > Throughout this skill, `{...}` is a placeholder for a name you take from your SDK (e.g. `{Operation}`, > `{ApiGroup}`, `{RootNamespace}`) — replace it with the concrete identifier from the source. > -> **One skill, every error shape.** This file covers every shape the 4.0.0 generator can emit. -> Which shapes YOUR SDK uses — which case each operation is, whether typed bodies carry a status, -> which `TryGet…` accessors exist — are facts of the API definition, not of this skill: take them -> from the operation's map row or the contract sheet, and **apply only the guidance that -> matches**. An API can be all Case B, nearly all Case A, or a mix. +> **One skill, every error shape.** This file covers every error shape the SDK can have. Which ones +> YOUR SDK uses — which case each operation is, whether typed bodies carry a status, which `TryGet…` +> accessors exist — is on the operation's map row or the contract sheet: **apply only the guidance +> that matches**. An API can be all Case B, nearly all Case A, or a mix. Endpoint methods **throw on non-success responses** by default (for a non-throwing alternative, see the **`ApiResult`** section below). The thrown type is always the generic `ApiException` — but `TError` comes in **two shapes**, depending on the operation: - **Typed model (Case A)** — a per-operation `{Operation}Error` (subclass of `ApiError`) exists under - `Errors/` for the operation; `TError` is that type and you read it with typed `TryGet*` accessors. + `Errors/` for the operation; `TError` is that type. Dispatch on it with its exhaustive `Match` (one + `on{Arm}` per declared body plus a required `otherwise`), or read one body with a `TryGet*` accessor. - **`RawError` (Case B)** — when the operation has no `{Operation}Error` type, `TError` is `RawError` *directly*. `RawError` is **not** an `ApiError` and has **no** `TryGet*` / `TryGetRawError` accessors; you - read the status and body straight off `ex.Error`. How common this is, is an API fact — some APIs are almost - entirely Case B, others almost entirely Case A; each operation's map row says which it is. - -`ApiException` is declared `public sealed class ApiException : ApiException` with **no** -`where TError : ApiError` constraint — which is exactly why `TError` can be either an `ApiError` model or a -`RawError`. + read the status and body straight off `ex.Error`. ### The `SdkException` family @@ -41,7 +36,7 @@ SdkException (abstract) Method, RequestUri — the call │ └─ ResponseDeserializationException TargetType — a body (success OR error) did not match the declared type ├─ SdkConnectionException — — no usable response: could not send, or could not read the body │ └─ SdkTimeoutException (sealed) Timeout — an attempt, the transport, or an SSE stream went silent -└─ AuthSchemeException (sealed) SchemeFailures — a credential could not be applied +└─ AuthSchemeException (sealed) SchemeFailures — a required credential is not configured, a provider returned nothing, or a credential could not be applied ``` Three rules follow from the shape, and the rest of this skill applies them: @@ -49,47 +44,31 @@ Three rules follow from the shape, and the rest of this skill applies them: - **Catch specific to general.** `ApiException` means *the server answered* (you have a status); `SdkConnectionException` means *it did not*; `SdkException` is *everything the SDK raises*. A ladder that handles only `ApiException` is incomplete — see *Connection failures* below. -- **The raw cause is always `InnerException`** — the `JsonException`, the `HttpRequestException`, the Polly - timeout rejection, the token endpoint's own failure — never the thing you catch. +- **The raw cause is always `InnerException`** — the `JsonException`, the `HttpRequestException`, the + per-attempt timeout's rejection, the token endpoint's own failure — never the thing you catch. - **Your own cancellation is never wrapped.** An `OperationCanceledException` from a token *you* cancelled passes through untouched; a `catch (SdkException)` does not see it. -The messages are a contract, asserted verbatim by the SDK's own tests, and each names the call with its query -stripped: `"GET https://host/path returned 400 (BadRequest)."`, `"{call} could not be sent: …"`, +Every message names the call with its query stripped: `"GET https://host/path returned 400 (BadRequest)."`, +`"{call} could not be sent: …"`, `"{call} could not read the response body: …"`, `"{call} received no response within 100 s."`, `"{call} returned a body that could not be deserialized into {Type}."`. A log line therefore identifies the failing call without a typed catch. -These types live in **distinct** namespaces — `Core.*` is **not** a single namespace, so don't assume -`ApiError` sits with the exceptions under `Core.Exceptions`: - -- the whole `SdkException` family → `{RootNamespace}.Core.Exceptions` -- `ApiError` **and** `RawError` → `{RootNamespace}.Core.ErrorResponse` -- the per-operation `{Operation}Error` models (e.g. `CreateWidgetError`) → `{RootNamespace}.Errors` +`Core.*` is **not** one namespace — don't assume `ApiError` sits with the exceptions: -So a typed (Case A) catch needs up to **four** namespaces, not three — how many depends on whether you -spell the `out` types out or use `out var`: - -| namespace | what you need from it | +| namespace | holds | | --- | --- | -| `{RootNamespace}.Core.Exceptions` | `ApiException` — the exception itself (and the rest of the family) | -| `{RootNamespace}.Errors` | the `{Operation}Error` you name in the `catch` | -| `{RootNamespace}.Core.ErrorResponse` | `RawError`, which the inherited `TryGetRawError` hands back | -| *depends on the body* | the **typed body** a `TryGet…` yields — see below | +| `{RootNamespace}.Core.Exceptions` | the whole `SdkException` family, `ApiException` included | +| `{RootNamespace}.Core.ErrorResponse` | `ApiError` and `RawError` (which the inherited `TryGetRawError` hands back) | +| `{RootNamespace}.Errors` | the per-operation `{Operation}Error` models (e.g. `CreateWidgetError`) | -**The fourth is not a fixed namespace.** A typed body is whatever the API definition declared, so where -its type lives follows the body's schema kind — a model in `{RootNamespace}.Models`, a union in +A typed body's type lives wherever its schema kind puts it — a model in `{RootNamespace}.Models`, a union in `.Models.OneOf` / `.Models.AnyOf`, an enum in `.Models.Enums`, a binary body in `.Core.Models` -(`ErrorByteContent`), and a map or dynamic body in no SDK namespace at all -(`IReadOnlyDictionary` needs `System.Collections.Generic` and `System.Text.Json`). A -scalar body — `TryGetString`, `TryGetLong` — needs nothing. Read the accessor's `out` type and import what -*it* names; do not assume `.Models`. - -The last two rows only bite when you write the `out` type out. `out var` needs neither, which is why the -template below imports three namespaces and not four — it uses `out var` for the typed bodies and names -`RawError` explicitly. A Case B catch needs only -`Core.Exceptions` and `Core.ErrorResponse`. This namespace layout is identical across the APIMatic .NET SDKs -checked. +(`ErrorByteContent`), a map or dynamic body in the BCL (`IReadOnlyDictionary` needs +`System.Collections.Generic` and `System.Text.Json`); a scalar body (`TryGetString`, `TryGetLong`) needs +nothing. Import what an `out` type you spell out names — `out var` needs none, which is why the template +below imports three namespaces. ## Catch the exception @@ -147,17 +126,23 @@ memory: 1. **List *every* `TryGet...` accessor the operation's `{Operation}Error` declares.** The operation's map row already lists them (with the HTTP status each maps to); take them from the contract sheet. - They are the `public bool TryGet...(out ...)` methods on the `{Operation}Error` type (grounded + They are the `public bool TryGet...([NotNullWhen(true)] out ...? value)` methods, a bare `out` for a + value-type body such as `long`, on the `{Operation}Error` type (grounded from the SDK map/source). These accessors are generated per operation — one per distinct error body the operation maps — and their names embed the body type. Expect a mix of: - **typed-body accessors** named after a model or scalar — `TryGetValidationErrors`, `TryGetProblemDetails`, `TryGetString`, `TryGetLong`, …; - - **status-specific `RawError` accessors** — e.g. `TryGetNoContent(out RawError)` — the names on your operation come from its map row; - - the inherited **`TryGetRawError(out RawError)`**, which every `{Operation}Error` exposes. -2. **Write one `if` / `else if` branch per `TryGet*` method — cover them all, and put `TryGetRawError` - *last*.** Each public `TryGet*` corresponds to a status/body the operation can return; skip one and you - silently drop that response. `TryGetRawError` must be the final branch because it is **not** a catch-all - (see below) — it only fires for statuses that have no more-specific accessor. + - **status-specific `RawError` accessors** — e.g. `TryGetNoContent([NotNullWhen(true)] out RawError? value)` — the names on your operation come from its map row; + - the inherited **`TryGetRawError([NotNullWhen(true)] out RawError? error)`**, which every `{Operation}Error` exposes. +2. **Dispatch through `ex.Error.Match(...)`, passing every arm by name.** `Match` has one `on{Arm}` + parameter per `TryGet{Arm}` accessor (same stem, same value) plus a required `otherwise` that receives + the `RawError` of a status the operation does not declare — the compiler refuses a call that leaves an + arm out, so no response is silently dropped. Pass the arms by name: they are positional, in the + ordinal order of their names, and a regenerated SDK whose operation gains or loses an error body + changes the signature (a source and binary break for a positional call site). Reach for a single + `TryGet{Arm}` only when one body is all you need, and for `TryGetRawError` only as the accessor + behind `otherwise`: it is **not** a catch-all — a status with a typed or status-specific accessor + (a `422` validation payload, `TryGetNoContent`) leaves it **false**. ```csharp using {RootNamespace}.Core.Exceptions; // ApiException @@ -171,38 +156,19 @@ try } catch (ApiException<{Operation}Error> ex) { - // ex.StatusCode / ex.Headers are always here; the body is behind the accessors below. - // ONE branch per public TryGet* declared on {Operation}Error — copy the exact names from the class - // under Errors/. The TryGet{...} names below are PLACEHOLDERS; yours are named after this operation's - // responses (a typed body may be a model OR a scalar such as TryGetString/TryGetLong). - if (ex.Error.TryGet{TypedBody1}(out var body1)) // e.g. TryGetValidationErrors — a typed body - { - // inspect body1 - } - else if (ex.Error.TryGet{TypedBody2}(out var body2)) // e.g. TryGetProblemDetails — another typed body - { - // inspect body2 - } - else if (ex.Error.TryGet{Status}(out RawError statusRaw)) // e.g. TryGetNoContent(out RawError) — status-specific - { - Console.Error.WriteLine($"HTTP {(int)statusRaw.StatusCode}"); - } - // ... KEEP GOING: one else-if for EVERY remaining TryGet* the class declares — do not stop early ... - else if (ex.Error.TryGetRawError(out RawError raw)) // ALWAYS LAST: fallback for untyped statuses only - { - Console.Error.WriteLine($"HTTP {(int)raw.StatusCode}: {raw.ReadAsString()}"); - } + // ex.StatusCode / ex.Headers are always here; the body is behind the arms below. + // ONE named arm per public TryGet* declared on {Operation}Error — copy the exact names from the class + // under Errors/ (on{Body} pairs with TryGet{Body}). The on{...} names below are PLACEHOLDERS; yours are + // named after this operation's responses (a typed body may be a model OR a scalar such as onString/onLong). + ex.Error.Match( + on{TypedBody1}: body1 => { /* inspect body1 — e.g. onValidationErrors */ }, + on{TypedBody2}: body2 => { /* inspect body2 — e.g. onProblemDetails */ }, + on{Status}: statusRaw => Console.Error.WriteLine($"HTTP {(int)statusRaw.StatusCode}"), // e.g. onNoContent + // ... one named arm for EVERY remaining TryGet* the class declares — the compiler enforces it ... + otherwise: raw => Console.Error.WriteLine($"HTTP {(int)raw.StatusCode}: {raw.ReadAsString()}")); // undeclared status } ``` -**Why `TryGetRawError` goes last — it is not a universal fallback.** It returns a raw body **only** for -statuses that have no more-specific accessor on this `{Operation}Error`; a status that has a typed accessor -(e.g. a `422` validation payload) lands in that typed slot and leaves `TryGetRawError` **false**. The -status-specific `RawError` accessors (e.g. `TryGetNoContent(out RawError)`) are likewise **not** surfaced by -`TryGetRawError`. So if you check `TryGetRawError` first — or omit any of the more-specific accessors — those -typed and status-specific bodies are silently dropped. Enumerate the class and handle every accessor -explicitly. - **Don't factor error-reading into a shared helper typed as `ApiError`.** The typed `TryGet*` accessors live on the concrete `{Operation}Error`, *not* on the `ApiError` base — which exposes only `TryGetRawError`. A helper like `string Describe(ApiError e)` can therefore reach **only** `TryGetRawError`, so for any status @@ -233,24 +199,25 @@ catch (ApiException ex) } ``` -Case B needs no `.Errors` using — `RawError` lives under `{RootNamespace}.Core.ErrorResponse`. Its public -members are `StatusCode`, `ReadAsBytes`/`ReadAsString`/`ReadAsJson`; note +Case B needs no `.Errors` using. `RawError`'s public members are `StatusCode`, +`ReadAsBytes`/`ReadAsString`/`ReadAsJson`; note `ReadAsJson()` **throws `JsonException`** when the body isn't valid JSON — and a `RawError` body may not be (a gateway or proxy can answer with HTML or plain text), so prefer `ReadAsString()` unless you know it's JSON. ## Result-style alternative — `ApiResult` (no throwing) -The generator can **optionally** emit a result-style variant of an operation — so it's not guaranteed to -exist. When enabled, it appears as a **sibling method** named `{Operation}Result` (next to the throwing -`{Operation}`), returning `Task>` and **does not throw** on a non-success -status — the error is carried in the returned value instead. (`{TError}` is the same two-case shape as -above: a typed `{Operation}Error`, or `RawError`.) `ApiResult` is a public -`readonly struct` under `{RootNamespace}.Core.Models`. If the controller has no `{Operation}Result` -overload, this variant wasn't generated — use the throwing method with `try/catch` instead. +An operation may have a **sibling method** named `{Operation}Result` (next to the throwing `{Operation}`), +returning `Task>`; it **does not throw** on a non-success status — the error +is carried in the returned value instead. (`{TError}` is the same two-case shape as above: a typed +`{Operation}Error`, or `RawError`.) `ApiResult` is a public `readonly struct` under +`{RootNamespace}.Core.Models`. If the controller has no `{Operation}Result`, use the throwing method with +`try/catch`. Unlike the throwing path, `ApiResult` exposes the HTTP **`StatusCode`** and **`Headers`** on *both* success -and failure — so this is the variant to use when you need the status code, rate-limit headers, or pagination -`Link` headers. +and failure — so this is the variant to use when you need a 2xx's status code, rate-limit headers, or +pagination `Link` headers. The other way to read them on the success path is an `SdkHook.OnResponse` hook +(see **dotnet-configuration-resilience** § Hooks); on the error path every `ApiException` already carries +`StatusCode` and `Headers`. ```csharp using {RootNamespace}.Core.Models; // ApiResult @@ -269,7 +236,7 @@ if (result.TryGetResponse(out var response)) // success else if (result.TryGetError(out var error)) // failure { // 'error' is the same TError as the throwing path: - // Case A → typed {Operation}Error (use its TryGet* accessors, then TryGetRawError) + // Case A → typed {Operation}Error (dispatch with error.Match(on{Arm}: …, otherwise: …), or read one arm with TryGet*) // Case B → RawError (read error.StatusCode / error.ReadAsString()) Console.Error.WriteLine($"HTTP {(int)result.StatusCode}"); } @@ -290,13 +257,11 @@ var (isSuccess, response, error) = result; ## Connection failures, and guarding every call -The `ApiException` catches above cover API errors (the server replied with a non-2xx status). They -do **not** cover connection failures — host unreachable, DNS failure, dropped connection, or timeout. Those -come through as **`SdkConnectionException`** (could not send, or could not read the body) and its leaf -**`SdkTimeoutException`** (an attempt, the transport, or an SSE stream went silent — `Timeout` says which -window), which a `catch (ApiException<...>)` will not match. If that catch is your only guard, a connection -failure escapes and takes down whatever was running the call. The raw `HttpRequestException` is the -`InnerException`; you never catch it directly. +The `ApiException` catches above cover API errors only. No usable response — host unreachable, DNS +failure, dropped connection, timeout — throws **`SdkConnectionException`** or its leaf **`SdkTimeoutException`** +(`Timeout` says which window), with the raw cause in `InnerException`. A `catch (ApiException<...>)` does +not match them; if it is your only guard, a connection failure escapes and takes down whatever was running +the call. **A file download is the exception:** a drop while you read the returned `BinaryContent` throws a raw `IOException` from your read, not `SdkConnectionException`. @@ -313,14 +278,11 @@ catch (ApiException<{Operation}Error> ex) // a Case A operation — typed { // Carry the body's identity fields (the provider's own error code or name, any correlation // id) — the typed body is the only thing that carries them, and it does not outlive this - // catch. Check the accessors in the SAME order as the Case A ladder above: every typed - // accessor this operation declares (names from its map row), then the RawError-yielding - // arms LAST. Carry ex.StatusCode alongside whichever branch fires. - if (ex.Error.TryGet{Body}(out {Body} e)) - throw new {ProviderException}(e.{MessageField} /* + identity fields — names from the model's map row */, ex.StatusCode, ex); - if (ex.Error.TryGetRawError(out RawError raw)) - throw new {ProviderException}($"HTTP {(int)ex.StatusCode}", ex.StatusCode, ex); - throw new {ProviderException}("unrecognised error shape", ex.StatusCode, ex); + // catch. Dispatch through Match so every declared body is handled and an undeclared status lands + // in otherwise; carry ex.StatusCode alongside whichever arm fires. + throw ex.Error.Match( + on{Body}: e => new {ProviderException}(e.{MessageField} /* + identity fields — names from the model's map row */, ex.StatusCode, ex), + otherwise: raw => new {ProviderException}($"HTTP {(int)ex.StatusCode}", ex.StatusCode, ex)); } catch (ApiException ex) // a Case B operation — no typed body, just the status { @@ -343,9 +305,9 @@ catch (SdkConnectionException ex) // could not send / could not r { throw new {ProviderException}("provider unreachable", ex); // no status — nothing usable answered } -catch (AuthSchemeException ex) // OUR credential could not be applied — see Notes +catch (AuthSchemeException ex) // OUR credential is missing, its provider returned nothing, or it could not be applied — see Notes { - throw new {ProviderException}("provider credentials rejected", ex); + throw new {ProviderException}("provider credentials missing or rejected", ex); } // Do NOT add `catch (OperationCanceledException)`: the caller's own cancellation is not a provider // failure and the SDK never wraps it — let it propagate. @@ -371,29 +333,19 @@ outcome and apply the identical catch ladder at every call site — same order, When the same kind of failure (a validation rejection, say) becomes a different result on a different operation, callers can't reason about it. One shared ladder, not per-call improvisation. -**Keep distinct failures distinct — and pick the discriminator from what the error path actually -delivers.** Your error type needs to carry something that separates "you sent something invalid" -from "the provider is down". The reflex is the HTTP status; whether you *can* carry one is an API -fact, settled from the contract sheet before the boundary is written: - -- **Every `ApiException` carries `StatusCode`** — Case A and Case B alike, and the - `ResponseDeserializationException` too — so the transport status is always available to carry - and to key the ladder on. A provider **4xx** the caller can act on surfaces as that same client - **4xx**; transport failures and unknowns surface as **5xx**. -- **Operations with a typed `{Operation}Error`** (Case A) usually have a **better** discriminator - than the status: the body's own **identity fields** — the provider's error code or name, - fine-grained issue codes, a correlation id — which say more than a status would (whether each - field is `required` or nullable is on the model's map row). A typed error class can route - several documented statuses into ONE accessor, so the accessor that fired and `ex.StatusCode` - are two different facts — carry both. Some operations add status-specific - `TryGet…(out RawError)` accessors as well. The operation's map row lists all of it. -- **Accessor names differ per operation** — they embed the body type (`TryGet{Body}`), so a - guessed name is a compile error (`CS1061`), not a runtime surprise. Take each name from the - operation's own map row every time. - -Whichever discriminator applies, collapsing every failure into one blanket status (e.g. 502 for -everything) throws away the one signal that separates "you sent something invalid" from "the -provider is down." +**Keep distinct failures distinct.** Your error type needs to carry something that separates "you sent +something invalid" from "the provider is down": + +- **Every `ApiException` carries `StatusCode`** — Case A, Case B and `ResponseDeserializationException` + alike — so a provider **4xx** the caller can act on can surface as that same **4xx**, and transport + failures and unknowns as **5xx**. +- **A Case A body usually discriminates better** — its **identity fields**: the provider's error code or + name, fine-grained issue codes, a correlation id (whether each is `required` is on the model's map row). + One accessor can cover several documented statuses, so carry both the body fields and `ex.StatusCode`. + Accessor names embed the body type, so a guessed one fails to compile (`CS1061`) — take each from the + operation's map row. + +Never collapse every failure into one blanket status (e.g. 502 for everything). One ladder, in the single place where your error type becomes a caller-facing status. This is where the discriminator you carried gets read back — a ladder with **no branch reading it** is @@ -438,27 +390,19 @@ bucket; validation, conflict and not-found are the caller's to fix. And keep the 5xx: a status or code you have not mapped is an unknown, not a caller error — the provider can add one without warning you. -**Status and headers on the *success* path** are not on the return value — for metrics on a 2xx, or -rate-limit headers, use the `{Operation}Result` sibling (above) or an `SdkHook.OnResponse` hook -(`options.Hooks` client-wide, or `requestOptions.Hooks` per call — see -**dotnet-configuration-resilience** § Hooks). On the *error* path you need neither: every -`ApiException` already carries `StatusCode` and `Headers`. Hooks run once per attempt, so under retry -"the status" they observe means the last attempt's. - -**An unreadable body is not one case but two — decide which before you map it.** An unreadable -**success** body is genuinely unknown: 5xx. An unreadable **error** body is not — the provider -rejected the request and only the *detail* was lost, so answering 5xx tells a retrying caller to -keep retrying something that can never succeed. The exception below tells you which you have. - -**A body that does not match the model is a third failure kind — catch it and sanitize.** The -server can return a body that no longer matches the declared type; the SDK wraps the -`System.Text.Json.JsonException` in **`ResponseDeserializationException`** — an `ApiException` -(so `StatusCode`, `Headers` and `ContentType` are on it) that also names the `TargetType` it was -building, with the `JsonException` as `InnerException`. It is **not** an `ApiException`, so a -ladder with only typed catches lets it through — and if it reaches a generic handler that writes -`exception.Message` the response leaks the SDK type name and the call URL. Catch it at the same -boundary and convert it with a caller-safe message, and **read `ex.StatusCode` to tell the two cases -apart**: +**A body that does not match the model is a third failure kind — catch it and sanitize.** The SDK +throws **`ResponseDeserializationException`** — an `ApiException` (so `StatusCode`, `Headers` and +`ContentType` are on it) that names the `TargetType` it was building, with the `JsonException` as +`InnerException`. It is **not** an `ApiException`, so a ladder with only typed catches lets it +through, and a generic handler that writes `exception.Message` leaks the SDK type name and the call URL. +It fires on a success body (a `OneOf` or `AnyOf` response type is the exception: its Unknown slot takes a +body no variant accepts, see `dotnet-models`), and on an error body that doesn't fit the operation's +`{Operation}Error` — +then your typed `catch` never fires, and there is no fallback to `RawError`. Catch it at the same boundary +with a caller-safe message, and **read `ex.StatusCode` to tell the two cases apart**: an unreadable +**success** body is genuinely unknown (5xx); an unreadable **error** body means the provider rejected the +request and only the *detail* was lost — keep that status, or a retrying caller keeps retrying something +that can never succeed: catch (ResponseDeserializationException ex) { @@ -467,15 +411,6 @@ apart**: throw new {ProviderException}("The provider returned a response that could not be processed.", ex.StatusCode, ex); } -**The error-path variant used to lose the status; it no longer does.** `{Operation}Error` models are -generated per operation and can disagree with the body the API really sends on that status. When they -do, the parse fails *while the error object is being constructed* and the SDK throws -`ResponseDeserializationException` **instead of** `ApiException<{Operation}Error>` — your typed -`catch` never fires. But the status, headers and content type ride on the exception, so "you were -rejected and I lost the reason" is fully expressible: map it by `ex.StatusCode` like any other -`ApiException`, not as a 5xx. The SDK deliberately does *not* degrade an unparseable error body to -`RawError`: a silent fallback would hide the contract drift that is the real defect here. - **Never map a parse failure onto a domain *absence*.** "I could not read the answer" is not "the provider said no." It is tempting on a lookup — an unreadable body and a genuine miss both leave you without a record — but they are different facts and only one of them is a *fact*. Where a lookup @@ -483,10 +418,8 @@ gates a create, that conversion turns a corrupt response into a spurious create; produces a confident wrong answer, which is worse than an error. If the operation's miss really is signalled by an empty body, match on *empty*, not on *unparseable*. -The rule generalizes: whatever converts SDK failures into your own type must carry only a -caller-safe message — never surface `ex.ToString()` or `exception.Message` from an SDK or -framework exception on the wire (the same leak the `ApiError.ToString()` bare-type-name trap -above produces). +Whatever converts SDK failures into your own type carries only a caller-safe message — never an SDK or +framework exception's `ToString()` or `Message` on the wire. **A successful reply can still hand you `null`.** An omitted optional member reads `null`, and so does a JSON `null` on a required string, list, model or enum. An absent required member, or `null` on a @@ -495,20 +428,20 @@ call, and every object you reach them through (`x.Y` before `x.Y.Z`). ## Notes -- A call can also throw `AuthSchemeException` (under `{RootNamespace}.Core.Exceptions`) — a credential - could not be *applied*, which is not an API error. It is an `SdkException` (so it names the API call you - made) but **not** an `ApiException`, so the typed catches above won't match it — give it its own arm, as - the ladder does. It carries `IReadOnlyList SchemeFailures`: with a **single** failing scheme, +- A call can also throw `AuthSchemeException` (under `{RootNamespace}.Core.Exceptions`) — a required + credential is not *configured*, or a credential provider *returned nothing*, so the call fails before + anything is sent, naming the scheme and carrying an empty `SchemeFailures`; or a credential could not be + *applied*. None of these is an API error. It is an + `SdkException` (so it names the API call you made) but **not** an `ApiException`, so the typed catches + above won't match it — give it its own arm, as the ladder does. It carries + `IReadOnlyList SchemeFailures`: with a **single** failing scheme, that failure is also the `InnerException` directly and the list's only entry; with **several** (an SDK whose API composes schemes with OR and none succeeded), `InnerException` is an `AggregateException` of them. The classic cause is an OAuth2 token endpoint refusing the client credentials: the token endpoint's own `ApiException` (pointing at the token URL, with its status) is the **cause** inside the `AuthSchemeException`, not what your `catch` sees — so log `InnerException` to learn *why* auth failed. An `AuthSchemeException` is never wrapped in another. -- Retries happen automatically before an exception is thrown, and `HttpMethodsToRetry` - (`GET/HEAD/PUT/OPTIONS` by default) gates **every** trigger — status, transport fault, and the SDK's own - per-attempt timeout alike. So an error on a `POST`/`PATCH`/`DELETE`, or on a call that sends a file, - surfaces on the first attempt, with no resend. That is not the same as "the write did not happen": a transport failure (`SdkConnectionException`) - may have been thrown after the bytes reached the provider, so the outcome is *unknown* and the caller needs - to be told that rather than "it failed". A per-attempt timeout that outlives its retries surfaces as - `SdkTimeoutException`. See **dotnet-configuration-resilience**. +- Retries run before anything is thrown; a call that sends a file is never retried, and with the defaults + neither is a `POST`/`PATCH`/`DELETE` — except that an OAuth2 `401` is re-sent once on any verb, a file + upload excepted. A transport failure on a write leaves its outcome *unknown* — tell the + caller that, not "it failed". See **dotnet-configuration-resilience**. diff --git a/plugins/slack/skills/dotnet/dotnet-getting-started/SKILL.md b/plugins/slack/skills/dotnet/dotnet-getting-started/SKILL.md index 2a41611e..d0dfe65e 100644 --- a/plugins/slack/skills/dotnet/dotnet-getting-started/SKILL.md +++ b/plugins/slack/skills/dotnet/dotnet-getting-started/SKILL.md @@ -1,17 +1,15 @@ --- name: "dotnet-getting-started" -description: "Slack Web API .NET SDK identity and lookup layer (.NET/C# only) you load directly — install, root namespace, environments, auth pattern, and the SDK map (shipped inside the SDK source repo): every operation signature and error case by lookup, plus the source file declaring each model, enum and error type. Load it for every contract fact, never memory; dotnet-integrate-slack-web-api is the workflow that uses it." +description: "Load for any Slack Web API .NET SDK contract fact in C#, instead of memory: install, namespaces, environments, auth, and the SDK map giving every operation signature and error case and the file declaring each model, enum and error type. .NET/C# only; dotnet-integrate-slack-web-api is the workflow that drives it." --- # Getting started with the Slack Web API .NET SDK -> **Who this skill is for.** This is the **map layer**: load it to ground every Slack Web API SDK fact. `dotnet-integrate-slack-web-api` is the workflow that drives it — you collect the contracts for the work in scope into `slack-web-api-plan.md`, implement from that sheet, and come back to the one map page a row cites for any fact the sheet is missing. Every contract fact comes from here, never from memory. +> **Map layer** for `dotnet-integrate-slack-web-api`: the contracts in scope go into `slack-web-api-plan.md`; come back to the map page a row cites for any fact the sheet lacks. -This is the **SDK-specific** entry point. For general patterns that apply to any APIMatic-generated .NET SDK (auth, calling endpoints, models, error handling, retries, testing), see the companion API-agnostic skills: `dotnet-client-initialization`, `dotnet-authentication`, `dotnet-calling-endpoints`, `dotnet-models`, `dotnet-error-handling`, `dotnet-configuration-resilience`, `dotnet-testing`. +Usage companions: `dotnet-client-initialization`, `dotnet-authentication`, `dotnet-calling-endpoints`, `dotnet-models`, `dotnet-error-handling`, `dotnet-configuration-resilience`, `dotnet-testing`. The SDK map is authoritative for the SDK's *surface* (signatures, model shapes, enums, which error type an operation throws); the companions are the *usage layer* — how to call each piece and the gotchas a signature cannot show. Reading the map or source does not replace a step's companion: at each step below, load the companion *and* confirm names against the map. -**The SDK map and these companion skills are complementary — load both.** The map (generated from the SDK source, which remains the ground truth) is authoritative for the SDK's *surface* (signatures, model shapes, enums, which error type an operation throws); the companion skills are the *usage layer* on top — the best-practice way to call each piece and the gotchas a signature cannot show. Reading the map or source does not remove the need to load the skill for that step, so at each step below, load the companion *and* confirm names against the map. - -> **Ground every signature, model, enum, and error type in the SDK map** (`sdk-map.md` + `map/operations/`, inside the SDK source repo — see the *SDK source* section for obtaining it). The map is **method-first**: operation signatures, error cases with their `TryGet…` accessors, pagination and server/auth wiring are on its pages by lookup — and for every type an operation names, the map names the **file that declares it**, so a shape question (fields, wire names, enum values, union accessors) is one targeted file open, never a search. When a map-sourced name fails to compile, re-read the file its row names; **never fill the gap from memory.** Do **not** decompile or reflect over the installed reference, do **not** fetch SDK files from the web ad hoc, and do **not** grep or run other expensive searches over the clone. +> **Ground every signature, model, enum, and error type in the SDK map** (`sdk-map.md` + `map/operations/`, inside the SDK source repo — see the *SDK source* section for obtaining it); **never fill a gap from memory.** ## SDK identity @@ -24,12 +22,10 @@ This is the **SDK-specific** entry point. For general patterns that apply to any | Client class | `SlackWebApiClient` | | Options class | `SlackWebApiClientOptions` | | Auth | **OAuth 2.0** authorization code — set `SlackAuth` | -| Environments | `ServerEnvironment.Production` *(default)* → `https://slack.com/api`
`ServerEnvironment.Environment2` → `https://slack.com/oauth` | -| Log environment variable | `SLACKWEBAPICLIENT_LOG` | +| Environments | `ServerEnvironment.Production` *(default)*
base URL per server group (2 groups): `sdk-map.md` *Servers & auth* | +| Log environment variable | `SLACK_WEB_API_LOG` | | Target framework | `netstandard2.0` (C# `LangVersion 14`) | -The table above is **orientation, not a copy-paste recipe** — it gives you the names and facts (install, namespaces, the auth *pattern*, the environments), while the actual integration code comes from the companion skills. Load every one the contract sheet's REQUIRED READING names before you start implementing (`dotnet-integrate-slack-web-api` makes that binding); the **Integration workflow** below says which governs which step. - ## Namespaces (using-directives) The SDK splits its public types across **separate child namespaces**. C# does **not** import child namespaces transitively, so `using SlackWebApi.Models;` alone does **not** make enums, union types, or error types visible — you get `CS0103`/`CS0246` ("name/type does not exist") on build. Add a separate `using` for each kind of type you reference: @@ -46,32 +42,31 @@ Models, enums, union types and the generated error types each sit in their own c This SDK is **not published to a package feed**, so there is no `dotnet add package` for it. Build it from its repository — , branch `main` — and reference the resulting assembly from the project that will call Slack Web API, then write the `using` directives from the table above. -> **Build against the assembly built from that repository, and do not copy the SDK source into your repository.** A copy is a fork: the next time the SDK is regenerated the copy stays behind, and the map then describes code you are not building against. The map is read from the read-only **reference clone** the *SDK source* section below describes, which lives in the system temp directory, is obtained at the start of SDK work and is never part of the build. +> **Build against the assembly built from that repository; never copy the SDK source into your repository** — a copy is a fork the map stops describing. The map is read from the read-only **reference clone** (*SDK source* below), never part of the build. ## SDK map — look up first, open the named file second, never grep -The SDK ships a generated map **inside the SDK source repo**, at the SDK root — the map and the SDK regenerate together in one repo, so they cannot drift apart. The map is **method-first**: operation contracts are on its pages; model, enum and error **shapes are deliberately not duplicated there** — the map names the file declaring each type, and you read the shape in that file. Every path below is relative to the SDK root in the clone — obtain it first (next section): +The map sits at the SDK root **inside the SDK source repo** and always matches the source beside it. It is **method-first**: operation contracts are on its pages; for model, enum and error shapes it names the file declaring each type, and you read the shape in that file. Every path below is relative to the SDK root in the clone — obtain it first (next section): - **`sdk-map.md`** — the index and the read-once pages: SDK identity, client construction and the full options surface, the error-handling model (Case A typed / Case B raw), the **defaults table** for operations, the model/enum/error directory conventions, *Namespaces by content type*, and *Servers & auth*. - **`map/operations/`** — one page per controller, one block per operation: the exact C# signature with its request record's required members, the return type, the error case (A: typed `{Operation}Error` with its `TryGet…` accessors and their statuses / B: `RawError`), pagination and server-group bullets **only where they differ from the defaults**, and a **Type sources** table naming the file that declares every type the operation mentions. -- **Shapes live in the source, one type per file.** Every file under `src/SlackWebApi/Models/`, `src/SlackWebApi/Errors/` and `src/SlackWebApi/Requests/` declares exactly one public type named after the file, so a type name *is* its path: take it from the operation's Type sources table (or the kind's directory — records `src/SlackWebApi/Models/`, enums `src/SlackWebApi/Models/Enums/`, typed errors `src/SlackWebApi/Errors/`, request records `src/SlackWebApi/Requests/`, or `src/SlackWebApi/Requests//` for an operation on a controller; an operation with several tags is filed under the first tag it declares) and read the fields, `required` flags, enum values and, on a model, the `[JsonPropertyName]` wire names from that one file (a request record is never serialized and carries none). The compiler is the backstop: a wrong name fails to build. +- **Shapes live in the source, one type per file.** Every file under `src/SlackWebApi/Models/`, `src/SlackWebApi/Errors/` and `src/SlackWebApi/Requests/` declares exactly one public type named after the file, so a type name *is* its path (the directories are under *Layout* below), or take it from the operation's Type sources table. Read the fields, `required` flags, enum values and, on a model, the `[JsonPropertyName]` wire names from that one file, scoped (a request record is never serialized and carries none). The compiler is the backstop: a wrong name fails to build. -**This map is how you traverse the SDK.** Do **not** grep, glob, `find`, or otherwise scan the clone to locate an operation, model, enum, union, or error type — the map (and the name-is-path convention) is the locator. Instead: +**Never grep, glob, `find` or otherwise scan the clone to locate anything** — the map and the name-is-path rule are the locator. Instead: 1. Open `sdk-map.md` and follow its controller table to the operations pages in scope; read every contract fact (signature, error accessors, pagination) by lookup. 2. **Silence means the default.** The index's defaults table states what holds for every operation (throw-only, no pagination, the default server group, inputs as one request record); an operation's block states only what differs. A block silent on pagination has none — take the default and move on rather than opening the source to confirm it. -3. For a **shape** (model fields, enum values, union accessors, a typed error's payload), open the one declaring file the map names — that is the normal flow here, not a fallback — and read it scoped. -4. The **HTTP verb/route and the endpoint's behavioural prose** live on the operation method itself — the XML `` docs in the `Api/{Controller}.cs` file the page header names; what each input means is in the per-member docs on its request record. Read them there when wire-level detail or call-acceptance semantics matter; never reconstruct a route from memory. +3. The **HTTP verb/route and the endpoint's behavioural prose** live on the operation method itself — the XML `` docs in the `Api/{Controller}.cs` file the page header names; what each input means is in the per-member docs on its request record. Read them there when wire-level detail or call-acceptance semantics matter; never reconstruct a route from memory. Keep lookups cheap — the rules that keep a session's context small: -- Collect the contracts for **every** in-scope operation in **one** pass — signatures and error accessors from the map pages, then required fields with wire names and enum values from the declaring files those pages name — into the **contract sheet** in `slack-web-api-plan.md`, then implement from the sheet. Do not re-open a map page or source file per field, and never re-look-up a fact the sheet already carries. +- Collect every in-scope contract in **one** pass into the **contract sheet** in `slack-web-api-plan.md` (format in `dotnet-integrate-slack-web-api`); never re-look-up a fact the sheet already carries. - When you do open a source file, read it **scoped**: with an offset/limit, or a search for the one symbol — never dump a whole file into the conversation. - Never open the SDK's `api-reference.md` — the map supersedes it. ## SDK source — get it first; the map lives inside it -The SDK source is where the map lives, so **getting it is the first step of SDK work this session, not a fallback**: one shallow clone at the recorded ref, into the **system temp directory** (`/slack-web-api-sdk-src/`), reused for the whole session. It is a read-only reference, never in the project repo, and **not** a build dependency. Opening the **one declaring file** a map page names is the normal flow here — that is where model, enum and error shapes live. What stays off-limits is *locating* anything by scanning: every file you open is one the map named, opened scoped, never found by grep. +The SDK source is where the map lives, so **getting it is the first step of SDK work this session, not a fallback**: one shallow clone at the recorded ref, into the **system temp directory** (`/slack-web-api-sdk-src/`), reused for the whole session. It is a read-only reference, never in the project repo, and **not** a build dependency. **Clone once, up front**, into a fresh timestamped folder under `/slack-web-api-sdk-src/`, and reuse that folder for the rest of your session: @@ -89,35 +84,35 @@ git clone --filter=blob:none --branch main https://github.com/context-plugins/sl # Reuse $dir for the rest of your session (it is your clone path). ``` -The source you read is branch `main`: a branch is a moving target, not a pin — it can be regenerated after this plugin ships, and then the map you read describes code the package no longer matches. If a name from the map fails to compile, trust the compiler, re-read the source file the map's row names, and report the mismatch; never patch around it from memory. +The source you read is branch `main`: a branch is a moving target, not a pin — it can move after this plugin ships, and then the map you read describes code the package no longer matches. If a name from the map fails to compile, trust the compiler, re-read the source file the map's row names, and report the mismatch; never patch around it from memory. The clone stays in the system temp directory, and `slack-web-api-plan.md` never carries its path — the plan must stay portable. Then confirm the SDK shape **only** from the clone — not by either of these: -- **Do not decompile or run reflection over the built assembly.** A compiled assembly drops what the source carries and the other skills rely on: the XML ``/parameter doc-comments, the exact parameter names and order, and each method's internal request-builder list. -- **Do not fetch SDK files from the web one at a time** as your way in — `…/blob/…` pages return HTML (not source) and guessed paths fail, which is exactly how ad-hoc fetching breaks. Read the local clone instead; only if you truly cannot clone (`git` is unavailable), fetch a **raw** URL derived from the source repo above — never a `…/blob/…` page. +- **Do not decompile or run reflection over the built assembly.** It drops what the source carries and the other skills rely on: the XML ``/parameter doc-comments and the exact parameter names and order. +- **Do not fetch SDK files from the web one at a time** as your way in — `…/blob/…` pages return HTML, not source. Read the local clone instead; only if you truly cannot clone (`git` is unavailable), fetch a **raw** URL derived from the source repo above — never a `…/blob/…` page. Layout — where the SDK map's file references resolve, relative to the SDK root in the clone (open these directly; do not scan for them): - `src/SlackWebApi/Api/` — one file per controller/group; **this is where the operation methods live** (the HTTP verb and route, and the XML `` docs carrying the endpoint's behavioural prose). The map's per-controller pages name the exact file. -- `src/SlackWebApi/Models/` (+ `src/SlackWebApi/Models/Enums/`) — body and response models, unions and enums; one public type per file, named after the file. -- `src/SlackWebApi/Requests/` — one request record per operation that takes input, carrying the per-member docs for each input; a controller's records sit in `src/SlackWebApi/Requests//` (an operation with several tags is filed under the first tag it declares). +- `src/SlackWebApi/Models/` (+ `src/SlackWebApi/Models/Enums/`) — body and response models, unions and enums. +- `src/SlackWebApi/Requests/` — one request record per operation that takes input, carrying the per-member docs for each input; a controller's records sit in `src/SlackWebApi/Requests//` (an operation on several controllers has one record, in one of their folders — its Type sources table names which). - `src/SlackWebApi/Errors/` — per-operation `{Operation}Error` types (only Case-A operations have one; the map's rows say which case each operation is). - `src/SlackWebApi/Core/` — HTTP infrastructure (the `SdkException` family, `RawError`, auth, retries, `SdkHook`). - `src/SlackWebApi/Servers/`, `src/SlackWebApi/SlackWebApiClient.cs`, `src/SlackWebApi/ServiceCollectionExtensions.cs` — environments, the client, DI. -**Leave the clone where it sits — do not delete it, copy it or edit it.** It is a read-only reference with nothing of yours in it, and keeping it is what lets every later step in this session reuse it instead of cloning again. An edit made in it never reaches the SDK, so report what needs changing instead of patching it; the OS reaps the temp directory on its own, and a future session simply makes its own timestamped clone. +**Leave the clone in place and unedited** — later steps reuse it instead of cloning again, and an edit made in it never reaches the SDK, so report what needs changing instead. The OS reaps the temp directory on its own. ## Idempotency — the real keys are on the map; the injected header is not one -The generator injects an `Idempotency-Key: Guid.NewGuid()` header on **every non-GET operation that does not already declare that header itself** — fresh on every call, invisible to you, and **not** an idempotency key in any meaningful sense: a value that changes per call deduplicates nothing, and Slack Web API may not document reading that header at all. `dotnet-configuration-resilience` explains why a visible header like this is worse than an absent one. +**Every non-GET call sends an `Idempotency-Key` header.** Unless the operation's request record carries that header as a member, its value is a fresh `Guid.NewGuid()` on every call — it deduplicates nothing, and Slack Web API may not read the header at all, so never cite it as a key. -Whether an operation takes a **real**, caller-supplied key is an API fact, visible on that operation's request record: look for a key-shaped member (an idempotency key, a request id) in the record file its **Type sources** table names. Its semantics — retention windows, when it is mandatory — are provider prose, in that member's XML docs and the method's `` in the `Api/` file the page names. Some APIs expose **`If-Match` optimistic concurrency** instead — a different guarantee (reject my write if the resource changed) solving a different problem (lost updates, not duplicates); those members show on the request record too. For every write with no key, the answer is reconciliation — `dotnet-configuration-resilience` — not hope. +Whether an operation takes a **real**, caller-supplied key is visible on that operation's request record: look for a key-shaped member (an idempotency key, a request id) in the record file its **Type sources** table names. Its semantics — retention windows, when it is mandatory — are in that member's XML docs and the method's `` in the `Api/` file the page names. An **`If-Match`** member on the record guards against lost updates, not duplicates. For every write with no key, the answer is reconciliation: `dotnet-configuration-resilience`. ## Sensitive data — check the request models before you log anything -Whether this API's **request** models carry fields you must never log — card or bank numbers, personal data, message content — is a shape question: each request model's declaring file (the map's Type sources table names it) lists every field with its `[JsonPropertyName]` wire name. If the scope touches such a field, three generator facts decide your logging posture (all in `dotnet-configuration-resilience`): JSON request bodies are logged **verbatim** when `LogRequestBody` is on, with no redaction; form bodies are masked only by deny-list; and leaving `options.Logging.LoggerFactory` unset arms the `SLACKWEBAPICLIENT_LOG` environment variable, whose `trace` level forces body logging on with no code change and no deploy. So on any build that can carry such a field: `LogRequestBody` stays off, `LoggerFactory` is set explicitly in production, and your own diagnostics never echo a request body on those paths. +Whether this API's **request** models carry fields you must never log — card or bank numbers, personal data, message content — is a shape question: each request model's declaring file (the map's Type sources table names it) lists every field with its `[JsonPropertyName]` wire name. If the scope touches such a field, the SDK's logging decides your posture (see `dotnet-configuration-resilience`): JSON request bodies are logged **verbatim** when `LogRequestBody` is on, with no redaction; form bodies are masked only by deny-list; and leaving `options.Logging.LoggerFactory` unset arms the `SLACK_WEB_API_LOG` environment variable, whose `trace` level forces body logging on with no code change and no deploy. So on any build that can carry such a field: `LogRequestBody` stays off, `LoggerFactory` is set explicitly in production, and your own diagnostics never echo a request body on those paths. Responses are often safer — many APIs return masked variants of what requests carry raw — but that too is a model-shape fact: check the response model's file before assuming. @@ -125,21 +120,21 @@ Responses are often safer — many APIs return masked variants of what requests On a success the SDK returns only the deserialized body: the HTTP status and headers of a successful call are **not on the return value**, and unless the map's error-handling model notes no-throw `{Operation}Result` siblings for this SDK, there is no non-throwing variant to get them from. On an error, what is reachable depends on the operation's error case — its map row: a Case B `RawError` carries `StatusCode`; a typed Case A body may or may not (see `dotnet-error-handling`). -**Hooks are the SDK's own seam for transport metadata.** `options.Hooks` (client-wide) and `requestOptions.Hooks` (per call, appended after the client-wide list) take `SdkHook` instances; `SdkHook.OnResponse((response, context) => …)` sees every raw `HttpResponseMessage` — status, `Retry-After`, rate-limit budget headers, a request-id echo for correlation — and `SdkHook.OnRequest` the outgoing request. A hook runs **inside the retry pipeline, once per attempt**, so "the" value is the last attempt's; a per-call hook can close over a local, which puts the observed value in scope in the same method's `catch`. `RawClient.ExecuteResult` does return an `ApiResult`, but `RawClient` is `internal sealed`, so hooks — not reflection, and not a `DelegatingHandler` you would otherwise need — are the supported way in. +The status and headers of a successful call (`Retry-After`, rate-limit budgets, a request-id echo) are reachable only through **hooks** — `SdkHook.OnResponse` on `options.Hooks`, or per call on `requestOptions.Hooks`, running once per attempt; see *Hooks* in `dotnet-configuration-resilience`. ## The `dotnet-*` skill names are not unique across plugins -Every APIMatic .NET plugin ships this same set of `dotnet-*` skill names. Copies from the **same generator version** are byte-identical, so between those plugins a collision is harmless. A copy from a **different generator version** is not — it describes a different runtime, and an older plugin's retry eligibility, request-options surface and unknown-field handling all differ from this SDK's. **Load the copy that ships with THIS plugin**: write plugin-qualified names where your harness supports them, and where it does not, confirm the copy you loaded describes the runtime this SDK actually ships — `RequestOptions` carrying both a log level and `Hooks`, and a `src/SlackWebApi/Core/Hooks/SdkHook.cs` in the source. The `X-APIMatic-Gen-Version` wire header does not distinguish these surfaces, so it is not the check. +Every APIMatic .NET plugin ships this same set of `dotnet-*` skill names, and a copy from another plugin may describe a different runtime. **Load the copy that ships with this plugin**: write plugin-qualified names where your harness supports them, and where it does not, confirm the copy you loaded describes the runtime this SDK ships — `RequestOptions` carrying both a log level and `Hooks`, and a `src/SlackWebApi/Core/Hooks/SdkHook.cs` in the source. The `X-APIMatic-Gen-Version` wire header does not distinguish these runtimes, so it is not the check. ## Integration workflow — load the companion skill at each step -You loaded every companion the sheet named before starting (per `dotnet-integrate-slack-web-api`); before you write the code for each step, re-read the one that governs it — even if you have already read the relevant source. Each step calls out the trap the signature hides (in *parens*). A typical integration reaches them in this order: +You loaded every companion the sheet named before starting (per `dotnet-integrate-slack-web-api`); before you write the code for each step, re-read the one that governs it — even if you have already read the relevant source. A typical integration reaches them in this order: -1. **Client & DI setup** — load **dotnet-client-initialization** before you write `new SlackWebApiClient(...)`, build its options, or DI-register it. (*The signature will not tell you:* the `HttpClient`/handler pipeline must be long-lived and reused via `IHttpClientFactory`, not rebuilt per request; the SDK client wrapper over it may be transient.) -2. **Authentication** — load **dotnet-authentication** before you set credentials. The scheme(s) this SDK accepts are the credentials properties on `SlackWebApiClientOptions` — the identity table above names them. (*The signature will not tell you:* set credentials before constructing the client or in the DI callback, and load secrets from configuration rather than hardcoding.) -3. **Calling an endpoint / building a request body** — load **dotnet-calling-endpoints** before the first `client.{ApiGroup}.{Operation}(...)` call. (*The signature will not tell you:* every input goes on the operation's request record — `required` members must be set, the rest are optional or already carry the spec's default; and whether a write takes a real idempotency key is on that record — the injected `Idempotency-Key` header is not one, see *Idempotency* above.) -4. **Models** — load **dotnet-models** the moment a request/response field is not a plain string or number. (*The signature will not tell you:* unions are built with factory methods and read via `TryGet…` (no `new`), enums are `OpenStringEnum` / `OpenIntEnum` records with a generated `Match` — not C# enums, and with no public factory — and unknown response fields are kept on any model that carries an extension-data bag — conventionally `AdditionalProperties`, but a schema that closes itself with `additionalProperties: false` has none, and one that already declares a member of that name pushes the bag to a deduplicated spelling. Check the model's own map row rather than assuming the property is there.) -5. **Error handling** — load **dotnet-error-handling** before you write any `try/catch`. (*The signature will not tell you:* an operation is either Case B (`ApiException`, no typed accessors) or Case A (a typed `{Operation}Error`) — how the API mixes them is its own fact, so confirm each operation's case in its map row; and `TryGetRawError` is not a catch-all on the typed errors. Whether no-throw `…Result` variants exist at all is stated once, in the map's defaults table; never assume one does.) -6. **Configuration & resilience** — load **dotnet-configuration-resilience** when you tune retries, timeouts, the base URL, pagination, or logging. (*The signature will not tell you:* `HttpMethodsToRetry` gates **every** retry trigger, so a `POST` is never resent by default — but a `GET` that hangs costs far more than the `Timeout` value suggests, because the per-attempt timeout is itself retried. `Timeout` is per-attempt not total, `RetryOptions.Disabled()` turns retries off, and there **is** a built-in logger on `options.Logging` — whose `LogRequestBody` does not redact JSON.) -7. **Testing** — load **dotnet-testing** before you stub the SDK. (*The signature will not tell you:* the `HttpClient` constructor argument is the test seam; match the project's existing framework and assertion style.) +1. **Client & DI setup** — load **dotnet-client-initialization** before you write `new SlackWebApiClient(...)`, build its options, or DI-register it. +2. **Authentication** — load **dotnet-authentication** before you set the credentials properties on `SlackWebApiClientOptions` — the identity table above names them. +3. **Calling an endpoint / building a request body** — load **dotnet-calling-endpoints** before the first `client.{ApiGroup}.{Operation}(...)` call; whether a write takes a real idempotency key is on its request record (*Idempotency* above). +4. **Models** — load **dotnet-models** the moment a request/response field is not a plain string or number. A model's extension-data bag for unknown fields is `AdditionalProperties`, a numbered variant of that name on a model that already has a property called that, and absent on a model that admits no extra fields — confirm it in the model's file. +5. **Error handling** — load **dotnet-error-handling** before you write any `try/catch`; confirm each operation's Case A or B in its map row. +6. **Configuration & resilience** — load **dotnet-configuration-resilience** when you tune retries, timeouts, the base URL, pagination, or logging. +7. **Testing** — load **dotnet-testing** before you stub the SDK. diff --git a/plugins/slack/skills/dotnet/dotnet-integrate-slack-web-api/SKILL.md b/plugins/slack/skills/dotnet/dotnet-integrate-slack-web-api/SKILL.md index 03370e86..b7378e73 100644 --- a/plugins/slack/skills/dotnet/dotnet-integrate-slack-web-api/SKILL.md +++ b/plugins/slack/skills/dotnet/dotnet-integrate-slack-web-api/SKILL.md @@ -1,55 +1,66 @@ --- name: "dotnet-integrate-slack-web-api" -description: "MANDATORY FIRST STEP for Slack Web API .NET SDK work in a C#/.NET project — load this BEFORE opening the SDK map or touching any project file; .NET/C# SDK ONLY, never load it for any other language. Applies when asked to integrate Slack Web API in C# — Admin, AdminApps, AdminAppsApproved, AdminAppsRequests, AdminAppsRestricted, AdminConversations, AdminConversationsEkm, AdminConversationsRestrictAccess, AdminEmoji, AdminInviteRequests, AdminInviteRequestsApproved, AdminInviteRequestsDenied, AdminTeams, AdminTeamsAdmins, AdminTeamsOwners, AdminTeamsSettings, AdminUsergroups, AdminUsers, AdminUsersSession, ApiApi, Apps, AppsEventAuthorizations, AppsPermissions, AppsPermissionsResources, AppsPermissionsScopes, AppsPermissionsUsers, Auth, Bots, Calls, CallsParticipants, Chat, ChatScheduledMessages, Conversations, Dialog, Dnd, Emoji, Files, FilesComments, FilesRemote, Migration, Oauth, OauthV2, Pins, Reactions, Reminders, Rtm, Search, Stars, TeamApi, TeamProfile, Usergroups, UsergroupsUsers, Users, UsersProfile, Views, Workflows — or when a Slack Web API .NET SDK call errors or behaves unexpectedly. It carries four binding rules stated NOWHERE else — (1) for implementation work, the plan file slack-web-api-plan.md is written at the project repo root BEFORE any project file is created or edited; (2) dotnet-getting-started and the SDK map it carries are loaded and used for every contract fact, never memory; (3) every dotnet-* skill the contract sheet's REQUIRED READING names is loaded before implementation starts; (4) every sheet row carries one of three labels — a map page, UNVERIFIED, or YOUR CALL — not in the map. Skip it and SDK facts get written from stale memory." +description: "MANDATORY FIRST STEP for any Slack Web API .NET SDK work in C#: integrating Slack Web API, or a Slack Web API .NET SDK call that errors or behaves unexpectedly. Load it before opening the SDK map or touching any project file — it sets the plan-first workflow (slack-web-api-plan.md before any code) and the map-grounding rules. .NET/C# only; never load it for another language." --- # Slack Web API .NET SDK — Workflow (map + skills) -You are the Slack Web API .NET SDK specialist for this task — one agent for every SDK need: planning, answering contract questions, implementing, and fixing SDK errors. Your scope is **C#/.NET only**: if a request concerns any other language or SDK, say so and stop. Your source of truth is the **SDK map that ships inside the SDK source repo** (`sdk-map.md` plus its `map/operations/` pages; model, enum and error shapes live in the source files those pages name), obtained per `dotnet-getting-started`, plus the companion `dotnet-*` skills for usage traps. Your training data on this SDK is stale — every fact you emit must come from a map page or a map-named source file you actually read this session, in that same clone. You never guess, and you never open the SDK's `api-reference.md`. You do all of it yourself — ground, plan, implement, fix — there is no helper agent to delegate to. +You orchestrate this task: the `slack-web-api-planner` agent writes the plan and its contract sheet; you answer contract questions, implement from the sheet and fix SDK errors yourself. Your source of truth is the **SDK map that ships inside the SDK source repo** (`sdk-map.md` plus its `map/operations/` pages; model, enum and error shapes live in the source files those pages name), obtained per `dotnet-getting-started`, plus the companion `dotnet-*` skills for usage traps. Your training data on this SDK is stale — every fact you emit must come from a map page or a map-named source file you actually read this session, in that same clone; you never guess. -**Scope guard:** the APIMatic-generated Slack Web API **.NET SDK** (root namespace `SlackWebApi`) in **C#/.NET projects only**. Unrelated API, or any language other than C#/.NET — do nothing; this skill does not apply. +**Scope guard:** the APIMatic-generated Slack Web API **.NET SDK** (root namespace `SlackWebApi`) in **C#/.NET projects only**. For any other API or language, say so and stop — this skill does not apply. + +## The planner agent + +`slack-web-api-planner` ships with this plugin. It writes `slack-web-api-plan.md` — the plan and its contract sheet — and revises it in place; it writes no project code. Start it the first of these ways your host allows: + +1. **Your subagent tool lists it.** Some hosts list a plugin's agents under the plugin's name, as `slack:slack-web-api-planner`; start it by whichever of the two names your subagent tool lists. +2. **It isn't listed, or you can't start a subagent.** Tell the user in one line that you are writing the plan yourself, then do so as *Step 1* describes. Don't stop to ask. + +However you start it: + +- **Start it on the same model you are running on.** If your subagent tool takes a model, pass your own model; if it has no model option, leave its default. Tell the user in one line which model you started it on. +- **Start it once per integration.** A plan revision is a follow-up message to that same agent; re-start it, carrying the clarification and the plan path, only where your host cannot message it. Never start a second one for the same integration. ## Grounding rules -- **Map for contracts; the map-named file for shapes.** Follow `dotnet-getting-started`'s *SDK map* and *SDK source* sections in full — they define how to obtain the source (the map lives inside it), that reading a model/enum/error shape means opening the one declaring file the map names (routine, scoped), and why locating anything by grep/glob/`find` over the tree is a defect rather than a shortcut. The clone stays in the system temp directory, and `slack-web-api-plan.md` never carries its path — the plan must stay portable. -- **Never grep, glob or `find` the SDK tree to locate something** — the map is the locator, and a type name is its path. Every lookup starts at the map index and ends on the one page (or the one source file) it names. -- **Your contract sheet never leaves a contract fact open for "later."** The map pages and the files they name answer nearly everything — resolve them during planning, not mid-implementation. For the rare in-scope fact even the source cannot settle: if only live traffic could confirm it, convert it into a concrete defensive-coding directive on the sheet and label the uncertainty `UNVERIFIED`. Never leave a row marked for a later source lookup: an open row is how you end up opening source mid-implementation. +- **Map for contracts; the map-named file for shapes** — follow `dotnet-getting-started`'s *SDK map* and *SDK source* sections in full. +- **Your contract sheet never leaves a contract fact open for "later."** The map pages and the files they name answer nearly everything — resolve them during planning. A fact only live traffic could confirm becomes a concrete defensive-coding directive on the sheet, labelled `UNVERIFIED` (§7); never leave a row marked for a later source lookup. - **When you judge how far a contract can be trusted**, the trust judgment may cite ONLY evidence visible in the map or SDK source (e.g. two generated definitions that disagree, a suspicious shared model) — never training-data memory of this API, and never claims about what the live wire "usually" sends. -- **The sheet records Slack Web API's call surface; the application's design is decided at implementation time.** Its persistence, its concurrency rules, and the request contract its own callers must satisfy are not SDK facts. Where an SDK fact forces an application decision, record the fact and its consequence on the sheet, mark the decision `YOUR CALL — not in the map`, and decide it at implementation time against the task. +- **The sheet records Slack Web API's call surface, not the application's design** — its persistence, its concurrency rules, and the request contract its own callers must satisfy. Where an SDK fact forces an application decision, record the fact and its consequence and mark the decision `YOUR CALL — not in the map` (§7), to be decided at implementation time against the task. - **Name only what you have read.** Never name a claim, header or route of the application as though you knew it exists — unless you have read that code. Name configuration by its binding key, never by a raw environment variable, and give the default the map documents where there is one: a setting you invent a name for is a setting no deployment will supply. ## Workflow **If the user opens with a reported SDK error or unexpected Slack Web API behaviour** (not new feature work), go straight to *Step 4 — Fixing SDK errors* below — do not run the plan-first flow for a bug report. Otherwise, for implementation work: -### Step 1 — Plan first: write `slack-web-api-plan.md` (always, for any implementation work) +### Step 1 — Plan first: the planner writes `slack-web-api-plan.md` (always, for any implementation work) -Your FIRST deliverable is `slack-web-api-plan.md` at `/slack-web-api-plan.md` — that exact path, always; never pick another location. It carries the plan and the contract sheet in the format below, and it is the only project-repo file you write before the HARD GATE further down. +Your FIRST action, once you have reached the SDK source (the one prerequisite below that comes before the start), is to start **`slack-web-api-planner`**, as *The planner agent* says, once, with the user's full request and the name of this skill, `dotnet-integrate-slack-web-api`. Dictate in its task the absolute project root, the absolute path of the SDK source you reached — it reads the map and the source there rather than reaching its own — and the absolute path it must write to — `/slack-web-api-plan.md`, that exact path, always; never another location. It grounds and writes the plan and the contract sheet exactly as *How to ground* and the format below describe, and returns the file's path. Those subsections are its instructions and your reference: you read the sheet in that format, and once the code compiles you fill its `TBD` cells and settle its `YOUR CALL — not in the map` entries, as *Step 3* says. Do the rest of the read-only prerequisites below in the same message as the start, and while it works. + +**If you couldn't start the planner** (case 2 in *The planner agent*), *How to ground* and the format are your own instructions: write the file yourself at that path. It is the only project-repo file you write before the HARD GATE further down. #### How to ground (map-first, one pass) 1. Load `dotnet-getting-started`; open `sdk-map.md` (the index). 2. From the index, open the **operations pages** for every controller in scope — take signatures (the request record each operation takes, and its required members), return types, error case (A: typed `ApiException<{Operation}Error>` with its `TryGet…` accessors and payload type / B: `ApiException`), and pagination — remembering that a block silent on a defaults-table point means the default applies. Where an operation's *semantics* decide what you must pass, that prose is the method's XML `` in the `Api/` file the page names, and the per-member docs on its request record: read it there. 3. Open, scoped, the **declaring source file** for every request/response model you will reference — the operation's **Type sources** table names it — and take field names WITH their `[JsonPropertyName]` wire names, `required` flags, nullability, and the envelope shape. Enum value lists and union accessors come from their declaring files the same way. -4. Identify which companion skill governs each step in scope. For each, write the trap note as a **named hazard plus a `MUST load` pointer** — *not* as the resolved answer. Naming the hazard ("what `Timeout` actually bounds") is right; resolving it inline ("`Timeout` is per-attempt") is wrong — a resolved trap gives you no reason to load the skill, and the skill carries the parts a one-line note cannot. **Never restate a companion skill's default or semantics in a trap note — not even when you believe it correct.** Write the *consequence*, not the answer. Contract *facts* are the opposite: those you resolve fully and inline. -5. Collect everything in ONE pass — the whole point is that you never have to rediscover a contract mid-coding. +4. Map each in-scope step to the companion skill that governs it, as a trap note (format in §3 below). + +#### Prerequisites -#### Prerequisites you can run alongside +**Reach the SDK source before you start the planner** (per `dotnet-getting-started`) — the map lives inside it, so this comes before any map work, and the planner reads the copy you reached rather than reaching its own. -These need no SDK knowledge and touch no project file, so do them before or alongside the map work: +The rest need no SDK knowledge and touch no project file, so do them while the planner works — or alongside your own map work, if you are writing the plan yourself: -- reaching the SDK source (per `dotnet-getting-started` — the map lives inside it, so this comes before any map work); - the repo survey (read-only exploration of conventions and layering) — record each convention as *pattern + the ONE exemplar file path to imitate*, NOT inline code snippets: you will read the exemplar at edit time anyway, so a snippet dump gets paid for twice; - `dotnet restore` and a baseline `dotnet build` / `dotnet test` of the UNTOUCHED solution, so later failures are attributable to your changes; - locating the SDK reference and its version in the project; - credentials/environment verification (per the task's secret-handling rules); - setting up your task tracking. -Never use this prerequisite work as a "head start" on implementation: **creating or editing ANY project file before the gate below is a defect**, no matter how obvious the code seems. - #### HARD GATE -**No project-file creation or edits until `slack-web-api-plan.md` exists at that path with every section below filled in.** Starting to code before the sheet exists defeats the plan-first design: the sheet is what keeps SDK facts out of your memory and in the map. The gate bars coding before the sheet exists; it does not bar the read-only prerequisite work above. +**No project-file creation or edits until the planner has RETURNED, `slack-web-api-plan.md` EXISTS at the path you dictated (check it — a helper can misreport where it saved), every section below is filled in, and you have read it.** If you wrote the plan yourself, the gate is the file existing at that path with every section filled in. The read-only prerequisites above are allowed; using them as a "head start" on code is a defect, however obvious the code seems. #### The `slack-web-api-plan.md` format (keep it tight — tables, not prose) @@ -68,28 +79,26 @@ The CONTRACT SHEET also carries a **CROSS-OPERATION INVARIANTS** table, directly **Enforced where** names the member that checks, before the write, that the caller's value is in that set. If the application never reads that set, say so there and add the read — the check is part of the work. `YOUR CALL — not in the map` is not a legal entry in any cell of this table. -3. **Trap notes** — one line per hazard, attached to the step where it bites, each ending in an inline **`MUST load `** pointer. Name the hazard and its consequence; do not resolve it. ⚠⚠ **"Do not resolve it" is the load-bearing half of this rule.** A trap note that answers its own question hands you a usable one-liner — and holding one, you do not open the skill. You implement from the sentence, and everything the skill carries beyond it never reaches the code. So: state the hazard, state what it costs, hand over the skill, and stop. No fix, no snippet, not even a partial answer. A trap note from which you could write correct code without loading the named skill is a defect. -4. **REQUIRED READING** — close the sheet with the de-duplicated list of every `dotnet-*` skill named above, one line each: skill · the step it governs. Write each name so the copy is unambiguous — every APIMatic .NET plugin ships these same skill names, and a bare name gives you no way to tell which one you loaded. State that these are to be loaded **before implementation starts**, and that the sheet deliberately does not carry their contents. This block is mandatory even when the trap notes are few — an integration always writes an error boundary, so `dotnet-error-handling` always appears here. Always include, verbatim, this hazard row: a body that does not match its declared type — a drifted or malformed **2xx** response (a missing `required` member) or a **non-2xx** body that does not match its operation's generated `{Operation}Error` shape — surfaces as `ResponseDeserializationException`, an `ApiException` that keeps the HTTP status and names the target type but is **not** an `ApiException`; a catch ladder that handles only `ApiException` lets it escape, so it must also catch `ResponseDeserializationException` (or `ApiException`). -5. **PRODUCTION READINESS** — the fixed table below, every row carrying a *decision*. Naming a skill in REQUIRED READING does not address a concern; it defers it. `N/A` is a legitimate answer where it is genuinely true, but it must carry its reason. +3. **Trap notes** — one line per hazard, attached to the step where it bites, each ending in an inline **`MUST load `** pointer. State the hazard and what it costs, never the answer — no fix, no snippet, not even a companion default you believe correct: "what `Timeout` actually bounds" is a trap note, "`Timeout` is per-attempt" is not. A trap note from which you could write correct code without loading the named skill is a defect. Contract *facts* are the opposite: resolve those fully and inline. +4. **REQUIRED READING** — close the sheet with the de-duplicated list of every `dotnet-*` skill named above, one line each: skill · the step it governs, each name plugin-qualified (every APIMatic .NET plugin ships these same names), all to be loaded **before implementation starts**. It always lists `dotnet-error-handling`, even when the trap notes are few, and always carries, verbatim, this hazard row: a body that does not match its declared type — a drifted or malformed **2xx** response (a missing `required` member) or a **non-2xx** body that does not match its operation's generated `{Operation}Error` shape — surfaces as `ResponseDeserializationException`, an `ApiException` that keeps the HTTP status and names the target type but is **not** an `ApiException`; a catch ladder that handles only `ApiException` lets it escape, so it must also catch `ResponseDeserializationException` (or `ApiException`). +5. **PRODUCTION READINESS** — the fixed table below, every row recording a *decision*, or `N/A` with its reason where that is genuinely true. A row that only names a skill — even one in REQUIRED READING — restates the concern, or sits blank is **not addressed**. 6. **Assumptions & Blockers** — anything you had to assume about the user's intent, and anything that blocks planning. An empty section is a valid outcome; an invented fact is not. If you expect the provider to reject a call the plan makes, that is a **Blocker**. -7. Every row's **source** cell cites its map page or the map-named declaring file, so a later lookup is one targeted open, not a search. A row with neither to cite is not a contract fact: write `YOUR CALL — not in the map` there instead. Three labels, one order — a fact the map settles cites that page or file; a fact only live traffic can settle is `UNVERIFIED`; a decision about the application is `YOUR CALL — not in the map`. Something that stops you planning goes in §6. +7. **Source labels** — every row's **source** cell is one of: the map page or map-named file it came from (so a later lookup is one targeted open); `UNVERIFIED` (only live traffic can settle it); `YOUR CALL — not in the map` (a decision about the application). Something that stops you planning goes in §6. | # | Concern | The decision the plan must record | | --- | --- | --- | -| 1 | **Credential fail-fast** | Where credentials are bound, and that the host refuses to start when one is missing or blank — rather than discovering it as a 401 on the first call in production. A multi-part credential needs **every** part checked, because a blank part is not a missing one. | +| 1 | **Credential fail-fast** | Where credentials are bound — code, the SDK's own environment variables, a provider or `IConfiguration` — and that the host refuses to start when one is missing or blank, rather than discovering it as an `AuthSchemeException` on the first call in production. The check follows the source: the SDK's variable itself when that supplies the credential, the provider's own source when a provider does. A multi-part credential needs **every** part checked, because a blank part is not a missing one. | | 2 | **Secret sourcing & rotation** | Where the secret comes from, and that the DI registration builds the options object **once at registration** and captures it in the singleton — so a rotated secret does not take effect until the process restarts. If rotation without a restart is required, say how. | -| 3 | **Total timeout budget** | The number the caller actually gets, not the knob. `Timeout` is **per attempt**, so a hung retryable call costs a multiple of it. State the budget and where it is enforced — a `CancellationToken` deadline is the only thing that bounds a whole call. | -| 4 | **Write-retry ownership** | Which of the scope's writes the SDK may resend and which it may not. The default `HttpMethodsToRetry` covers `GET, HEAD, PUT, OPTIONS`, so `POST`/`PATCH`/`DELETE` are never resent by the SDK — and `PUT` **is**. | -| 5 | **Idempotency & ambiguous writes** | For each write in scope: the key it uses, or that none exists. Whether an operation takes a REAL caller-supplied key — and its member name — is on that operation's request record: the record file its map row's **Type sources** table names. The generator-injected `Idempotency-Key` header (`Guid.NewGuid()`, fresh on every call) is **not** a key and must not be cited as one. Where no key exists, record the reconciliation path instead. | -| 6 | **Observability** | What is logged at which level, that **JSON request bodies are logged unredacted** when `LogRequestBody` is on, and which correlation id from the provider's error bodies reaches your own logs. | -| 7 | **Sensitive data** | Whether the scope carries data you would not want in a log — each request model's declaring file lists every field in scope. If it does: `LogRequestBody` stays off **and** `LoggerFactory` is assigned explicitly, so the SDK's log environment variable cannot switch it on from outside the code (see `dotnet-getting-started`). Form bodies are masked only by deny-list, so a key you have not listed prints in the clear. | +| 3 | **Total timeout budget** | The number the caller actually gets, not the knob — state the budget and where it is enforced. What `Timeout` bounds, and what bounds a whole call: `dotnet-configuration-resilience`. | +| 4 | **Write-retry ownership** | Which of the scope's writes the SDK may resend and which it may not — the retried verbs are under *Retries* in `dotnet-configuration-resilience`. | +| 5 | **Idempotency & ambiguous writes** | For each write in scope: its real key — a member of its request record (*Idempotency* in `dotnet-getting-started`) — or that none exists, and then its reconciliation path. The `Idempotency-Key` header every non-GET call sends is **not** a key and must not be cited as one. | +| 6 | **Observability** | What is logged at which level, and which correlation id from the provider's error bodies reaches your own logs. | +| 7 | **Sensitive data** | Whether the scope carries data you would not want in a log (*Sensitive data* in `dotnet-getting-started`). If it does: `LogRequestBody` off, `LoggerFactory` assigned explicitly, and every sensitive form-body key added to the deny-list. | | 8 | **Environment selection** | Which base URLs each deployment talks to. Enumerate the server groups and environment members from the map's *Servers & auth* section — there may be more than one group, and each operation resolves through its own. State which groups the scope touches and what each deployment sets; if the SDK declares no sandbox environment, say how test traffic is kept away from the live system. | | 9 | **Duplicate prevention under concurrency** | For each write a caller can trigger twice: its row in **DUPLICATE CLAIMS** below. If this codebase has nowhere to keep a claim that outlives the process, that is a Blocker in §6, not a row. | | 10 | **Partial results** | For each paged read that can stop at a cap: the field or return type that tells the caller the result was cut short. | | 11 | **Unknown outcomes** | For each write whose connection can fail after the provider may have acted: how the code settles the outcome instead of reporting a failure. | -A reviewer grades that table alone: each row either records a decision or records why it does not apply. A row that points at a skill, restates the concern, or sits blank is **not addressed**. Rows 5, 7, 8, 9 and 11 are the ones where "not addressed" costs something that cannot be recovered afterwards — a duplicate charge or duplicate write, sensitive data in a log, or test traffic sent to a live system. - **DUPLICATE CLAIMS** — one row per write a caller can trigger twice; `none` if the task has no such write. | Write | Where the claim is stored | What rejects the second one | Where that rejection is caught | Where in the code | @@ -125,36 +134,35 @@ Keep the file lean: no copied map pages, no full model dumps, and no clone path ### Step 2 — Required reading (do this before you write any code) -The contract sheet ends with a **REQUIRED READING** block, and its rows carry inline `MUST load ` pointers. **Load every `dotnet-*` skill the sheet names, now, before you start implementing** — not lazily at the step that needs it. The sheet deliberately does *not* carry the how-to: it names the hazard and hands you the skill that resolves it, so an unloaded pointer is a gap in what you know, not a formality. If the sheet names none, load `dotnet-error-handling` anyway — every integration writes an error boundary. - -These are API-agnostic usage skills; loading them is not the same as reading the map. Contract *facts* still come only from the sheet or a map lookup. +The contract sheet ends with a **REQUIRED READING** block, and its rows carry inline `MUST load ` pointers. **Load every `dotnet-*` skill the sheet names, now, before you start implementing** — not lazily at the step that needs it; the sheet names hazards, not their answers. If the sheet names none, load `dotnet-error-handling` anyway — every integration writes an error boundary. Before implementing, check the plan's **Assumptions & Blockers** section: -- Blocker or major assumption → surface it to the user in plain language, get their answer, then revise `slack-web-api-plan.md` in place with targeted edits — edit the changed rows, append the new section. Rewriting the whole file to change a few rows is a defect. +- Blocker or major assumption → surface it to the user in plain language, get their answer, and send it to the SAME planner as a follow-up message (re-start it, carrying the clarification and the plan path, only where your host cannot message it). It revises `slack-web-api-plan.md` in place and replies with the changed rows verbatim: work from that reply, not a re-read of the file. If you wrote the plan yourself, revise it in place with targeted edits — edit the changed rows, append the new section. Rewriting the whole file to change a few rows is a defect. - Minor assumptions only → proceed. Full re-planning only on genuine scope change; for a single missing fact mid-implementation, look it up in the map — never guess. ### Step 3 — Implement from the contract sheet -1. Read `slack-web-api-plan.md` once. Treat its contracts as authoritative — do not re-derive or "double-check" them from memory. A row whose source column says `YOUR CALL — not in the map` is the one exception: that row is a planning-time judgment about YOUR application, so weigh it against the task and follow the task. -2. Implement sequentially, following the repo's own conventions and layering. You loaded the companion skills the sheet named in Step 2 — implement each step in line with the one that governs it. Take every contract *fact* (signatures, wire names, error accessors, enum values) from the contract sheet or a map lookup — never re-derive one from a companion. +1. Read `slack-web-api-plan.md` once and treat its contracts as authoritative — never re-derive or "double-check" one from memory; re-open the map page a row cites. Only a `YOUR CALL — not in the map` row is weighed against the task, and the task wins. +2. Implement sequentially, following the repo's own conventions and layering, each step in line with the companion that governs it. Take every contract *fact* (signatures, wire names, error accessors, enum values) from the contract sheet or a map lookup — never from memory or a companion. 3. After every change: `dotnet build`; fix non-SDK errors yourself. -4. **Any compile or runtime error involving an SDK type or member** (`CS1061`, `CS0117`, `CS0234`, `CS0104`, `CS1503`, `CS7036`, … on `SlackWebApi.*`, or a provider error at runtime) → *Step 4* below. Do not attempt more than one self-fix of an SDK-name error before switching to that procedure — rewriting from the same knowledge that produced the error is guessing. +4. **Any compile or runtime error involving an SDK type or member** → *Step 4* below, after at most one self-fix. 5. Once the code is complete, open each member the **DUPLICATE CLAIMS** and **UNKNOWN OUTCOMES** rows name and confirm it runs when that write runs. Where the code falls short of a row, fix the code, not the row. -6. Run the project's tests (`dotnet test`); verify the integration end to end the way the task demands. +6. Then settle every `YOUR CALL — not in the map` entry in `slack-web-api-plan.md`: overwrite the marker where it stands, in its row or in **Assumptions & Blockers**, with the decision the code made and the member that implements it, so no entry is left open. Never gather the decisions in a section of their own. Name each one in your final report. A `YOUR CALL` left in the plan is a decision nobody recorded; one the report leaves out is a decision the user never saw. +7. Run the project's tests (`dotnet test`); verify the integration end to end the way the task demands. ### Step 4 — Fixing SDK errors (map-first, in place) -A compile or runtime error involving an SDK type or member (`CS1061`, `CS0117`, `CS0234`, `CS0104`, `CS1503`, `CS7036`, … on `SlackWebApi.*`, or a provider error). Resolve it map-first — never patch it by guessing. Load `dotnet-getting-started` first if you have not already — the map is where every fix below comes from. +A compile or runtime error involving an SDK type or member (`CS1061`, `CS0117`, `CS0234`, `CS0104`, `CS1503`, `CS7036`, … on `SlackWebApi.*`, or a provider error). Resolve it map-first — load `dotnet-getting-started` first if you have not already — never by guessing. -1. **Map lookup first.** For an operation symbol, find its block on the controller's operations page; for a model, enum, error or request-record symbol, open the declaring file — its name is its path (`src/SlackWebApi/Models/{Type}.cs`, `src/SlackWebApi/Models/Enums/{Type}.cs`, `src/SlackWebApi/Errors/{Type}.cs`, `src/SlackWebApi/Requests/{Type}.cs`, or `src/SlackWebApi/Requests/{Controller}/{Type}.cs` for an operation on a controller — an operation with several tags is filed under the first tag it declares), or take it from the operation's Type sources table. If the code contradicts what you read (wrong field name, missed response envelope, wrong param order, wrong namespace), that is the fix. Response envelopes are the classic case: response types often wrap their payload in one field — reads go one level down. +1. **Map lookup first.** For an operation symbol, find its block on the controller's operations page; for a model, enum, error or request-record symbol, open the declaring file — its name is its path (the layout in `dotnet-getting-started`'s *SDK source* section), or take it from the operation's Type sources table. If the code contradicts what you read (wrong field name, missed response envelope, wrong param order, wrong namespace), that is the fix. Response envelopes are the classic case: response types often wrap their payload in one field — reads go one level down. 2. **Go one level deeper on a real gap.** If what you read matches the code, or ambiguity remains, open the operation's own method in the `Api/{Controller}.cs` file the page header names — its `` docs and the request it builds — and the per-member docs on its request record, in this session's SDK clone, scoped. Never scan the tree. -3. **Never re-guess.** Rewriting the failing code from the same knowledge that produced the error is prohibited — that is how the error happened. Each failing symbol gets a map/source-grounded answer before its line changes; never mutate payloads, field names, or status handling speculatively to "see if it works". +3. **Never re-guess** from the knowledge that produced the error: each failing symbol gets a map/source-grounded answer before its line changes; never mutate payloads, field names, or status handling speculatively to "see if it works". 4. **Fix in place** — edit only the project files involved in the error, grounded in the map row (or the named source file). 5. **Build to verify, and classify the outcome:** compiles clean → run `dotnet test` on the touched tests when they exist; compile error → the fix is not done, resolve it the same map-first way and rebuild; build blocked (output locked) → the solution is running, so stop it if you started it, or ask the user to rather than killing their process. -6. **Runtime / provider errors** — read the provider's error payload through the documented path: the operation's error case and `TryGet…` accessors from its map row; `dotnet-error-handling` for the Case A/B mechanics. Config-shaped failures (401, wrong host, timeouts): check auth, the server-node/base-URL configuration, and retry semantics before touching call sites. +6. **Runtime / provider errors** — read the provider's error payload through the documented path: the operation's error case and `TryGet…` accessors from its map row; `dotnet-error-handling` for the Case A/B mechanics. Config-shaped failures (`AuthSchemeException`, 401, wrong host, timeouts): check auth, the server-node/base-URL configuration, and retry semantics before touching call sites. If a fix corrects a row in `slack-web-api-plan.md`, correct the row in the file too — the sheet stays the record of what was verified. @@ -164,10 +172,8 @@ A standalone Slack Web API question with no code change: load `dotnet-getting-st ## Anti-patterns — never do these +- **Never create or edit a project file while `slack-web-api-planner` is running**, and never start a second one for the same integration. - **Never write a Slack Web API/SDK fact from memory** — every signature, field name, enum value, and error type in your code must come from the contract sheet or a map lookup. And **never write a call from memory "to fix later".** -- **Do not re-derive or double-check a sheet row from memory** — re-open the one map page it cites. -- **Do not re-derive a contract fact from a `dotnet-*` companion** — they are usage guidance; facts come from the map. - **Do not grep, glob or `find` the SDK tree, and do not open its `api-reference.md`** — the map is the locator; `dotnet-getting-started` says why. - **Do not web-search Slack Web API for an implementation detail** — the map and the SDK source it lives in are the ground truth for THIS SDK version, and `SlackWebApi` is what the generated source declares, not what public docs describe. -- **Do not resolve a trap note inline on the sheet** — name the hazard and the skill. diff --git a/plugins/slack/skills/dotnet/dotnet-models/SKILL.md b/plugins/slack/skills/dotnet/dotnet-models/SKILL.md index c426a34b..146ebd6f 100644 --- a/plugins/slack/skills/dotnet/dotnet-models/SKILL.md +++ b/plugins/slack/skills/dotnet/dotnet-models/SKILL.md @@ -1,6 +1,6 @@ --- name: dotnet-models -description: Working with models in an APIMatic-generated .NET SDK in C# — building request models, required members and nullability, enums, union/AnyOf accessors, and JSON wire names versus C# property names. Load before constructing request payloads or mapping SDK models onto your own domain types. +description: Load before building request payloads for an APIMatic .NET SDK in C# or mapping its models onto your own types — required members and nullability, OneOf/AnyOf unions, open enums, dates, collections, validation attributes, JSON wire names versus C# property names, and unknown fields. --- # Working with models in an APIMatic .NET SDK @@ -17,19 +17,24 @@ installed package. When a field can be one of several types, APIMatic generates a union `record` (under `{RootNamespace}.Models.OneOf` or `.Models.AnyOf`). Build these with the generated **static factory -methods** (one per variant) and read them back with **`TryGet…` methods** — a union has no -object-initializer. JSON (de)serialization is automatic. +methods** (one per variant) and read them back with **`TryGet…` methods** or branch over every variant +with **`Match`** — a union has no object-initializer, and the `Optional` backing each variant is +internal, so the factories, `TryGet…` and `Match` are the whole surface. JSON (de)serialization is +automatic. - `OneOf` — the value is exactly one variant, selected on the wire by a **discriminator property** (e.g. `type`). The generated converter reads that property and switches on it. - `AnyOf` — no discriminator; the converter **tries each variant's schema in declaration order** and takes the first that deserializes. -⚠ **A payload matching no variant throws.** Both converters end in -`throw new JsonException("JSON does not match … schemas: …")`, raised mid-deserialization of the response — -you do not get a null union or an unset variant. A provider that adds a variant your SDK predates turns -into a `JsonException` on a call that was previously fine, so a union field is a place to expect -regeneration pressure. See `dotnet-error-handling` for where that surfaces in a catch ladder. +⚠ **A payload matching no variant does not throw** — it lands in the union's **Unknown** slot as the raw +`JsonElement`: `TryGetUnknown(out var raw)` returns `true`, every `TryGet{Variant}` returns `false`, and +the value serializes back verbatim. A variant the provider adds after your SDK was generated therefore does +not break the call; your code decides what to do with it. A `OneOf` whose discriminator property is missing +or not a string still throws, and so does a known discriminator value whose body does not fit that variant +(a missing required member or a wrong-typed value); both reach your catch as +`ResponseDeserializationException` (see `dotnet-error-handling`). You cannot build an Unknown value +yourself: its factory is not public. ### Construct @@ -43,49 +48,62 @@ var u2 = {Union}.{Variant}(new {Variant} { /* ... */ }); {Union} u4 = new {Variant} { /* ... */ }; // same as {Union}.{Variant}(...) ``` -**A `OneOf`'s variants are always model or enum references** — the generator builds them from the schema's -discriminator mappings, so a `OneOf` has no primitive, list or map variant at all, and every variant it does -have gets an implicit conversion. An `AnyOf` is the open one: primitives and models get a conversion, while -list, map and untyped-object variants do not, and neither do two variants that share one CLR type (the -operators would collide). The factory is the form that always exists — reach for the implicit conversion -only where you can see one. +**A `OneOf`'s variants are always model or enum references** — it has no primitive, list or map variant, and +every variant gets an implicit conversion. On an `AnyOf`, primitive and model variants get one; list, map and +untyped-object variants do not, and neither do two variants that share one CLR type. The factory always +exists — reach for the implicit conversion only where you can see one. ### Read / unwrap ```csharp -// Each variant has a bool TryGet{Variant}(out var value). The member name comes from the -// variant's SCHEMA type, not its CLR type — a `decimal` variant reads TryGetBigDecimal: +// Each variant has a bool TryGet{Variant}([NotNullWhen(true)] out T? value), a bare out T for a +// value type. The member name comes from the variant's SCHEMA type, not its CLR type — a `decimal` +// variant reads TryGetBigDecimal: if (u1.TryGetString(out var s)) { /* use s (string) */ } else if (u1.TryGetBigDecimal(out var d)) { /* use d (decimal) */ } // OneOf: branch over the variants you expect if (resp.{Field}.TryGet{Variant}(out var v)) { /* ... */ } else if (resp.{Field}.TryGet{OtherVariant}(out var w)) { /* ... */ } + +// Match: one on{Variant} handler per variant, in the order the union declares them, then otherwise, +// which receives the raw JsonElement of a value the SDK could not place. +// The Func overload returns a value; the Action overload (same handler names) runs a side effect. +var result = resp.{Field}.Match( + on{Variant}: v => Handle(v), + on{OtherVariant}: w => HandleOther(w), + otherwise: raw => HandleUnrecognised(raw)); ``` +Every `Match` handler is required, `otherwise` included, so a variant you leave out is a compile error — +unlike a `TryGet` chain, whose last `else` the compiler never checks and which silently drops an Unknown +value. Pass the handlers **by name**: a regenerated SDK whose spec adds or reorders a variant changes the +`Match` signature, and two variants of one CLR type (`onString` / `onEmailString`) would swap silently at +a positional call site. When you read with `TryGet…` instead, end the chain with +`TryGetUnknown(out var raw)` or an `else`, so an unrecognised value is handled on purpose. + The factory and `TryGet` names are built from the **variant's schema type name, which is often not its CLR type name** — this is the single easiest thing to get wrong when writing a union branch from memory: | Variant | Factory method | Reader | | --- | --- | --- | -| a model `{Variant}` | `.{Variant}({Variant})` | `TryGet{Variant}(out {Variant})` | -| a big-decimal (CLR `decimal`) | `.BigDecimal(decimal)` | `TryGetBigDecimal(out decimal)` | -| a UUID (CLR `Guid`) | `.Guid(Guid)` | `TryGetGuid(out Guid)` | -| a date-time (CLR `DateTimeOffset`) | `.DateTime(DateTimeOffset)` | `TryGetDateTime(out DateTimeOffset)` | -| a date (**also** CLR `DateTimeOffset`) | `.Date(DateTimeOffset)` | `TryGetDate(out DateTimeOffset)` | -| an email / uri / ip (all CLR `string`) | `.EmailString(...)` / `.UriString(...)` / `.IpString(...)` | `TryGetEmailString(...)`, … | -| a list of `{Variant}` | `.ListOf{Variant}(IReadOnlyList<{Variant}>)` | `TryGetListOf{Variant}(out IReadOnlyList<{Variant}>)` | -| a map of `{Variant}` | `.MapOf{Variant}(...)` | `TryGetMapOf{Variant}(out …)` | - -So a `decimal` variant is `TryGetBigDecimal`, never `TryGetDecimal`; three variants that are all CLR -`string` get three different names; and a `DateTimeOffset` variant is `TryGetDateTime` **or** `TryGetDate` -depending on which the definition declared — two members, one CLR type, and the C# signature cannot tell -them apart. Where two variants would collide outright the generator suffixes them (`String`, `String2`). -The primitive rows apply to `AnyOf` only, since a `OneOf` has no primitive variants. **Take the exact member -name from the contract sheet** (grounded from the SDK map/source) rather than deriving it from -the C# type you see. (Unions use the per-variant factories and `TryGet…` readers shown above; -`TryGetKnownValue` belongs to enums.) The `Optional` backing a union is internal — interact only through the factories and -`TryGet…`. +| a model `{Variant}` | `.{Variant}({Variant})` | `TryGet{Variant}([NotNullWhen(true)] out {Variant}? value)` | +| a big-decimal (CLR `decimal`) | `.BigDecimal(decimal)` | `TryGetBigDecimal(out decimal value)` | +| a UUID (CLR `Guid`) | `.Guid(Guid)` | `TryGetGuid(out Guid value)` | +| a date-time (CLR `DateTimeOffset`) | `.DateTime(DateTimeOffset)` | `TryGetDateTime(out DateTimeOffset value)` | +| a date (**also** CLR `DateTimeOffset`) | `.Date(DateTimeOffset)` | `TryGetDate(out DateTimeOffset value)` | +| an email / uri / ip (all CLR `string`) | `.EmailString(...)` / `.UriString(...)` / `.IpString(...)` | `TryGetEmailString([NotNullWhen(true)] out string? value)`, … | +| a list of `{Variant}` | `.ListOf{Variant}(IReadOnlyList<{Variant}>)` | `TryGetListOf{Variant}([NotNullWhen(true)] out IReadOnlyList<{Variant}>? value)` | +| a map of `{Variant}` | `.MapOf{Variant}(...)` | `TryGetMapOf{Variant}([NotNullWhen(true)] out IReadOnlyDictionary? value)` | + +A reference-type reader is `[NotNullWhen(true)] out T?`: `out var` infers `T?`, and the compiler narrows it to +`T` inside the `if`; outside the check the value may be null. A value-type reader stays a bare `out T`. + +The primitive rows apply to `AnyOf` only. Two variants that would collide outright are suffixed (`String`, +`String2`); a variant named `Unknown`, or named like its own union, takes a `Variant` suffix +(`UnknownVariant`). Each row's `Match` handler is `on` + its factory name (`onBigDecimal`, `onEmailString`, +`onListOf{Variant}`). **Take the exact member name from the contract sheet** (grounded from the SDK +map/source) rather than deriving it from the C# type you see. ## Collections @@ -109,21 +127,16 @@ never a cast to `Dictionary`. ## Dates & numbers -- **A date/time field is not necessarily a `DateTimeOffset?` — check the property type.** The generator - emits `DateTimeOffset?` only where the API definition marks the field as a date/time. Where it does not, - the field is a plain `string?`, frequently carrying a `[RegularExpression]` attribute that *documents* an - RFC-3339 shape without enforcing it (see below). Both are common in the same SDK, and one of the sampled - SDKs has **no** `DateTimeOffset` in its models at all. Take the type from the contract sheet; a - `DateTimeOffset.Parse` written against a field that is already a `DateTimeOffset` will not compile, and a - hand-built string written into a `DateTimeOffset?` field will not either. -- **A `DateTimeOffset` model property carries no converter** — it round-trips as `System.Text.Json`'s - default, ISO-8601 with an offset (`"2024-06-17T15:30:45+00:00"`), *even where the API documents a - date-only shape*. The generator does ship four date converters (ISO-8601, RFC-1123, Unix epoch seconds, - date-only), but it attaches them to **whole-response payloads** — an operation whose response body is a - date scalar, or a list or map of them — not to properties inside a model. So if a field's documented wire shape is `YYYY-MM-DD` and - the property is a `DateTimeOffset?`, what the SDK sends is the full ISO-8601 form, and reconciling that - with the provider is your problem, not the SDK's. Do not hand-format anyway; for your own formatting use - the BCL (`DateTimeOffset.Parse`, `.ToString("O")`), never the SDK's internal converters. +- **A date/time field is not necessarily a `DateTimeOffset?` — check the property type.** It can be a + plain `string?`, often with a `[RegularExpression]` that *documents* an RFC-3339 shape without enforcing it + (see below); both occur in one SDK, and some SDKs have no `DateTimeOffset` at all. Take the type from the + contract sheet: `DateTimeOffset.Parse` against a field that is already a `DateTimeOffset` will not compile, + nor will a hand-built string written into a `DateTimeOffset?` field. +- **A `DateTimeOffset` model property round-trips as `System.Text.Json`'s default**, ISO-8601 with an offset + (`"2024-06-17T15:30:45+00:00"`), *even where the API documents a date-only shape* — a field documented as + `YYYY-MM-DD` is sent in the full form, and reconciling that with the provider is yours. Do not + hand-format it; for your own formatting use the BCL (`DateTimeOffset.Parse`, `.ToString("O")`), never the + SDK's internal converters. - Money/quantities may be `string`, `decimal`, or a string-or-number `AnyOf` union; the model's property type is the source of truth. Numeric types vary per SDK (`int`, `long`, `double`, …) — take the exact type from the contract sheet; don't assume `double`. @@ -164,13 +177,13 @@ enums. Use the static constants; they convert implicitly to their underlying val (or the implicit conversion) yields the raw wire value — but **not** `ToString()`, see the warning below — and `==` compares by value, so two instances read from the same wire value are equal. -There is **no public factory**: `{EnumType}.FromValue(...)` does not exist, and a value the spec does not -declare cannot be constructed in code. Resolve a raw value with `{EnumType}.TryGetKnownValue(value, out var +There is **no public factory**: `{EnumType}.FromValue(...)` does not exist, and an undeclared value cannot +be constructed in code. Resolve a raw value with `{EnumType}.TryGetKnownValue(value, out var known)` — exact, case-sensitive — and guard a received value with `instance.IsKnownValue()`. A server value the SDK does not declare still deserializes (enums are open on reads), round-trips unchanged with the server's own casing, and compares without constructing one: `instance.Is("raw")` or `instance == "raw"`. -Branch with the generated `Match`, not a `switch`: one `on{Member}` arm per declared value in spec order, +Branch with the generated `Match`, not a `switch`: one `on{Member}` arm per declared value in declaration order, then `otherwise`, which receives the raw wire value of anything undeclared. Pass the arms by name — the parameters are positional, and a regenerated SDK that adds or reorders a value changes the signature (a source break, and `MissingMethodException` for an assembly compiled against the old shape). @@ -212,18 +225,17 @@ See [reference.md](reference.md) for full string- and int-enum declarations and Models declare their wire properties explicitly. An object or allOf model also carries a `[JsonExtensionData]` bag — `public AdditionalProperties AdditionalProperties { get; init; } = [];` -(`{RootNamespace}.Core.Models`) — so unknown JSON fields are **kept**, not dropped: a field the provider -added after this SDK was generated survives deserialization and round-trips back out on serialize. A -schema with `additionalProperties: false` has no bag, a `OneOf`/`AnyOf` union has none of its own, and the -bag is named `AdditionalProperties2` when a spec property's C# name is already `AdditionalProperties`. -Take the bag's name and type from the contract sheet. +(`{RootNamespace}.Core.Models`) — so unknown JSON fields are **kept**: a field this SDK does not model +survives deserialization and round-trips back out on serialize. A model that admits no extra fields has no +bag and drops them, a `OneOf`/`AnyOf` union has none of its own, and the bag is named `AdditionalProperties2` +when the model already has an `AdditionalProperties` property. Take the bag's name and type from the contract +sheet. Read one with `response.AdditionalProperties.TryGetValue("field_name", out var value)` (deserializes the captured `JsonElement` to `T`), or `TryGetElement` for the raw `JsonElement`; `Set(key, value)` adds -one to a request. When the schema types its extra fields, the bag is `AdditionalProperties`, whose -`TryGetValue("field_name", out var value)` takes no type argument. -Two cautions: the keys are **wire names** (there is no C# property, so nothing maps the -casing for you), and a field appearing here rather than as a typed property is a regeneration signal — -prefer regenerating the SDK over building program logic on stringly-typed lookups. The -bag itself has no `[JsonPropertyName]` and no wire name — its contents merge -into the model's own JSON object. +one to a request. When every extra field has one type, the bag is `AdditionalProperties`, whose +`TryGetValue("field_name", out var value)` takes no type argument. Two cautions: the keys are **wire names** +(there is no C# property, so nothing maps the casing for you), and a field appearing here rather than as a +typed property is one this SDK version does not type — prefer an SDK version that does over building +program logic on stringly-typed lookups. The bag itself has no `[JsonPropertyName]` and no wire name — its +contents merge into the model's own JSON object. diff --git a/plugins/slack/skills/dotnet/dotnet-models/reference.md b/plugins/slack/skills/dotnet/dotnet-models/reference.md index e780a4e6..1147fca3 100644 --- a/plugins/slack/skills/dotnet/dotnet-models/reference.md +++ b/plugins/slack/skills/dotnet/dotnet-models/reference.md @@ -1,19 +1,5 @@ # Models reference (APIMatic .NET) -## Date/time - -**Check the property type first.** A date/time field is `DateTimeOffset?` only where the API definition -marks it as a date/time; otherwise it is a plain `string?`, often with a `[RegularExpression]` attribute -documenting (not enforcing) an RFC-3339 shape. Both appear in generated SDKs, and some SDKs contain no -`DateTimeOffset` at all. - -Where it *is* a `DateTimeOffset`, the property carries **no converter attribute** and round-trips as -`System.Text.Json`'s default — ISO-8601 with offset, `"2024-06-17T15:30:45+00:00"` — even where the API -documents a date-only shape. The four generated date converters (ISO-8601, RFC-1123, Unix epoch seconds, -date-only) are attached to whole-response payloads, not to model properties. Work with `DateTimeOffset` -directly and let the SDK serialize it; for formatting in your own code use the BCL -(`DateTimeOffset.Parse`, `.ToString("O")`, …), not the SDK's internal converters. - ## String-enums Every enum — schema enums under `Models/Enums/` and the server-environment enum under `Servers/` — is a @@ -77,22 +63,24 @@ public sealed record {EnumType} : OpenIntEnum<{EnumType}> long n = {EnumType}.On; // implicit conversion to long ``` -Member names come from the spec's `x-enum-varnames` when it declares them, otherwise `Value{n}` / -`Negative{n}` from the value itself. +A member with no declared name is `Value{n}` / `Negative{n}`, from the value itself. ## Union types — finding the exact members For a `OneOf`/`AnyOf` type, the contract sheet lists the exact members (grounded from the SDK map/source). Each variant `{V}` produces: -- a factory `static {Union} {V}({V} value)` (the parameter type usually equals the variant type name), and -- a reader `bool TryGet{V}(out {V} value)`. +- a factory `static {Union} {V}({V} value)` (the parameter type usually equals the variant type name), +- a reader `bool TryGet{V}([NotNullWhen(true)] out {V}? value)` for a reference type, `bool TryGet{V}(out {V} value)` + for a value type, and +- a handler `on{V}` in both `Match` overloads (`Func<{V}, TResult>` / `Action<{V}>`), in declaration order, + before the closing `otherwise` (`Func` / `Action`). + +Every union also has `bool TryGetUnknown(out JsonElement value)` for a value the SDK could not place. Its +factory is internal: application code can read such a value and send it back, but cannot create one. -A `OneOf`'s variants are always model/enum references (they come from the schema's discriminator -mappings), and each gets an `implicit operator {Union}({Variant})`. On an `AnyOf`, primitive and model -variants get one; list, map and untyped-object variants do not, and neither do two variants sharing one CLR -type. Unions are immutable records — there are no object-initializers and no way to mutate -one after construction. +Which variants also get an `implicit operator {Union}({Variant})` is in the SKILL. Unions are immutable +records — there are no object-initializers and no way to mutate one after construction. ## Notes @@ -102,12 +90,3 @@ one after construction. `required` property, which writes `null` when its type is nullable (`public required string? Reason`), and a non-optional property with a default (`public long Priority { get; init; } = 1L;`), whose type cannot hold null. There is no way to send an explicit `null` for an optional property; the difference matters on a PATCH. -- Unless its schema sets `additionalProperties: false`, an object or allOf model ends with a - `[JsonExtensionData]` bag, usually `public AdditionalProperties AdditionalProperties - { get; init; } = [];` — unknown response fields are captured there (keyed by **wire name**) and - round-trip on serialize. See the SKILL's *Unknown / future fields* for the read/write API and the - cautions. On the older 4.0.0 surface this property does not exist and unknown fields are dropped — - check the core-surface stamp before carrying this expectation across SDKs. -- Validation attributes (`[StringLength]`, `[RegularExpression]`, `[MaxLength]`, `[MinLength]`) are - transcribed from the API definition and are **never evaluated by the SDK** — see the SKILL for what to do - about that. diff --git a/plugins/slack/skills/dotnet/dotnet-testing/SKILL.md b/plugins/slack/skills/dotnet/dotnet-testing/SKILL.md index 720a21eb..b7b008f0 100644 --- a/plugins/slack/skills/dotnet/dotnet-testing/SKILL.md +++ b/plugins/slack/skills/dotnet/dotnet-testing/SKILL.md @@ -1,6 +1,6 @@ --- name: dotnet-testing -description: Testing code that calls an APIMatic-generated .NET SDK in C# — which seam to fake, covering error and edge paths, asserting real behaviour rather than execution, and keeping tests independent of SDK internals. Load before writing tests for the integration layer. +description: Load before writing tests for code that calls an APIMatic .NET SDK in C# — the HttpClient stub seam, error and retry paths, faking the clock, constructing SDK exceptions directly, and asserting the outgoing request. --- # Testing code that uses an APIMatic .NET SDK @@ -57,10 +57,19 @@ static {Api}Client ClientReturning(HttpStatusCode status, string json) { Content = new StringContent(json, System.Text.Encoding.UTF8, "application/json") }); - return new {Api}Client(new HttpClient(handler), new {Api}ClientOptions { /* auth not needed for stubs */ }); + return new {Api}Client(new HttpClient(handler), new {Api}ClientOptions + { + {Credential} = "test-token", // one placeholder per credential the operations under test require + }); } ``` +**Set every credential the operations under test require, even against a stub.** An unset required +credential throws `AuthSchemeException` before the stub sees a request. A value set in code also shields +the test from any `{API}_*` environment variable on the machine — `{API}` being the SDK name in upper snake +case. For an OAuth2 scheme, see *Test a client with OAuth credentials*: the placeholder makes the stub's +first request the token `POST`. + ## Test a success path ```csharp @@ -77,12 +86,9 @@ public async Task ReturnsDeserializedBody() ## Test an error path -Endpoint methods throw `ApiException` on non-2xx (see `dotnet-error-handling`). `TError` is the -operation's `{Operation}Error` model (**Case A**) for operations that have a generated `{Operation}Error` -type, or `RawError` **directly** (**Case B**) otherwise — so assert the type that matches your operation. -Whichever the case, the exception itself carries `StatusCode`, `Headers` and `ContentType` (from -`ApiException`) plus the failed call's `Method` and `RequestUri` (from the `SdkException` root), and its -`Message` is the call and the status — `"POST https://host/path returned 422 (UnprocessableEntity)."`. +Endpoint methods throw `ApiException` on non-2xx — `{Operation}Error` (**Case A**) or `RawError` +(**Case B**); see `dotnet-error-handling` — so assert the type that matches your operation. The exception +carries `StatusCode`, `Headers`, `ContentType`, `Method` and `RequestUri`. **Case A — typed `{Operation}Error`:** @@ -99,17 +105,13 @@ public async Task ThrowsOnApiError() () => client.{ApiGroup}.{Operation}(request, cancellationToken: default)); Assert.Equal(HttpStatusCode.UnprocessableEntity, ex.StatusCode); // the status is on the exception - // ex.Error is the typed ApiError. For a status the operation maps to a typed body (e.g. 422), assert the - // typed accessor — its name embeds the body type; the contract sheet lists the exact accessor name. - // TryGetRawError is FALSE for those statuses, so don't assert through it here: + // Assert the accessor for this status (name from the contract sheet); TryGetRawError is false here. Assert.True(ex.Error.TryGetSomeTypedBody(out var typed)); - // ...assert on 'typed'. TryGetRawError fires ONLY for a status that falls to the error factory's - // default arm. A status with its own RawError accessor — TryGetNoContent, say — populates that - // accessor and leaves TryGetRawError false, so assert the specific one. + // ...assert on 'typed'. } ``` -**Case B — `ApiException`** (e.g. read/list/find/archive/delete operations). Here `ex.Error` *is* +**Case B — `ApiException`.** Here `ex.Error` *is* the `RawError` — there is no `TryGet*` / `TryGetRawError`; read it directly: ```csharp @@ -123,11 +125,11 @@ Assert.Equal(HttpStatusCode.UnprocessableEntity, ex.StatusCode); // same value // You can also assert the deserialized error body: ex.Error.ReadAsString() / ex.Error.ReadAsJson(). ``` -**A body that does not match the model is a third outcome.** Stub a 2xx whose JSON does not fit the -response type — or an error status whose body does not fit the `{Operation}Error` template — and the call -throws `ResponseDeserializationException`: an `ApiException` (so `StatusCode` tells you which of the two it -was) but **not** an `ApiException`, carrying the `TargetType` it tried to build and the -`JsonException` as `InnerException`. Lock this down for any operation whose provider is known to drift: +**A body that does not match the model is a third outcome.** A 2xx whose JSON does not fit the response type, +or an error body that does not fit `{Operation}Error`, throws `ResponseDeserializationException` (see +`dotnet-error-handling`); its `StatusCode` says which. A `OneOf` or `AnyOf` response type is the exception: a +body no variant accepts lands in its Unknown slot (see `dotnet-models`), so assert `TryGetUnknown` there +instead of a throw. Lock it down for any operation whose provider is known to drift: ```csharp var client = ClientReturning(HttpStatusCode.OK, """{ "{resource}": "not-an-object" }"""); @@ -141,9 +143,8 @@ Assert.Equal(typeof({ReturnType}), ex.TargetType); ## Test the result-style (`ApiResult`) variant -If the operation exposes the optional non-throwing `{Operation}Result` sibling (see `dotnet-error-handling`), -there is nothing to catch — stub the response and assert on the returned `ApiResult` -directly. The status code and headers are available on both the success and failure outcomes. +If the operation has a `{Operation}Result` sibling (see `dotnet-error-handling`), there is nothing to catch — +assert on the returned `ApiResult`; status and headers are on both outcomes: ```csharp using {RootNamespace}.Core.Models; // ApiResult @@ -169,22 +170,21 @@ public async Task ResultVariantReportsFailureWithoutThrowing() With OAuth credentials set, the first request your stub sees is the token `POST`. `ClientReturning` answers every request alike, so give `StubHandler` a responder that returns queued responses, a token response such as `{ "access_token": "t", "token_type": "Bearer" }` first. The token is cached, so two calls make three -requests. Or keep the credentials set and give `options.{Scheme}TokenStrategy` a stub that returns -`new OAuthToken { AccessToken = "t", TokenType = "Bearer" }` (for authorization code, an -`OAuthTokenRefreshable`, with `TryRefreshToken` returning `null`), because a strategy without credentials is -never used. Either way, an authorization-code client also needs a `PromptForAuthorizationCode` that returns a -fixed code. -For a bad-credentials test, answer the token request with a 4xx and assert `AuthSchemeException`. +requests. An authorization-code client also needs a `PromptForAuthorizationCode` that returns a fixed code. +A `401` on an authenticated call makes the SDK drop the token, fetch a new one and re-send once, so a stub that +answers `401` sees a second token request and a second call before the `401` reaches the test. +For a bad-credentials test, answer the token request with a 4xx and assert `AuthSchemeException`; for a missing +credential, leave the property unset (and its `{API}_*` environment variable too) and assert +`AuthSchemeException` before any request reaches the stub. ## Fake the clock The SDK reads time through exactly one seam — `{Api}ClientOptions.TimeProvider` (default `TimeProvider.System`). Retry backoff, `Retry-After`, the per-attempt timeout, the SSE idle timeout, OAuth2 -token expiry and the logged request durations all follow it, so one fake provider drives them together and -a retry test no longer sleeps through `1s + 2s + 4s` of real backoff. Use a provider that **implements -timers** — `FakeTimeProvider` from `Microsoft.Extensions.TimeProvider.Testing` — because the retry delay -and the idle window are timers on the provider: a `GetUtcNow`-only fake throws when the SDK asks it for a -timer, which is deliberate and better than a silent real sleep. +token expiry and the logged request durations all follow it, so one fake provider drives them together with +no real sleeps. Use a provider that **implements timers** — `FakeTimeProvider` from +`Microsoft.Extensions.TimeProvider.Testing` — because the retry delay and the idle window are timers on the +provider: a `GetUtcNow`-only fake throws when the SDK asks it for a timer. ```csharp using Microsoft.Extensions.Time.Testing; // FakeTimeProvider (Microsoft.Extensions.TimeProvider.Testing) @@ -192,7 +192,11 @@ using Microsoft.Extensions.Time.Testing; // FakeTimeProvider (Microsoft.Extens var clock = new FakeTimeProvider(); var responses = new Queue([HttpStatusCode.ServiceUnavailable, HttpStatusCode.OK]); var handler = new StubHandler(_ => new HttpResponseMessage(responses.Dequeue()) { Content = new StringContent("{}") }); -var client = new {Api}Client(new HttpClient(handler), new {Api}ClientOptions { TimeProvider = clock }); +var client = new {Api}Client(new HttpClient(handler), new {Api}ClientOptions +{ + {Credential} = "test-token", // as in ClientReturning + TimeProvider = clock, +}); var call = client.{ApiGroup}.{Operation}(request, cancellationToken: default); // a GET: retryable clock.Advance(TimeSpan.FromSeconds(2)); // past the 1s backoff (+ up to 500ms jitter) @@ -202,10 +206,8 @@ Assert.Equal(2, handler.Requests.Count); ``` The awaited call does not complete until the fake clock moves past the backoff — start the call, `Advance`, -then `await`. Under DI, register the fake as the container's `TimeProvider` (before *or* after -`Add{Api}Client` — order does not matter) and the SDK seeds the option from it; an explicit -`o.TimeProvider = clock` in the configure callback wins over the container. The SDK never registers a -`TimeProvider` itself, so nothing of yours is overwritten. +then `await`. Under DI, register the fake as the container's `TimeProvider` (either order) or set +`o.TimeProvider = clock` in the configure callback (see **dotnet-configuration-resilience** § *The clock*). ## Construct an SDK exception directly @@ -250,13 +252,13 @@ Because the stub captures `LastRequest`, you can assert method, path, query, hea ```csharp var handler = new StubHandler(_ => new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent("{}") }); -var client = new {Api}Client(new HttpClient(handler), new {Api}ClientOptions()); +var client = new {Api}Client(new HttpClient(handler), new {Api}ClientOptions { {Credential} = "test-token" }); await client.{ApiGroup}.{Operation}(request, cancellationToken: default); Assert.Equal(HttpMethod.Post, handler.LastRequest!.Method); Assert.Contains("/expected/path", handler.LastRequest!.RequestUri!.AbsolutePath); -Assert.Contains("per_page=20", handler.LastRequest!.RequestUri!.Query); // query params are snake_case on the wire +Assert.Contains("per_page=20", handler.LastRequest!.RequestUri!.Query); // the wire name, not the C# property // Assert the serialized request body of a POST/PUT/PATCH: var sentJson = handler.LastBody; // NOT LastRequest.Content — see below @@ -266,31 +268,23 @@ Assert.Contains("\"expected_field\"", sentJson); ## Notes - ⚠ **Read the request body inside the handler, never off the captured request afterwards.** The SDK - disposes the request content in a `finally` that runs per attempt, *inside* the pipeline — so by the time - your awaited call returns, `handler.LastRequest.Content.ReadAsStringAsync()` throws - `ObjectDisposedException`. That is why the stub above buffers `Bodies` during `SendAsync`. Everything - else on the captured `HttpRequestMessage` — method, URI, headers — survives and can be asserted normally. + disposes the request content after each attempt, so once your awaited call returns, + `handler.LastRequest.Content.ReadAsStringAsync()` throws `ObjectDisposedException` — hence `Bodies` in the + stub above. Method, URI and headers on the captured `HttpRequestMessage` survive and can be asserted. - Mocking libraries (Moq, NSubstitute) work too — mock `HttpMessageHandler.SendAsync` (it's `protected`, so use `Protected()` with Moq). The hand-written stub above avoids that friction. -- A stubbed retryable response — the default set is exactly `408, 429, 500, 502, 503, 504`, not all `5xx` - — on a retryable method will be retried by the SDK before the call returns. `HttpMethodsToRetry` (`GET/HEAD/PUT/OPTIONS` by default) gates **every** trigger, so a - `POST` retries on nothing — not a `503`, not a thrown `HttpRequestException`, not the per-attempt timeout - — unless you add its verb to the list (see `dotnet-configuration-resilience`). To observe retries firing, - stub a `GET` that returns `503` then `200` and count invocations. -- **Status faults and transport faults are separate retry triggers** — the SDK distinguishes them itself - (`RetryAttempt.Reason` is `RetryReason.Status(...)` *or* `RetryReason.Failure(Exception)`), and a third, - the per-attempt timeout, arrives as `RetryReason.Failure(TimeoutRejectedException)`. A test that stubs a - `503` therefore proves nothing about what happens when the *connection* fails. The verb filter holds all - three at one send for a `POST` — which is exactly the property worth locking down with a test, because it - is a *configuration* guarantee and someone widening `HttpMethodsToRetry` for the read path silently - removes it. What reaches the test is the SDK's wrapper, never the raw `HttpRequestException`: a failed - send surfaces as `SdkConnectionException` (message `"POST https://host/path could not be sent: connection - reset"`, the raw exception as `InnerException`), and an exhausted per-attempt timeout as - `SdkTimeoutException` with `Timeout` set to the window that elapsed. +- **Retries run before the call returns.** A stubbed `408`/`429`/`500`/`502`/`503`/`504` (not every `5xx`) on + `GET`/`HEAD`/`PUT`/`OPTIONS` is retried — stub `503` then `200` and count requests; a `POST` is retried on + nothing but an OAuth2 `401`, which every verb re-sends once (see `dotnet-configuration-resilience`). Status and transport faults are separate triggers + (`RetryAttempt.Reason` is `RetryReason.Status(...)` or `RetryReason.Failure(...)`), so a `503` stub proves + nothing about a connection failure — and the one-send `POST` is worth a test, since widening + `HttpMethodsToRetry` silently removes it. A thrown `HttpRequestException` surfaces as + `SdkConnectionException` with the raw exception as `InnerException`, and an exhausted per-attempt timeout + as `SdkTimeoutException`: ```csharp // Transport fault: the stub throws instead of answering, then we count what the server actually received. var handler = new StubHandler(_ => throw new HttpRequestException("connection reset")); - var client = new {Api}Client(new HttpClient(handler), new {Api}ClientOptions()); + var client = new {Api}Client(new HttpClient(handler), new {Api}ClientOptions { {Credential} = "test-token" }); var ex = await Assert.ThrowsAsync( () => client.{ApiGroup}.{Operation}(request, cancellationToken: default)); @@ -298,10 +292,8 @@ Assert.Contains("\"expected_field\"", sentJson); Assert.IsType(ex.InnerException); Assert.Equal(1, handler.Requests.Count(r => r.Method == HttpMethod.Post)); // no resend ``` -- **Your own cancellation is the one thing the SDK never wraps.** A token you cancel surfaces as the usual - `OperationCanceledException` / `TaskCanceledException`, not as an `SdkException` — so a test that cancels - mid-call asserts on the framework type, and a `catch (SdkException)` in the code under test must be - expected *not* to fire. +- **Your own cancellation surfaces as `OperationCanceledException`**, never an `SdkException` — assert the + framework type, and expect a `catch (SdkException)` in the code under test *not* to fire. - For DI-based code, the SDK's `Add{Api}Client` resolves the **default (unnamed)** `IHttpClientFactory` client, so register your stub on that one, then resolve `{Api}Client` from the provider: ```csharp @@ -309,8 +301,6 @@ Assert.Contains("\"expected_field\"", sentJson); services.AddHttpClient(Options.DefaultName).ConfigurePrimaryHttpMessageHandler(() => stubHandler); var client = services.BuildServiceProvider().GetRequiredService<{Api}Client>(); ``` - A `TimeProvider` registered in the same container is picked up by the SDK automatically — see *Fake the - clock* below. - To look up an operation's signature, its request type, or a `{Operation}Error`'s accessor names, take them from the contract sheet (grounded from the SDK map/source) — not a decompiled or reflected view of the installed package, and not memory. diff --git a/plugins/slack/skills/python/python-authentication/SKILL.md b/plugins/slack/skills/python/python-authentication/SKILL.md index 87665c39..4b770f4e 100644 --- a/plugins/slack/skills/python/python-authentication/SKILL.md +++ b/plugins/slack/skills/python/python-authentication/SKILL.md @@ -1,6 +1,6 @@ --- name: python-authentication -description: Authentication for an APIMatic-generated Python SDK — supplying credentials in typed or dict form, the scheme shapes, the managed OAuth2 token lifecycle and its caching, what a failed token fetch actually raises (and why it bypasses the non-raising response mode), and loading secrets safely. Load before wiring credentials into the client, or when a call fails with 401/403. +description: Load before setting credentials on an APIMatic-generated Python SDK client, or when a call fails with 401/403 or a token fetch fails. Covers each scheme's constructor keyword in typed or dict form — Basic, bearer, API key and the three OAuth2 grants — the managed token lifecycle and caching, composite schemes, what a failed token fetch raises, and loading secrets. --- # Authenticating an APIMatic Python SDK client @@ -16,22 +16,19 @@ dict of the same keys; set the one(s) your API uses, then construct the client ( To see which schemes a specific SDK accepts, read the **credentials keywords on its client constructor** — those are the source of truth (take them from the contract sheet, grounded in the SDK map's constructor-keyword table and its *Servers & auth* section, not from recall). -`{root_package}/auth.py` is the cheap cross-check: -its `AuthSchemes` holder carries exactly one field per declared scheme, and the field names *are* the -constructor keywords. The `{root_package}/core/auth/schemes/` directory ships *every* scheme the -generator supports as shared runtime code regardless of what the API accepts, so never infer a scheme -from that directory. (An SDK whose API uses only OAuth2 client credentials, for instance, exposes a -single `{oauth2}=` keyword and its `{oauth2}_token_source=` override.) +`{root_package}/auth.py` is the cheap cross-check: its `AuthSchemes` holder carries exactly one field +per declared scheme, named as the constructor keyword. Never infer a scheme from +`{root_package}/core/auth/schemes/`: it ships every scheme kind, whatever the API accepts. (An SDK +whose API uses only OAuth2 client credentials, for instance, exposes a single `{oauth2}=` keyword and +its `{oauth2}_token_source=` override.) The credential classes below live under `{root_package}.core` and are the **same across all APIMatic -Python SDKs**; only the **keyword names** are generated per-API — each is the security scheme's id from -the spec, snake_cased (hence the `{...}` placeholders). +Python SDKs**; only the **keyword names** differ per SDK — each is the scheme's id, snake_cased (hence +the `{...}` placeholders). ## The two spellings -Every credential keyword accepts a typed model or a mapping, and they are exactly equivalent — a -`coerce` classmethod is the single place the dict form is resolved, so the two cannot produce different -requests: +Every credential keyword accepts a typed model or a mapping, and the two produce identical requests: ```python from {root_package}.core import ClientCredentials @@ -74,15 +71,14 @@ its discovery document says how a token is obtained, not how it is sent. ## API key (header, query, or cookie) The key is sent as a header, query parameter, or cookie — its placement and name are fixed by the -generated scheme. Set the configured key keyword to your key string: +SDK's scheme. Set the configured key keyword to your key string: ```python client = {Client}({api_key}="API_KEY") ``` A query-placed key is percent-encoded exactly as an endpoint's own query parameter; a cookie-placed key -is sent verbatim, because RFC 6265's `cookie-value` alphabet already admits every character a base64 -key uses and encoding it would corrupt the credential. +is sent verbatim. > **Applies only when the SDK declares an OAuth2 scheme.** The next five sections — the three grants, > the managed token lifecycle, and the token-fetch failure mode — describe machinery that exists only @@ -105,10 +101,9 @@ client = {Client}({oauth2}=ClientCredentials( pre-join it yourself, or you send one scope literally named `"a b"`. Omit it to get whatever the client's default scopes are. -When the flow declares a scope vocabulary, the generator emits a `Literal` alias for it in -`{root_package}/auth.py` (`{Flow}Scope`) and types `scopes` by that alias — so a scope the flow does not -document fails the type check at the call site instead of the request at the provider. A flow that -declares no scopes has no alias, and `scopes` is a plain `list[str] | None`. +Where `{root_package}/auth.py` declares a `{Flow}Scope` `Literal` alias, `scopes` is typed by it — so +a scope the flow does not document fails the type check at the call site instead of the request at the +provider. A flow with no alias takes a plain `list[str] | None`. ## OAuth 2.0 — authorization code (3-legged, with PKCE) @@ -168,20 +163,18 @@ is the part that matters: - **The token is fetched lazily, on the first authenticated call** — not at construction. A client built with bad credentials constructs perfectly happily; the failure surfaces at the first operation. -- The fetch is a `POST` to the token endpoint derived from the client's `base_url`, form-encoded, with - the client id and secret sent per the placement the spec declares — commonly HTTP Basic - (`client_secret_basic`, both halves percent-encoded before base64), otherwise in the form body - (`client_secret_post`). +- The fetch is a form-encoded `POST` to the token endpoint derived from the client's `base_url`, with + the client id and secret sent as HTTP Basic (`client_secret_basic`) or in the form body + (`client_secret_post`), per the scheme. - The resulting token is **cached in memory on the client's auth scheme** and reused across calls, which - is the whole reason a client must be long-lived (`python-client-initialization`). The cache is - double-checked under a lock, so a burst of concurrent first calls pays for **one** fetch. + is the whole reason a client must be long-lived (`python-client-initialization`); a burst of + concurrent first calls pays for **one** fetch. - A token with an `expires_in` is renewed ~30s before expiry (or at half its lifetime, whichever leaves more time, for tokens shorter than a minute). Without an `expires_in` there is no client-side deadline and the token is used until the server rejects it. -- **Refreshing applies only to the authorization-code grant**, whose scheme prefers a refresh over a - re-acquisition — a re-acquisition would run your prompt again. Client-credentials and password - re-acquire instead (RFC 6749 §4.4.3 says the client-credentials grant SHOULD NOT be issued a refresh - token), so the password grant re-sends the resource owner's password at every expiry. +- **Refreshing applies only to the authorization-code grant**, where a re-acquisition would run your + prompt again. Client-credentials and password re-acquire instead, so the password grant re-sends the + resource owner's password at every expiry. - **On a `401`, the cached token is invalidated** so the next call re-authenticates — but **the failing request is not retried**. This is deliberate: the caller sees one `401` and then recovery. Do not write a retry loop *just* for this; do expect that a revoked credential surfaces as exactly one @@ -197,59 +190,41 @@ anything satisfying the token-source protocol: `TokenSource` (`fetch(credentials scheme's cache, which is private. Your source **must not issue a request that itself uses this scheme** — it runs inside that scheme's lock and would deadlock. -## The failure mode that surprises everyone +## A failed token fetch raises `AuthSchemeError` -**A failed token fetch raises the SDK's ordinary API exception — but its payload is a different type -than any operation's.** For a managed-OAuth SDK, the token endpoint's error body is fixed by -RFC 6749 §5.2, so the SDK decodes it into an `OAuthProviderError` (`error`, `error_description`, -`error_uri`) — or a `RawError` if the provider's body does not conform. - -Two consequences, and both are the sort of thing that costs an afternoon: - -1. **The exception surfaces out of your *operation* call**, because that is where the lazy fetch - happens. A traceback for bad credentials points at the operation you called, and the frames - underneath name the token source. Reading only the top frame sends you looking in the wrong place - entirely. -2. **The non-raising response mode does not protect you.** The `with_raw_response` variant returns a - result object instead of raising *for the operation* — but the token fetch passes its own result - through `unwrap()` internally, so an auth failure raises even there. Any code path that touches the SDK needs to handle - this, including one written specifically to avoid exceptions. - -So a boundary that catches only the operation's error union is incomplete. Narrow on the payload type: - -```python -from {root_package}.core import ApiError, OAuthProviderError, RawError - -try: - result = client.{controller}.{operation}(body) -except ApiError as e: - if isinstance(e.error, OAuthProviderError): - # Credentials/token problem — no operation request was ever sent. - log.error("auth failed: %s (%s)", e.error.error, e.error.error_description) - raise ConfigurationError("API credentials rejected") from e - ... # the operation's own error union -``` - -Treat this as a **configuration** failure, distinct from an operation rejection: nothing was attempted, -so retrying it or reporting it as a failed operation are both wrong. `python-error-handling` has the -full catch ladder. +It names **your operation's** call, not the token endpoint, so an `except ApiError` around that call +never catches the token endpoint's `401`. What went wrong is on `__cause__`: an `ApiError` whose +`error` is a `RawError` when the endpoint refused (the RFC 6749 `error` code is in +`e.__cause__.error.json()`), or an `SdkConnectionError` when it could not be reached. It +surfaces out of your **operation call**, where the lazy fetch happens — the top frame names the +operation, the frames beneath it the token source — and it raises under `with_raw_response` too. +Treat it as a **configuration** failure: no operation request was sent, so neither retry it nor report +it as a failed operation; `python-error-handling` has the ladder. ## Combined / multiple schemes -When an operation (or the whole API) requires more than one scheme, APIMatic composes them per -operation — OpenAPI's OR-of-ANDs, arm by arm — and the generated client wires the composition for you. -You configure it by setting the relevant credentials keywords: +When an operation (or the whole API) requires more than one scheme, the client composes them per +operation for you. You configure it by setting the relevant credentials keywords: - **AND** (`AllSchemes`) — every *configured* member applies to the request. -- **OR** (`AnySchemes`) — the first *configured* member applies. Selection is on **credential presence**, - never on "applying it did not fail", so an unconfigured member listed first cannot win and send the - request unauthenticated. - -**This layer never withholds a request over a missing credential, and never raises for one.** An -unconfigured member simply drops out and the request goes out with whatever *was* configured; with -nothing configured at all it goes out unauthenticated. The server decides. Because composition is -per-operation, one client may authenticate different operations with different schemes — set every -keyword the operations your integration calls actually need. +- **OR** (`AnySchemes`) — the first *configured* member that applies wins. An unconfigured member is + never tried, so one listed first cannot win and send the request unauthenticated, and a configured + member that raises yields to the next. Only when every configured member raised does the call raise + `AuthSchemeError`, each failure in `scheme_failures`. A failure a later member recovers from is + absorbed: the call goes ahead on that member's credential. A failed token request logs its own + lines (a WARNING where it was refused, an ERROR where it got no response), and those are the signal + that a fallback credential is in use. The group adds no line of its own; wrap that scheme if you + want one naming it. + +**A missing credential never withholds a request and never raises.** Omitting a credentials keyword is +legal and silent — the client is built with a no-auth scheme — and an unconfigured composite member +simply drops out, so the request goes out with whatever *was* configured; with nothing configured at +all it goes out unauthenticated, and the server decides. Most APIs then answer `401`; an API that +serves anonymous traffic at all (public endpoints, or a reduced rate limit for keyless callers) +answers `200` and hides the omission entirely. Because composition is per-operation, one client may +authenticate different operations with different schemes — so verify every keyword the operations +your integration calls actually need is set, and on blanket `401`s check that before suspecting the +credentials themselves. ## No auth @@ -286,19 +261,8 @@ Two things that help, both already built in: ## Notes -- A given SDK only exposes the credentials keywords for the schemes its API uses; those names are - generated per-API (hence the `{...}` placeholders above). -- **Omitting a credentials keyword is legal and silent.** The client is then built with a no-auth - scheme and requests go out unauthenticated. Nothing warns you at construction. Most APIs then - answer `401`; an API that serves anonymous traffic at all (public endpoints, or a reduced rate - limit for keyless callers) answers `200` and hides the omission entirely — so verify the keyword is - actually set rather than waiting for a `401` to tell you, and if you *are* getting blanket `401`s, - check that before suspecting the credentials themselves. -- Set credentials **at construction**. The scheme is built there; assigning to a private attribute - afterwards is not supported. To rotate a credential, build a new client and close the old one. -- Rotation with a long-lived client: the token cache is per client instance, so swapping in a new - client atomically (build, then replace the reference, then close the old one) rotates without a - window where calls have no credential. -- A per-call `extra_headers` outranks the credential: header precedence is API-wide → the endpoint's - own → auth → `extra_headers`. That is the deliberate way to override an `Authorization` header — or - blank it for a call meant to go out anonymous — and also the way to break auth by accident. +- Set credentials **at construction**; assigning to a private attribute afterwards is not supported. + To rotate a credential, build a new client, replace the reference, then close the old one — the + token cache is per client instance, so there is no window where calls have no credential. +- A per-call `extra_headers` outranks the credential, so it can override or blank `Authorization` for + one call (`python-calling-endpoints`). diff --git a/plugins/slack/skills/python/python-calling-endpoints/SKILL.md b/plugins/slack/skills/python/python-calling-endpoints/SKILL.md index a6e72427..17495ee7 100644 --- a/plugins/slack/skills/python/python-calling-endpoints/SKILL.md +++ b/plugins/slack/skills/python/python-calling-endpoints/SKILL.md @@ -1,6 +1,6 @@ --- name: python-calling-endpoints -description: Calling operations on an APIMatic-generated Python SDK — finding the group that owns an operation, the positional/keyword-only split and the parameters that never appear in the signature at all, passing a body as a model or a dict, uploading a file or a raw binary body, the two response modes, consuming a streamed file response, consuming an event stream, per-call request options, and async usage. Load before writing the first call to an SDK operation, or when an operation's shape or return type is unclear. +description: Load before writing the first call to an operation on an APIMatic-generated Python SDK, or when an operation's parameters or return type are unclear. Covers finding the group that owns an operation, the positional/keyword-only split, parameters absent from the signature, bodies as models or dicts, the parsed and with_raw_response modes, return types, iterating a paginator, per-call request_options and async calls. --- # Calling endpoints on an APIMatic Python SDK @@ -36,29 +36,21 @@ parameter you must pass `None` to just to reach a later one. Omit what you do no ### Where a parameter lands — the rule -Each parameter the description declares produces **one of three** outcomes, and the third one catches -people out: - -| What the description declares | What you get | +| Declared as | What you get | |---|---| | **required**, no fixed value | a **positional** parameter, no default | | **optional** | a **keyword-only** parameter defaulting to `None` | | a **default value** | a **keyword-only** parameter defaulting to *that value* — even if the parameter is required | | a **constant** value | **no parameter at all** — the value is baked into the request and you cannot change it | -Two consequences worth stating on the contract sheet: - -- **"Required" does not mean "path".** Positional parameters are ordered **path → query → header → - body**, so a required *query* or *header* parameter is positional too, sitting between the path - parameters and the body. Take the boundary from the sheet; never infer it from the URL. -- **A parameter with a declared default is keyword-only whatever its optionality**, and the SDK sends - that default on every call you don't override. +**"Required" does not mean "path".** Positional parameters are ordered **path → query → header → +body**, so a required *query* or *header* parameter is positional too, sitting between the path +parameters and the body. Take the boundary from the sheet; never infer it from the URL. ### Non-`None` defaults silently narrow what comes back -This is the single most common wasted afternoon on a generated SDK. A parameter carrying a -spec-declared default is *always sent*, so the response you get is the one that default asked for — -not the full resource. Typical shapes: +A parameter's non-`None` default is **sent on every call** you don't override, so the response you +get is the one that default asked for — not the full resource. Typical shapes: - a representation/verbosity switch defaulting to the minimal form, so a create returns little more than an id, a status and some links; @@ -87,7 +79,7 @@ Prefer models in application code: better inference, better errors, and required at construction. The dict form suits payloads assembled from external data. See `python-models`. **Form and multipart** — there is **no single body parameter**. Each field (and each file) becomes its -own parameter, following the same three-way split rule above. Do not go looking for a `body=`; read the +own parameter, following the same rule above. Do not go looking for a `body=`; read the signature. An optional part is omitted by leaving its parameter at its default: a part passed `None` is dropped from the body rather than sent empty. @@ -102,26 +94,18 @@ position. **No payload** — no body parameter at all. -**An optional-looking body is not permission to omit it.** A body typed `... | None = None` reflects -what the *description* marked optional, not what the endpoint needs. A create whose body is optional in -the spec will type-check with no arguments and then fail at the provider. Where a call obviously needs -a payload, pass one. +**An optional-looking body is not permission to omit it.** A body typed `... | None = None` does not +mean the endpoint works without one: a create with an optional body type-checks with no arguments and +then fails at the provider. Where a call obviously needs a payload, pass one. Serialization happens while the request is built, **before** anything is sent — so a body the SDK cannot dump raises out of the call with no request made. See `python-models`. ### File and binary parameters -**One name per client, whichever position it is.** A multipart file part and a raw binary body take -the same alias, and only the client you called decides which: `FileInput` on the sync client, -`AsyncFileInput` on the async one, and `list[…]` of either for an array part. Both are imported from -`{root_package}.core`. - -Nothing validates a file, so what the alias accepts is wider than the annotation shows — `bytes`, a -`Path`, any object with a binary `read`, a chunk iterator, and an `anyio`-style handle on the async -client. Which one you pass has consequences the signature cannot show: what stays resident, what can -be re-sent, who closes your handle, whether the body goes out sized or chunked, and what the file is -called on the wire. There is **no `str` arm** at either position — wrap a path in `Path`. +A multipart file part and a raw binary body take the same alias — `FileInput` on the sync client, +`AsyncFileInput` on the async one, `list[…]` of either for an array part — imported from +`{root_package}.core`. There is **no `str` arm** at either position — wrap a path in `Path`: ```python from pathlib import Path @@ -129,10 +113,8 @@ from pathlib import Path client.{group}.{operation}(Path("invoice.pdf")) # the default: streams, sized, names itself ``` -**Load `python-file-handling`** before passing anything other than a `Path`, and before consuming a -file an operation returns. It carries the arm-by-arm decision with its costs, the three behaviours -that differ between a part and a raw body, overriding the filename or media type, and how to read a -`FileResponse` without leaking its connection. +**Load `python-file-handling`** before passing anything other than a `Path` — what each arm costs, +the part-vs-raw-body differences, and overriding the filename or media type are there. ## Making the call and reading the response @@ -146,10 +128,11 @@ raises `ApiError`: value = client.{group}.{operation}(...) ``` -**Non-raising — `with_raw_response`.** Returns a result you branch on. Use it when you need the +**Non-raising — `with_raw_response`.** Returns a result you branch on — **2xx is `Success`, +everything else is `Failure`**, both carrying `.status_code` and `.headers`. Use it when you need the **status code or response headers** (the parsed form exposes neither on success, except for a file -response, which carries its own `headers`), or when a non-2xx is -an expected outcome rather than an exception: +response, which carries its own `headers`), or when a non-2xx is an expected outcome rather than an +exception: ```python from {root_package}.core import Success, Failure @@ -162,16 +145,15 @@ match client.{group}.with_raw_response.{operation}(...): ``` Both are frozen dataclasses, so `match` needs no boilerplate and `isinstance` narrowing is equivalent. -`unwrap(result)` (from `{root_package}.core`) collapses either back to the payload — which is literally -how the parsed form is built: every parsed method is `unwrap(...)` around its raw peer. +`unwrap(result)` (from `{root_package}.core`) collapses either back to the payload, raising on a +`Failure` exactly as the parsed form does. **`with_raw_response` removes one exception path, not the need for a `try`.** Two failures still raise -in both modes: a failed token fetch (it unwraps internally), and any decode failure. See -`python-error-handling`. +in both modes: a failed token fetch and any decode failure. See `python-error-handling`. ### Return types -Five shapes, and the sheet names which one each operation has — the map block states it directly as +Six shapes, and the sheet names which one each operation has — the map block states it directly as **Returns (parsed)** and **Returns (raw)**: - **A decoded model** — the JSON case, and the common one. @@ -181,6 +163,9 @@ Five shapes, and the sheet names which one each operation has — the map block - **An event stream** — `EventStream[T]` (`AsyncEventStream[T]` on the async client), for an operation declaring a `text/event-stream` response. It arrives **unread**, holds a connection, and iterating it yields `T`; see below. +- **A paginator** — `Paginator[Page, Item]` (`AsyncPaginator[Page, Item]` on the async client), for + a paginated operation, whose map block also carries a **Paging** bullet. It sends nothing until you + iterate it, and iterating it yields `Item`s from every page; see below. - **`None`** — the operation declares no response body. **`-> None` means the call succeeded.** Do not bind it and do not test it — success is "no exception @@ -188,20 +173,12 @@ raised", exactly as for the others. Two follow-ons: if you need the resulting st separate call; and if you need the status code (`200` vs `204`), the raw peer is `ApiResult[None, ...]` and `Success(payload=None, status_code=...)` is the only place it appears. -Writing `value = client.{group}.{operation}(...)` on a `-> None` operation type-checks under a loose -annotation and then fails later with an `AttributeError` on `None`. - ### Consuming a file response -A `FileResponse` is a body that has **not been read yet** and holds its connection until it is, -which makes it the one return value with a lifecycle. Three calls consume it and all three close it — -`save_to(...)`, `read()`, or a drained `iter_bytes()` under `with` — and the async twin mostly -`a`-prefixes them. - -Getting this wrong leaks a connection rather than raising, so **load `python-file-handling`** before -writing the consuming code. It carries the lifecycle in full: which warning fires when one is -abandoned and how to make it fail a test, the single-use rule, what `save_to` does with a directory, -and why a `try` around the call alone catches nothing. +A `FileResponse` arrives **unread** and holds its connection until `save_to(...)`, `read()` or a +drained `iter_bytes()` under `with` closes it; the async twin mostly `a`-prefixes them. A mistake +leaks a connection rather than raising, so **load `python-file-handling`** before writing the +consuming code. ### Consuming an event stream @@ -209,6 +186,33 @@ An `EventStream[T]` is iterated, not read: a drained `for` releases its connecti needs `with`. **Load `python-event-streams`** before writing the loop — it carries the lifecycle, the union narrowing, and the failures that are silent. +### Iterating a paginator + +A `Paginator` is a lazy walk over the whole collection, not a page. Calling the method sends nothing; +the first request goes out when you start iterating, and each new iteration starts again from the +first page. Iterate it for items, or call `iter_pages()` for the pages: + +```python +for item in client.{group}.{operation}(...): + ... + +for page in client.{group}.{operation}(...).iter_pages(): + ... +``` + +- **The arguments set the first request only.** The SDK moves the offset, page, cursor or link forward + from each response and stops on the API's own signals — the map block's **Paging** bullet says + which. There is no next-page method; to resume from a known point, pass it as the first-page + argument. +- **Cap a walk with `break` or `itertools.islice`.** There is no page-cap argument, and either stops + the walk with no further request. A `list(...)` over an uncapped paginator fetches every page. +- **Errors raise from the loop, not the call** — so a `try` around the call alone catches nothing. + `python-error-handling` has the detail. +- **The raw peer's pages are results.** `client.{group}.with_raw_response.{operation}(...)` returns + `Paginator[ApiResult[Page, E], Item]` and never raises for an API error: iterating it for items + yields the items of every successful page and ends at a failed one, and `iter_pages()` yields one + `Success` or `Failure` per page, the `Failure` last. + ## Per-call overrides — `request_options` @@ -219,30 +223,36 @@ accepted typed or dict-shaped: client.{group}.{operation}(..., request_options={"timeout": 5.0}) ``` -The keys are exactly `timeout` (seconds, must be > 0), `extra_headers`, and the two retry overrides -`max_retries` and `status_codes_to_retry` (`python-configuration-resilience`). It is validated with +The keys are exactly `timeout` (seconds, must be > 0), `extra_headers`, the two retry overrides +`max_retries` and `status_codes_to_retry`, `log_level` and `hooks` (`python-configuration-resilience`). +The typed form is `RequestOptions` on the sync client and `AsyncRequestOptions` on the async one: the +same keys, the async `hooks` being `AsyncSdkHook` or an `AsyncSdkHooksDict` where the sync ones are +`SdkHook` or an `SdkHooksDict`, so a hook of the other client's flavour is a type error at the call +site. It is validated with `extra="forbid"`, so `{"timeuot": 5}` raises `ValidationError` rather than being ignored — and because the dict form is a closed `TypedDict`, a type checker catches it at the call site first. -`extra_headers` wins over both the API's and the endpoint's own headers, which makes it the deliberate -way to override a header the SDK sets — including blanking an auth header for a call meant to go out -anonymous. That precedence is a footgun as much as a feature: setting `authorization` here overrides -the managed token. +`extra_headers` wins over the API's, the endpoint's and the auth scheme's headers (precedence +API-wide → endpoint → auth → `extra_headers`), which makes it the deliberate way to override a header +the SDK sets — including blanking an auth header for a call meant to go out anonymous — and the way to +break auth by accident: setting `authorization` here overrides the managed token. Two mechanics: - **Header names are lowercased on the way out**, at every layer including yours, so the merge is - genuinely case-insensitive and the request reaching the transport is keyed in lowercase. Look - request headers up that way (`python-testing`). -- **`Cookie` folds instead of replacing.** Every other field takes the later layer and discards the - earlier; a cookie you add joins the jar alongside whatever the endpoint or a credential put there - (RFC 6265 permits one `Cookie` field). So a cookie-carried credential cannot be blanked with - `extra_headers` the way a header-carried one can. + case-insensitive and the request reaching the transport is keyed in lowercase. Look request headers + up that way (`python-testing`). +- **`Cookie` folds instead of replacing.** Every other field takes the later layer; a cookie you add + joins whatever the endpoint or a credential put there, so a cookie-carried credential cannot be + blanked with `extra_headers` the way a header-carried one can. ## Async -The async client's operations are identical in name and parameters — you await them. There is no -`_async` suffix and no separate method list; the client class you hold decides the flavour: +The async client's operations have the same names and parameter names — you await them, and their +`request_options` is `AsyncRequestOptionsOrDict` (above). There is no +`_async` suffix and no separate method list; the client class you hold decides the flavour. The one +exception is a paginated operation: it is a **plain call** returning `AsyncPaginator`, so you +`async for` over it with no `await` on the call. ```python value = await client.{group}.{operation}(...) @@ -269,12 +279,9 @@ results = await asyncio.gather(*(one(a) for a in args)) ## Timeouts and cancellation -There is no cancellation-token parameter. Python's own mechanisms apply: - -- **Per call** — `request_options={"timeout": ...}`, which sets the limit on each wait for this one request. -- **The whole call** — `asyncio.wait_for(...)` around it, in async code; see - `python-configuration-resilience`. -- **Sync code has no whole-call limit.** The timeout only limits each wait — set one anyway. +There is no cancellation-token parameter. `request_options={"timeout": ...}` limits each wait of one +request; `asyncio.wait_for(...)` around the call limits the whole call in async code +(`python-configuration-resilience`). Sync code has no whole-call limit — set the timeout anyway. ## Next diff --git a/plugins/slack/skills/python/python-client-initialization/SKILL.md b/plugins/slack/skills/python/python-client-initialization/SKILL.md index 357e6284..7bff951b 100644 --- a/plugins/slack/skills/python/python-client-initialization/SKILL.md +++ b/plugins/slack/skills/python/python-client-initialization/SKILL.md @@ -1,6 +1,6 @@ --- name: python-client-initialization -description: Creating and holding an APIMatic-generated Python SDK client in Python — construction, the keyword-only constructor shape, choosing the sync or async class, transport ownership and the close/aclose obligation, and where the client lives in a script, an ASGI app, or a forking worker. Load before wiring the client into an application or writing the factory that builds it. +description: Load before constructing an APIMatic-generated Python SDK client or wiring it into an application — a script, an ASGI app (FastAPI, Starlette), a WSGI app or a forking worker (Gunicorn, Celery). Covers the keyword-only constructor, choosing the sync or async class, transport ownership and the close/aclose obligation, and how long the client lives. --- # Initializing an APIMatic Python SDK client @@ -23,8 +23,10 @@ constructor: {Api}Client( *, # server selection — one of four shapes, see "Choosing the server / base URL" - timeout: float = 30.0, # seconds; the generator's default + timeout: float = 30.0, # seconds retry_options=None, # None: the default policy; 0 disables; a count, RetryOptions or dict tunes it + logging_options=None, # what the built-in HTTP logging records — see python-configuration-resilience + hooks=None, # hook objects or {"on_request": [...], ...} — see python-configuration-resilience custom_http_client=None, # your own transport {scheme}=None, # one credentials keyword per declared scheme {scheme}_token_source=None, # managed-OAuth schemes only @@ -35,25 +37,23 @@ Every parameter sits after `*` — there are **no positional arguments**, so a p immediate `TypeError`. There is no options object, no builder, and no separate configuration type to populate: everything is a constructor keyword. -Operations are exposed on the client. Most are grouped under **group accessors** (one per API resource -group) and called `client.{group}.{operation}(...)` — for example, a `widgets` group's `list_widgets` -operation is `client.widgets.list_widgets(...)`. An operation that belongs to no group sits **directly -on the client**, called `client.{operation}(...)`. Accessors are `cached_property`, so they are -attributes without parentheses and return the same object each time. The available accessors (and any -direct operations) come from the contract sheet, grounded in the SDK map's controller table -(`sdk-map.md`) — not from a runtime `dir()` or a REPL poke. See -`python-calling-endpoints`. +Operations hang off **group accessors** — `client.{group}.{operation}(...)`, or `client.{operation}(...)` +for an ungrouped one. Accessors are `cached_property` attributes, not methods: no parentheses, and the +same object each time. Take them from the contract sheet, grounded in the SDK map's controller table +(`sdk-map.md`), not from a runtime `dir()` (`python-calling-endpoints`). Both classes are also exported under the fixed aliases `Client` and `AsyncClient`. **Prefer the full names** — a bare `Client` collides in any application that talks to more than one API. -The async class is a peer, not a variant: same accessors, same operation names, same parameters. Four -names differ: +The async class is a peer, not a variant: same accessors, same operation names, same parameter names. +What differs at the client: | | Sync | Async | |---|---|---| | Transport keyword | `custom_http_client=` | `custom_async_http_client=` | | Transport protocol | `HttpClient` | `AsyncHttpClient` | +| Hooks | `SdkHook` / `SdkHooksDict` | `AsyncSdkHook` / `AsyncSdkHooksDict` | +| Per-call options | `RequestOptions` | `AsyncRequestOptions` | | Shutdown | `client.close()` | `await client.aclose()` | | Scope form | `with` | `async with` | @@ -83,18 +83,11 @@ client = {Api}Client( ) ``` -`timeout` is validated at construction: non-positive (or NaN) raises `ValueError` immediately. -Credentials passed in dict form are validated by pydantic with `extra="forbid"`, so a misspelled key -raises `ValidationError` there and then. - -Two things are **not** validated, so a clean construction does not mean a working client: - -- **`base_url` is taken unchecked.** A typo or the wrong environment surfaces as a connection error or - a `401` at the first call. -- **Credentials are never exercised.** Managed-OAuth schemes fetch the token lazily on the first API - call, so wrong credentials construct happily and fail later, pointing at whichever operation ran - first. Every credentials keyword also defaults to `None`, and omitting it configures the client for - **no auth** — requests go out unauthenticated and the server answers `401`. +Construction validates `timeout` (`ValueError`) and dict-form credentials (`ValidationError`), but a +clean construction does not mean a working client: **`base_url` is taken unchecked** — a typo or the +wrong environment surfaces as a connection error or a `401` at the first call — and **credentials are +never exercised**: a managed-OAuth token is fetched on the first call, and an omitted credentials +keyword means no auth (`python-authentication`). ### Transport ownership and the close obligation @@ -120,23 +113,10 @@ is `aclose`, and calling `close()` on an async client is an `AttributeError`. ## Choosing the server / base URL -Server selection is **not** an environment enum. What the constructor accepts depends on what the spec -declares, in one of four shapes: - -| The API declares | Constructor keywords | -|---|---| -| one server, one environment | `base_url: str \| None = None` | -| one server, several environments | `environment` (a string literal alias, with a default), then `base_url` | -| several servers, one environment | `server_config: {Server}ConfigOrDict \| None = None` | -| several servers, several environments | `environment`, then `timeout`, then `server_config` | - -Omitting the server keyword falls through to the config's own default rather than writing `None` over -it — and **that default is whatever the spec listed first, which for many providers is a sandbox.** -Nothing announces it. Confirm the default from the contract sheet — the SDK map's *Servers & auth* -section names the base URL each arm resolves to — and pass the server explicitly in -every environment, production included. Server template variables live on the config class, so how you -reach them follows the arm above. **python-configuration-resilience** owns server / base-URL -configuration in full. +The server keyword takes one of four shapes, and **omitting it silently selects the API's +first-listed environment — often a sandbox.** Pass it explicitly in every environment, production +included; **python-configuration-resilience** owns the shapes, their nesting and server template +variables. ## Where the client lives @@ -184,48 +164,48 @@ thread-safe. The async client may be built outside a running loop, but from its ## Supplying your own transport The transport is a `Protocol` — a structural interface, not a base class. The sync one requires -`send(request) -> HttpResponse` and `close()`; the async one `send` and `aclose()`. There is one -request seam whatever the operation returns, a file included, so a transport that implements those -two satisfies the Protocol under `mypy --strict`: +`send(request) -> HttpResponse` and `close()`; the async one `send` and `aclose()`: ```python client = {Api}Client(custom_http_client=MyTransport(), {scheme}=...) ``` -This is the seam for **logging, tracing, metrics and tests** — the SDK ships no logging or middleware of -its own. Wrap the SDK's own transport rather than reimplementing HTTP: +This is the seam for **tests and for replacing the send itself**. Tracing, metrics and changing a +request or response go in a hook instead, and HTTP logging is built in +(`python-configuration-resilience` covers both), so wrap the transport only for what neither can do. +Wrap the SDK's own transport rather than reimplementing HTTP: ```python -class LoggingTransport: - def __init__(self, inner): self._inner = inner +class ReplayTransport: + def __init__(self, inner, replies): self._inner, self._replies = inner, replies def send(self, request): + if (reply := self._replies.get((request.method, request.url))) is not None: + return reply(request) # your own HttpResponse; nothing is sent, which no hook can do # The head only: the body is still on the socket, and the caller closes it. - response = self._inner.send(request) - log.info("%s %s -> %s", request.method, request.url, response.status_code) - return response + return self._inner.send(request) def close(self): self._inner.close() ``` -`send` returns an `HttpResponse` — `url`, `status_code`, lowercased `headers`, +`send` returns an `HttpResponse` — `method`, `url`, `status_code`, lowercased `headers`, `iter_bytes(chunk_size)`, `read()` and `close()` — whose body has **not** been read. That is true of every response, not just a download, so a wrapper must hand each one back unread; logging its size means consuming it, which leaves the caller nothing to read. `iter_bytes(None)` must yield each chunk as the network delivered it, holding nothing back — an event stream reads it that way, and a wrapper that re-chunks to a fixed size delays every small event. -Four obligations the protocol places on anything you supply, all silent when broken: **do not mutate +Five obligations the protocol places on anything you supply, all silent when broken: **do not mutate the incoming request** (it is frozen); **honour `request.timeout`** when set, falling back to your own -when it is `None`; **lowercase the response header names**, because callers look them up that way; and -**return once the head has arrived**, leaving the body for whoever reads it. - -Two consequences. First, **the `timeout=` you passed to the client no longer reaches the wire** — that -value only builds the client's *own default* transport, so set the timeout on the one you pass or you -have silently reverted to the underlying library's default. The per-call -`request_options={"timeout": ...}` is the exception: it travels on the request object and reaches any -transport honouring the obligation above. Second, **the client still closes it** — don't close it -yourself while the client is alive, and don't share one transport between two clients. +when it is `None`; **lowercase the response header names**, because callers look them up that way; +**return once the head has arrived**, leaving the body for whoever reads it; and **raise +`SdkConnectionError`** (`SdkTimeoutError` for a timeout) from `send` and from the response's reads when +no usable response arrives, chained `from` your library's exception (`python-configuration-resilience`). + +Two consequences. First, **the client's `timeout=` does not reach the wire** — set the timeout on your +transport, or you get the underlying library's default; a per-call `request_options` timeout still +arrives on the request (`python-configuration-resilience`). Second, **the client still closes it** — +don't close it yourself while the client is alive, and don't share one transport between two clients. ## Next diff --git a/plugins/slack/skills/python/python-configuration-resilience/SKILL.md b/plugins/slack/skills/python/python-configuration-resilience/SKILL.md index 05c86314..9d48e42e 100644 --- a/plugins/slack/skills/python/python-configuration-resilience/SKILL.md +++ b/plugins/slack/skills/python/python-configuration-resilience/SKILL.md @@ -1,6 +1,6 @@ --- name: python-configuration-resilience -description: Client configuration and resilience for an APIMatic-generated Python SDK — server and base-URL selection, the retry policy (on by default, off with `max_retries=0`) and what it will and will not repeat, what a timeout actually bounds, proxies and TLS, and request/response logging through the transport seam. Load before you configure or tune the client — the keyword names alone do not reveal what is handled for you and what is not. +description: Load before configuring or tuning an APIMatic-generated Python SDK client — choosing the server or base URL, retries, idempotency keys, timeouts, proxies and TLS, turning on request/response logging, or running your own code on every request with hooks. Covers the default retry policy and what it repeats, what a timeout bounds, the built-in HTTP logging (off by default; `logging_options`, `{ROOT_PACKAGE}_LOG` and a per-call `log_level`), request and response hooks (`hooks=` on the client and per call), and what the SDK leaves to you. --- # Configuration & resilience for an APIMatic Python SDK @@ -9,34 +9,26 @@ description: Client configuration and resilience for an APIMatic-generated Pytho > `{group}`, `{root_package}`) — replace it with the concrete identifier from the source. Configuration is not an options object here. Everything is either a **constructor keyword** on the -client (`python-client-initialization`), a field on a **config model** — the server config or -`RetryOptions` — or a **per-call `request_options`**. There is no third place to look. +client (`python-client-initialization`), a field on a **config model** — the server config, +`RetryOptions` or `LoggingOptions` — or a **per-call `request_options`**. There is no third place to look. ## What this SDK does not do for you -Read this before designing around a capability you assume exists. The generator emits **none** of the -following, so each is yours to build or deliberately do without: - -| Capability | Status | What to do instead | -|---|---|---| -| **Streaming — file responses** | a `FileResponse` arrives with its body unread and holds its connection until you consume it | `save_to` / `read` / `iter_bytes` (see `python-file-handling`) | -| **Streaming — SSE** | an `EventStream` arrives with its body unread; iterating yields each event's decoded data, and `timeout` bounds the gap between events | a `for` loop, or `with` for an early exit (see `python-event-streams`) | -| **Request/response logging** | none — no hook, no event | Wrap the transport; see below | -| **Circuit breaking, rate limiting** | none | Your own, around the call | -| **A mock/offline mode** | none | Point `base_url` at a mock server, or supply a fake transport (`python-testing`) | - -**Retries are on by default.** A client built without `retry_options` retries idempotent calls up to -three times; set `max_retries` to `0` to turn that off — see *Retries* below. +| Capability | What to do instead | +|---|---| +| **Circuit breaking, rate limiting** | Your own, around the call | +| **A mock/offline mode** | Point `base_url` at a mock server, or supply a fake transport (`python-testing`) | What the SDK *does* own: the request pipeline, auth application and token caching, response decoding, -error mapping, connection pooling, one timeout, and — once you turn it on — the retry loop. +error mapping, connection pooling, one timeout, the retry loop (on by default — see *Retries* below), +HTTP logging (silent until its logger is raised — see *Logging* below), and streamed file and +event-stream responses (`python-file-handling`, `python-event-streams`). ## Server and base-URL configuration -Server selection is **not** an environment enum. What the constructor accepts depends on what the -description declares, in one of four shapes — take yours from the contract sheet, grounded in the SDK -map's *Servers & auth* section, which names the environments and servers this SDK declares and so -settles which arm it is: +Server selection is **not** an environment enum. The constructor takes one of four shapes, set by what +the API declares — take yours from the contract sheet; the SDK map's *Servers & auth* section settles +which arm it is: | The API declares | Constructor keywords | |---|---| @@ -55,18 +47,15 @@ client = {Api}Client(environment="production", server_config={"{server}": {"prod wrong nesting raises `ValidationError` rather than being ignored.** With one environment each server's field holds `base_url` directly. With several, each server's field holds **one field per environment** and the `base_url` sits inside the environment's variant — passing `{"{server}": {"base_url": ...}}` -there fails with `Extra inputs are not permitted`. Take the nesting from the SDK map's *Servers & auth* -section rather than from this shape. +there fails with `Extra inputs are not permitted`. -Either way `server_config` is a pydantic model with a dict companion, coerced through `.coerce()`, -holding **one field per server the API declares**. Template variables sit beside `base_url` at +Either way `server_config` is a pydantic model with a dict companion, holding **one field per server +the API declares**. Template variables sit beside `base_url` at whichever level carries it. -**Omitting the server keyword takes the description's own default, and that default is whatever the -spec listed first — for many providers a sandbox.** Nothing announces it. A deployment that believes it -configured production and did not gets sandbox behaviour with production credentials, which fails auth -in a way that looks like a credentials problem, not an environment one. Pass the server explicitly in -every environment, production included. +**Omitting the server keyword silently selects the API's first-listed environment — often a +sandbox.** Production credentials against it fail like a credentials problem, not an environment one. +Pass the server explicitly in every environment, production included. **Server template variables are only reachable in the `server_config` arms.** They are fields on the config class, so where the constructor takes a `server_config` you set them there. Where it takes a @@ -88,10 +77,8 @@ the token fetch too. ## Retries — on by default -A client built without `retry_options` uses the **default policy** in the table below: a `GET`, `HEAD`, -`PUT` or `OPTIONS` call that meets a `408`, `429`, `500`, `502`, `503`, `504` or a dropped connection is -retried up to three times. -Retrying is configured by one options class, `RetryOptions` (from `{root_package}.core`), passed to the +A client built without `retry_options` uses the **default policy** in the table below. Retrying is +configured by one options class, `RetryOptions` (from `{root_package}.core`), passed to the client in any of four spellings: ```python @@ -140,11 +127,14 @@ A call is repeated only when **all** of these hold: A `401` is never in the default set; it invalidates the cached credential for the next call instead (`python-authentication`). Whatever you add to `status_codes_to_retry` is retried, so leave out statuses that cannot succeed a second time. When the last attempt fails, you see what a single attempt -would give you: the `ApiError`, the raw response's `Failure`, or the HTTP library's own exception. +would give you: the `ApiError`, the raw response's `Failure`, or `SdkConnectionError` with the HTTP +library's exception on `__cause__`. -A **custom transport** must raise `TransportError` (`from {root_package}.core import TransportError`) -for a failed send to be retried; the shipped `Httpx2Client` does. Anything else it raises reaches you on -the first attempt. +A **custom transport** must raise `SdkConnectionError` (`SdkTimeoutError` for a timeout) from `send` +for a failed send to be retried, naming the call as `method=request.method, url=safe_url(request.url)` +(`from {root_package}.core import SdkConnectionError, SdkTimeoutError, safe_url`). Its response's reads +must raise the same for a body they could not deliver. The shipped `Httpx2Client` does both. +Anything else it raises reaches you, unwrapped, on the first attempt. ### Per-call overrides @@ -159,18 +149,11 @@ client.{group}.{operation}(arg, request_options={"status_codes_to_retry": frozen and each of your attempts is a new call with a new idempotency key (below). If you need behaviour the options cannot express, turn the SDK's off for that call and own it. -**Only a write that was sent may have landed.** A write that timed out *after it was sent* may have -succeeded — a reset after the bytes reached the server is indistinguishable from one before. A write -that was never sent did not happen; `python-error-handling` names the four exceptions that mean so. - -**The retry arithmetic is not a ceiling.** `(max_retries + 1) × timeout` plus the waits between them -can be exceeded, because one attempt can outlast its timeout; see *Bounding a call*. - ### Making a write safe when you retry **Every operation other than a `GET` sends an `Idempotency-Key` header** — a UUID minted once per call, -unless the description declares its own header of that name, in which case that one is a keyword you -set. Within the SDK's retry loop every attempt carries the *same* key, which is what makes adding `POST` +unless the operation has its own `Idempotency-Key` header parameter, which is then a keyword you set. +Within the SDK's retry loop every attempt carries the *same* key, which is what makes adding `POST` to `http_methods_to_retry` safe **where the provider deduplicates on it**. A retry you write yourself is a new call and mints a new key — the provider sees two submissions. @@ -227,8 +210,7 @@ await asyncio.wait_for(async_client.{group}.{operation}(arg), budget) # the wh ``` - The value is **seconds, as a float**; the per-call option overrides the client's. -- It must be **> 0**. The constructor raises `ValueError` otherwise — and rejects NaN too, since the - guard is written `not timeout > 0`. +- It must be **> 0** (NaN is rejected too); the constructor raises `ValueError` otherwise. - The default is **30 seconds** per wait. - Under the default transport, one float sets connect, read, write and pool timeouts alike. To separate them (a short connect, a longer read), build your own transport with an @@ -240,7 +222,7 @@ keeps arriving slowly is never cut off, and each attempt — up to `max_retries longer than the number you set. This timeout firing is a transport failure and retries on the curve like any other; a `408` is the server's request timeout and sits in the default status set. -**If you supply `custom_http_client`, the client's `timeout=` no longer reaches the wire.** That value +**If you supply `custom_http_client`, the client's `timeout=` does not reach the wire.** That value only builds the SDK's *own* default transport. Set the timeout on the transport you pass, and honour `request.timeout` inside it (`python-client-initialization`). @@ -271,52 +253,70 @@ client = {Api}Client(custom_http_client=transport, {scheme}=...) - **`verify=False` disables certificate verification.** It is not a debugging convenience for anything carrying credentials; fix the trust store instead. -## Logging — wrap the transport +## Logging — off by default, through the standard logger -There is no logging hook and no event to subscribe to. The transport protocol is the seam: implement -it, delegate to the real one, and log around the call. +The SDK writes every HTTP exchange through Python's standard `logging` module under the +`{root_package}` logger and configures nothing itself: no handler, no level, never the root. Turn it +on as for any library, or from the environment for a run you cannot edit — `{ROOT_PACKAGE}_LOG` is the +package name upper-cased with `_LOG` appended: ```python -import logging, time -from {root_package}.core import Httpx2Client +import logging -log = logging.getLogger(__name__) +logging.basicConfig() # your handler; the root stays at WARNING +logging.getLogger("{root_package}").setLevel(logging.INFO) # INFO: the lines; DEBUG: the dumps too +``` -class LoggingTransport: - def __init__(self, inner): self._inner = inner +```bash +{ROOT_PACKAGE}_LOG=info python app.py # the request and response lines +{ROOT_PACKAGE}_LOG=debug python app.py # plus request headers, request body and response headers +``` - def send(self, request): - started = time.monotonic() - # The head only -- do not read the body here; the caller owns it. - response = self._inner.send(request) - log.info( - "%s %s -> %s (%.0f ms)", - request.method, request.url, response.status_code, - (time.monotonic() - started) * 1000, - ) - return response +| Level | What is written | +|---|---| +| `INFO` | `HTTP GET https://api.example.com/items?page=2` as each attempt is sent, and `HTTP GET … -> 200 (12 ms)` when its head arrives | +| `WARNING` | the response line for any status outside 2xx, and `HTTP GET … retrying in 1.0 s (attempt 1/3): 503 Service Unavailable` before each retry | +| `ERROR` | `HTTP GET … failed after 6210 ms: ConnectError` when a call ends in an exception, with the exception attached | +| `DEBUG` | the request headers, the request body and the response headers — each only when its flag below is on | - def close(self): self._inner.close() +The dumps are opt-in through `logging_options`, a dict or a `LoggingOptions` from `{root_package}.core`: +```python client = {Api}Client( - custom_http_client=LoggingTransport(Httpx2Client(timeout=10.0)), {scheme}=... + logging_options={"log_request_headers": True, "log_response_headers": True, "log_request_body": True}, + {scheme}=..., ) ``` -The async version is the same shape with `async def send` and `async def aclose`. Both members are -required, and they are the only two: one request seam serves every operation, a download included, -so there is no second method to forget. - -**The elapsed time above bounds the head, not the call.** `send` returns once the response head has -arrived, so a body still on the wire is not in that measurement — for a download it is barely in it -at all. Timing the whole exchange means timing where the body is consumed, which is the caller's -code, not this wrapper. - -**Log the method, URL and status — not headers or bodies.** The auth header carries a live credential -and bodies carry whatever the API moves; neither belongs in your logs or your traces. If you must -capture a body to debug, gate it behind a flag that is off by default and redact before writing. - -This same wrapper is where OpenTelemetry spans, metrics and request-id propagation belong. +| Option | Default | Effect | +|---|---|---| +| `log_request_headers` | `False` | the sent headers at DEBUG, masked | +| `log_response_headers` | `False` | the received headers at DEBUG, masked | +| `log_request_body` | `False` | the request body at DEBUG: its text when in memory, a description when streamed | +| `body_size_limit` | `32768` | bytes of a logged body kept before it is cut | +| `redaction_placeholder` | `"REDACTED"` | what a hidden value prints as | +| `unmask_headers` / `mask_headers` | none | header names to show, or hide, against the built-in safe list | +| `mask_keys` | 11 credential names | query and form keys whose values are always hidden; naming a set replaces the default | + +**What is never printed.** A header value is shown only when its name is on a built-in list of +standard headers that carry no credential, so `Authorization`, `Cookie` and API-key headers print +`REDACTED`. A query value is shown only for nine paging names (`cursor`, `limit`, `offset`, `page`, +`since`, `size` and three more), and a URL's user and password are dropped. A form field under +`mask_keys` is hidden. A JSON body is printed as sent, so turn `log_request_body` on only where its +content may be logged. A response body is never logged. + +**One call, quieter.** `request_options={"log_level": logging.WARNING}` is a floor: records below it +are not written for that call. It never turns on a record the client's options leave off. + +**`{ROOT_PACKAGE}_LOG` sets the level and, where no handler listens, adds a stderr one;** `debug` +also turns the three flags on. An application that configured logging keeps its own handlers and +format. The SDK never touches the `httpx2` or `httpcore2` loggers; if your root logger is at INFO, +raise those two to WARNING yourself, or httpx2 prints its own unmasked line per attempt. + +**Tracing, metrics and anything the records do not carry** go in a hook (*Hooks* below). The +transport seam stays for what a hook cannot do, replacing the send itself: wrap the SDK's own transport +and delegate (`python-client-initialization` shows the shape). The wrapper sees the head only — do not +read the body there — and the auth header is live, so never log it yourself. ### Verify on the wire (first run of any new call) @@ -324,22 +324,74 @@ On success the SDK returns the decoded body and nothing else — never the URL o parameter, a header you thought you set, or a query parameter that silently did not serialize produces **no in-band signal**; the only symptom is a `404`/`422` that looks like a provider problem. -Run the logging transport the first time you execute any new call, and check: +Run the first call under `{ROOT_PACKAGE}_LOG=debug`, and check in the request line and header dump: 1. the **method** matches the operation; 2. the **path** has no unsubstituted `{placeholder}`; 3. path segments carry **wire values** — an enum's string, not a Python member name; -4. the **query parameters** you set actually appear. +4. the **query parameter names** you set appear (a value outside the paging names prints `REDACTED`). + +Then drop the variable. + +## Hooks — your code on every attempt + +A hook is caller code the SDK runs on **every attempt** of every request, inside the retry loop. +`before_request(request, context)` runs after authentication and before the request line is logged, +and returns the request to send. `after_response(response, context)` runs after the response line and +the 401 check and before the retry decision, and returns the response the call acts on. + +```python +from dataclasses import replace + +from {root_package}.core import HookContext, HttpRequest, SdkHook + + +# new_traceparent() stands for your own tracer. +class Tracing(SdkHook): + def before_request(self, request: HttpRequest, context: HookContext) -> HttpRequest: + return replace(request, headers={**request.headers, "traceparent": new_traceparent()}) + + +def stamp(request: HttpRequest, context: HookContext) -> HttpRequest: + return replace(request, headers={**request.headers, "x-tenant": "acme"}) + + +client = {Api}Client(hooks=[Tracing()]) # every call +client.{group}.{operation}(arg, request_options={"hooks": {"on_request": [stamp]}}) # this call, after the client's +``` -Then gate the wrapper behind a debug flag. +- **Subclass `SdkHook` and override either method, or pass plain functions keyed by event**, + `{"on_request": [...], "on_response": [...]}` (an `SdkHooksDict`). One place takes one spelling, + never a mix; a hook that keeps state between the request and its response is a class. Any other key + is a type error and is ignored at run time. A request is frozen: return it, or a + `dataclasses.replace` of it. +- **A call's hooks are appended to the client's, never substituted**, so a call site cannot switch off + what the client installed. +- **The client keeps the hooks you pass, uncopied**, so a list changed after construction is read by + the next call. +- **The async client takes `AsyncSdkHook`**, whose two methods are `async def` and receive an + `AsyncHookContext` and an `AsyncHttpResponse`; its dict (`AsyncSdkHooksDict`) takes `async def` + functions under the same two keys, and a call's hooks go in `AsyncRequestOptions`. A hook of the + wrong flavour is a type error; nothing is checked at run time. +- **A hook runs once per attempt**, so it must be safe to run more than once, and `before_request` may + run with no `after_response` to follow when the send fails. +- **A hook that raises ends the call** with that exception, unwrapped. To have the attempt retried as a + failed send, raise `SdkConnectionError(message, method=context.method, url=safe_url(context.url))` + (both from `{root_package}.core`) **from `before_request`**; it is then retried under the same method + and retry-count rules as a transport failure. Raised from `after_response`, it ends the call like any + other exception. +- **On a token request an OAuth scheme makes, only the client's hooks run**, not the call's, and one + that raises reaches you as `AuthSchemeError` with its exception in `scheme_failures` + (`python-error-handling`); in an OR requirement the next configured scheme is tried first. +- **A hook that reads the response body must return a response that still carries it**, and one that + returns a different response must close the original or keep it inside. +- **Hooks see the credential in clear**, on API calls and on the token requests an OAuth scheme makes. + Never log `request.headers` from one. ## Connection pooling -The client holds one pooled transport. Reuse the client and close it on shutdown; a client per call -pays a fresh TCP and TLS handshake every time, and under managed auth a fresh token fetch as well. -Under forking servers (Gunicorn, uWSGI, Celery prefork), construct it **after** the fork — a pool -inherited across `fork()` is shared by processes that each believe they own it, which surfaces as -intermittent, unexplainable connection errors. See `python-client-initialization`. +The client holds one pooled transport. Reuse one client and close it on shutdown; under forking +servers construct it **after** the fork (`python-client-initialization`). ## Next diff --git a/plugins/slack/skills/python/python-error-handling/SKILL.md b/plugins/slack/skills/python/python-error-handling/SKILL.md index 02bf6bbe..b1cc97be 100644 --- a/plugins/slack/skills/python/python-error-handling/SKILL.md +++ b/plugins/slack/skills/python/python-error-handling/SKILL.md @@ -1,6 +1,6 @@ --- name: python-error-handling -description: Error and exception handling for an APIMatic-generated Python SDK — load before writing any try/except around an SDK call, an exception-translation layer, or error middleware. Covers the single ApiError type and its per-operation error union, narrowing with isinstance or match, the failures that are NOT ApiError and reach your boundary unmatched, and the traps that make an otherwise reasonable except ladder silently wrong. +description: Load before writing any try/except around an APIMatic-generated Python SDK call, an exception-translation layer or error middleware. Covers the SdkError family — ApiError and its per-operation error union, ResponseDecodeError, SdkConnectionError / SdkTimeoutError and AuthSchemeError — narrowing with isinstance or match, and with_raw_response. --- # Error handling for an APIMatic Python SDK @@ -10,41 +10,49 @@ description: Error and exception handling for an APIMatic-generated Python SDK > source. Operations **raise on non-2xx responses** by default (for a non-raising alternative, see the -**`with_raw_response`** section below). The raised type is always `ApiError` — there is exactly one -exception class in these SDKs, and the variation lives entirely in the payload it carries. +**`with_raw_response`** section below). Everything the SDK raises for a call derives from one root, +`SdkError`, so one `except SdkError` covers any number of calls: + +| Exception | Raised when | Attributes beyond `method`, `url` | +|---|---|---| +| `ApiError[E]` | an error status (parsed mode only) | `error`, `status_code`, `headers` | +| `ResponseDecodeError` | a body, 2xx or documented error, its declared type rejects | `status_code`, `headers` | +| `SdkConnectionError` | no usable response: the send failed after the retries, or the body read failed | — | +| `SdkTimeoutError` (a `SdkConnectionError`) | the connection failure that was a timeout | `timeout` | +| `AuthSchemeError` | a credential that could not be applied | `scheme_failures` | + +Every member names the call (`e.method`, and `e.url`, the path rendered with no query) and keeps what +caused it, as the library or pydantic raised it, on `e.__cause__`. `ApiError` and `ResponseDecodeError` +are **siblings**: `except ApiError` never catches a 2xx that broke its contract, and +`except (ApiError, ResponseDecodeError)` spells "the server answered". ```python -from {root_package}.core import ApiError, RawError +from {root_package}.core import ApiError, RawError, SdkError ``` `ApiError` is generic in its payload (`ApiError[E]`), but you catch it **unparametrized**. A runtime `except` clause cannot discriminate a type parameter, so `except ApiError` catches every operation's -failure and you narrow on `e.error` afterwards. This is the opposite of a generator that encodes the -error type into the exception class: here the compiler-equivalent check happens at the `isinstance`, -not at the `except`. +failure and you narrow on `e.error` afterwards. ## Catch the exception -`ApiError` carries three things: +`ApiError` carries three things beyond the call: | Attribute | Type | Notes | |---|---|---| | `e.error` | the operation's error union | The decoded body. **This is the information.** | -| `e.status_code` | `int` | The status that failed. | +| `e.status_code` | `int` | The status that failed — set whichever arm of the union you got. | | `e.headers` | `Mapping[str, str]` | The response head, keys lowercased. | -**`str(e)` and `repr(e)` deliberately omit the body.** They render as `HTTP 422: {TypedError}` — the -status and the payload's *type name* only, so response bodies stay out of logs and tracebacks by -default. That is a sound default and a trap: a handler that logs `str(e)` and nothing else records -that something failed and discards every diagnostic. Read `.error` explicitly and log the fields you -choose. - -The status is **always** on `e.status_code`, whichever arm of the union you got — you never have to -choose between a typed body and knowing the status. +**`str(e)` and `repr(e)` deliberately omit the body**, so response bodies stay out of logs and +tracebacks: `str(e)` is the call and the status, `GET https://host/path returned 404 (Not Found)`, and +`repr(e)` the status and the payload's *type name*. A +handler that logs `str(e)` and nothing else discards every diagnostic; read `.error` and log the +fields you choose. ### Which error union does an operation carry? -Every operation's union is generated into its own module, `{root_package}/errors/{operation}_error.py`, +Every operation's union is declared in its own module, `{root_package}/errors/{operation}_error.py`, as a type alias: ```python @@ -56,16 +64,14 @@ Four places give you that alias, in order of preference: 1. **The contract sheet** — it lists the union per operation. 2. **The operation's map block** (`map/operations/{group}.md`) — its **Error** line names the alias and its case, and its **Error arms** bullet lists each arm *with the HTTP statuses it maps from*. - This is where the sheet's row should have come from. 3. **The operation's docstring**, whose `Raises:` section ends with the union verbatim: `` `error` is `{TypedError} | RawError`. `` 4. **The error module itself**, whose `map` is a `match` on `status_code` naming the schema each status decodes to. -**`RawError` is always the last arm.** The generator emits it unconditionally as the catch-all, so -every operation can hand you a `RawError` for any status it does not document — there is no operation -whose failure is guaranteed typed. An operation that documents *no* error schema has no error module -at all and always yields `RawError`. +**`RawError` is always the last arm**: any status the operation does not document yields `RawError`, +so no operation's failure is guaranteed typed. An operation that documents *no* error schema has no +error module at all and always yields `RawError`. ### Narrowing the union @@ -73,16 +79,13 @@ at all and always yields `RawError`. > per-operation error unions, or an operation whose alias is `RawError` alone (Case B), has nothing to > narrow — `e.error` is always `RawError` there. Skip to *Result-style alternative* for those. -**The typed arm is not one type across the API, and assuming it is is the mistake that costs the -afternoon.** A description that declares a different error schema per tag gets a different model per -tag, so a check written against one operation's arm silently fails on another's — those failures fall -through to the `RawError` branch and lose every field they actually carried. Take the arm from the -contract sheet per operation — the map's **Error arms** bullet is per-operation for exactly this -reason — never reuse one from a sibling call. +**The typed arm differs per operation.** A check written against one operation's arm silently falls +through to the `RawError` branch on another's and loses every field it carried, so take each +operation's arms from its own sheet row or the map's per-operation **Error arms** bullet — never from +a sibling call. An operation can also declare **more than one** typed arm — one per documented status or status -*range* (`4XX`, `5XX` are legal), so a union may read `{TypedError1} | {TypedError2} | RawError`. -Handle each arm you declared. +*range* (`4XX`, `5XX`), so a union may read `{TypedError1} | {TypedError2} | RawError`. Handle each. Narrow with `match` or `isinstance` — a type checker understands both — on a class arm only; a `oneOf` alias is not a class either, so match its variants. After narrowing the class arms, what remains is @@ -120,8 +123,9 @@ undocumented case — so prefer `text()` for logging unless you know better. ## Result-style alternative — `with_raw_response` (no raising) -Every operation has a raw peer reached through `with_raw_response`, which returns the outcome instead -of raising: +Every operation's raw peer, reached through `with_raw_response`, returns the outcome instead of +raising — **2xx is `Success`, everything else is `Failure`**, both carrying `.status_code` and +`.headers` (`python-calling-endpoints` has the mechanics): ```python from {root_package}.core import Success, Failure @@ -133,54 +137,41 @@ match client.{Group}.with_raw_response.{Operation}(...): ... # 'err' is the same union as the raising path ``` -`Success` and `Failure` are frozen dataclasses, so pattern matching needs nothing added; both carry -`.status_code` and `.headers` as fields of their own. On the **success** path this mode is the only -way to read either — except for a file response, which carries its own `headers` on the parsed path. -On the failure path `ApiError` already carries both, so the choice there is about whether you want an -exception, not about what you can see. `unwrap(result)` (from `{root_package}.core`) collapses either -back to the raising behaviour — in fact every parsed method is literally `unwrap(...)` around its raw peer. - -The split is mechanical: **2xx is `Success`, everything else is `Failure`.** No nuance, no per-status -judgement. Use this variant when you need the status code or headers on the *success* path, or when a -non-2xx is an expected outcome rather than an exception. - -**This mode is not exception-free.** See the next section: a decode failure raises in both modes, and -so does a failed token fetch. Mapping a `Failure` to your own error uses the same function as the -raising path — see *Guarding every call site*. +On the failure path `ApiError` already carries the status and headers, so choosing this mode there is +about whether you want an exception — use it when a non-2xx is an expected outcome. **It is not +exception-free**: the rest of the family — a decode, connection or authentication failure — raises in +both modes (next section). Map a +`Failure` through the same function as the raising path — see *Guarding every call site*. ## The failures that are not `ApiError` -Each of these reaches your boundary without matching `except ApiError`. - -### Decode failures — and they bypass *both* response modes +Each of these reaches your boundary without matching `except ApiError`, and each is an `SdkError`. -If a body does not deserialize, decoding raises `pydantic.ValidationError` (a subclass of -`ValueError`), or a plain `ValueError` when the body is not JSON at all. The pipeline states the rule -outright: *a deserialization failure is not an API error, so it propagates in both response modes -rather than becoming a failure.* `with_raw_response` does **not** convert it into a `Failure`. +### Decode failures — `ResponseDecodeError`, in *both* response modes -It arrives from two directions that mean opposite things: +If a body does not deserialize, the call raises `ResponseDecodeError` — pydantic's `ValidationError`, +or the parser's `ValueError` for a body that is not JSON at all, is its `__cause__` — in both response +modes: `with_raw_response` does **not** convert it into a `Failure`. Its `status_code` tells apart two +cases that mean opposite things: - **A 2xx whose body drifted** → the call may well have *succeeded* server-side and you cannot read - the result. The outcome is **unknown**. For a write, re-read state rather than retrying blindly. + the result. The outcome is **unknown** (a 5xx at your boundary). For a write, re-read state rather + than retrying blindly. - **A non-2xx whose body does not match the declared error schema** → the request was **rejected**; - only the detail was lost. Retrying is pointless, since it can never succeed. - -Mapping both to a 5xx is wrong half the time. At minimum, do not report a deterministic rejection as -an outage. + only the detail was lost. Retrying can never succeed, so do not report it as an outage — a 5xx tells + a retrying caller to keep retrying. -**On the success path this fires far less often than you would expect, and the gap it leaves is -worse.** Models are generated with required members only where the description marks them required — -which is frequently nowhere — and every other member defaults to `UNSET`. A response missing a field -therefore validates cleanly: +**On the success path a missing member does not raise.** Only a model's bare-annotated members are +required — on a response model often none — and every other member defaults to `UNSET`, so a response +missing a field validates cleanly: ```python value = client.{Group}.{Operation}(...) # 200 with a truncated or empty body value.{member} # UNSET — not an exception, not None ``` -A `ValidationError` on a 2xx means a *type* mismatch or a non-JSON body, not an absent field. So the -guard belongs somewhere else than you would place it by habit: +A `ResponseDecodeError` on a 2xx means a *type* mismatch or a non-JSON body, not an absent field. Guard the +members you depend on, immediately after every call that matters: ```python value = client.{Group}.{Operation}(...) @@ -188,24 +179,15 @@ if value.{member} is UNSET: raise ProviderError(502, "{Operation} returned no {member}", outcome_unknown=True) ``` -**Assert on the members you depend on, immediately after every call that matters.** For a write, an -absent identifier has the same "outcome unknown" character as a decode failure — the call may have -taken effect and you cannot name what it created. Nothing in the SDK does this for you. - -### Transport failures — the HTTP library's exceptions, unwrapped - -The SDK does **not** wrap its transport's exceptions where you catch them. The protocol says -implementations *may raise their underlying library's exceptions*; the shipped transport reports a -failed send to the retry loop, and when the last attempt fails the pipeline raises the library's own -exception. So connection refused, DNS failure, TLS error, dropped socket and timeout all reach you as -`httpx2` exceptions. +For a write, an absent identifier is "outcome unknown" like a decode failure — the call may have taken +effect and you cannot name what it created. Nothing in the SDK does this for you. -⚠ **`httpx2.HTTPError` is the base class of every one of them, timeouts included.** A lone -`except httpx2.HTTPError` arm therefore catches connection-refused and read-timeout together and gives -them one outcome — and those are opposite facts. +### Connection failures — `SdkConnectionError`, the library's exception on `__cause__` -**Which transport failures reached the server, and which did not.** This is a property of the -exception class, not a judgement call: +Connection refused, DNS failure, TLS error, dropped socket and timeouts reach you — after the last +attempt — as `SdkConnectionError`, with the `httpx2` exception on `__cause__`; a timeout is its leaf +`SdkTimeoutError`, whose `timeout` is the window that elapsed. Whether the request reached the server +is a property of the **cause's** class: | exception | did the request reach the server? | outcome | | --- | --- | --- | @@ -217,100 +199,104 @@ exception class, not a judgement call: | `httpx2.WriteTimeout` | **maybe** — sending was interrupted mid-body | **unknown** | | `httpx2.RemoteProtocolError` | **maybe** — the peer closed after the request went out | **unknown** | -`ConnectTimeout`, `PoolTimeout` and `ReadTimeout` are all `httpx2.TimeoutException` and they fall on -**opposite sides of this table**, so splitting on `TimeoutException` does not split on the thing that -matters. Split on whether the request was ever sent: +`ConnectTimeout`, `PoolTimeout` and `ReadTimeout` all arrive as `SdkTimeoutError` yet fall on +**opposite sides of this table**, so `except SdkTimeoutError` does not split them — test `__cause__`: ```python import httpx2 +from {root_package}.core import SdkConnectionError -except (httpx2.ConnectError, httpx2.ConnectTimeout, httpx2.PoolTimeout, httpx2.ProxyError) as e: - # Nothing reached the provider. Fail the operation outright; there is nothing to reconcile. - ... -except httpx2.RequestError as e: - # It may have landed. Record the outcome as UNKNOWN and reconcile before any retry. - ... -``` +NEVER_SENT = (httpx2.ConnectError, httpx2.ConnectTimeout, httpx2.PoolTimeout, httpx2.ProxyError) -Catch `httpx2.RequestError`, not `httpx2.HTTPError`, in that second arm. `HTTPError` is also the base of -`HTTPStatusError` — what `raise_for_status()` raises — and that one means a **complete response -arrived**, so sweeping it into the unknown-outcome arm mislabels the one case that is fully known. - -⚠ **`PoolTimeout` is the one to get right.** It is the characteristic failure of a saturated sync -client, which is the setup this skill recommends — so it arrives *in bulk*, exactly when the system is -already under strain. Marking it unknown floods reconciliation with work at the worst moment, for -requests that were never sent. - -**Only the second arm has an unknown outcome.** Marking a refused connection "unknown" is not the -cautious default: it schedules reconciliation for an event that provably did not happen, and it -trains the caller to distrust a failure that is in fact definitive. +except SdkConnectionError as e: + if isinstance(e.__cause__, NEVER_SENT): + ... # Nothing reached the provider. Fail the operation outright; there is nothing to reconcile. + else: + ... # It may have landed. Record the outcome as UNKNOWN and reconcile before any retry. +``` -Note the coupling: your error boundary imports the transport's exception types because the SDK's -transport does. If you supply a custom transport (`python-client-initialization`), it is *your* -transport's exceptions that arrive and this clause needs revisiting. +A `__cause__` of `None` (a custom transport that chained nothing) falls to the unknown arm, the safe +one. `PoolTimeout`, the saturated-pool failure that arrives in bulk under load, was never sent; +marking it unknown floods reconciliation with requests that never left. A custom transport +(`python-client-initialization`) raises this family too, with *its* library's classes on `__cause__`, +so `NEVER_SENT` needs those. ### A streamed download moves the failure out of the call -An operation that returns a file is one place where the call returning successfully does not mean -the transfer succeeded. The pipeline yields as soon as the response *head* arrives; the body is still -on the socket. So a connection dropped mid-transfer raises out of `read()`, `iter_bytes()` or -`save_to(...)` — not out of the call — and a `try` wrapped around the call alone catches nothing: +A file response returns as soon as the *head* arrives, so its status and headers are final, but a +connection dropped mid-transfer raises out of `read()`, `iter_bytes()` or `save_to(...)` — not out of +the call — and a `try` wrapped around the call alone catches nothing (`python-file-handling` has the +lifecycle, async included): ```python f = client.{group}.{operation}(...) # returns on the head; nothing is downloaded yet try: - f.save_to("out.bin") # the transport failure surfaces here -except httpx2.RequestError: + f.save_to("out.bin") # the connection failure surfaces here +except SdkConnectionError: ... ``` -Three consequences. The status code and headers are trustworthy before the body is — a `Failure` on a -streamed call is a real outcome, not a guess. A partial write is possible, which is why `save_to` -stages through `.part` and renames only on success, so a failed download never appears under the -final name. And `request_options={"timeout": ...}` bounds **each read**, not the call as a whole, so a -stalled transfer raises rather than hanging. The same holds on the async client, with the failure -raising out of the awaited consumer. `python-calling-endpoints` has the lifecycle itself. - ### An event stream raises from the loop An operation that returns an event stream succeeds as soon as the head arrives, like a download. What -follows raises from the **loop**: a frame the event type rejects raises pydantic's `ValidationError` -after the stream has closed, an oversized event or bad UTF-8 raises `ValueError`, and a dropped or -stalled connection raises `httpx2.RequestError` — there is no SSE exception class. +follows raises from the **loop**: a frame the event type rejects, an oversized event or bad UTF-8 +raises `ResponseDecodeError` after the stream has closed, and a dropped or stalled connection raises +`SdkConnectionError` — there is no SSE-specific class. `python-event-streams` has the full table. -### Authentication failures wear the same exception +### A paginator raises from the loop + +A paginated operation sends nothing at the call — it returns a `Paginator` — so its failures arrive +while iterating. Parsed item iteration raises `ApiError` at the failed page, after every item before +it: **wrap the `for`, not the call**. + +```python +try: + for item in client.{group}.{operation}(...): + ... +except ApiError as e: + ... +``` + +Raw mode never raises for an API error. Iterating the raw paginator for items yields the items of +every successful page and ends at the failed one; `iter_pages()` yields each page's `ApiResult`, and +a `Failure` is the last one it yields, so the walk ends there with the error body and no exception. +`ResponseDecodeError` and `SdkConnectionError` still raise from either loop, and a link walk raises +`ValueError` on a next link to a different origin. + +### Authentication failures — `AuthSchemeError` -A failed token fetch raises `ApiError` — but its payload is `OAuthProviderError | RawError`, **not** -the operation's union. Two consequences: +A credential that could not be applied raises `AuthSchemeError`, naming **your** call, not the token +endpoint's, so an `except ApiError` around the call never catches a token endpoint's `401`. The +scheme's own failure is `__cause__`, and every failure is in `scheme_failures`: + +| `e.__cause__` | What happened | +|---|---| +| `ApiError` (its `error` a `RawError`) | the token endpoint refused; the RFC 6749 `error` code is in `e.__cause__.error.json()` | +| `SdkConnectionError` | the token endpoint could not be reached | +| `ResponseDecodeError` | the token endpoint answered with a body it should not have | +| `AnySchemesError` | every configured member of an OR requirement raised | +| anything else | your own scheme or token source raised it, or a client hook did on the token request (`python-configuration-resilience`) | + +Two consequences: - It surfaces out of the **operation call**, because the token is fetched lazily on first use. The traceback points at whichever operation ran first, not at the client you configured. - It raises in `with_raw_response` mode too, because the fetch happens while the request is being built, before anything is sent. -Check it **first** in the ladder — nothing was ever sent, so it is a configuration fault, not a -rejection: - -```python -from {root_package}.core import OAuthProviderError - -except ApiError as e: - if isinstance(e.error, OAuthProviderError): - raise ProviderError(502, "provider refused our credentials") from e - ... -``` +Nothing was ever sent, so it is a configuration fault, not a rejection. The `except AuthSchemeError` +arm below maps it that way. -**A missing credential raises nothing at all.** The SDK never refuses to send a request because a -credential is absent — an unconfigured scheme contributes nothing and the request goes out -unauthenticated, so the server decides. With composite (AND/OR) security this holds too: a partial -set is applied as-is rather than withheld. There is no local "auth could not be satisfied" exception -to catch; you get a `401` from the provider instead. See `python-authentication`. +**A missing credential raises nothing**: the request goes out without it and the provider answers, +typically `401` (`python-authentication`). ### Your own mistakes -`ValidationError` from constructing a model with a missing or wrong-typed member, and `TypeError` from -passing a positional argument to a keyword-only signature, are programming errors. Let them fail +`ValidationError` from constructing a model with a missing or wrong-typed member, `TypeError` from +passing a positional argument to a keyword-only signature, and the `ValueError` for a value the SDK +refuses before sending (a path value its type rejects) are programming errors. None is an +`SdkError`. Let them fail loudly in development; do not let a production ladder swallow them. ## Guarding every call site @@ -321,8 +307,8 @@ job, a health check). A connection failure during a read fails just as hard as o call left unguarded next to one that is guarded is the one that breaks. **Convert failures to your own type in one place**, so the rest of the code has a single failure type -rather than four unrelated ones. The type is yours — the SDK's only exception class is `ApiError`; -transport and decode failures arrive as library exceptions, below. If your codebase already has an +rather than several. The type is yours: the SDK's family says *what happened*, and yours carries *what +your boundary answers*. If your codebase already has an error type, give it these two fields instead of adding another: ```python @@ -338,14 +324,15 @@ arms whichever way you called (below): ```python import httpx2 -from pydantic import ValidationError -from {root_package}.core import ApiError, OAuthProviderError +from {root_package}.core import ApiError, AuthSchemeError, ResponseDecodeError, SdkConnectionError from {root_package}.models import {TypedError} +NEVER_SENT = (httpx2.ConnectError, httpx2.ConnectTimeout, httpx2.PoolTimeout, httpx2.ProxyError) + def provider_error(status, error) -> ProviderError: match (status, error): # OUR credentials or OUR quota: the caller did nothing wrong and cannot fix it. - case (401 | 403, _) | (_, OAuthProviderError()): + case (401 | 403, _): return ProviderError(502, "provider refused our credentials") case (429, _): return ProviderError(503, "rate-limited") @@ -366,14 +353,18 @@ try: except ApiError as e: raise provider_error(e.status_code, e.error) from e -except ValidationError as e: - raise ProviderError(502, "unreadable response", outcome_unknown=True) from e # do NOT assume failure +except AuthSchemeError as e: + raise ProviderError(502, "provider refused our credentials") from e # never sent: configuration -except (httpx2.ConnectError, httpx2.ConnectTimeout, httpx2.PoolTimeout, httpx2.ProxyError) as e: - raise ProviderError(502, "Never sent.", outcome_unknown=False) from e # KNOWN: nothing happened +except ResponseDecodeError as e: + if 200 <= e.status_code < 300: + raise ProviderError(502, "unreadable response", outcome_unknown=True) from e # do NOT assume failure + raise provider_error(e.status_code, None) from e # rejected; detail lost -except httpx2.RequestError as e: - raise ProviderError(504, "No response.", outcome_unknown=True) from e # UNKNOWN: may have landed +except SdkConnectionError as e: + if isinstance(e.__cause__, NEVER_SENT): + raise ProviderError(502, "Never sent.", outcome_unknown=False) from e # KNOWN: nothing happened + raise ProviderError(504, "No response.", outcome_unknown=True) from e # UNKNOWN: may have landed ``` **Your own time limit needs its own arm.** In async code, an `asyncio.wait_for` around the call raises @@ -381,8 +372,8 @@ except httpx2.RequestError as e: `ProviderError(504, "No response.", outcome_unknown=True)`. **The raw variant maps through the same function.** A `Failure` is a value, not an exception, so there -is nothing to chain `from`; and a refused token fetch still raises `ApiError` here (it happens before -the request is sent), so the `except ApiError` above stays around the raw call too: +is nothing to chain `from`; and a refused token fetch still raises `AuthSchemeError` here (it happens +before the request is sent), so the `except` arms above stay around the raw call too: ```python match client.{Group}.with_raw_response.{Operation}(...): @@ -392,10 +383,6 @@ match client.{Group}.with_raw_response.{Operation}(...): raise provider_error(status, err) ``` -Note the last two arms, and their order: the narrow tuple must come **first**, because -`httpx2.RequestError` is its base class and would otherwise swallow it. The two are different facts, -and a single `except httpx2.HTTPError` merges them. - ⚠ **Two arms raising the same class with the same values is not a split.** The distinction has to reach something that acts on it, or it is a comment. Note that both arms above raise the **same class** on purpose — what differs is the **values they pass**, so there is no way to write either @@ -412,26 +399,9 @@ except ProviderError as e: return error_response(e.status_code, safe_message) # 502 never sent · 504 outcome unknown ``` -**Then write the test that tells the two apart.** This is what decides whether the split is real. The -check is not "are there two arms" but **"does one assertion pass for both inputs?"** — if it does, the -distinction is not real, however well the production branch reads: +Test that the two inputs yield different `(status_code, outcome_unknown)` (`python-testing`). -```python -def test_unsent_is_not_the_same_failure_as_unknown(): - unsent = failure_from(httpx2.ConnectError("refused")) # never left the process - unknown = failure_from(httpx2.ReadTimeout("no reply")) # may have landed - - assert (unsent.status_code, unsent.outcome_unknown) == (502, False) - assert (unknown.status_code, unknown.outcome_unknown) == (504, True) - assert unsent.status_code != unknown.status_code # the caller can tell them apart - assert reconciled() == [unknown.reference] # and only one reconciles -``` - -Two tests asserting the *same* exception for a refused connection and a read timeout is this defect -wearing a passing suite. - -Always `raise ... from e`. Losing `__cause__` costs you the traceback that names which of the four -paths you were on. +Always `raise ... from e`. Losing `__cause__` costs you the traceback that names which path you were on. ## Presenting failures at your boundary @@ -445,34 +415,21 @@ unknown error has no meaningful client status and belongs at 5xx. Collapsing eve blanket status discards the only signal separating "you sent something invalid" from "the provider is down". -**Not every provider failure is the caller's fault.** A `401`/`403` means *your* credentials are wrong, -and a `429` means *your* quota is spent — passing either straight through tells the caller they are -unauthenticated or throttled when they are neither. Those belong at 5xx (the `match` above), and so -does the default arm. - -**An unreadable body is two cases, not one — decide which before you map it.** An unreadable -*success* body is genuinely unknown: 5xx. An unreadable *error* body is not — the provider rejected -the request and only the detail was lost, so answering 5xx tells a retrying caller to keep retrying -something that can never succeed. - **Never map a parse failure onto a domain absence.** "I could not read the answer" is not "the provider said no". On a lookup both leave you without a record, but only one is a fact — and where a lookup gates a create, conflating them turns a corrupt response into a spurious create. If a miss is signalled by an empty body, match on *empty*, not on *unparseable*. -**Never surface `str(e)` or a traceback to your caller.** For an SDK exception the string is only -`HTTP 422: {TypedError}`, so it is useless as well as leaky; a `ValidationError` embeds pydantic type -and field-path detail. Log the detail, return a message you wrote. +**Never surface `str(e)` or a traceback to your caller** — an `SdkError`'s message names the provider's +URL, and its `__cause__` (a pydantic `ValidationError`, an `httpx2` error) embeds field-path and host +detail. Log the detail, return a message you wrote. ## Notes -- **Retries are on by default.** A retryable status or transport failure surfaces only after the last - attempt, and the exception you catch is the same one a single attempt would raise. With `max_retries` - set to `0` nothing is resent. See `python-configuration-resilience`. -- **A `401` invalidates the cached credential but does not retry the request.** Your code sees one - `401` (your boundary answers it as `502`), and the *next* call obtains - a fresh token. Do not read a single 401 as a permanent credential failure. -- `ApiError` implements `__reduce__`, so it pickles — it survives crossing a process boundary (a - Celery result, a multiprocessing queue) with its payload intact. -- `e.headers` has **lowercased keys**, guaranteed by the transport contract — look up - `"x-request-id"`, never `"X-Request-Id"`. +- **Retries are on by default**; what you catch is the last attempt's failure, the same one a single + attempt would raise (`python-configuration-resilience`). +- **A `401` drops the cached token without retrying the call** (`python-authentication`): your code + sees one `401` — your boundary answers `502` — and the next call fetches a fresh token. +- Every `SdkError` pickles, so it survives crossing a process boundary (a Celery result, a + multiprocessing queue) with its payload intact; `copy` and `deepcopy` work too. +- Your own cancellation (`KeyboardInterrupt`, `asyncio.CancelledError`) is never wrapped. diff --git a/plugins/slack/skills/python/python-event-streams/SKILL.md b/plugins/slack/skills/python/python-event-streams/SKILL.md index 90ce063f..9ff44026 100644 --- a/plugins/slack/skills/python/python-event-streams/SKILL.md +++ b/plugins/slack/skills/python/python-event-streams/SKILL.md @@ -1,6 +1,6 @@ --- name: python-event-streams -description: Consuming a server-sent-events (text/event-stream) operation on an APIMatic-generated Python SDK — what EventStream[T] / AsyncEventStream[T] yields, how the loop must end so the connection is released, narrowing a union of event types, what raises and when (there is no SSE exception class), the silent failures, and bounding the wait. Load before writing the loop over an operation that returns an event stream, in addition to `python-calling-endpoints`. +description: Load before writing the loop over an APIMatic-generated Python SDK operation that returns a server-sent-events (text/event-stream) stream, together with `python-calling-endpoints`. Covers what EventStream[T] / AsyncEventStream[T] yields, ending the loop so the connection is released, narrowing event unions, what raises from the loop, and bounding the wait. --- # Event streams on an APIMatic Python SDK @@ -74,17 +74,16 @@ does **not** — it leaves `T | UnsetType`. | What failed | Parsed call | `with_raw_response` | |---|---|---| | a non-2xx status (the head) | raises `ApiError` at the call | returns `Failure` — no raise | -| a frame the event type rejects | raises pydantic's `ValidationError` from the loop, **after** the stream closed | same | -| an event over 1 MiB, or bad UTF-8 | raises `ValueError` / `UnicodeDecodeError` from the loop | same | -| the wire stalls | raises `httpx2.ReadTimeout` from the loop | same | -| the connection drops mid-stream | raises an `httpx2.RequestError` subclass from the loop, such as `RemoteProtocolError` or `ReadError` | same | +| a frame the event type rejects | raises `ResponseDecodeError` from the loop, **after** the stream closed; pydantic's `ValidationError` on `__cause__` | same | +| an event over 1 MiB, or bad UTF-8 | raises `ResponseDecodeError` from the loop; the `ValueError` / `UnicodeDecodeError` on `__cause__` | same | +| the wire stalls | raises `SdkTimeoutError` from the loop; `httpx2.ReadTimeout` on `__cause__` | same | +| the connection drops mid-stream | raises `SdkConnectionError` from the loop; an `httpx2` error such as `RemoteProtocolError` or `ReadError` on `__cause__` | same | | **the connection closes a body with no `Content-Length` that is not chunked** | **nothing — the loop ends early** | same | | **the body is not an event stream** | **nothing — the loop ends with zero events** | same | -**There is no SSE exception class.** Everything the loop raises for a bad body is already a -`ValueError`, so one `except ValueError` covers the family. A stalled or dropped connection is not a -bad body: it raises `httpx2.RequestError` (`ReadTimeout` included), so catch that too. Put both -boundaries around the **loop**, not only the call — the call returns as soon as the head arrives. +**There is no SSE-specific exception class.** A bad body is `ResponseDecodeError` and a stalled or +dropped connection `SdkConnectionError`, both `SdkError`, so one `except SdkError` covers the loop. Put +the boundary around the **loop**, not only the call — the call returns as soon as the head arrives. The last row is a known gap: the SDK does not check `Content-Type`, so a 200 carrying a proxy's HTML page or a buffered JSON body parses as a stream of zero events and ends quietly. If a stream yields diff --git a/plugins/slack/skills/python/python-file-handling/SKILL.md b/plugins/slack/skills/python/python-file-handling/SKILL.md index df25a80e..eb832423 100644 --- a/plugins/slack/skills/python/python-file-handling/SKILL.md +++ b/plugins/slack/skills/python/python-file-handling/SKILL.md @@ -1,6 +1,6 @@ --- name: python-file-handling -description: Sending and receiving files with an APIMatic-generated Python SDK — which arm of the upload alias to hand an endpoint and what each one costs in memory, re-sendability and ownership, the three behaviours that differ between a multipart part and a raw body, when a body goes out chunked rather than sized, overriding a filename or media type, and consuming a streamed file response without leaking its connection. Load before passing a file to an operation or consuming one it returns, in addition to `python-calling-endpoints`. +description: Load before passing a file to an APIMatic-generated Python SDK operation or consuming a file it returns, together with `python-calling-endpoints`. Covers which upload arm to pass and its memory, re-send and ownership costs, multipart part vs raw body, chunked vs sized bodies, filename and media-type overrides, and consuming a file response without leaking its connection. --- # File handling on an APIMatic Python SDK @@ -17,8 +17,9 @@ AsyncFileInput = AsyncBinaryContent | NamedFile[AsyncBinaryContent] # asyn ``` So you make exactly one choice: **where the bytes come from**. The destination is fixed by the -endpoint, and the flavour by the client. All of these are imported from `{root_package}.core`, and -`list[FileInput]` is an array part. +endpoint, and the flavour by the client. These aliases and their content unions, `NamedFile`, the two +reader protocols and the two response classes are all imported from `{root_package}.core` — they are +not re-exported from the package root — and `list[FileInput]` is an array part. Nothing validates what you pass, so a wrong arm is a type error at build time and a wrong *value* is a failure at send time. What each arm accepts is wider than the annotation suggests. @@ -67,10 +68,8 @@ These are the only places the position still matters, and none of them is visibl windows rather than one whole `bytes` from an `AsyncIterable` — your pieces are forwarded as you yield them, so a single large `bytes` is resident before the SDK ever sees it. - So **do not reach for an async handle over a file you could have named.** `anyio.open_file(p)` in - a part costs two reads and a write where `Path(p)` costs one read. The async arms earn their keep - when there is no path — bytes arriving from another connection, a queue, a subprocess — and cost a - round trip through the filesystem when there is one. + So prefer `Path(p)` to `anyio.open_file(p)` in a part — one read instead of two reads and a write; + the async arms are for bytes with no path behind them (another connection, a queue, a subprocess). On the **async client**, reading a *sync* arm inside a multipart body occupies the event loop while it reads, so `bytes` and the async arms are the spellings that never block it there. A raw body has @@ -109,8 +108,8 @@ client.{group}.{operation}(NamedFile(b"...", filename="invoice.pdf", media_type= Set `filename` and it wins over a `Path`'s own name and a handle's `.name` alike, so wrapping a named source renames it rather than being ignored. -**Every file currently goes out as `application/octet-stream`** whatever the spec declares, so -`NamedFile(content, media_type=...)` is the only way to send anything else. If the server validates a +**Every file goes out as `application/octet-stream`** unless you pass +`NamedFile(content, media_type=...)` — the only way to send anything else. If the server validates a part's `Content-Type`, say the type yourself. ## There is no `str` arm @@ -161,30 +160,24 @@ Both iterators take a `chunk_size`, defaulting to 64 KiB. f.aread()`, `async for chunk in f.aiter_bytes()`, `await f.aclose()`, and `async with` as the spelling to reach for. **`save_to` is the exception**: it keeps its name and is awaited — `await f.save_to("out.bin")` — so there is no `asave_to`. Calling it without `await` creates a coroutine - and drops it: nothing is written and the connection stays held. An abandoned response defers its - warning to loop shutdown, where it is far less useful — and that warning is silenced by default - too. + and drops it: nothing is written and the connection stays held. An abandoned async response defers + its warning to loop shutdown, and that `ResourceWarning` is hidden by Python's default warning + filters — so the leak is silent unless you enable it. - **`save_to` accepts a directory**, naming the file from the server's `Content-Disposition` — reduced to a safe basename first, because that header is attacker-controlled — and raising `ValueError` when - the server sent no filename, or sent one that reduces to nothing safe to create: empty, `.` or - `..`, a reserved device name (`CON`, `NUL`, `COM1`…), or longer than 255 characters. It writes - `.part` and moves it into place atomically, so an interrupted download never appears under + the server sent no filename or none that is safe to create: empty, `.` or `..`, a reserved device + name (`CON`, `NUL`, `COM1`…), or longer than 255 characters. It writes `.part` and moves it + into place atomically, so an interrupted download never appears under the final name. If the destination cannot be opened at all — a missing parent directory, or permissions — the response is still consumable. - **The head has already arrived**, so `headers`, `media_type`, `content_length` and `filename` are readable before you read a byte. `filename` is the server's suggestion and may be `None`. - **`request_options={"timeout": ...}` bounds each read of the body**, not the call as a whole, so a - stalled download raises rather than hanging. -- **A transport failure mid-download raises out of the *read*, not out of the call.** The call already + stalled download raises `SdkTimeoutError` rather than hanging. +- **A connection failure mid-download raises `SdkConnectionError` out of the *read*, not out of the call.** The call already returned successfully — only the head had arrived — so a `try` wrapped around the call alone catches nothing. Put the boundary around the consuming code (`python-error-handling`). With `with_raw_response`, the payload is the same unread `FileResponse`. The raw peer buys you the status code and headers, not the bytes — a result carries no body of its own, because here the body *is* the payload. - -## Where these types live - -Import all of them from `{root_package}.core`: the two aliases and their content unions, `NamedFile`, -the two reader protocols, and the two response classes. They are not re-exported from -`{root_package}/__init__.py`, so the package root is not where to look for them. diff --git a/plugins/slack/skills/python/python-getting-started/SKILL.md b/plugins/slack/skills/python/python-getting-started/SKILL.md index 779f3909..5a7a5d8d 100644 --- a/plugins/slack/skills/python/python-getting-started/SKILL.md +++ b/plugins/slack/skills/python/python-getting-started/SKILL.md @@ -1,20 +1,16 @@ --- name: "python-getting-started" -description: "Slack Web API Python SDK identity and lookup layer (Python only) — install, import root, base URL/environments, the auth pattern, the SDK map that ships at the SDK root (`sdk-map.md` + `map/operations/`) and how to traverse it, and the module table naming the one file owning each fact the map leaves to the source. Load this before answering any Slack Web API Python SDK contract question or writing any SDK code." +description: "Load before answering any Slack Web API Python SDK question or writing Python code against the SDK (Python only). The SDK's lookup layer: install, imports, environments and base URL, auth, the SDK map (`sdk-map.md` + `map/operations/`) and how to read it, and the module that owns each fact the map leaves to the source." --- # Getting started with the Slack Web API Python SDK -> **Who this skill is for.** This is the **lookup layer** for anyone writing Slack Web API Python SDK code — it is yours to follow directly and fully. Ground every contract fact here (in the SDK map, and in the source modules it names) rather than in recall, and carry those facts onto a contract sheet before you implement. Load `python-integrate-slack-web-api` for the workflow that wraps this skill. +> **Lookup layer** for Slack Web API Python SDK code: ground every contract fact here, in the SDK map and in the source modules they name — never in recall — and carry those facts onto a contract sheet before you implement. `python-integrate-slack-web-api` holds the workflow around it. -This is the **SDK-specific** entry point. For general patterns that apply to any APIMatic-generated Python SDK (client construction, auth, calling endpoints, models, error handling, resilience, testing), see the companion API-agnostic skills: `python-client-initialization`, `python-authentication`, `python-calling-endpoints`, `python-models`, `python-error-handling`, `python-configuration-resilience` and `python-testing`. - -**This page and those companion skills are complementary — load both.** This page is authoritative for the SDK's *identity and surface* (what to install, what to import, the controllers, which module owns which fact); the companion skills are the *usage layer* on top — the best-practice way to call each piece and the gotchas a signature cannot show. Reading a module in the installed package does not remove the need to load the skill for that step, so at each step below, load the companion *and* confirm names against the installed package. +This page owns the SDK's *identity and surface* (install, imports, controllers, which module owns which fact). The API-agnostic companion skills own *usage* — `python-client-initialization`, `python-authentication`, `python-calling-endpoints`, `python-models`, `python-error-handling`, `python-configuration-resilience` and `python-testing`; load each at its step (see **Integration workflow**) and confirm names against the installed package. ## SDK identity -Verified against `slack_web_api/` and `pyproject.toml` of the generated package at version `1.7.0`. **Re-verify after a version bump** — this page is a snapshot, not a live read. - | Fact | Value | | --- | --- | | API | Slack Web API | @@ -22,21 +18,18 @@ Verified against `slack_web_api/` and `pyproject.toml` of the generated package | Import root (what you import) | `slack_web_api` — not the string you install | | Source repository | https://github.com/context-plugins/slack-python-sdk | | Source branch | `main` | -| Version | `1.7.0` | +| Version | `1.7.0` — re-verify this page after a version bump | | Sync client class | `SlackWebApiClient` (alias `Client`) | | Async client class | `AsyncSlackWebApiClient` (alias `AsyncClient`) | -| Client construction | **keyword-only**: `environment` · `base_url` · `timeout` (default `30.0`) · `retry_options` · `slack_auth` · `slack_auth_token_source`, and the transport override — `custom_http_client` on the sync client, `custom_async_http_client` on the async one (the names differ; see step 1) | +| Client construction | **keyword-only**: `server_config` · `timeout` (default `30.0`) · `retry_options` · `logging_options` · `hooks` · `slack_auth` · `slack_auth_token_source`, and the transport override — `custom_http_client` on the sync client, `custom_async_http_client` on the async one (the names differ) | | Auth | **OAuth 2.0** authorization code — set `slack_auth` | -| Environments | 2 environments selected by `environment` (default `"production"`), overridable with `base_url` | -| Base-URL config | `ServerConfig` (`slack_web_api/server/server_config.py`), frozen, `extra="forbid"` | +| Environments | one environment; 2 named servers configured through `server_config` | +| Base-URL config | `ServerConfig` (`slack_web_api/server/server_config.py`) | | Python floor | **`>=3.10`** (classifiers list `3.10–3.14`) | | Runtime dependencies | `httpx2 (>=2.13.1,<3.0.0)` · `certifi (>=2024.7.4)` · `pydantic[email] (>=2.11.0,<3.0.0)` · `typing-extensions (>=4.13.0,<5.0.0)` | -| Typing | ships `py.typed`; the package is checked under `mypy --strict` with `warn_unreachable`. Callers get full inference — **a type error against this SDK is a real contract violation, not noise** | -| Line length / lint | `ruff`, 120 cols (only relevant when editing the SDK itself) | +| Typing | ships `py.typed` — **a type error against this SDK is a real contract violation, not noise** | | Surface | 253 operations across 56 controllers · 357 models · 0 unions · 89 enums · 0 per-operation error unions | -The table above is **orientation, not a copy-paste recipe** — it gives you the names and facts (install, import roots, the auth *pattern*, the base-URL knob), while the actual integration code comes from the companion skills. Load each one as you reach its step (see **Integration workflow** below) and confirm its types against the installed package. - ## Install — from source Into the same environment your project runs in, install the distribution from its repository, — it is not published to a package index: @@ -48,58 +41,56 @@ python -c "import slack_web_api, pathlib; print(pathlib.Path(slack_web_api.__fil **Run the second line too.** A `pip install` that reports success is not proof the SDK is importable where your project runs. If the probe raises `ModuleNotFoundError`, the install went into a different interpreter: re-run it through the one your project uses (`python -m pip install …`) and probe again. If it prints a path whose contents are not this SDK, what you installed is not this distribution. -The distribution carries its own `pyproject.toml`, so `pip` builds and installs it like any released package, copied into site-packages. Do not vendor its source into your project, add its directory to `sys.path`, or install it editable (`-e`) from a throwaway clone — an editable install points at that directory, so deleting the clone breaks every import. - -Once the second line prints this SDK's directory, write the imports from the table above: the distribution name you install and the package name you import are not the same string. Requires Python 3.10 or newer. +Install it as a package, into site-packages. Do not vendor its source into your project, add its directory to `sys.path`, or install it editable (`-e`) from a throwaway clone — an editable install points at that directory, so deleting the clone breaks every import. ## Imports — the package splits its surface across four modules Python does not re-export child modules transitively, so `from slack_web_api import models` alone does **not** make enums, error unions, or runtime types reachable. Import each kind of type from the module that owns it. -`slack_web_api/__init__.py` exports exactly 6 names beside the `slack_web_api.models` subpackage it re-exports: +`slack_web_api/__init__.py` exports exactly 7 names beside the `slack_web_api.models` subpackage it re-exports: ```python from slack_web_api import ( AsyncClient, AsyncSlackWebApiClient, Client, - Environment, ServerConfig, + ServerConfigDict, + ServerConfigOrDict, SlackWebApiClient, ) ``` -Everything else comes from its own subpackage, and the split matters because each kind of type a caller reaches for lives in a different module: +Everything else comes from its own subpackage: | What you need | Where it lives | | --- | --- | | Domain models, their `…Dict` companions | `slack_web_api.models` | | Enums (and their open `…OrStr` aliases) | `slack_web_api.models.enums` | -| `ApiError` · `RawError` · `ApiResult` · `RequestOptions` · `AuthorizationCodeCredentials` · `HttpClient` · `SdkBaseModel` · `UNSET` · `Optional` | `slack_web_api.core` | +| `SdkError` · `ApiError` · `RawError` · `ApiResult` · `RequestOptions` · `AuthorizationCodeCredentials` · `HttpClient` · `SdkBaseModel` · `UNSET` · `Optional` | `slack_web_api.core` | | Per-operation error *unions* | `slack_web_api.errors` — *this SDK declares none* | -`slack_web_api.core` re-exports its whole public surface (a curated `__all__`), so import from `…core` rather than from the private modules beneath it (`…core.results`, `…core.exceptions`, `…core.auth.schemes`). +`slack_web_api.core` re-exports its whole public surface, so import from `…core` rather than from the private modules beneath it (`…core.results`, `…core.exceptions`, `…core.auth.schemes`). -## Environments +## Servers — one config object, several servers -The constructor takes an `environment` keyword — a **string literal alias**, not an enum — followed by `base_url`. The declared environments and the base URL each resolves to: +This SDK has 2 named servers and a single environment, so the constructor takes `server_config: ServerConfigOrDict | None = None` rather than a bare `base_url`. Each server is a field on that config: -| `environment=` | Base URL | Hosting | -| --- | --- | --- | -| `"production"` *(default)* | `https://slack.com/api` | — | -| `"environment2"` | `https://slack.com/oauth` | — | +| Server field | Base URL | +| --- | --- | +| `default` | `https://slack.com/api` | +| `auth_server` | `https://slack.com/oauth/v2` | Consequences to state on every contract sheet that touches configuration: -- Omitting `environment` gives you **`"production"`**, silently — it is whatever the description listed first, not necessarily production. -- `base_url` overrides the environment's URL entirely when both are passed. -- The token endpoint is derived from the same base URL (`/oauth.access`), so it always follows the environment — you never configure it separately. +- Omitting `server_config` falls through to the config's own defaults rather than writing `None` over them. +- The token endpoint (`/oauth.v2.access`) resolves against the `default` server rather than a client-wide base URL, so `server_config` is what moves token traffic. - `ServerConfig` is a frozen pydantic model with `extra="forbid"`: a misspelled keyword raises `ValidationError` at construction rather than being ignored. - `timeout` is validated too — the base client raises `ValueError` for any non-positive value. ## Auth pattern (one scheme) -OAuth 2.0 authorization code, exposed as the client's `slack_auth=` keyword taking `AuthorizationCodeCredentials` **or a plain dict**. The client fetches and caches the bearer token itself, lazily, from `/oauth.access`. +OAuth 2.0 authorization code, exposed as the client's `slack_auth=` keyword taking `AuthorizationCodeCredentials` **or a plain dict**. The client fetches and caches the bearer token itself, lazily, from `/oauth.v2.access` on the `default` server. ```python from slack_web_api import Client @@ -112,83 +103,18 @@ client = Client(slack_auth=AuthorizationCodeCredentials(client_id="…", client_ client = Client(slack_auth={"client_id": "…", "client_secret": "…", "redirect_uri": "…", "prompt_for_authorization_code": prompt}) # equivalent ``` -**Every credentials keyword is optional at the type level and that is a trap worth flagging on every sheet.** Omit it and the client is built with `no_auth`: every request goes out unauthenticated. Nothing fails at construction. Most APIs then answer `401`; an API that serves anonymous traffic at all answers `200` and hides the omission entirely — verify the keyword is set rather than waiting for a `401` to tell you. - -See `python-authentication` for the full picture, including what a *failed token fetch* raises — it is not what a caller expects, and it is the single most common surprise in this SDK. +**Every credentials keyword is optional** — omit it and requests go out unauthenticated, with nothing failing at construction; `python-authentication` covers how to catch that, and what a *failed token fetch* raises. ## Controllers -Controllers and their operation counts (`client.`): - -| Attribute | Class | Ops | Area | -| --- | --- | --- | --- | -| `client.admin` | `Admin` / `AsyncAdmin` | 56 | `admin_apps_approve` · `admin_apps_approved_list` · `admin_apps_requests_list` · `admin_apps_restrict` · `admin_apps_restricted_list` · `admin_conversations_archive` · … | -| `client.admin_apps` | `AdminApps` / `AsyncAdminApps` | 2 | `admin_apps_approve` · `admin_apps_restrict` | -| `client.admin_apps_approved` | `AdminAppsApproved` / `AsyncAdminAppsApproved` | 1 | `admin_apps_approved_list` | -| `client.admin_apps_requests` | `AdminAppsRequests` / `AsyncAdminAppsRequests` | 1 | `admin_apps_requests_list` | -| `client.admin_apps_restricted` | `AdminAppsRestricted` / `AsyncAdminAppsRestricted` | 1 | `admin_apps_restricted_list` | -| `client.admin_conversations` | `AdminConversations` / `AsyncAdminConversations` | 13 | `admin_conversations_archive` · `admin_conversations_convert_to_private` · `admin_conversations_create` · `admin_conversations_delete` · `admin_conversations_disconnect_shared` · `admin_conversations_get_conversation_prefs` · … | -| `client.admin_conversations_ekm` | `AdminConversationsEkm` / `AsyncAdminConversationsEkm` | 1 | `admin_conversations_ekm_list_original_connected_channel_info` | -| `client.admin_conversations_restrict_access` | `AdminConversationsRestrictAccess` / `AsyncAdminConversationsRestrictAccess` | 3 | `admin_conversations_restrict_access_add_group` · `admin_conversations_restrict_access_list_groups` · `admin_conversations_restrict_access_remove_group` | -| `client.admin_emoji` | `AdminEmoji` / `AsyncAdminEmoji` | 5 | `admin_emoji_add` · `admin_emoji_add_alias` · `admin_emoji_list` · `admin_emoji_remove` · `admin_emoji_rename` | -| `client.admin_invite_requests` | `AdminInviteRequests` / `AsyncAdminInviteRequests` | 3 | `admin_invite_requests_approve` · `admin_invite_requests_deny` · `admin_invite_requests_list` | -| `client.admin_invite_requests_approved` | `AdminInviteRequestsApproved` / `AsyncAdminInviteRequestsApproved` | 1 | `admin_invite_requests_approved_list` | -| `client.admin_invite_requests_denied` | `AdminInviteRequestsDenied` / `AsyncAdminInviteRequestsDenied` | 1 | `admin_invite_requests_denied_list` | -| `client.admin_teams` | `AdminTeams` / `AsyncAdminTeams` | 2 | `admin_teams_create` · `admin_teams_list` | -| `client.admin_teams_admins` | `AdminTeamsAdmins` / `AsyncAdminTeamsAdmins` | 1 | `admin_teams_admins_list` | -| `client.admin_teams_owners` | `AdminTeamsOwners` / `AsyncAdminTeamsOwners` | 1 | `admin_teams_owners_list` | -| `client.admin_teams_settings` | `AdminTeamsSettings` / `AsyncAdminTeamsSettings` | 6 | `admin_teams_settings_info` · `admin_teams_settings_set_default_channels` · `admin_teams_settings_set_description` · `admin_teams_settings_set_discoverability` · `admin_teams_settings_set_icon` · `admin_teams_settings_set_name` | -| `client.admin_usergroups` | `AdminUsergroups` / `AsyncAdminUsergroups` | 4 | `admin_usergroups_add_channels` · `admin_usergroups_add_teams` · `admin_usergroups_list_channels` · `admin_usergroups_remove_channels` | -| `client.admin_users` | `AdminUsers` / `AsyncAdminUsers` | 8 | `admin_users_assign` · `admin_users_invite` · `admin_users_list` · `admin_users_remove` · `admin_users_set_admin` · `admin_users_set_expiration` · … | -| `client.admin_users_session` | `AdminUsersSession` / `AsyncAdminUsersSession` | 2 | `admin_users_session_invalidate` · `admin_users_session_reset` | -| `client.api2` | `Api2` / `AsyncApi2` | 1 | `api_test` | -| `client.apps` | `Apps` / `AsyncApps` | 8 | `apps_event_authorizations_list` · `apps_permissions_info` · `apps_permissions_request` · `apps_permissions_resources_list` · `apps_permissions_scopes_list` · `apps_permissions_users_list` · … | -| `client.apps_event_authorizations` | `AppsEventAuthorizations` / `AsyncAppsEventAuthorizations` | 1 | `apps_event_authorizations_list` | -| `client.apps_permissions` | `AppsPermissions` / `AsyncAppsPermissions` | 2 | `apps_permissions_info` · `apps_permissions_request` | -| `client.apps_permissions_resources` | `AppsPermissionsResources` / `AsyncAppsPermissionsResources` | 1 | `apps_permissions_resources_list` | -| `client.apps_permissions_scopes` | `AppsPermissionsScopes` / `AsyncAppsPermissionsScopes` | 1 | `apps_permissions_scopes_list` | -| `client.apps_permissions_users` | `AppsPermissionsUsers` / `AsyncAppsPermissionsUsers` | 2 | `apps_permissions_users_list` · `apps_permissions_users_request` | -| `client.auth_api` | `AuthApi` / `AsyncAuthApi` | 2 | `auth_revoke` · `auth_test` | -| `client.bots` | `Bots` / `AsyncBots` | 1 | `bots_info` | -| `client.calls` | `Calls` / `AsyncCalls` | 6 | `calls_add` · `calls_end` · `calls_info` · `calls_participants_add` · `calls_participants_remove` · `calls_update` | -| `client.calls_participants` | `CallsParticipants` / `AsyncCallsParticipants` | 2 | `calls_participants_add` · `calls_participants_remove` | -| `client.chat` | `Chat` / `AsyncChat` | 10 | `chat_delete` · `chat_delete_scheduled_message` · `chat_get_permalink` · `chat_me_message` · `chat_post_ephemeral` · `chat_post_message` · … | -| `client.chat_scheduled_messages` | `ChatScheduledMessages` / `AsyncChatScheduledMessages` | 1 | `chat_scheduled_messages_list` | -| `client.conversations` | `Conversations` / `AsyncConversations` | 18 | `conversations_archive` · `conversations_close` · `conversations_create` · `conversations_history` · `conversations_info` · `conversations_invite` · … | -| `client.dialog` | `Dialog` / `AsyncDialog` | 1 | `dialog_open` | -| `client.dnd` | `Dnd` / `AsyncDnd` | 5 | `dnd_end_dnd` · `dnd_end_snooze` · `dnd_info` · `dnd_set_snooze` · `dnd_team_info` | -| `client.emoji` | `Emoji` / `AsyncEmoji` | 1 | `emoji_list` | -| `client.files` | `Files` / `AsyncFiles` | 13 | `files_comments_delete` · `files_delete` · `files_info` · `files_list` · `files_remote_add` · `files_remote_info` · … | -| `client.files_comments` | `FilesComments` / `AsyncFilesComments` | 1 | `files_comments_delete` | -| `client.files_remote` | `FilesRemote` / `AsyncFilesRemote` | 6 | `files_remote_add` · `files_remote_info` · `files_remote_list` · `files_remote_remove` · `files_remote_share` · `files_remote_update` | -| `client.migration` | `Migration` / `AsyncMigration` | 1 | `migration_exchange` | -| `client.oauth` | `Oauth` / `AsyncOauth` | 3 | `oauth_access` · `oauth_token` · `oauth_v2_access` | -| `client.oauth_v2` | `OauthV2` / `AsyncOauthV2` | 1 | `oauth_v2_access` | -| `client.pins` | `Pins` / `AsyncPins` | 3 | `pins_add` · `pins_list` · `pins_remove` | -| `client.reactions` | `Reactions` / `AsyncReactions` | 4 | `reactions_add` · `reactions_get` · `reactions_list` · `reactions_remove` | -| `client.reminders` | `Reminders` / `AsyncReminders` | 5 | `reminders_add` · `reminders_complete` · `reminders_delete` · `reminders_info` · `reminders_list` | -| `client.rtm` | `Rtm` / `AsyncRtm` | 1 | `rtm_connect` | -| `client.search` | `Search` / `AsyncSearch` | 1 | `search_messages` | -| `client.stars` | `Stars` / `AsyncStars` | 3 | `stars_add` · `stars_list` · `stars_remove` | -| `client.team_api` | `TeamApi` / `AsyncTeamApi` | 5 | `team_access_logs` · `team_billable_info` · `team_info` · `team_integration_logs` · `team_profile_get` | -| `client.team_profile` | `TeamProfile` / `AsyncTeamProfile` | 1 | `team_profile_get` | -| `client.usergroups` | `Usergroups` / `AsyncUsergroups` | 7 | `usergroups_create` · `usergroups_disable` · `usergroups_enable` · `usergroups_list` · `usergroups_update` · `usergroups_users_list` · … | -| `client.usergroups_users` | `UsergroupsUsers` / `AsyncUsergroupsUsers` | 2 | `usergroups_users_list` · `usergroups_users_update` | -| `client.users` | `Users` / `AsyncUsers` | 12 | `users_conversations` · `users_delete_photo` · `users_get_presence` · `users_identity` · `users_info` · `users_list` · … | -| `client.users_profile` | `UsersProfile` / `AsyncUsersProfile` | 2 | `users_profile_get` · `users_profile_set` | -| `client.views` | `Views` / `AsyncViews` | 4 | `views_open` · `views_publish` · `views_push` · `views_update` | -| `client.workflows` | `Workflows` / `AsyncWorkflows` | 3 | `workflows_step_completed` · `workflows_step_failed` · `workflows_update_step` | - -Every controller has an `Async…` peer whose operations are identical in name and parameters and differ solely by being awaited. Do not emit a separate row for an async operation; state the rule once on the sheet. - -The SDK map's controller table carries the same counts and links to a page per controller (`map/operations/.md`) — go there for the operations themselves. +56 controllers, reached as `client.`. Every controller has an `Async…` peer whose operations have the same names and parameter names and are awaited, their `request_options` being `AsyncRequestOptionsOrDict` — state that once on the sheet rather than a row per async operation. `sdk-map.md`'s **Operations — by controller** table lists each controller's attribute, classes and operation count, and links its page (`map/operations/.md`), one block per operation. ## SDK map — look up first, open the module second The SDK ships a generated map at its **root** — the directory holding `pyproject.toml`, the `slack_web_api/` source directory, and these two entries: -- **`sdk-map.md`** — the index: client construction with the full constructor-keyword table, the error-handling model (`ApiError` / `ApiResult` / `RawError`, Case A vs Case B), where models, enums and error aliases live, servers and auth, and the link table into the operations pages. -- **`map/operations/.md`** — one page per controller, one `###` block per operation: the HTTP verb and route, the sync parsed signature, each parameter's role and wire name, both return types, the error alias with the status each arm maps from, and a **Type sources** table naming the module that declares every *generated* type the operation mentions. +- **`sdk-map.md`** — the index: constructor keywords, the error model (`ApiError` / `ApiResult` / `RawError`, Case A vs Case B), where models, enums and error aliases live, servers and auth, and links to the operations pages. +- **`map/operations/.md`** — one `###` block per operation: verb and route, signature, parameter roles and wire names, both return types, error arms with the status each maps from, and a **Type sources** table naming the module of every *generated* type it mentions. **Installing the distribution does not give you the map.** `pyproject.toml` ships the `slack_web_api/` package only, so `sdk-map.md` and `map/operations/` are absent from the installed package — they live in the SDK's own source tree, at the root of its repository, , in lockstep with the code the map describes — clone it to a temporary directory, outside the project repo: @@ -198,25 +124,17 @@ git clone --depth 1 --branch main https://github.com/context-plugins/slack-pytho Confirm the map comes from the release you installed before you read anything out of it: the clone above is pinned to `main`, the branch this SDK is released from — the repository's default branch may carry a different version. A map read from any other release describes code you do not have. -Every `Source` path on the map is relative to that SDK root, so `slack_web_api/models/apimethodusers_get_presence.py` opens as written from there — and the same path resolves inside the installed package, which is where you read a module's body once the map has named it. +Every `Source` path on the map is relative to that SDK root, so `slack_web_api/models/ap_imethodusers_get_presence.py` opens as written from there — and the same path resolves inside the installed package, which is where you read a module's body once the map has named it. -**The map is the locator; the source modules are the shapes.** Read the map first — signatures, routes, parameter roles, return types, error unions, and which module declares a type are all answered there without opening a single `.py` file. Then open the one module the map names for what it deliberately does not carry: a model's members, an enum's values, a field's wire alias. The map says so itself — *"Shapes live only in the source … Never grep for a type."* +**The map is the locator; the source modules are the shapes.** Read the map first — an operation's signature, route, parameter roles and return types, the client's constructor keywords, the `timeout` default, the members of `ApiError` / `Success` / `Failure` / `RawError`, each operation's error union with the status each arm maps from, base-URL and auth wiring, and which module declares a type are all answered there; don't open a module for them. Open the one module the map names only for what it leaves out: a model's members, an enum's values, a field's wire alias. The map says so itself — *"Shapes live only in the source … Never grep for a type."* -**The map carries shapes; what an operation *means* lives elsewhere.** When *what* to pass depends on meaning — which values a field accepts beyond its type, a rule that couples two fields, what a defaulted parameter actually selects — the map will not settle it. Open the operation's docstring in `slack_web_api/apis/.py` (or `client.py` where operations sit on the client) and `api-reference.md` at the SDK root for that operation *before* writing the sheet row, and record what you found there. A value you already "know" for a field the map types as a plain `str` is a lookup, not a recall — the memory ban applies to it. +**Meaning is not on the map.** When what to pass depends on semantics — values a field accepts beyond its type, a rule that couples two fields, what a defaulted parameter selects — read the operation's docstring in `slack_web_api/apis/.py` (or `client.py` where operations sit on the client) and its entry in `api-reference.md` at the SDK root before writing the sheet row, and record what you found — even for a value you think you know. `sdk-map.md` carries the invariants every operation block assumes, so load it before any `map/operations/` page; the pages are written to be read beside it. ## Contract facts — the map first, then the module -**Six of these are map lookups — don't open the module for them:** an operation's signature, parameters and return type; the client's constructor keywords; the `timeout` default; the members of `ApiError` / `Success` / `Failure` / `RawError`; an operation's error union and the status each arm maps from; base-URL and auth wiring. The table below covers everything else, and the full body behind a map row. - -Read the one module that owns the fact **inside the installed package**. Locate it first: - -```bash -python -c "import slack_web_api, pathlib; print(pathlib.Path(slack_web_api.__file__).parent)" -``` - -Failing that, it is under the project's environment (`.venv/Lib/site-packages/slack_web_api` on Windows, `.venv/lib/python3.*/site-packages/slack_web_api` elsewhere). **If the package is not installed, install it first** — see *Install* above; until then mark the fact `UNVERIFIED` and say what would settle it rather than answering from memory. Paths below are relative to that package root: +For everything the map leaves out, and the full body behind a map row, read the one module that owns the fact **inside the installed package** — locate it with the probe from *Install*. Failing that, it is under the project's environment (`.venv/Lib/site-packages/slack_web_api` on Windows, `.venv/lib/python3.*/site-packages/slack_web_api` elsewhere). **If the package is not installed, install it first** — see *Install* above; until then mark the fact `UNVERIFIED` and say what would settle it rather than answering from memory. Paths below are relative to that package root: | Question | Module | | --- | --- | @@ -224,9 +142,11 @@ Failing that, it is under the project's environment (`.venv/Lib/site-packages/sl | Client construction, keywords, controller wiring | `client.py`, `async_client.py`, `base_client.py` | | Timeout default and validation | `base_client.py` (`DEFAULT_TIMEOUT = 30.0`) | | The request/response pipeline, 401 handling, 2xx-vs-error split | `core/raw_client.py` | -| Exception shape (`ApiError.error`, `.status_code`, `.headers`) | `core/exceptions.py` | +| Exception family (`SdkError` and its members; `ApiError.error`, `.status_code`, `.headers`) | `core/exceptions.py` | | `Success`/`Failure`/`RawError` | `core/results.py` | | Per-call overrides | `core/request_options.py` | +| Request and response hooks | `core/hooks.py` | +| Logging options, levels and masking | `core/logging.py` | | `UNSET`, `Optional`, `OptionalNullable` | `core/optionality.py` | | Model base config, `to_dict`/`to_json` | `core/models.py` | | A model's members, required vs `UNSET`, wire aliases | `models/.py` | @@ -240,36 +160,37 @@ Failing that, it is under the project's environment (`.venv/Lib/site-packages/sl **Read scoped.** These modules carry long design docstrings; `grep -n` for the symbol and read the surrounding lines rather than whole files. Never quote a docstring's design rationale onto a contract sheet — the sheet carries facts an implementer must obey, not the reasoning behind them. -Keep lookups cheap — the rules that keep a session's context small: +Keep lookups cheap: -- Collect the contracts for **every** in-scope operation in **one** pass — signature, required members with wire aliases, the error union, enum values — into a short **contract sheet** in your plan or working notes, then implement from the sheet. Don't re-open a module per member, and never re-look-up a fact the sheet already carries. -- Recurse into a model's members only where the task actually sets them — a full transitive expansion is hundreds of rows and nobody needs it. -- Trust the interpreter over this page: if a name here ever fails to type-check or import, re-read the module the table above names and report the drift; never patch around it from memory. +- Collect the contracts for **every** in-scope operation in **one** pass — signature, required members with wire aliases, the error union, enum values — onto the contract sheet, then implement from it; never re-open a module for a fact the sheet carries. +- Expand a model's members only where the task sets them. +- If a name here fails to type-check or import, re-read the module the table names and report the drift; never patch around it from memory. ## Integration workflow — load the companion skill at each step -Before you write the code for each step, load the named companion skill — even if you have already read the relevant module. Each step calls out the trap the signature hides (in *parens*). A typical integration reaches them in this order: +Before you write the code for each step, load the named companion skill — even if you have already read the relevant module; it owns the traps the signature hides. A typical integration reaches them in this order: -1. **Client construction & lifetime** — load **python-client-initialization** before you write `Client(...)` or `AsyncClient(...)`. (*The signature won't tell you:* the constructor is keyword-only, so nothing can be passed positionally; the client owns an `httpx2` connection pool and you **must** `close()` (sync) or `await aclose()` (async) or use it as a context manager; it must be long-lived and module- or app-scoped, never rebuilt per request; the sync and async clients do not mix; and the transport-override keyword differs by client — `custom_http_client` vs `custom_async_http_client`.) -2. **Authentication** — load **python-authentication** before you set credentials. The one scheme is `slack_auth=`. (*The signature won't tell you:* every credentials keyword is *optional* — omit it and every request goes out unauthenticated, with no failure at construction and not necessarily a `401` to tell you; the token is fetched lazily and cached by the client; and a **failed token fetch** raises something other than what a caller expects and **bypasses the non-raising response mode** entirely. Load secrets from the environment or a secret store, never hardcode.) -3. **Calling an endpoint** — load **python-calling-endpoints** before the first `client..(...)` call. (*The signature won't tell you:* every operation splits positional path params (and sometimes the body) from a keyword-only tail after `*`; every keyword-only parameter has a **real** default, so there is no "must pass `None` explicitly" hazard; and the two response modes — raising vs `ApiResult` — behave differently on failure.) -4. **Models** — load **python-models** the moment a request/response member is not a plain string or number. (*The signature won't tell you:* `Optional[T]` here is `T | UnsetType`, **not** `typing.Optional` — `None` is not a legal value for it; models are frozen pydantic instances with `…Dict` TypedDict companions; enums are **open** (`…OrStr`), so an unknown wire value passes through as a plain `str` rather than raising; wire aliases differ from Python member names; unknown response fields are **preserved**, not dropped; and serialize via `to_dict`/`to_json`.) -5. **Error handling** — load **python-error-handling** before you write any `try/except`. (*The signature won't tell you:* there is a single `ApiError` type whose `.error` is a **per-operation union**, and a decode failure raises `ValidationError`/`ValueError`, not `ApiError`, and bypasses both response modes; `httpx2` transport exceptions reach your boundary unwrapped.) -6. **Configuration & resilience** — load **python-configuration-resilience** when you set the base URL, timeouts, retries, proxies, TLS, or logging. (*The signature won't tell you:* **retrying is on by default** — `retry_options` takes a count, a `RetryOptions` or its dict, `max_retries` set to `0` turns it off, and one call overrides it through `request_options`; a `401` is never retried; `timeout` defaults to `30.0` and is a single float that maps onto `httpx2`'s timeout semantics, limiting each wait rather than the whole call; and there is no logging hook — you wrap the transport seam.) -7. **Testing** — load **python-testing** before you stub the SDK. (*The signature won't tell you:* the seam is the **transport protocol** (`HttpClient`/`AsyncHttpClient` in `core/transport.py`) passed as `custom_http_client` — not the client class; a fake transport implements `send` and `close`, the two the protocol declares, and `send` answers with the head alone; assert on the request the SDK actually built, and cover all four failure kinds, decode failures included.) +1. **Client construction & lifetime** — load **python-client-initialization** before you write `Client(...)` or `AsyncClient(...)`. +2. **Authentication** — load **python-authentication** before you set credentials. +3. **Calling an endpoint** — load **python-calling-endpoints** before the first `client..(...)` call. +4. **Models** — load **python-models** the moment a request/response member is not a plain string or number. +5. **Error handling** — load **python-error-handling** before you write any `try/except`. +6. **Configuration & resilience** — load **python-configuration-resilience** when you set the base URL, timeouts, retries, proxies, TLS, or logging. +7. **Testing** — load **python-testing** before you stub the SDK. ## What a contract sheet must carry for this SDK Beyond the usual signatures and model members, a Python sheet is incomplete without these, because each one is a decision the implementer cannot make correctly from the signature alone: -1. **Sync or async** — which client class, and the reminder that the two do not mix. Plus the `close()`/`aclose()` obligation and where the client is held. -2. **The keyword-only boundary** for each operation: what is positional (path params, sometimes the body) and what sits after `*`. Every keyword-only parameter has a real default, so there is no "must pass `None` explicitly" hazard — say so, so nobody writes defensive `None`s. +1. **Sync or async** — the client class, where it is held, and its `close()`/`aclose()`. +2. **The keyword-only boundary** for each operation: what is positional (each required parameter without a fixed value, path → query → header → body) and what sits after `*`. Every keyword-only parameter has a real default, so write no defensive `None`s. 3. **Every operation returns a payload** — no operation in this SDK returns `None`, so the `with_raw_response` peer is needed only where the status code itself matters. -4. **Required vs `UNSET`** for every model member the task sets, and the fact that `Optional[T]` here is `T | UnsetType` — **not** `typing.Optional`, so `None` is not a legal value for it. +4. **Required vs `UNSET`** for every model member the task sets. 5. **The `ApiError.error` union** for each operation in scope — no operation in this SDK documents a typed error body, so `.error` is always `RawError`. -6. **That a decode failure raises `ValidationError`/`ValueError`, not `ApiError`, in both response modes** — `core/raw_client.py` states this in `execute`'s own docstring. **And that the 2xx path declares at least one required member on 250 return types, so a truncated body fails to decode there and passes silently everywhere else.** Any sheet row for a call whose result is used must name the members the implementer has to assert on. -7. **That retrying is on by default** — `retry_options` on the client tunes it, `max_retries` set to `0` turns it off, and `request_options` overrides it per call — so the sheet says whether this integration keeps, tunes or disables it, and for which methods, since a write is repeated only when the policy names its method. -8. **What limits a whole call.** `timeout` limits each wait, not the call, so a reply whose pieces each arrive within it is never cut off. In async code, state the budget and the one place `asyncio.wait_for` enforces it for every call, and what the boundary returns for its `asyncio.TimeoutError`; in sync code, say there is none. -9. **Which environment the `environment` keyword selects**, because omitting it is silently `"production"` of the 2 declared. -10. A **REQUIRED READING** block naming the `python-*` companions that govern the steps, with `MUST load` pointers. +6. **That a decode failure raises `ResponseDecodeError`, not `ApiError`, in both response modes. And that the 2xx path declares at least one required member on 250 return types, so a truncated body fails to decode there and passes silently everywhere else.** Any sheet row for a call whose result is used must name the members the implementer has to assert on. +7. **Retries are on by default** — the sheet says whether this integration keeps, tunes (`retry_options`) or disables them (`max_retries` set to `0`), and for which methods; a write is retried only when the policy names its method. +8. **Whether logging is on, and how loud** — the sheet says whether this integration raises the `slack_web_api` logger, which `logging_options` dumps it turns on — a JSON body is logged as sent — and any per-call `log_level`. +9. **What limits a whole call.** `timeout` limits only each wait (`python-configuration-resilience`). In async code, state the budget and the one place `asyncio.wait_for` enforces it for every call, and what the boundary returns for its `asyncio.TimeoutError`; in sync code, say there is none. +10. **Which server each call resolves against**, set through `server_config`. +11. A **REQUIRED READING** block naming the `python-*` companions that govern the steps, with `MUST load` pointers. diff --git a/plugins/slack/skills/python/python-integrate-slack-web-api/SKILL.md b/plugins/slack/skills/python/python-integrate-slack-web-api/SKILL.md index 2179585a..9e41da8b 100644 --- a/plugins/slack/skills/python/python-integrate-slack-web-api/SKILL.md +++ b/plugins/slack/skills/python/python-integrate-slack-web-api/SKILL.md @@ -1,21 +1,32 @@ --- name: "python-integrate-slack-web-api" -description: "MANDATORY FIRST STEP for Slack Web API Python SDK work in a Python project — load this BEFORE you write any code; Python SDK ONLY, never load it for any other language. Applies when asked to integrate Slack Web API in Python — approve an app for installation on a workspace, list approved apps for an org or workspace, list app requests for a team/workspace, restrict an app for installation on a workspace, list restricted apps for an org or workspace, archive a public or private channel, convert a public channel to a private channel, delete a public or private channel — or when a Slack Web API Python SDK call errors or behaves unexpectedly. Knowing the SDK exists is NOT a substitute for loading this, because it carries five binding gates stated NOWHERE else and not inferable from the package — (1) load python-getting-started, confirm the package is actually installed and read the SDK map that ships with it before any lookup, (2) the exact plan-file path and the no-project-file-edits window until a contract sheet with no open lookups exists there and you have read it, (3) the mandatory load of every python-* companion skill the sheet names, (4) sync-vs-async decided once from the host application before the first call, and (5) the memory ban, where every signature, wire alias, error union and enum member comes from a lookup and never from recall or runtime introspection." +description: "MANDATORY FIRST STEP for Slack Web API Python SDK work in a Python project (never another language): load before writing code to integrate Slack Web API in Python — approve an app for installation on a workspace, list approved apps for an org or workspace, list app requests for a team/workspace — or when a Slack Web API Python SDK call errors or behaves unexpectedly. Holds the plan-first workflow: the plan file, the contract sheet and its no-edits gate, and which python-* companion skills to load." --- # Slack Web API Python SDK — Integration workflow (lookup layer + contract sheet) -You do the SDK lookups yourself: `python-getting-started` is your **lookup layer** — load it and ground every contract fact in it (and in the source modules its table names) before writing code. The `python-*` companion skills are a different thing: they are API-agnostic *usage* guidance, they are yours to load, and Step 1c below makes loading them mandatory. +`python-getting-started` is your **lookup layer**; the `python-*` companions are API-agnostic *usage* skills that Step 1c makes mandatory. ## Your lookup layer -- **`python-getting-started`** is the entry point for every SDK need. It carries the SDK's identity (distribution name vs import root, version, Python floor, install-from-source), what the root package exports and the four modules the surface splits across, environments and the base-URL knob, the auth pattern, the controllers, and a **module table** naming the one file that owns each kind of fact. Load it first, always. -- **The SDK map is your lookup surface, and you open it yourself.** The SDK ships `sdk-map.md` and `map/operations/` at its root. There is no helper agent on the Python side — the map is yours to read, not something to delegate. `python-getting-started` tells you how to traverse it: read `sdk-map.md` once, then the one controller page your operations live on. -- **The installed package is the ground truth; the module table is only the locator.** Confirm the package is importable before you rely on a lookup — `python -c "import slack_web_api, pathlib; print(pathlib.Path(slack_web_api.__file__).parent)"`. **If it is not installed, install it first** — `python-getting-started` carries the command; until then mark the fact `UNVERIFIED`, say what would settle it, and do not fill the hole from memory. (The distribution is not on any package index — it installs from its repository; `python-getting-started` carries the command.) -- **Read scoped.** Those modules carry long design docstrings. `grep -n` for the symbol and read the surrounding lines rather than whole files, and never copy a docstring's design rationale onto a contract sheet — the sheet carries facts an implementer must obey, not the reasoning behind them. -- **Write a contract sheet with no open lookups** before you implement: exact signatures, the keyword-only boundary, wire aliases, required-vs-`UNSET` members, the `ApiError.error` union per operation, and enum members for the operations in scope. `python-getting-started` ends with a checklist of the rows a Python sheet is incomplete without — treat that list as the checklist for your own sheet, and collect every in-scope operation in ONE pass rather than re-opening a module per member. +- **`python-getting-started`** is the entry point for every SDK need: the SDK's identity (distribution name vs import root, version, Python floor, install-from-source), the root package's exports and the modules the surface splits across, environments and the base-URL knob, the auth pattern, the controllers, and a **module table** naming the one file that owns each kind of fact. Load it first, always. +- **The SDK map** (`sdk-map.md` and `map/operations/`, at the SDK root) is yours to open and read: `sdk-map.md` once, then the one controller page your operations live on. +- **The installed package is the ground truth; the module table is only the locator.** Confirm the package imports, with the probe in `python-getting-started`, before you rely on a lookup; **if it is not installed, install it first**. Until then mark the fact `UNVERIFIED`, say what would settle it, and do not fill the hole from memory. (The distribution is not on any package index — it installs from its repository; `python-getting-started` carries the command.) +- **Write a contract sheet with no open lookups** before you implement — every in-scope operation in one pass, against the checklist that ends `python-getting-started`. -**Scope guard:** the APIMatic-generated Slack Web API **Python SDK** (import root `slack_web_api`, distribution `slack-web-api`) in **Python projects only**. Unrelated API, or any language other than Python — do nothing; this skill does not apply. +**Scope:** the Slack Web API **Python SDK** (import root `slack_web_api`, distribution `slack-web-api`) in **Python projects only**. + +## The planner agent + +`slack-web-api-planner` ships with this plugin. It writes `slack-web-api-plan.md` — the plan and its contract sheet — and revises it in place; it writes no project code. Start it the first of these ways your host allows: + +1. **Your subagent tool lists it.** Some hosts list a plugin's agents under the plugin's name, as `slack:slack-web-api-planner`; start it by whichever of the two names your subagent tool lists. +2. **It isn't listed, or you can't start a subagent.** Tell the user in one line that you are writing the plan yourself, then do so as *Step 1* describes. Don't stop to ask. + +However you start it: + +- **Start it on the same model you are running on.** If your subagent tool takes a model, pass your own model; if it has no model option, leave its default. Tell the user in one line which model you started it on. +- **Start it once per integration.** A plan revision is a follow-up message to that same agent; re-start it, carrying the clarification and the plan path, only where your host cannot message it. Never start a second one for the same integration. ## Workflow @@ -23,23 +34,29 @@ You do the SDK lookups yourself: `python-getting-started` is your **lookup layer ### Step 1 — Plan first (always, for any implementation work) -Your FIRST action is to load `python-getting-started` and work through the user's full request (all features in scope — one plan covers the whole implementation). Then write the plan and its contract sheet to `/slack-web-api-plan.md` — that absolute path, not a location you pick later. +Your FIRST action, once the SDK is installed and you have reached its source (both are prerequisites below; installing follows the toolchain check and the baseline, and the gate allows it), is to start **`slack-web-api-planner`**, as *The planner agent* says, once, with the user's full request — all features in scope; one plan covers the whole implementation — and the name of this skill, `python-integrate-slack-web-api`. Dictate in its task the absolute project root, the absolute path of the SDK source you reached — it reads the map there rather than reaching its own — and the absolute path it must write to — `/slack-web-api-plan.md`, that absolute path, not a location you pick later. It loads `python-getting-started`, writes the plan and its contract sheet as this step and *Step 1c* describe, and returns the file's path. -**Do the read-only prerequisites in the same pass — they need no SDK knowledge and touch no project file:** +**If you couldn't start the planner** (case 2 in *The planner agent*), load `python-getting-started`, work through the request yourself, and write the file at that path. + +**Do these two read-only prerequisites before you install the SDK — the install changes the tree they read:** -- the repo survey (read-only exploration of conventions, layering, and **whether the project is sync or `async`**) — capture each convention as *pattern + the ONE exemplar file path to imitate*, NOT inline code snippets: you will read the exemplar at edit time anyway, so a snippet dump gets paid for twice; - **establish the toolchain before you need it**: which environment manager the repo uses (`uv`, `poetry`, `pip` + venv, `pdm`), whether `slack-web-api` is already a dependency and at what version, and the exact commands that run the project's tests and type checker. Getting this wrong later costs a broken install mid-implementation — and an uninstalled package costs you the lookup layer itself; -- a baseline run of the project's checks (`pytest`, `mypy`, `ruff` — whatever it has) on the UNTOUCHED tree, so later failures are attributable to your changes; -- credentials/environment verification (per the task's secret-handling rules) — including which host `environment` will select, since omitting it is silent; -- **a read-only smoke of each in-scope operation against the real credential**, run from your scratchpad, not the project, once the map has given you the signatures and before you finalise the sheet. A plan-, region- or entitlement-gated endpoint answers `403` here — the map presents every operation uniformly and cannot know which ones your key may call — and learning that now reorders the plan rather than the build. Skip only operations whose side effects you cannot reverse; -- setting up your task tracking. +- a baseline run of the project's checks (`pytest`, `mypy`, `ruff` — whatever it has) on the UNTOUCHED tree, so later failures are attributable to your changes. + +**Then make sure the SDK is installed and reach its source, before you start the planner** (both per `python-getting-started`) — the installed package does not carry the map, which lives in the SDK's source tree, and the planner reads the copy you reached rather than reaching its own. -Never use the planning phase to get a "head start" on implementation: **creating or editing ANY project file before the gate below is a defect**, no matter how obvious the code seems. +**Do the rest while the planner works — they need no SDK knowledge and touch no project file:** -**HARD GATE — no project-file creation or edits until:** `slack-web-api-plan.md` EXISTS at the repo root, its contract sheet has **no open lookups**, and you have read it. The gate bars coding "meanwhile"; it does not bar the read-only prerequisite work above. Starting to code before the sheet exists defeats the entire plan-first design. +- the repo survey (read-only exploration of conventions, layering, and **whether the project is sync or `async`**) — capture each convention as *pattern + the ONE exemplar file path to imitate*, NOT inline code snippets: you will read the exemplar at edit time anyway, so a snippet dump gets paid for twice; +- credentials/environment verification (per the task's secret-handling rules) — including which host `server_config` will select, since omitting it is silent; +- setting up your task tracking. + +**HARD GATE — no project-file creation or edits until** the planner has returned, `slack-web-api-plan.md` exists at the repo root (check it — a helper can misreport where it saved), its contract sheet has **no open lookups**, and you have read it. If you wrote the plan yourself, the gate is the same without the return. The read-only prerequisites above are not gated. **What the gate does not cover:** creating or activating a virtual environment, installing `slack-web-api` and the toolchain into it, and the files those writes produce (`.venv/`, a lockfile the installer updates) are **prerequisites, not project-file edits**. On a greenfield repo they are the only way to reach the lookup layer at all, and they are the only writes permitted before the gate. Nothing you author by hand may change. +**One read-only prerequisite waits for the signatures: a smoke of each in-scope operation against the real credential**, run from your scratchpad, not the project, once the planner has returned and you have read the sheet, with the signatures it records, and before your first project edit — or, if you are writing the plan yourself, once the map has given you the signatures and before you finalise the sheet. A plan-, region- or entitlement-gated endpoint answers `403` here — the map presents every operation uniformly and cannot know which ones your key may call — and learning that now reorders the plan rather than the build. Send each `403` to the SAME planner as a revision, as *Step 1c* sends a blocker, and implement from its reply; if you wrote the plan yourself, revise the sheet in place. Skip only operations whose side effects you cannot reverse. + **DUPLICATE CLAIMS** — one row per write a caller can trigger twice; `none` if the task has no such write (`python-configuration-resilience`, *The same operation arriving twice*). | Write | Where the claim is stored | What rejects the second one | Where that rejection is caught | Where in the code | @@ -47,7 +64,7 @@ Never use the planning phase to get a "head start" on implementation: **creating Every row follows one order: **claim → SDK call → record the result**. The claim is a write of its own, made before the SDK call, so a second caller is stopped before it reaches the provider; release it when the provider refuses the call. -⚠⚠ **Where the claim is stored**: a store this application owns — the one the codebase already keeps its records in — never the provider. A provider idempotency key goes beside the claim, never in place of it; the SDK's own `Idempotency-Key` header is not one — it is new on every call. If this codebase has nowhere to keep a claim that outlives the process, that is a Blocker in the plan's **Assumptions & Blockers**, not a row. +⚠⚠ **Where the claim is stored**: a store this application owns — the one the codebase already keeps its records in — never the provider. A provider idempotency key goes beside the claim, never in place of it; the SDK's own `Idempotency-Key` header is not one. If this codebase has nowhere to keep a claim that outlives the process, that is a Blocker in the plan's **Assumptions & Blockers**, not a row. ⚠⚠ **What rejects the second one**: the store refusing the second caller's claim, the way this codebase already refuses a duplicate. A conflict on the save *after* the SDK call is too late — both callers have already reached the provider. A read before the write — a status check, a lookup by key — is not a refusal either: it lets both callers through. Pick a refusal the store you run against enforces. @@ -57,15 +74,13 @@ Write `TBD` in **Where in the code** while you plan — every row; it names code ### Step 1c — Required reading (do this before you write any code) -End the contract sheet with a **REQUIRED READING** block whose rows carry inline `MUST load ` pointers. **Load every `python-*` skill the sheet names, now, before you start implementing** — not lazily at the step that needs it. The sheet deliberately does *not* carry the how-to: it names the hazard and hands you the skill that resolves it, so an unloaded pointer is a gap in what you know, not a formality. +End the contract sheet with a **REQUIRED READING** block whose rows carry inline `MUST load ` pointers. **Load every `python-*` skill the sheet names, now, before you start implementing** — not lazily at the step that needs it, and even if you have already read the module. The sheet deliberately does *not* carry the how-to: it names the hazard and hands you the skill that resolves it, so an unloaded pointer is a gap in what you know, not a formality. **A fixed floor applies regardless of what the sheet says** — the sheet can add to it, never remove from it: `python-error-handling` always (every integration writes an error boundary); `python-client-initialization` before the client is constructed; `python-testing` before the first test file you create or edit, *including* a throwaway verification script that fakes the transport. A sheet row that excuses one of these ("out of scope", "no test suite requested") is not a substitute for loading it. -These are API-agnostic usage skills; loading them is not a substitute for the lookup layer, and reading a module in the installed package does not remove the need to load the skill for that step. Contract *facts* still come only from your sheet or a fresh lookup. - Before implementing, check the plan's **Assumptions & Blockers** section: -- Blocker or major assumption → surface it to the user in plain language, get their answer, and revise `slack-web-api-plan.md` in place. +- Blocker or major assumption → surface it to the user in plain language, get their answer, and send it to the SAME planner as a follow-up message (re-start it, carrying the clarification and the plan path, only where your host cannot message it). It revises `slack-web-api-plan.md` in place and replies with the changed rows verbatim: work from that reply, not a re-read of the file. If you wrote the plan yourself, revise it in place. - Minor assumptions only → proceed. Full re-planning only on genuine scope change; for a single missing fact mid-implementation, do the lookup, never guess. @@ -73,13 +88,13 @@ Full re-planning only on genuine scope change; for a single missing fact mid-imp ### Step 2 — Implement from the contract sheet 1. Read `slack-web-api-plan.md` once. Treat its contracts as authoritative — do not re-derive or "double-check" them from memory. When a lookup revises a row, update the file so the sheet and the code never disagree. -2. **Decide sync vs async once, from the host application, before the first call** — and take the decision from the repo survey, not from preference. This SDK ships two complete client classes (`Client` / `AsyncClient`) and there is no bridge between them: a sync client in an `async def` blocks the event loop, and an async client in sync code is a coroutine nobody awaits. Getting this wrong is not a local fix later; it is every call site. The choice also changes the transport-override keyword (`custom_http_client` vs `custom_async_http_client`) and the teardown obligation (`close()` vs `await aclose()`). -3. **Pick the response mode per call, deliberately.** Each operation exists twice: the plain call raises `ApiError` on failure, and its `with_raw_response` peer returns `ApiResult` instead. For the operations that return `None`, the raw peer is the only way to observe the status code — so a call whose outcome you must inspect needs the mode chosen at write time, not retrofitted. -4. Implement sequentially, following the repo's own conventions and layering. You loaded the companion skills the sheet named in Step 1c — implement each step in line with the one that governs it. Take every contract *fact* (signatures, wire aliases, error unions, enum members) from the contract sheet or a fresh lookup — never re-derive one from a companion. -5. After every change: run the project's **type checker** (`mypy`/`pyright`) as well as its tests. The package ships `py.typed` and is generated under `mypy --strict`, so a type error against it is a real contract violation, not noise — it is the closest thing Python gives you to the compile step. **Treat a clean type check as the gate you do not skip.** If the project has no type checker configured, install `mypy` into the environment and run `mypy --strict` on the files you touched — the SDK is generated under that setting, so it checks cleanly against it. If you genuinely cannot install one, say so in your final report rather than silently substituting a smoke run. Fix non-SDK errors yourself. -6. **Any error involving an SDK type or member** — an `AttributeError`/`TypeError` on a `slack_web_api.*` object, a `pydantic.ValidationError` you cannot place, a mypy error naming an SDK type, an unexpected `ApiError` — → go back to `python-getting-started`'s module table and read the one module that owns the fact. Do not attempt more than one self-fix of an SDK-name error before doing that lookup: rewriting from the same knowledge that produced the error is guessing. Remember that a **decode failure raises `ValidationError`/`ValueError`, not `ApiError`, and bypasses both response modes**, and that `httpx2` transport exceptions arrive unwrapped — so an exception that does not look like an API error may still be one of the SDK's failure kinds. +2. **Decide sync vs async once, from the repo survey, before the first call** — `Client` or `AsyncClient`. The two have no bridge, and the choice fixes the transport-override keyword and the teardown (`python-client-initialization`). +3. **Pick the response mode per call, at write time:** the plain call raises `ApiError`; its `with_raw_response` peer returns `ApiResult`, the only way to see the status of an operation that returns `None`. +4. Implement sequentially, in the repo's own conventions and layering, in line with the companion that governs each step. Take every contract *fact* (signatures, wire aliases, error unions, enum members) from the sheet or a fresh lookup — never from a companion. +5. After every change: run the project's **type checker** (`mypy`/`pyright`) as well as its tests. The package ships `py.typed`, so a type error against it is a real contract violation, not noise — it is the closest thing Python gives you to the compile step. **Treat a clean type check as the gate you do not skip.** If the project has no type checker configured, install `mypy` into the environment and run `mypy --strict` on the files you touched — the SDK checks cleanly under it. If you genuinely cannot install one, say so in your final report rather than silently substituting a smoke run. Fix non-SDK errors yourself. +6. **Any error involving an SDK type or member** — an `AttributeError`/`TypeError` on a `slack_web_api.*` object, a `pydantic.ValidationError` you cannot place, a mypy error naming an SDK type, an unexpected `ApiError` — → go back to `python-getting-started`'s module table and read the one module that owns the fact. Do not attempt more than one self-fix of an SDK-name error before doing that lookup. A decode, connection or authentication failure is an `SdkError` too, though not an `ApiError` (`python-error-handling`). 7. Once the code is complete, open each function the **DUPLICATE CLAIMS** rows name and confirm it runs when that write runs. Where the code falls short of a row, fix the code, not the row. -8. Run the project's tests; verify the integration end to end the way the task demands. Retrying is **on by default**, so decide whether the task keeps it, tunes it through `retry_options`, or turns it off with `max_retries` set to `0`, rather than wrapping the call in a retry of your own — and say which you did. +8. Run the project's tests; verify the integration end to end the way the task demands. Keep, tune (`retry_options`) or disable (`max_retries` set to `0`) the default retries rather than wrapping the call in a retry of your own, and say which you did. Logging is **off by default**: run a new call once under `SLACK_WEB_API_LOG=info` to see what went on the wire. ### Step 3 — Answering pure questions @@ -87,11 +102,9 @@ A standalone Slack Web API question with no code change: look it up in `python-g ## Anti-patterns — never do these -- **Always load `python-getting-started` first.** It is your lookup layer, not optional background. (The `python-*` companions are the complement: load the ones the sheet names, per Step 1c.) Don't re-derive a contract *fact* from a companion — exact signatures, wire aliases, error unions and enum members come from the sheet or a fresh lookup. +- **Never create or edit a project file while `slack-web-api-planner` is running**, and never start a second one for the same integration. - **Never write a Slack Web API/SDK fact from memory** — every signature, field name, enum member, and error union in your code must come from the contract sheet or a lookup. And **never write a call from memory "to fix later".** - **Don't web-search Slack Web API topics to find an implementation detail** — the installed package's own source is the ground truth, and the module table tells you where to look. Public Slack Web API docs describe the REST API, not this SDK's generated surface, and the two disagree on names. - **Never introspect the SDK at runtime to discover its shape.** `dir()`, `model_fields`, `inspect.signature`, or a REPL poke is the Python-flavoured version of decompiling the package: it answers what exists, never what is *supported*, and it silently invites private attributes into your code. Read the source module instead. -- **Don't grep the package to *locate* a type** — the SDK map is the locator (and says so: *"Never grep for a type"*); grep only *inside* the module its **Type sources** table names, for the symbol. A sweep for a *shape* is a different thing, and is fine: "every member typed `Optional[Any]`", "every discriminator field" are cross-cutting questions nothing indexes, and one targeted `grep -rn` over `models/` is the right tool for them — record what it found on the sheet. -- **Don't vendor, `sys.path`-hack, or editable-install the SDK from a throwaway clone** to make a lookup possible. Install the distribution properly into the project's environment (see `python-getting-started`); an editable install pointed at a clone breaks every import the moment the clone is deleted. -- **Don't create or edit project files before the HARD GATE** in Step 1 — plan and contract sheet first, code second. +- **Don't grep the package to *locate* a type** — the map's **Type sources** table is the locator; grep only inside the module it names. A cross-cutting *shape* sweep ("every member typed `Optional[Any]`", "every discriminator field") is fine as one `grep -rn` over `models/`, recorded on the sheet. diff --git a/plugins/slack/skills/python/python-models/SKILL.md b/plugins/slack/skills/python/python-models/SKILL.md index cbf33c8f..b4daa979 100644 --- a/plugins/slack/skills/python/python-models/SKILL.md +++ b/plugins/slack/skills/python/python-models/SKILL.md @@ -1,6 +1,6 @@ --- name: python-models -description: Working with models in an APIMatic-generated Python SDK — pydantic models and their TypedDict companions, required members vs the UNSET sentinel, why Optional here is not typing.Optional, open enums, union aliases and discriminators, collections, wire aliases, frozen instances, unknown-field preservation, and serializing with to_dict/to_json. Load before constructing request payloads or mapping SDK models onto your own types. +description: Load before building request payloads for an APIMatic-generated Python SDK or mapping its response models onto your own types. Covers pydantic models and their TypedDict companions, required members vs UNSET (Optional here is not typing.Optional), open enums, union aliases and discriminators, wire aliases, unknown-field preservation, and to_dict/to_json. --- # Working with models in an APIMatic Python SDK @@ -18,9 +18,8 @@ REPL poke at the installed package. ## The base every model shares -Domain models subclass a generated base (`{root_package}.core.SdkBaseModel`) with a deliberate -configuration. It is **static generator code, identical in every APIMatic Python SDK**, and four of its -choices change how you write code: +Domain models subclass `{root_package}.core.SdkBaseModel`, configured identically in every APIMatic +Python SDK; four of its settings change how you write code: | Config | What it means for you | |---|---| @@ -48,8 +47,8 @@ class {RequestType}(SdkBaseModel): - **`Optional[T] = UNSET` is optional.** Leave it out entirely and the key is omitted from the JSON. **`Optional` here means `T | UnsetType` — present or absent, with no `None` arm.** It is *not* -`typing.Optional[T]` (`T | None`), and the difference is the arm that matters: a field the spec does -not declare nullable must not be able to reach the wire as `null`. So: +`typing.Optional[T]` (`T | None`), and the difference is the arm that matters: a field that is not +nullable cannot reach the wire as `null`. So: ```python {RequestType}({required_field}="...", {required_list}=[...], {optional_field}=None) # ✗ type error, and rejected @@ -59,9 +58,8 @@ not declare nullable must not be able to reach the wire as `null`. So: Never "clear" an optional field by passing `None`. Omit it, or pass `UNSET` explicitly if you are building the kwargs dynamically. -A field annotated **`OptionalNullable[T]`** (`T | None | UnsetType`) is the three-state case: omitted, -explicitly `null`, or a value. The generator emits it for exactly the properties the spec declared both -optional *and* nullable. There, `None` *is* meaningful — it sends `null`, which for a PATCH-style API +A field annotated **`OptionalNullable[T]`** (`T | None | UnsetType`) — a member both optional *and* +nullable — is the three-state case: omitted, explicitly `null`, or a value. There, `None` *is* meaningful — it sends `null`, which for a PATCH-style API is how you erase a value rather than leave it unchanged. Read the annotation before deciding what `None` means. @@ -99,10 +97,8 @@ rather than a runtime surprise. Three caveats: - the companion is a typing construct only — it performs no runtime validation until the SDK validates the whole body; - it cannot express `UNSET`, so a dict simply omits what it does not set; -- **the closed check only helps if a type checker actually runs.** At runtime the model base is - `extra="allow"`, so a misspelled key that no checker saw is *accepted* and sent as an extra field - rather than rejected (see *Unknown fields are preserved* below). The dict spelling is only as safe - as your `mypy`/`pyright` gate. +- **the closed check only helps if a type checker actually runs.** At runtime a misspelled key is + accepted and sent as an extra field (see *Unknown fields are preserved* below). ## Enums are open @@ -137,10 +133,9 @@ match response.{enum_field}: # handle the open arm explicitly An `if/elif` chain over members with no final `else` silently does nothing for an unknown value. -**Stringifying differs by enum kind.** The generator gives every enum `__str__ = str.__str__`. On a -`(str, Enum)` that is what you want — `str(member)` and f-string interpolation give the **wire value** -(`"{wire_value}"`), not `"{Enum}.{MEMBER}"`, so logging and comparison against raw strings both behave. -On an `(int, Enum)` that same assignment makes `str(member)` raise +**Stringifying differs by enum kind.** On a `(str, Enum)`, `str(member)` and f-string interpolation +give the **wire value** (`"{wire_value}"`), not `"{Enum}.{MEMBER}"`, so logging and comparison against +raw strings both behave. On an `(int, Enum)`, `str(member)` raises `TypeError: descriptor '__str__' requires a 'str' object` — so never interpolate an int-enum member into a log line or an f-string. Use `member.value` (or `int(member)`) instead. @@ -194,8 +189,8 @@ Four things the alias does not show: ## Collections -List properties are `list[T]`; maps are `dict[str, V]` — **the key type is always `str`**, whatever -the spec said. Inside a companion, a model element is typed as that model's companion +List properties are `list[T]`; maps are `dict[str, V]` — **the key type is always `str`**. +Inside a companion, a model element is typed as that model's companion (`list[{Model}Dict]`). ```python @@ -210,10 +205,9 @@ are different wire messages — do not use `[]` to mean "leave this alone". ## Wire aliases -The generator emits a pydantic alias for a field **exactly when the Python name no longer matches the -wire name** — snake-casing a `camelCase` property, sanitizing a name that is not a valid identifier, -escaping a Python keyword (trailing underscore, `type_` for `type`), or de-duplicating a collision. -Where the wire name is already a valid snake_case identifier, no alias is emitted at all. +A field carries a pydantic alias **exactly when its Python name differs from the wire name** — +snake-casing a `camelCase` property, sanitizing a name that is not a valid identifier, escaping a Python +keyword (trailing underscore, `type_` for `type`), or de-duplicating a collision. ```python {field}: Optional[str] = Field(default=UNSET, alias="{wireField}") @@ -224,17 +218,15 @@ input, and output uses the alias. When a sheet lists a member as `{field} (wire `{field}` in code and expect `{wireField}` in a captured request body — do not "fix" a test that asserts the alias. -**The `…Dict` companion is keyed by the PYTHON name, not the alias.** A `TypedDict` cannot declare a -keyword or a non-identifier as a key through class syntax, and the base config's `validate_by_name` is -what makes the Python spelling work: +**The `…Dict` companion is keyed by the PYTHON name, not the alias:** ```python client.{controller}.{operation}(body={"{field}": "..."}) # ✓ the companion's key client.{controller}.{operation}(body={"{wireField}": "..."}) # validates, but type-checks as nothing ``` -The serialized body carries `"{wireField}"` either way. The second form *does* validate at runtime via -`validate_by_alias` — so both happen to work, and only one is checked. Write the Python name. +The serialized body carries `"{wireField}"` either way; both validate at runtime, but only the first +type-checks. Write the Python name. ## Serializing @@ -270,13 +262,11 @@ pydantic_core._pydantic_core.PydanticSerializationError: Unable to serialize unknown type: ``` -`UnsetType` carries its own serializer, but `Any` absorbs the union arm before that serializer is -reached, so the sentinel arrives at pydantic's generic any-serializer, which has never heard of it. Every other `Optional[T]` is fine, and so is a *container* of `Any` (`Optional[list[Any]]`, `Optional[dict[str, Any]]`) — this is specific to a bare `Any` at the top of the annotation. -You get `Any` wherever the spec left a property unconstrained: a free-form object, an anonymous -object, or no schema at all. **Check the contract sheet for which members are typed `Any`** — it is +A member is typed `Any` wherever it is unconstrained: a free-form object, an anonymous object, or +no schema at all. **Check the contract sheet for which members are typed `Any`** — it is usually a small, fixed list, and a JSON-Patch-style `value` member is the classic case, because the ops that take no value are exactly the ones that would leave it unset. @@ -287,17 +277,11 @@ client.{controller}.{operation}(body={Model}({field}=None)) # request body -> {"{field}": null} ``` -It type-checks (`Any` admits `None`) and it serializes. Note the cost: the request now carries -`"{field}": null` where it should have carried nothing. Two consequences worth stating on any sheet -that touches such an operation: - -- an explicit `null` is not the same wire message as an omitted key, so a strict server-side validator - could reject it — confirm against sandbox before shipping; -- this is the one place where `None` on an `Optional[...]` field is correct. Everywhere else it is a - type error (see above). Do not generalise it. - -The dict spelling is no escape — it validates into the same model, sentinel included. If a future SDK -version widens these annotations, drop the explicit `None`. +It type-checks (`Any` admits `None`) and it serializes, at the cost of sending `"{field}": null` +instead of nothing — an explicit `null` is not the same wire message as an omitted key, so a strict +server-side validator could reject it; confirm against sandbox before shipping. This is the one place +where `None` on an `Optional[...]` field is correct; everywhere else it is a type error (see above). +The dict spelling is no escape — it validates into the same model, sentinel included. **The trap fires on the read path too.** A *response* model whose `Any`-typed member the server omitted decodes fine — and then fails `to_dict()` / `to_json()` with the same error, because that @@ -321,8 +305,8 @@ Never pass a raw member straight through to something that will encode it. ## Unknown fields are preserved -Unlike SDKs that drop unmodelled JSON, `extra="allow"` keeps them — at every nesting level, readable -via `model_extra`, and **re-emitted under the key they arrived with**: +`extra="allow"` keeps unknown fields — at every nesting level, readable via `model_extra`, and +**re-emitted under the key they arrived with**: ```python extra = response.model_extra or {} @@ -331,14 +315,14 @@ new_field = extra.get("{some_new_field}") This makes it safe to read an object, change one member and send it back without silently discarding server-side state you never modelled. The symmetry also means an unknown key *you* supply is sent -rather than rejected — convenient for a field newer than the SDK, and a silent no-op when you simply -misspell a real one. A misspelled optional member does not error; it becomes an extra. If a value you -set is not taking effect, check it against the sheet's member list before suspecting the API. +rather than rejected — convenient for a field newer than the SDK, and a silent no-op when you +misspell a real one. If a value you set is not taking effect, check it against the sheet's member list +before suspecting the API. ## Dates and numbers -The generator maps spec types to Python as follows — take the exact type of any given member from the -contract sheet rather than assuming: +Spec types map to Python as follows — take the exact type of any given member from the contract sheet +rather than assuming: | Spec type | Python type | |---|---| @@ -358,8 +342,8 @@ Three consequences: `datetime`/`date` and read one back; do not format strings by hand. Every one of those names is an `Annotated` alias over the stdlib type, declared in `{root_package}/core/converters/date_time.py`: `Date` → `datetime.date`; `RFC3339DateTime`, `RFC1123DateTime` and `UnixSecondsDateTime` → - `datetime.datetime`. The alias only governs the wire format. They are runtime types, so the map's - **Type sources** tables do not list them — this is where they live; do not go searching. + `datetime.datetime`. The alias only governs the wire format. The map's **Type sources** tables do + not list these runtime types. - **There is no `Decimal` arm.** A fractional number becomes `float`, so a spec that models money as a number gives you binary floating point. Most payment APIs instead model money as a **`str`** scaled to the currency (`"10.00"`) — where yours does, build it with `Decimal` and format explicitly, never @@ -387,11 +371,9 @@ Three consequences: amount(Decimal("1.2344"), "KWD") # "1.234" -- not "1.23" ``` -- **`binary`/`file` is never `bytes`.** A file position takes `FileInput` (`AsyncFileInput` on the - async client) and an operation that returns one hands back `FileResponse` (`AsyncFileResponse`). - Both pairs live in `{root_package}.core` rather than `{root_package}.models`, so nothing on this - page applies to them — see **python-file-handling**. Nothing base64-encodes or decodes for you - either: where an endpoint asks for base64, hand it content that already is. +- **`binary`/`file` is never `bytes` at a file position**: it takes `FileInput` and returns + `FileResponse` (`AsyncFileInput` / `AsyncFileResponse` on the async client), from + `{root_package}.core` — see **python-file-handling**. Currency codes are typically plain `str` with no enum — pass `"USD"`. diff --git a/plugins/slack/skills/python/python-models/reference.md b/plugins/slack/skills/python/python-models/reference.md index 8524cc0a..2dc7a18f 100644 --- a/plugins/slack/skills/python/python-models/reference.md +++ b/plugins/slack/skills/python/python-models/reference.md @@ -16,13 +16,6 @@ from {root_package}.core import UNSET, UnsetType - It is only ever a **default**. Never construct `UnsetType()` yourself; pass `UNSET` if you need to spell "omitted" explicitly while building kwargs. -The two annotations that admit it, one per spelling a spec can declare: - -```python -Optional = T | UnsetType # optional — omitted or a value -OptionalNullable = T | None | UnsetType # optional+nullable — omitted, null, or a value -``` - Building a payload conditionally, without a `None` ever reaching a non-nullable field: ```python @@ -50,18 +43,13 @@ from {root_package}.models.enums import {Enum} {Enum}("{wire_value}") # wire value -> member; ValueError if unknown {Enum}.{MEMBER}.value # -> "{wire_value}" -str({Enum}.{MEMBER}) # -> "{wire_value}" (str enums only — see below) +str({Enum}.{MEMBER}) # -> "{wire_value}" (str enums only; an int enum raises TypeError) list({Enum}) # every member ``` -Coercing an unknown value with `{Enum}(...)` raises `ValueError` — that is the *closed* lookup. -The **open** alias used on model fields (`{Enum}OrStr` / `{Enum}OrInt`) does not raise; it passes the -unknown value through as the underlying scalar. Do not reimplement that coercion at your boundary; -read the field and handle the scalar arm. - -`__str__ = str.__str__` is emitted on **every** enum, which is right for a `(str, Enum)` and wrong for -an `(int, Enum)`: on an int enum, `str(member)` and f-string interpolation raise -`TypeError: descriptor '__str__' requires a 'str' object`. Use `.value` for int enums. +`{Enum}(...)` is the *closed* lookup. The open alias on model fields passes an unknown value through +as the scalar (`SKILL.md` *Enums are open*) — read the field and handle that arm rather than +reimplementing the coercion at your boundary. Tolerating an unknown value when you must map to your own enum: @@ -75,35 +63,14 @@ def to_domain(value: {Enum} | str) -> MyEnum: ## Union aliases — finding the exact arms -A union is a **type alias**, not a class, so there is nothing to construct and nothing to unwrap. The -contract sheet lists the arms; each arm is used directly. The SDK map names the **module** declaring -the alias, not its arms — read them off the alias there. - ```python from {root_package}.models import {Union} # also {root_package}.models.unions.{module} ``` -- **Plain (`anyOf`)** — `{Union}: TypeAlias = {Variant1} | {Variant2}`, with a companion - `{Union}Dict: TypeAlias = {Variant1}Dict | {Variant2}Dict`. Named after its arms when the spec gave - it no name (`{Variant1}Or{Variant2}`). -- **Discriminated (`oneOf` with a discriminator, or an `allOf` base with subtypes)** — - `{Union}: TypeAlias = Annotated[Annotated[{Variant1}, Tag("{value1}")] | …, WireDiscriminator("{tag}")]`. - The tag is the union's: build the variant and the union writes it. Some variants also declare the - tag as a field of their own, in which case it is yours to set. Where the companion alias names a - wrapper (`{Union}{Variant1}Dict`), that is the dict spelling to use — the variant's own dict shape - plus the tag key. -- **One surviving arm** — no alias module is emitted at all; the field is typed with that arm directly - (`{Variant} | None` where a dropped arm was nullable). An alias the sheet does not list does not - exist. -- Read a union back with `isinstance` / `match`; there are no `TryGet…`-style readers. - -Two runtime notes that the annotation does not show: - -```python -{RequestType}({union_field}={"{tag}": "{value}", ...}) # ✓ dict form must carry the tag -{RequestType}({union_field}={...}) # ✗ ValidationError: union_tag_not_found -model.to_dict(exclude_unset=True) # ✗ drops the defaulted tag; no longer validates back -``` +The SDK map names the **module** declaring a union, not its arms — read them off the alias there. An +unnamed `anyOf` alias is named after its arms (`{Variant1}Or{Variant2}`). A discriminated alias exists +for a `oneOf` with a discriminator **and** for an `allOf` base with subtypes. Construction and reading +rules are in `SKILL.md` *Union types*. ## Reading nested optional structures @@ -138,14 +105,6 @@ Unknown keys are also reachable by attribute access **unless** the name collides ## Type-checking notes -The SDK ships `py.typed`, so `mypy`/`pyright` check your calls against it fully. - -- `Optional[T]` from the SDK and `typing.Optional[T]` are **different types**. If you import both into - one module you will confuse yourself and your reader; the SDK's generated modules never import - `typing.Optional` — unions are spelled with PEP 604 `|` — and yours should not shadow the name. -- Passing `None` to an `Optional[T]` field is a type error the checker reports. Believe it — at - runtime it is also a `ValidationError`. (`OptionalNullable[T]` is the annotation that does admit - `None`.) -- A `{Model}Dict` literal is checked structurally, so an unknown key is an error there too. That check - is what makes the dict spelling safe to use at all — it is the *only* thing that catches a - misspelling, since the model base is `extra="allow"` at runtime. +The SDK ships `py.typed`, so `mypy`/`pyright` check your calls against it fully. The SDK's modules +never import `typing.Optional` (unions are spelled with PEP 604 `|`); don't import it into a module +that also uses the SDK's `Optional`, a different type. diff --git a/plugins/slack/skills/python/python-testing/SKILL.md b/plugins/slack/skills/python/python-testing/SKILL.md index 883b947a..789ccfc6 100644 --- a/plugins/slack/skills/python/python-testing/SKILL.md +++ b/plugins/slack/skills/python/python-testing/SKILL.md @@ -1,6 +1,6 @@ --- name: python-testing -description: Testing code that calls an APIMatic-generated Python SDK — which seam to fake (the transport protocol), asserting on the request the SDK actually built, covering the error and decode-failure paths, and keeping tests independent of SDK internals. Load before writing tests for the integration layer. +description: Load before writing unit or integration tests (pytest or unittest) for code that calls an APIMatic-generated Python SDK. Covers faking the transport protocol, asserting on the request the SDK built, and covering the error, decode, transport and token-fetch failure paths. --- # Testing code that uses an APIMatic Python SDK @@ -24,14 +24,13 @@ Substitute your own `{Api}Client` and operation names as well. The transport is a `Protocol`, so a fake needs no base class, no registration and no `Mock` — just its two methods, `send` and `close`. `send` answers with the response **head**; the body stays on -the stub until something reads it, which is what lets one stub serve a JSON call and a download -alike: +the stub until something reads it: ```python import json from collections.abc import Iterator, Mapping from dataclasses import dataclass, field -from {root_package}.core import HttpRequest, HttpResponse +from {root_package}.core import HttpMethod, HttpRequest, HttpResponse @dataclass class StubResponse: @@ -40,6 +39,7 @@ class StubResponse: status_code: int = 200 headers: Mapping[str, str] = field(default_factory=dict) chunks: list[bytes] = field(default_factory=list) + method: HttpMethod = "GET" # what a streamed payload names in its errors, with url url: str = "https://api.test/resource" closed: bool = False @@ -82,9 +82,7 @@ def json_response(status: int, body: object) -> StubResponse: ) ``` -A download is queued exactly like anything else: one seam means one kind of stubbed response, and -nothing about the stub says which operation it answers. Assert on `StubResponse.closed` to prove the -caller consumed the body and released the connection. +Assert on `StubResponse.closed` to prove the caller consumed the body and released the connection. `chunks` defaults to empty, so an empty `204` is just `StubResponse(status_code=204)` — which is what an operation declaring no response body expects (`python-calling-endpoints`). @@ -94,8 +92,7 @@ Wire it in and you have a real client with no network: ```python def client_returning(*responses: StubResponse) -> tuple[{Api}Client, StubTransport]: transport = StubTransport(*responses) - # retry_options=0: retries are on by default, so without it a stubbed 429 or 503 on a GET would be - # sent four times, with real waits between them. + # retry_options=0 turns off the default retries (see Notes): one stubbed response, one send. client = {Api}Client(custom_http_client=transport, retry_options=0, {scheme}=...) return client, transport ``` @@ -106,10 +103,10 @@ contract sheet lists. Its value is that scheme's type: a plain `str` for a beare the credentials model or dict for basic auth or an OAuth grant (`python-authentication`). **Do not patch the client's private attributes** (`_raw_client`, `_auth`, …) and do not -`Mock(spec={Api}Client)`. Both couple your tests to internals the generator is free to change, and a +`Mock(spec={Api}Client)`. Both couple your tests to internals that change without notice, and a mocked client cannot catch the mistakes that actually happen — a wrong path parameter, a body that does not serialize, a header you forgot. Faking the transport exercises the real request-building -pipeline; that is the whole point. +pipeline. ### The token request comes first @@ -129,8 +126,8 @@ assert len(transport.requests) == 2 req = transport.last_request # index from the end, not [0] ``` -Or bypass acquisition entirely with a stub token source — the generator's supported injection point -(`python-authentication`) — so the stub transport only ever sees your operation: +Or bypass acquisition entirely with a stub token source (`python-authentication`), so the stub +transport only ever sees your operation: ```python from {root_package}.core import OAuthTokenRefreshable @@ -157,7 +154,8 @@ client = {Api}Client( The token is **cached on the scheme**, so only the first call fetches one: a test making two calls against one client sees three requests, not four. Forgetting the token request is the most common way a first test fails confusingly — the operation's decoder is handed the token body, and you get a -`ValidationError` about your payload rather than anything mentioning auth. The tests below queue only +`ResponseDecodeError` (a `ValidationError` about your payload on `__cause__`) rather than anything +mentioning auth. The tests below queue only the operation's response; for OAuth where the SDK fetches the token itself, put `token_response()` first (except in the bad-credentials test). @@ -217,17 +215,14 @@ def test_unmapped_status_is_raw(): # Body on demand: .text() always, .json() only if you know it is JSON (it raises ValueError). ``` -**Take the union from the contract sheet per operation.** The typed arm is not one type across the -API, so an error test copied from a sibling operation can pass for the wrong reason — it lands in the -`RawError` branch and asserts nothing about the typed body you meant to check. And never assert on -`str(e)` or `repr(e)`: they render as status plus payload *type name* by design, and are not a stable -contract. +**Take each operation's union from its own sheet row** — an error test copied from a sibling +operation can land in the `RawError` branch and pass for the wrong reason, asserting nothing about the +typed body you meant to check. ## Test the result-style (`with_raw_response`) variant -If your code uses the non-raising peer (`python-calling-endpoints`), there is nothing to catch — stub -the response and assert on the returned `ApiResult` directly. The split is mechanical: **2xx is -`Success`, everything else is `Failure`**, and both carry `.status_code` and `.headers`. +If your code uses the non-raising peer, there is nothing to catch — stub the response and assert on +the returned `Success` / `Failure` (`python-calling-endpoints`): ```python from {root_package}.core import Failure, Success @@ -243,9 +238,7 @@ def test_raw_response_reports_failure_without_raising(): assert "/{expected/path}" in transport.last_request.url # the operation, not the token ``` -This is also the mode to test in when your code depends on a header on the *success* path -(`Success(payload=..., status_code=..., headers=...)`), because the parsed form exposes neither — -except for a file response, which carries its own `headers` on the parsed path. +Test in this mode when your code reads a header on the *success* path. ## Assert the outgoing request @@ -253,66 +246,60 @@ except for a file response, which carries its own `headers` on the parsed path. actually change: ```python +import json from {root_package}.core import JsonBody req = transport.last_request assert req.method == "POST" assert req.url.endswith("/{expected/path}") assert "{query_param}=..." in req.url # query is part of the URL string -assert isinstance(req.body, JsonBody) and isinstance(req.body.value, dict) # narrow before indexing -assert req.body.value["{wire_field}"] == "..." # JsonBody carries the dumped payload +assert isinstance(req.body, JsonBody) # narrow before reading +assert json.loads(req.body.content)["{wire_field}"] == "..." # JsonBody carries the wire bytes assert req.headers["authorization"] == "Bearer t" # lowercase key — see below assert req.headers["{header}"] == "..." # a real default reached the wire ``` -**`HttpRequest.headers` keys are lowercased, not just the response's.** Every layer — the API's, the -endpoint's, the auth scheme's and your own `extra_headers` — is normalized before the merge, which is -exactly what makes the merge case-insensitive. So `req.headers["Authorization"]` is a `KeyError` and -`req.headers["authorization"]` is the assertion you want. This is the single most common way a first -request assertion fails confusingly. (The defensive `"authorization" in {k.lower() for k in -req.headers}` also works, but there is no case to defend against — assert the lowercase key.) +**`HttpRequest.headers` keys are lowercased**, at every layer — the API's, the endpoint's, the auth +scheme's and your own `extra_headers` — so assert `req.headers["authorization"]`; +`req.headers["Authorization"]` is a `KeyError`. **The body is already serialized by the time a transport sees it.** `req.body` is one of `JsonBody` -(`.value`, the dumped JSON-safe object), `FormBody` (`.fields`), `MultipartBody` (`.parts`, an -ordered sequence of `MultipartText` and `MultipartFile` — **not** a `.fields`/`.files` pair, and a -file part's `content` is the unread descriptor you passed, never bytes), `BinaryBody` -(`.content`, `.media_type`) or `TextBody` (`.text`, `.media_type`, `.charset`) — no transport ever -serializes anything — so assert on the dumped value -directly rather than re-parsing bytes. Note it uses **wire aliases**, because that is what -serialization produces: if a model's Python name differs from its JSON name, the request body has the -JSON name. Do not "fix" that in the test. - -**A list-valued query or form parameter has a per-parameter wire format.** The `Param` the generator -emitted for it in `apis/{controller}.py` carries a `SerializationFormat` — `indexed` -(`name[0]=a&name[1]=b`, URL-encoded as `name%5B0%5D=a`), `unindexed` (`name[]=a&name[]=b`), `plain` -(`name=a&name=b`), or `csv` / `tsv` / `psv` (`name=a,b`). Read it before asserting on `req.url`; -`"name=a" in req.url` is the assertion that fails against an indexed parameter. Path and header -arrays are not configurable — both fold to one comma-separated value. +(`.content`, the compact UTF-8 JSON bytes, and `.media_type`), `FormBody` (`.content`, the +url-encoded bytes), `MultipartBody` (`.parts`, an ordered sequence of `MultipartText` and +`MultipartFile` — **not** a `.fields`/`.files` pair; a text part's `.content` is its UTF-8 bytes, and a +file part's `.content` is the unread descriptor you passed, never bytes), `BinaryBody` +(`.content`, `.media_type`) or `TextBody` (`.content`, `.media_type`, `.charset`). Parse the JSON bytes +with `json.loads` and assert on the result — there is no dumped object to read — and expect **wire +aliases**: a member whose Python name differs from its JSON name is under the JSON name +(`python-models`). + +**A list-valued query or form parameter has a per-parameter wire format** — the `SerializationFormat` +on its `Param` in `apis/{controller}.py`: `indexed` (`name[0]=a&name[1]=b`, URL-encoded as +`name%5B0%5D=a`), `unindexed` (`name[]=a&name[]=b`), `plain` (`name=a&name=b`), or `csv` / `tsv` / +`psv` (`name=a,b`). Read it before asserting on `req.url`; `"name=a" in req.url` is the assertion that +fails against an indexed parameter. Path and header arrays always fold to one comma-separated value. Worth asserting once, somewhere, because they are silent when wrong: -- **The value actually reached the wire.** Models *preserve* unknown fields rather than rejecting them - (`python-models`), so a misspelled optional member becomes a preserved extra field instead of an - error. The only thing that catches it is an assertion on the serialized body. +- **The value actually reached the wire.** A misspelled optional member becomes a preserved extra + field, not an error (`python-models`); only an assertion on the serialized body catches it. - **Idempotency keys**, on operations that accept one: the same logical operation retried sends the *same* value, and two different operations send different ones (`python-configuration-resilience`). -- **Timeout plumbing.** `req.timeout` reflects a per-call `request_options={"timeout": ...}` and - **only** that. The client's own `timeout=` never rides the request — it configures the SDK's default - transport — so `req.timeout is None` on an ordinary call is correct, not a bug. A test that asserts - the client-level timeout on a captured request is asserting something that was never there; and once - you supply a stub transport, the client's `timeout=` reaches nothing at all. +- **Timeout plumbing.** `req.timeout` carries a per-call `request_options={"timeout": ...}` and + **only** that, so it is `None` on an ordinary call. The client's own `timeout=` never rides the + request — it configures the SDK's default transport, and with a stub transport it reaches nothing. - **Bodies that cannot serialize.** A value the SDK cannot dump raises *before* anything is sent, so the failure never reaches your stub and `transport.requests` stays empty. Worth one test where it applies (`python-models`). ## Cover the failures that are not `ApiError` -Three failure kinds never match `except ApiError`, and code that handles only the raised-`ApiError` -path is the norm (`python-error-handling`). Each is cheap to simulate. +Three failure kinds never match `except ApiError` (`python-error-handling`); each is cheap to +simulate. -**A decode failure — and it bypasses *both* response modes.** A body that does not deserialize raises -`pydantic.ValidationError` (or a plain `ValueError` for a non-JSON body). `with_raw_response` does -**not** turn it into a `Failure`: +**A decode failure** raises `ResponseDecodeError` (pydantic's `ValidationError`, or a plain `ValueError` +for a non-JSON body, on `__cause__`) in both response modes — `with_raw_response` does **not** turn it +into a `Failure`: ```python def test_unreadable_success_body_is_not_reported_as_failure(): @@ -324,9 +311,8 @@ def test_unreadable_success_body_is_not_reported_as_failure(): assert "/{expected/path}" in transport.last_request.url # the operation, not the token ``` -**A truncated 2xx that decodes cleanly.** Members are required only where the description marks them -required — often nowhere — so a response missing a member validates fine and reads back `UNSET`. Only -your own guard catches it, so test the guard: +**A truncated 2xx that decodes cleanly.** A response missing an optional member validates fine and +reads back `UNSET` (`python-error-handling`). Only your own guard catches it, so test the guard: ```python def test_truncated_success_body_is_not_reported_as_success(): @@ -337,28 +323,35 @@ def test_truncated_success_body_is_not_reported_as_success(): assert "/{expected/path}" in transport.last_request.url # the operation, not the token ``` -**A transport failure**, which arrives as the HTTP library's own exception, unwrapped — have the stub -answer any token response you queue, then raise on the operation's request: +**A connection failure**, which arrives as `SdkConnectionError` with the HTTP library's exception on +`__cause__`. A transport owes that shape, so the stub raises it too: answer any token response you +queue, then raise on the operation's request: ```python +import httpx2 +from {root_package}.core import SdkConnectionError, SdkTimeoutError, safe_url + class RaisingTransport(StubTransport): - """Answers the queued responses, then raises `error` on the next send.""" + """Answers the queued responses, then raises the family's exception for `cause` on the next send.""" - def __init__(self, error: Exception, *responses: StubResponse) -> None: + def __init__(self, cause: httpx2.TransportError, *responses: StubResponse) -> None: super().__init__(*responses) - self._error = error + self._cause = cause def send(self, request: HttpRequest) -> HttpResponse: if self._responses: # a queued token response, if any return super().send(request) self.requests.append(request) - raise self._error + method, url = request.method, safe_url(request.url) + if isinstance(self._cause, httpx2.TimeoutException): + raise SdkTimeoutError(f"{method} {url} timed out", method=method, url=url, timeout=5.0) from self._cause + raise SdkConnectionError(f"{method} {url} could not be sent: {self._cause}", method=method, url=url) from self._cause -def client_raising(error: Exception, *responses: StubResponse) -> tuple[{Api}Client, RaisingTransport]: +def client_raising(cause: httpx2.TransportError, *responses: StubResponse) -> tuple[{Api}Client, RaisingTransport]: # Pass token_response() only for OAuth where the SDK fetches the token itself (no # {scheme}_token_source); never for bearer, API key or basic auth. - transport = RaisingTransport(error, *responses) + transport = RaisingTransport(cause, *responses) return {Api}Client(custom_http_client=transport, retry_options=0, {scheme}=...), transport @@ -378,16 +371,13 @@ def test_read_timeout_is_an_unknown_outcome(): assert "/{expected/path}" in transport.last_request.url # the operation, not the token ``` -**Two transport failures, both inputs — never one.** A refused connection was never sent, so its -outcome is known: nothing happened. A read timeout may have landed, so its outcome is not. Test both -and expect **different** values — as the two tests above, or as the single two-input test -`python-error-handling` shows. A test that builds only one of them, or two that one assertion -satisfies, cannot tell the cases apart — and then neither can your code. When the SDK fetches a token, -let the token request through first: a failure *there* means your operation was never sent at all, -whatever the exception is called. +Test both inputs and expect **different** values: a test of only one, or two that one assertion +satisfies, cannot tell a never-sent failure from one that may have landed. When the SDK fetches a +token, let the token request through first — a failure *there* means your operation was never sent at +all. -And the one people forget: **bad credentials**. A failed token fetch raises `ApiError` too, but its -payload is `OAuthProviderError | RawError` — *not* the operation's union — and it surfaces out of the +And the one people forget: **bad credentials**. A failed token fetch raises `AuthSchemeError`, with +the token endpoint's `ApiError` on `__cause__` (never the operation's), and it surfaces out of the operation call. Return an RFC 6749 error body from the **token** request and assert your configuration error, not a rejection error: @@ -407,13 +397,14 @@ the response with `aiter_bytes`, `aread` and `aclose`, so queue an `AsyncStubRes ```python from collections.abc import AsyncIterator -from {root_package}.core import AsyncHttpResponse, HttpRequest +from {root_package}.core import AsyncHttpResponse, HttpMethod, HttpRequest @dataclass class AsyncStubResponse: status_code: int = 200 headers: Mapping[str, str] = field(default_factory=dict) chunks: list[bytes] = field(default_factory=list) + method: HttpMethod = "GET" # what a streamed payload names in its errors, with url url: str = "https://api.test/resource" closed: bool = False @@ -473,11 +464,8 @@ a `# type: ignore`. derives its payload from the model's own definition cannot detect a wrong payload. - **Build fixtures with models, then serialize** — `{request_fixture}().to_dict()` — rather than hand-writing wire JSON, so a member rename fails the fixture instead of passing a stale test. -- **Test your own boundary's output, not the SDK's.** The valuable assertions are that a 4xx the - caller caused becomes your 4xx, a 4xx that is **yours** — `401`, `403`, `429` — becomes your `502` - or `503`, and a transport failure becomes `502` if it was never sent and `504` if it may have landed - (`python-error-handling`). That the SDK raises `ApiError` on a 422 is the SDK's own tested - behaviour, not yours. +- **Test your own boundary's output** — the `provider_error` mapping in `python-error-handling` — not + that the SDK raises `ApiError` on a 422, which is the SDK's own tested behaviour. ## Integration tests against a live environment @@ -506,20 +494,18 @@ never gate CI on a third party's uptime unless you mean to. `retry_options=0` so one stubbed response is seen exactly once. In a test *about* retrying, set a policy with `initial_delay` and `max_jitter` small, queue one response per attempt and count `transport.requests`. For the loop to retry a - *transport* failure the fake must raise `TransportError` from `{root_package}.core` — a - bare `httpx2.ConnectError` bypasses the loop and reaches the test on the first attempt + *connection* failure the fake must raise `SdkConnectionError` from `{root_package}.core`, as + `RaisingTransport` does — a bare `httpx2.ConnectError` bypasses the loop and reaches the test, + unwrapped, on the first attempt (`python-configuration-resilience`). -- **A `401` invalidates the cached token but does not retry the request.** A test that stubs a `401` - therefore sees one failed operation — and the *next* call in the same test re-fetches a token, so - queue another `token_response()` for it. +- A stubbed `401` fails one operation and the *next* call re-fetches a token + (`python-authentication`), so queue another `token_response()` for it. - Mocking libraries (`unittest.mock`, `pytest-mock`) work too — the protocol is structural, so a `Mock()` with `send` and `close` configured satisfies it. The hand-written stub above gives you typed captured requests and ordered responses for free. -- **Stubbing a download** needs nothing extra: the SDK wraps the same `StubResponse` in the - `FileResponse` your assertions see, so the stub decides what the caller reads and when the - connection is released. Give it `chunks` if the test drives `iter_bytes`. What the caller may then - do with it — and the `ResourceWarning` an abandoned one emits, which a category default filters - unless you enable it here — is `python-file-handling`. +- **A download** is the same `StubResponse`, wrapped in the `FileResponse` your code sees; give it + `chunks` if the test drives `iter_bytes`. Making an abandoned download's `ResourceWarning` fail a + test is in `python-file-handling`. - **Use the client as a context manager or close it** in tests as in production; a stub's `close()` is a no-op, but the habit keeps the test and the real wiring the same shape (`python-client-initialization`). diff --git a/plugins/slack/skills/typescript/typescript-authentication/SKILL.md b/plugins/slack/skills/typescript/typescript-authentication/SKILL.md index ae49a764..c676f732 100644 --- a/plugins/slack/skills/typescript/typescript-authentication/SKILL.md +++ b/plugins/slack/skills/typescript/typescript-authentication/SKILL.md @@ -1,12 +1,12 @@ --- name: typescript-authentication -description: Authentication for an APIMatic-generated TypeScript SDK — supplying credentials on the client options object, the credential shape each scheme kind takes, OAuth 2 token caching and refresh, and replacing the token source. Load before wiring credentials into the client, or when a call comes back 401/403. +description: Load before setting credentials on an APIMatic-generated TypeScript SDK client, or when a call returns 401/403 — API keys, bearer and basic auth, the OAuth 2 client-credentials, password and authorization-code grants, token caching and refresh, and supplying your own token source. --- # Authenticating an APIMatic TypeScript SDK client -How you authenticate depends on the security scheme(s) the API declares. APIMatic surfaces each scheme -as an **optional credential member on `ClientOptions`**; set the one(s) your API uses, then construct +How you authenticate depends on the security scheme(s) the API declares. Each scheme is an +**optional credential member on `ClientOptions`**; set the one(s) your API uses, then construct the client (see `typescript-client-initialization`). There is no separate credentials builder, no per-request auth override, and no way to change a credential after construction. @@ -24,19 +24,17 @@ scheme factory as shared runtime code regardless of what the API accepts, so rel rather than that folder. Where a member's name does not tell you its kind, `src/auth-schemes.ts` shows which core factory each member is wired to. -The credential types below live under `src/core/auth/` and are exported from the package root; they -are the **same across all APIMatic TypeScript SDKs**. Only the **option member names** are generated -per-API (hence the `{scheme}` placeholders). The generator distinguishes **eight** scheme kinds — that -list is closed, so if the spec declared something outside it, read `src/auth-schemes.ts` to see what -was actually emitted rather than assuming a ninth shape. The eight collapse to **three** credential +The credential types below live under `src/core/auth/`, are exported from the package root and are +the **same across all APIMatic TypeScript SDKs**; only the **option member names** are per API (hence +the `{scheme}` placeholders). There are exactly **eight** scheme kinds, taking **three** credential shapes: | Scheme kind | `ClientOptions.{scheme}` type | Sent as | | --- | --- | --- | | HTTP bearer | `TokenProvider` | `Authorization: Bearer {token}` | -| API key in header | `TokenProvider` | the spec's header name | -| API key in query | `TokenProvider` | the spec's query parameter | -| API key in cookie | `TokenProvider` | a `Cookie` pair under the spec's name | +| API key in header | `TokenProvider` | the API's header name | +| API key in query | `TokenProvider` | the API's query parameter | +| API key in cookie | `TokenProvider` | a `Cookie` pair under the API's name | | HTTP basic | `BasicAuthCredentials` | `Authorization: Basic base64(user:pass)` | | OAuth 2 client credentials | `OAuth2ClientCredentials` | `Authorization: Bearer {fetched token}` | | OAuth 2 password | `OAuth2PasswordCredentials` | `Authorization: Bearer {fetched token}` | @@ -72,7 +70,7 @@ Sends `Authorization: Bearer ACCESS_TOKEN`. ## API key (header, query, or cookie) The key is sent as a header, query parameter, or cookie — its placement and name are fixed by the -generated scheme, not by anything you pass. Set the configured key member to your key string: +SDK, not by anything you pass. Set the configured key member to your key string: ```ts const client = new {Api}Client({ {scheme}: process.env.API_KEY! }); @@ -124,9 +122,9 @@ The SDK fetches and caches the token itself, acquiring a fresh one when it expir invalidates the cached token and re-acquires on the next call. `scope` is a **single space-delimited string**, not a list — you join it yourself, per RFC 6749 §3.3. -An empty string is treated as absent and no `scope` field is sent. The generator emits **no scope -enum or literal union** even where the spec declares a scope vocabulary, so a scope the flow does not -document type-checks fine and fails at the provider instead. +An empty string is treated as absent and no `scope` field is sent. It is typed plain `string` — **no +scope enum or literal union** — so a scope the provider does not offer type-checks and fails at the +provider. ## OAuth 2.0 — authorization code (3-legged, with PKCE) @@ -158,8 +156,8 @@ The URL handed to your callback carries `response_type=code`, `client_id`, `redi never see or manage it. - **`promptForAuthorizationCode` is called lazily**, on the first request needing the scheme — the - same point at which the other grants fetch their token. In a server app that is almost never what - you want mid-request; see *Supplying your own token source* below. + same point at which the other grants fetch their token. For a server app, see *Supplying your own + token source* below. - **PKCE is on by default.** Omitting `pkce` means `PkceMethod.S256`; `pkce: null` disables it. The verifier and challenge are generated with `crypto.getRandomValues` / `crypto.subtle`, so the runtime needs Web Crypto (Node 20+ and browsers have it). @@ -185,19 +183,18 @@ on the authorization request and never generated or checked here — the SDK nev producing and verifying it are yours alone. Your redirect handler must compare it against what you generated before returning the code, or the CSRF token is decorative. -⚠ **`clientSecret` is optional in the type, and only one of the two ways it can be missing throws.** +⚠ **`clientSecret` is optional in the type, and leaving it out throws only when PKCE is off.** | PKCE | `clientSecret` missing ⇒ | | --- | --- | | disabled (`pkce: null`) | `AuthError("A client secret is required when PKCE is disabled…")` — **before** the prompt runs | -| enabled, token request is header-placed | no error: the SDK sends `Authorization: Basic base64(clientId:)` and the provider rejects it — **after** the user has completed the full browser round-trip | -| enabled, token request is body-placed | fine — this is the public-client case | +| enabled | fine — this is the public-client case: the code exchange and every refresh send `client_id` as a form field and no `Authorization` header | -The placement is fixed by the spec, not by you, and is visible as the `placement` argument in -`src/auth-schemes.ts` (`"header"` sends `Authorization: Basic base64(clientId:clientSecret)` on the -token request; `"body"` sends `client_id` / `client_secret` as form fields). Check which one your -generated `src/auth-schemes.ts` passes before treating the secret as optional — the header case's -failure is the expensive one, because it costs an interactive login before the exchange fails. +An empty string counts as missing. The placement is not yours to choose: it is the `placement` +argument in `src/auth-schemes.ts` — `"header"` sends `Authorization: Basic +base64(clientId:clientSecret)` on the token request, `"body"` sends `client_id` / `client_secret` +as form fields. Without a secret, both placements send `client_id` alone, so a public client works +whichever one your spec chose. ## OAuth 2.0 — resource owner password @@ -215,7 +212,8 @@ const client = new {Api}Client({ ## Token caching & refresh (all OAuth 2 grants) -- Tokens are cached **in memory, per client instance**, and reused until **30 s** before expiry. +- Tokens are cached **in memory, per client instance**, and reused until **30 s** before expiry, or + for **half their lifetime** when that is longer. - Acquisition is **lazy** — on the first request that requires the scheme, not at construction. A client built with bad credentials constructs perfectly happily; the failure surfaces at the first operation. One in-flight acquisition is **shared**: concurrent requests that arrive during a fetch @@ -223,48 +221,39 @@ const client = new {Api}Client({ - The fetch is a form-encoded `POST` to the token endpoint, sent with **no auth scheme of its own**, and it runs on its own `retry.timeout` and the call's abort signal — so token-fetch time does not come out of the operation's attempt. -- **A failure while obtaining the token is not retried by the call.** It ends the call. -- **The token request is itself a `POST` under the same policy.** With the default - `httpMethodsToRetry`, an error status from the token endpoint — a `503` included — is not retried: - it is an `AuthError` and ends the call. Name `POST` in the gate and the token request retries a - retryable status like any other `POST`; the `AuthError` ends the call once those retries are spent. +- **A failure while obtaining the token ends the call.** The token request is itself a `POST` under the + client's retry policy, so with the default `httpMethodsToRetry` even a `503` from the token endpoint + is an immediate `AuthError`; name `POST` in the gate and the token request retries a retryable status + first. - **The cache lives in the client object.** Build the client once (see `typescript-client-initialization`) or every call re-runs the grant. -- **Only the authorization-code grant refreshes.** It is the one grant wired to - `oauth2RefreshableScheme` / `OAuth2RefreshableTokenStrategy`. Client-credentials and - resource-owner-password re-run the whole grant when the token expires — and a `refresh_token` in a - password-grant response is **discarded**, because the non-refreshable `OAuthToken` has no field for - it. Do not infer refresh behaviour from what the provider returns. -- When the authorization-code grant does refresh, a refresh response that omits `refresh_token` - carries the previous one forward. A refresh that fails does not throw — it returns `null` internally - and falls back to a full re-grant. +- **Only the authorization-code grant refreshes.** Client-credentials and resource-owner-password + re-run the whole grant when the token expires, and a `refresh_token` in a password-grant response is + **discarded** — do not infer refresh behaviour from what the provider returns. A refresh response + that omits `refresh_token` keeps the previous one, and a failed refresh does not throw: it falls back + to a full re-grant. - On `401`, the cached token is invalidated and re-acquired on the **next** call — `401` is not in the - default `statusCodesToRetry`, so the failing request is **not** re-sent. Handle the 401 as an ordinary `ApiError` (see `typescript-error-handling`); - the recovery is automatic on the following attempt, not on this one. + default `statusCodesToRetry`, so the failing request is **not** re-sent; handle it as an ordinary + `ApiError` (see `typescript-error-handling`). Add `401` to `statusCodesToRetry` to have the failing + call re-sent with a fresh token — every attempt resolves its credential again. A static key is + re-sent unchanged, so that only helps a scheme that fetches its credential. +- **Invalidation is a hint, not a barrier.** It clears the cache without cancelling a token fetch + already in flight, so that fetch can complete and re-populate it; "invalidate, then read" does not + guarantee a fresh token. ⚠ **A `401` on the authorization-code grant is an interactive re-authorization, not a silent refresh.** Invalidation clears the whole cached token, refresh token included, so "re-acquired" means the *full* grant runs again and `promptForAuthorizationCode` fires. Expiry takes the refresh path; a `401` does not. Plan for that in a non-interactive host. -⚠ **The 30-second buffer is flat, with no floor.** A token whose `expires_in` is **30 or less** is -already past its adjusted deadline the moment it is cached, so every request re-runs the grant and the -cache never serves anyone. There is no half-of-lifetime fallback for short tokens. If your provider -issues sub-minute tokens, supply your own token strategy rather than paying a token round-trip per -call. - -⚠ **If the token response omits `expires_in`, the token never expires as far as the SDK is -concerned** — and a non-positive `expires_in` is treated the same way. `expires_in` is RECOMMENDED but -not required by RFC 6749, and the SDK's expiry check short-circuits to "not expired" when it is -absent, so the first token is cached for the life of the client and the only thing that ever replaces -it is a `401`. That is usually fine and occasionally not: a token revoked server-side keeps being sent -until a request fails with it. If your provider omits `expires_in` and you need proactive rotation, -supply your own token strategy (below) rather than trying to bound the cache. - -- **Invalidation is a hint, not a barrier.** It clears the cache without cancelling an acquisition - already in flight, so that fetch can complete and re-populate it. That is deliberate — the newer - token post-dates the invalidation — but it means "invalidate then immediately read" is not a - guarantee of a fresh token. +**A short-lived token is renewed halfway through its lifetime.** The 30-second buffer applies to a +token issued for a minute or more; below that, the token is reused for half its `expires_in` — a 20 s +token for 10 s. So no token is stale the moment it is cached, and a sub-minute token costs one token +round-trip per half-lifetime rather than one per call. + +⚠ **A token response without a positive `expires_in` never expires in the cache** — the first token +is kept for the life of the client and only a `401` replaces it, so a token revoked server-side is +sent until a request fails with it. For proactive rotation, supply your own token strategy (below). ### Supplying your own token source @@ -311,42 +300,10 @@ turns into a redirect attempt inside a request. ## The failure mode that surprises everyone -**A failed token fetch surfaces out of your *operation* call, and `.asApiResult()` does not protect -you from it.** - -Auth is resolved inside the same dispatch the operation runs through, so both consequences follow from -one fact — the token fetch happens *during* your operation: - -1. **The traceback points at the operation you called**, not at anything named "auth". A token - endpoint that answers `400 invalid_client` becomes an `AuthError` thrown from - `client.{resource}.{operation}(...)`, with the underlying `ApiError` on `.cause` — and its own - `method` and `uri` name that operation, not the token endpoint. Reading only the top frame sends you - looking in the wrong place entirely. -2. **The non-throwing form still rejects.** `.asApiResult()` converts the *operation's* error response - into an `{ ok: false }` result instead of throwing — but auth is resolved before any response - exists, so an `AuthError` propagates straight out of the `await`. Code written specifically to - avoid exceptions still needs a `try`/`catch` around an authenticated call. - -So a boundary that only inspects `result.ok` is incomplete: - -```ts -import { AuthError } from "{package-name}"; - -try { - const result = await client.{resource}.{operation}(request).asApiResult(); - if (!result.ok) { /* the operation's own error union */ } -} catch (err) { - if (err instanceof AuthError) { - // Credentials/token problem — the operation request was never sent. - throw new Error("API credentials rejected", { cause: err }); - } - throw err; -} -``` - -Treat it as an **auth** failure, distinct from an operation rejection: nothing was attempted, -so retrying it or reporting it as a failed operation are both wrong. `typescript-error-handling` has -the full catch ladder. +A token endpoint that answers `400 invalid_client` rejects the *operation* call with `AuthError` — its +`method`/`uri` name the operation, the token endpoint's `ApiError` is on `.cause`, nothing was sent, +and `.asApiResult()` does not convert it. Catch it around every authenticated call; the ladder is in +**typescript-error-handling**. ## Combined / multiple schemes @@ -361,10 +318,6 @@ by `allAuth(...)` / `anyAuth(...)`; you configure it by setting the relevant cre not on which looks more specific. A `TokenProvider` **function** always counts as "has credentials", even if it returns an empty string — so a function provider always wins the OR. -**This layer never withholds a request over a missing credential, and never throws for one.** An -unconfigured member simply drops out and the request goes out with whatever *was* configured; with -nothing configured at all it goes out unauthenticated. The server decides. - Because composition is **per operation**, one client may authenticate different operations with different schemes — so set every member the operations your integration actually calls need, not just the ones the API's front page advertises. The per-operation requirement is the **Auth** bullet on the @@ -373,10 +326,8 @@ out: `` `{scheme}` ``, `all of …`, or `any of … — the first one configured ## No auth -An operation the spec marked public is wired to `noneAuth` and sends **no credential even when every -option member is filled**. Its **Auth** bullet reads `none — public; no credential is sent`. Nothing -you pass at construction adds a credential to such an operation — if it needs one, that is a spec -problem, not a configuration one. +An operation whose **Auth** bullet reads `none — public; no credential is sent` sends **no credential +even when every option member is filled**, and nothing you pass at construction adds one. ## ⚠ Missing credentials must stop the app from starting @@ -394,31 +345,10 @@ An API that serves anonymous traffic at all — public endpoints, or a reduced r callers — makes this worse by answering `200` and hiding the omission entirely. So verify the member is actually set rather than waiting for a `401` to tell you. -**A required credential that is not configured is a deployment fault, not a request fault.** If the -app boots with a blank secret, an operator sees a provider outage, retry logic hammers a call that can -never succeed, and the actual cause — an unset environment variable — is two layers away from the -symptom. There is no `.env` support and no `fromEnvironment()` helper in the SDK, so **validate at the -call site and refuse to boot**: - -```ts -function buildClient(): {Api}Client { - const key = process.env.API_KEY; - if (!key) { - throw new Error( - "API_KEY is not configured. Set it via environment variable or your secret store " + - "before starting the app.", - ); - } - - return new {Api}Client({ - serverEnvironment: ServerEnvironment.Production, - {scheme}: key, - }); -} -``` - -Run that check **before** the app is ready to serve — at module load or in your startup path, not -lazily on first use, which is a request, which is exactly the late failure you are trying to avoid. +**A required credential that is not configured is a deployment fault, not a request fault.** There is +no `.env` support and no `fromEnvironment()` helper in the SDK, so **validate every required +credential in your startup path and refuse to boot** — not lazily on first use, which is a request. +The factory in **typescript-client-initialization** shows the shape. Three rules for the message it fails with: @@ -435,38 +365,26 @@ absent, so a blank env var is the same fault as an unset one. ## Notes -- A given SDK only exposes the credential members for the schemes its API declares; those names are - generated per-API (hence the `{scheme}` placeholders above). Fill every member the operations you - call need. - **Credentials are fixed at construction.** `ClientOptions` is `readonly` and the auth schemes are built in the constructor, so to rotate a credential you use a `TokenProvider` **function**, replace the strategy, or build a new client. There is no mutable accessor. - **Rotating a long-lived client:** the token cache is per client instance, so swap atomically — build the new client, then replace the shared reference. In-flight calls finish on the old one and there is no window where calls have no credential. Do not mutate the old client. -- **Auth wins every header, query and cookie collision.** Auth params are merged **last**, after the - client's defaults and the endpoint's own, so a scheme's `Authorization` header overwrites anything - set earlier under that name. There is no per-request header override to undo it — a `fetch` wrapper - is the only place you can strip or replace an auth header (see +- **Auth wins every header, query and cookie collision** — a scheme's `Authorization` header + overwrites anything else under that name, and only a `fetch` wrapper can strip or replace it (see `typescript-configuration-resilience`). - **Nothing hides secrets in a log you write.** Credentials are plain objects with no redacting `toString`, so `console.log(options)` or a serialized `ClientOptions` prints them in full. The SDK's - own logging, off by default, masks the `Authorization` header, a query value off its safe list and - the OAuth form keys (`client_secret`, `password`, `refresh_token`, …) — but a JSON request body it - logs verbatim once `logRequestBody` is on (see **typescript-configuration-resilience**). -- On the OAuth 2 token request, header placement sends `base64(clientId:clientSecret)` **without - percent-encoding either half** first. A client id or secret containing a character RFC 6749 §2.3.1 - would have you encode is sent raw, so a provider that follows the RFC strictly may reject it — use - body placement or a custom strategy if your secret is not in the unreserved set. -- **`AuthError` means a credential could not be obtained** — the token request failed, every - configured branch of an alternatives requirement failed, PKCE was disabled without a secret, or your - `promptForAuthorizationCode` rejected. Being *refused* a credential by the API is an `ApiError` with - status 401/403 instead, so one `catch` arm cannot absorb the other. A token endpoint that answers with - an error status surfaces as `AuthError` with that `ApiError` on `.cause`; an alternatives requirement - whose every branch failed carries an `AggregateError` there, holding each branch's failure. -- Credentials never appear in a thrown error's message. -- **A token endpoint may live on a different server group than the operations.** Overriding - `serverOptions.default.{environment}.baseUrl` therefore does not move the token request — override - that group too if you need both redirected at a mock. See `typescript-configuration-resilience`. -- Keep secrets out of source — read `process.env` or your secret manager at the call site. Set - credentials **before** constructing the client; there is no way to add them afterwards. + own logging masks a credential in a header, the query or an OAuth form body, but not in a JSON request + body (**typescript-configuration-resilience**). +- On the OAuth 2 token request, header placement with a secret sends + `base64(clientId:clientSecret)` **without percent-encoding either half** first. A client id or + secret containing a character RFC 6749 §2.3.1 would have you encode is sent raw, so a provider that + follows the RFC strictly may reject it — use body placement or a custom strategy if your secret is + not in the unreserved set. +- `AuthError` (a credential could not be *obtained*) versus a 401/403 `ApiError` (refused by the API): + **typescript-error-handling**. +- A token endpoint may live on its own server group, so redirecting the operations' group at a mock + does not move it (**typescript-configuration-resilience**). +- Keep secrets out of source — read `process.env` or your secret manager at the call site. diff --git a/plugins/slack/skills/typescript/typescript-calling-endpoints/SKILL.md b/plugins/slack/skills/typescript/typescript-calling-endpoints/SKILL.md index 74e5dd04..df47f393 100644 --- a/plugins/slack/skills/typescript/typescript-calling-endpoints/SKILL.md +++ b/plugins/slack/skills/typescript/typescript-calling-endpoints/SKILL.md @@ -1,16 +1,16 @@ --- name: typescript-calling-endpoints -description: Calling operations on an APIMatic-generated TypeScript SDK — finding the resource that owns an operation, building the one flat channel-blind request object, required vs optional vs defaulted fields and the values that never appear on the request at all, passing a body, the ApiPromise return and the two ways to read it, bounded concurrency, and cancellation. Load before writing the first call to an SDK operation, or when an operation's shape or return type is unclear. +description: Load before writing the first call to an APIMatic-generated TypeScript SDK operation, or when an operation's request shape or return type is unclear — the one flat request object, required, optional, defaulted and SDK-fixed fields, request bodies and file uploads, binary responses, reading an `ApiPromise` or `.asApiResult()`, the `Pageable` walk a paged operation returns, and per-call retry and cancellation. --- # Calling endpoints on an APIMatic TypeScript SDK -Operations are **methods returning `ApiPromise`** on the client. Most are **grouped under a resource -getter** and called `client.{resource}.{operation}(...)`; an operation the spec left untagged sits -**directly on the client**, called `client.{operation}(...)`. The resource getter, the exact operation -name and its signature come from the generated SDK map (grounded in `src/client.ts` and -`src/resources/`) — operation names follow no fixed verb/resource pattern, so take the real name from -the map, never from memory. +Operations are **methods returning `ApiPromise`** on the client — or `Pageable`, for an operation the +API pages (see [A paged operation](#a-paged-operation)). Most are **grouped under a resource +getter** and called `client.{resource}.{operation}(...)`; an operation with no resource group sits +**directly on the client**, called `client.{operation}(...)`, and an SDK may have no resource level at +all. Take the getter, the exact operation name and its signature from the SDK map, never from memory — +operation names follow no fixed verb/resource pattern. > Throughout this skill, `{...}` is a placeholder for a name you take from your SDK (e.g. `{Api}Client`, > `{package-name}`, `{resource}`, `{Resource}`, `{Operation}`, `{Enum}`) — replace it with the concrete @@ -30,8 +30,7 @@ the map, never from memory. the docs do not carry. Both the docs and `src/` ship inside `node_modules/{package-name}/`, so read them there rather than the -compiled `dist/`. **Do not assume a `client.{resource}` level exists** — when the spec declares no tags, -or exactly one tag covering every operation, no resource classes are emitted at all. +compiled `dist/`. Resource classes are exported from the package root, but only for their merged namespaces and for `instanceof`. Never construct one: its constructor takes engine internals that are not exported. @@ -44,26 +43,23 @@ Every operation has the same shape, with no positional overload and no sync vari {operation}(request: {Resource}.{Operation}Request, options?: RequestOptions): ApiPromise ``` -- **There is exactly one request parameter**, and it is **not optional** — even when every field on it - is. An all-optional request still needs `{}` passed explicitly. -- **`options` is on every generated operation**, always last, always optional. It is - `RequestOptions` = `{ signal?: AbortSignal; retry?: RequestRetryOptions }` and nothing else — see +- **There is exactly one request parameter.** It is required when any field on it is. When every field + is optional it defaults to `{}`, so the call may leave it out — `{operation}()` sends what + `{operation}({})` sends. +- **`options?: RequestOptions` is on every operation**, always last — see [Cancellation and per-call retry](#cancellation-and-per-call-retry). -- **An operation may declare no request parameter at all.** When every value the request carries is - fixed by the spec, the generator emits no parameter and exports no request type, and `options` moves - into first position. Check the **Signature** bullet before passing `{}` — it will not type-check - against an operation whose only parameter is `RequestOptions`. +- **An operation whose every value is fixed takes no request parameter** and has no request type; + `options` is then its only parameter. Check the **Signature** bullet before passing `{}` — it will + not type-check against such an operation. ```ts await client.{resource}.{operation}(); // no request await client.{resource}.{operation}({ signal }); // options only ``` -- **The map is the source of truth for the signature.** Whether a field is required, optional or - defaulted — and whether the operation takes a body at all — varies per operation. -- **Return type** varies by operation — see - [Making the call and reading the response](#making-the-call-and-reading-the-response). -- A non-2xx response **rejects** the promise unless you opt out with `.asApiResult()` — see - **typescript-error-handling**. +- Requiredness, defaults, whether there is a body, and the return type all vary per operation — read + each from its map entry. +- A paged operation returns `Pageable` in place of `ApiPromise`, and its **Returns** + bullet names the paging strategy and what ends the walk. ## The request object is flat and channel-blind @@ -90,27 +86,18 @@ the field list either, so the table is the only place to learn what went on the ### Where a field lands — the rule -Each value the spec declares produces **one of four** outcomes, and the last one catches people out: - -| What the spec declares | What you get | +| In the map | What you get | |---|---| -| **required**, no fixed value | `f: T` — a required member of the request object | -| **optional** | `f?: T` — omit it and nothing is sent for it | -| a **default value** | `f?: T` — omit it and the SDK **still sends the default** | -| a **constant** value | **no field at all** — the value is baked into the request and you cannot change it | - -Three consequences worth taking off the map before you write the call: - -- **A constant appears in no signature and in no Fields table.** Its only listing is the operation's - **SDK-sent** bullet, which spells each fixed pair as it goes on the wire. If you are hunting for a - field to set a `Content-Type`, an API version or a fixed `grant_type` with, that is why you cannot - find one — and there is no override for it short of wrapping `fetch`. -- **"Required" says nothing about the channel.** A required field may travel in the query, a header or - the form body just as easily as the path; requiredness and channel are independent columns. Never - infer one from the route. -- **Field names are the generated `camelCase` identifiers, not the wire names.** A header field - `traceId` is transmitted as `X-Trace-Id`, and the `Wire` column is where that mapping lives — it is - written only where the two differ, so a `—` means they match. +| `Req` yes | `f: T` — a required member of the request object | +| `Req` no, no `Default` | `f?: T` — omit it and nothing is sent for it | +| a `Default` | `f?: T` — omit it and the SDK **still sends the default** | +| listed only under **SDK-sent** | **no field at all** — a fixed value (a `Content-Type`, an API version, a `grant_type`) spelled as it goes on the wire; no override short of wrapping `fetch` | + +- **Requiredness and channel are independent.** A required field may travel in the query, a header or + the form body just as easily as the path; never infer one from the route. +- **Field names are `camelCase` identifiers, not the wire names.** A header field `traceId` is + transmitted as `X-Trace-Id`; the `Wire` column gives the wire name where the two differ, and `—` + means they match. The request type is declared in the resource's merged namespace, so it is `{Resource}.{Operation}Request` — importable from the package root if you want to name it: @@ -123,17 +110,11 @@ const request: {Resource}.{Operation}Request = { /* ... */ }; ## Building request models -**A JSON, text or binary operation has a `body` field.** Where the API declares an -`application/x-www-form-urlencoded` or `multipart/form-data` request, the generator emits the parts as -**individual flat request fields** alongside the path and query ones and assembles the form itself — -there is no nested body object to construct and no `body` field to pass. The operation's **Request -body** bullet says which you are looking at; the signature settles it. - -The runtime carries six request-body shapes: **empty, JSON, form-urlencoded, text, multipart and -binary**. An **XML** body has no carrier, so the operation is still emitted but **degrades to no body -field at all** — there is nothing to supply the payload through, and the request goes out with no -body. Its **Request body** bullet reads `none` in that case. If you need such an endpoint, call it -with `fetch` directly; the SDK cannot send it. +**A JSON, text or binary operation has a `body` field; a form-urlencoded or multipart operation has +none** — its parts are **individual flat request fields** beside the path and query ones, and the SDK +assembles the form. The operation's **Request body** bullet says which. An **XML**-body operation has +no body field and sends no body (its **Request body** reads `none`); call that endpoint with `fetch` +directly. **A file field takes bytes, not a path.** Every binary `body` field and every multipart file field is typed `FileInput`, which is a `Blob`, a `Uint8Array`, an `ArrayBuffer`, a `ReadableStream` of bytes, @@ -156,64 +137,38 @@ the read, so an unread stream holds the connection until you read it, cancel it `signal`. A server-chosen file name is untrusted input: sanitise it before writing to disk. -For the JSON case, the `body` field's type is a generated model — a plain object literal, no builders. -Required members must be set; optional ones are omitted from the JSON when left `undefined`, except one -with a spec default (`s.defaulted(...)` in the model's schema), which the SDK fills in and sends. Take the -type's name and the file that declares it from the **Type sources** table: - -```ts -const result = await client.{resource}.{operation}({ - body: { - requiredProp: value, // required members must be provided - optionalProp: value, // optional; unset means omitted, unless it has a spec default - }, -}); -``` - -A body's **shape varies**: some are flat scalars, others nest an inner model. The **Fields** table and -the model file named beside it carry the real members. +For the JSON case, the `body` field's type is a generated model written as a plain object literal +(**typescript-models**); take its name and the file that declares it from the **Type sources** table. -**An optional-looking body is not permission to omit it.** A `body?: T` reflects what the *spec* marked -optional, not what the endpoint needs. A create whose body is optional in the spec type-checks with -`{}` passed and then fails at the provider. Where a call obviously needs a payload, pass one. +**An optional-looking body is not permission to omit it.** A `body?: T` is optional only in the type: +a create passed `{}` type-checks and then fails at the provider. Where a call obviously needs a +payload, pass one. ### Defaults are sent, not omitted -A field the spec gave a default is filled **by the SDK** when you omit it, and it goes on the wire. -Omitting such a field is therefore not "let the server decide" — the server sees the value. Which -fields have defaults is the `Default` column of the **Fields** table. +An omitted field with a `Default` is filled **by the SDK** and sent, so the server sees the default, +and the response is the one that default asked for — a verbosity switch defaulting to the minimal form +(a create resolving to little more than an id and a status), or a field selector defaulting to one +section. Read the `Default` column **before** concluding the API dropped data — it was never +requested. -**And a default can silently narrow what comes back.** A defaulted field is *always sent*, so the -response you get is the one that default asked for, not the full resource. The two shapes that cost -people an afternoon: +### Every value is shape-checked before anything is sent -- a representation or verbosity switch defaulting to the minimal form, so a create resolves to little - more than an id, a status and some links; -- a field selector defaulting to one section, so whole branches of the response are simply absent. - -Read the `Default` column **before** concluding the API dropped data — it was never requested. - -### Every value is validated before anything is sent - -Each field is schema-encoded on the way out. A wrong type or a malformed format (a bad date string, +Each field is schema-encoded on the way out: a wrong type or a malformed format (a bad date string, say) rejects with an `EncodeError` — its `cause` the `SchemaError` naming the field — and **nothing is -sent**: no request reaches the network. That is an error in -your code, not an API failure; see **typescript-error-handling**. - -## Enums - -Enum fields take a member of the generated `const` object. The type alias is **open** — it carries a -`| (string & {})` (or `| (number & {})`) tail — so a raw string also type-checks: +sent** (**typescript-error-handling**). -```ts -import { {Enum} } from "{package-name}"; +A value constraint the spec declares — `minLength`, `pattern`, `minimum`, `uniqueItems`, a checked +`format` such as `email` — is **not** applied by the operation, so a value that breaks one is sent as +built and refused, if at all, by the service. Whether `{model}Schema.validate(body)` checks it first, +and whether an operation exports a `{Group}.{operation}RequestSchema` to `validate` the request object +against, is stated in **typescript-models** (*Checking a value before you send it*). Either `validate` +returns `{ success: true }` or `{ success: false, message }` with every failing field named. -await client.{resource}.{operation}({ status: {Enum}.Active }); // preferred — a rename is caught -await client.{resource}.{operation}({ status: "active" }); // also compiles -``` +## Enums -Prefer the member: the string form silently survives a spec change that renames the value. See -**typescript-models** for read-back semantics and for guarding an unknown value off the wire. +Enum fields take a member of the generated `const` object — `{ status: {Enum}.Active }`. A raw string +also compiles (the type is open), but only the member catches a rename. See **typescript-models**. ## Union types, collections, and dates @@ -228,10 +183,9 @@ Some fields are not plain scalars: `oneOf`/`anyOf`/polymorphic unions declared u const value = await client.{resource}.{operation}({ /* ... */ }); ``` -> **Wrap the call in error handling — a non-2xx response *rejects*, it is not signalled by the return -> value.** The bare `await` above shows only the happy path. Before writing a real call, **load -> `typescript-error-handling`** for the `try`/`catch` shape and which error type to narrow on per -> operation — or use the non-throwing `.asApiResult()` form below. +> **A non-2xx response *rejects*.** Before writing a real call, **load `typescript-error-handling`** for +> the `try`/`catch` shape and which error type to narrow on per operation — or use the non-throwing +> `.asApiResult()` form below. Operations return `ApiPromise`, a `Promise` subclass. Two ways to consume it: @@ -256,25 +210,18 @@ type ApiResult = payload: PayloadOf }; ``` -Five things to know: - -- **`.asApiResult()` must be called on the value the operation returned.** `ApiPromise` overrides +- **Call `.asApiResult()` on the value the operation returned.** `ApiPromise` overrides `Symbol.species`, so `.then()`, `.catch()` and `.finally()` hand back a plain `Promise` and the - method is gone. `op(...).then(x => x).asApiResult()` does not compile. -- **`.asApiResult()` still rejects for every other failure** — a body that would not decode, a value that - would not encode, a connection error, a timeout, a credential that could not be obtained, or a caller - abort. It converts only the *HTTP error status* branch into a value, so it still needs a - `try`/`catch` around it. -- **On failure, `outcome` carries the error's own members, not the error object** — `status`, - `headers`, `message`, `method`, `uri` and `payload` — so `outcome.payload.kind` narrows exactly as - `err.payload.kind` would. The `ApiError` instance is not reachable through this path. -- **Nothing suppresses an unhandled rejection.** A call you never await that fails is reported by the - runtime — `unhandledRejection` on Node, which by default ends the process. `.asApiResult()` marks the - promise handled as its first act, so call it on the returned value in the same turn, and never start - a call you do not consume. -- **Both paths read one underlying outcome**, so awaiting an `ApiPromise` *and* calling - `.asApiResult()` on it issues no second request. The request goes out when the operation is called, - not when you await it — which also means a call you build and hold has already been sent. + method is gone — `op(...).then(x => x).asApiResult()` does not compile. +- **It converts only the HTTP error status.** Every other failure still rejects, so keep the + `try`/`catch`; on failure `outcome` carries the error's members, not the error object + (**typescript-error-handling**). +- **The request goes out when the operation is called**, not when you await it; awaiting and + `.asApiResult()` read the same outcome and never send twice, so a call you build and hold has already + been sent. +- **Nothing suppresses an unhandled rejection.** A call you never consume that fails is an + `unhandledRejection` — on Node, by default, the process ends. `.asApiResult()` marks the promise + handled as its first act, so call it on the returned value in the same turn. ### Status and headers @@ -284,73 +231,77 @@ deliberately unreachable. ### The success type -`T` is whatever the operation's success body decodes to. The **Returns** bullet names it, and the cases -you will meet are: +The operation's own **Returns** bullet names `T`, which can differ between sibling operations: -- **A model type** — a JSON body decoded through the generated schema. The **Type sources** table names - the file under `src/models/` where you read its shape; the map does not duplicate it. -- **A primitive** — a `text/plain` body decoded by the plain-text scalar decoder, not by a model. -- **`undefined`** — the operation's success response has no body. That is a real value, not a mistake: - the decoder asserts the body is empty, and a non-empty one rejects with `DecodeError`. +- **A model type** — a JSON body decoded through its schema. The **Type sources** table names the file + under `src/models/` where you read its shape. +- **A primitive** — a `text/plain` body. +- **`undefined`** — no body; a non-empty one rejects with `DecodeError`. Resolving *is* the success + signal: do not test the value, re-read the resulting state with a separate call if you need it, and + use `.asApiResult()` to tell a `200` from a `204`. +- **`EventStream`** — a `text/event-stream` body. The call resolves at the response headers with + nothing read, and `for await` over the stream yields each event's decoded `data` as a `T`; the + stream holds its connection until the loop ends or you `close()` it. Load + **typescript-event-streams** before you write the loop. -**On an `undefined` operation, resolving *is* the success signal.** Do not bind the value and do not -test it — success is "did not reject", exactly as for the others. Two follow-ons: if you need the -resulting state, re-read it with a separate call; and if you need to tell a `200` from a `204`, -`.asApiResult()` is the only place the status appears. +### A paged operation -Endpoints in the same family can differ, so let each operation's own **Returns** bullet decide how you -read it. +An operation the API pages returns **`Pageable`** instead of `ApiPromise`. The +**Signature** bullet shows it, and the **Returns** bullet names the strategy and what ends the walk. +Nothing is sent when you call it: the walk is lazy, the first page goes out when a loop starts, and +each new loop starts again from the first page. -## Cancellation and per-call retry +```ts +// Items, across every page — the SDK fetches the next page as the previous one runs out: +for await (const item of client.{resource}.{operation}({ /* ... */ })) { + process(item); +} -`RequestOptions` is the entire per-call surface: +// Pages, when you need the page's own members (a total, a cursor, a link): +for await (const page of client.{resource}.{operation}({ /* ... */ }).pages()) { + process(page.{items}); +} -```ts -type RequestOptions = { - signal?: AbortSignal; - retry?: RequestRetryOptions; // Pick -}; +// The result form — an error status as a value instead of a throw: +for await (const result of client.{resource}.{operation}({ /* ... */ }).asApiResult().pages()) { + if (!result.ok) break; // the failed page is the last one the walk yields +} ``` -`retry` overrides three fields of the client's retry policy for this call alone, field by field — a -field you leave out keeps the client's value: +The request's paging fields (`page`, `offset` or `cursor`, and `limit`) **seed the first page** with +their declared defaults applied; the SDK advances the page, offset or cursor from there. `options` +applies to every page the walk sends. Either loop throws `E` at the first error status, and every +other failure exactly as an awaited call would reject — a `{Api}Error` member, or a caller abort's +own `reason`. An item loop over `.asApiResult()` **ends silently** at an error status, so use +`.pages()` on the result form when the distinction matters. **Every walk needs a bound of your +own** — a page cap, an item cap or a deadline; **typescript-configuration-resilience** carries the +strategies, their stop rules and the bounded shape. + +## Cancellation and per-call retry + +`RequestOptions` = `{ signal?: AbortSignal; retry?: RequestRetryOptions; logging?: RequestLoggingOptions }` +is the entire per-call surface. `retry` overrides `maxRetries`, `timeout` and `statusCodesToRetry` for +this call, field by field — a field you leave out keeps the client's value — and `logging` takes only a +`level`. Headers, base URL, auth and the other retry and logging fields are client-level only +(**typescript-client-initialization**, **typescript-configuration-resilience**). ```ts await client.{resource}.{operation}({ /* ... */ }, { retry: { maxRetries: 0 } }); // one attempt await client.{resource}.{operation}({ /* ... */ }, { retry: { timeout: 5_000 } }); // 5 s per attempt -``` - -There is **no** per-call header, base URL or auth override, and the type admits no other retry field -(though the runtime honours one it is handed) — those belong on -`ClientOptions` at construction (**typescript-client-initialization**), and the retry policy's other -fields on `ClientOptions.retry` (**typescript-configuration-resilience**). -```ts const controller = new AbortController(); setTimeout(() => controller.abort(new Error("too slow")), 5_000); - await client.{resource}.{operation}({ /* ... */ }, { signal: controller.signal }); ``` -An already-aborted signal rejects immediately. See **typescript-configuration-resilience** for -deadlines across a whole call and for combining signals. - -Three mechanics that decide how you catch the result: - -- **Your signal and each attempt's `retry.timeout` race the same internal controller**, so an - attempt ends on whichever fires first. `retry.timeout` bounds **one attempt**, in milliseconds, even - when set per call — an idempotent call that keeps failing gets up to four of them, plus backoff — so - a signal plus your own timer is how you bound the whole call. An abort also cuts a backoff wait short, - and is never retried. -- **An abort rejects with the signal's own `reason`, unwrapped, and a timeout with `TimeoutError`** - once no retry is left. - Whatever you passed to `controller.abort(reason)` — or the `DOMException` a bare `abort()` supplies — - is what the call rejects with, so it is **not** an `{Api}Error`; the timeout is the SDK's own and - stays in the family. -- **Neither is an `ApiError`.** A `catch` that narrows on `ApiError` — or on an operation's declared - error class — will **not** match an abort, a timeout or a connection failure. See - **typescript-error-handling** for a ladder over the whole family, and for rethrowing what is outside - it. +- `retry.timeout` bounds **one attempt**, in milliseconds, even when set per call — an idempotent call + gets up to four attempts plus backoff — so only your `signal` bounds the whole call + (**typescript-configuration-resilience** for deadlines and combining signals). An abort — an + already-aborted signal included — ends the call at once, cuts a backoff wait short and is never + retried. +- An abort rejects with the signal's own `reason`, unwrapped, and an exhausted timeout with + `TimeoutError`. Neither is an `ApiError`, and the abort is not an `{Api}Error` at all — see + **typescript-error-handling** for a ladder over the whole family. ## Concurrency @@ -386,8 +337,11 @@ const all = await mapLimit(ids, 10, (id) => client.{resource}.{operation}({ id } Note that `Promise.all` rejects on the first failure and leaves the rest of the batch running unobserved; `Promise.allSettled` is usually what you want when partial success is acceptable. -Nothing is paginated and nothing is async-iterable, so there is no `for await` form. If an operation -returns a page, advance its page or cursor field yourself in a loop — see +A paged operation returns a `Pageable`: `for await` it and the SDK fetches the pages one at a time — +see [A paged operation](#a-paged-operation). The only other `for await` form is over an +`EventStream`, which only an operation whose **Returns** bullet reads `EventStream` hands back +(**typescript-event-streams**). A list operation whose **Signature** returns `ApiPromise` is a single +call; to page one of those, advance its page or cursor field yourself in a loop — see **typescript-configuration-resilience**. ## Worked example — a list/GET call @@ -425,7 +379,8 @@ if (!outcome.ok) { > This operation's success body is a model that nests its list under a member, so you read that member > and then iterate. Another operation may return the array directly, or a primitive, or `undefined`. -> Check its **Returns** bullet. +> Check its **Returns** bullet — and when its **Signature** returns `Pageable`, it is walked with +> `for await` rather than awaited (see [A paged operation](#a-paged-operation)). ## Next diff --git a/plugins/slack/skills/typescript/typescript-client-initialization/SKILL.md b/plugins/slack/skills/typescript/typescript-client-initialization/SKILL.md index 8f8dcacf..8e23d37f 100644 --- a/plugins/slack/skills/typescript/typescript-client-initialization/SKILL.md +++ b/plugins/slack/skills/typescript/typescript-client-initialization/SKILL.md @@ -1,6 +1,6 @@ --- name: typescript-client-initialization -description: Creating and reusing an APIMatic-generated TypeScript SDK client — construction, the ClientOptions shape, fetch ownership and client lifetime, and wiring the client into an application's startup. Load before wiring the client into an app or writing the factory that builds it. +description: Load before writing the code that builds an APIMatic-generated TypeScript SDK client — `ClientOptions`, environments and base URLs, client lifetime and the token cache, wiring the client into app startup or dependency injection, ESM and CommonJS, and inbound webhooks. --- # Initializing an APIMatic TypeScript SDK client @@ -18,8 +18,8 @@ from the SDK you are using: - `{resource}` / `{operation}` — a resource getter on the client and an operation on it. - `{scheme}` — a credential member on the options object, one per auth scheme the API declares. -Everything under `src/core/` is vendored static code that is **byte-identical in every generated -TypeScript SDK**, so the engine behaviours below hold without checking yours. What varies per SDK is +Everything under `src/core/` is **the same in every APIMatic TypeScript SDK**, so the engine behaviours +described in these skills hold without checking yours. What varies per SDK is `src/client.ts`, `src/client-options.ts`, `src/servers.ts`, `src/auth-schemes.ts`, `src/resources/` and `src/models/`. @@ -42,8 +42,8 @@ Two facts about where those files live: `dist`, `src`, `README.md`, `api-reference.md`, `sdk-map.md` and `map`, so the readable TypeScript source and the lookup index are both inside `node_modules/{package-name}/`. Read them there rather than the compiled `dist/`. -- **`dist/` must exist before the package can be referenced.** The SDK builds with `tshy`; a freshly - generated SDK consumed by path needs its `build` script run once. A `Cannot find module` on a +- **`dist/` must exist before the package can be referenced.** The SDK builds with `tshy`; an SDK + consumed by path needs its `build` script run once. A `Cannot find module` on a path-installed SDK is usually this, not a bad import. ## Shape of the client @@ -59,69 +59,52 @@ Nothing on it is required and neither is the argument, so `new {Api}Client()` co object is the whole configuration surface, and reading the environment into it is yours to do at the call site. -Operations are exposed on the client. Most are grouped under **resource getters** (one per API -resource group) and called `client.{resource}.{operation}(...)` — for example, a `widgets` resource's -`listWidgets` operation is `client.widgets.listWidgets(...)`. But when the spec declares **no tags**, -or exactly **one tag covering every operation**, no resource classes are emitted at all and every -operation sits **directly on the client**, called `client.{operation}(...)`. The available resource -getters (and any direct operations) come from the contract sheet (grounded in `src/client.ts` and -`src/resources/`) — not from the API's own documentation, and not from the compiled `dist/`. See -**typescript-calling-endpoints**. +Operations hang off resource getters, `client.{resource}.{operation}(...)`, or sit directly on the +client when the SDK has no resource level — take them from the contract sheet, not the API's own +documentation (**typescript-calling-endpoints**). -The options type always carries these five knobs (credential members vary per API — see +The options type always carries these six knobs (credential members vary per API — see **typescript-authentication**): ```ts export type ClientOptions = { - readonly serverEnvironment?: ServerEnvironment; // selects the base URL - readonly serverOptions?: ServerOptions; // per-server, per-environment baseUrl override - readonly retry?: RetryOptions | undefined; // retry policy + per-attempt timeout (MILLISECONDS). - // Retries ON by default - readonly logging?: LoggingOptions | undefined; // request/response logging — OFF by default - readonly fetch?: FetchLike | undefined; // the ONE transport extension point — - // see typescript-configuration-resilience + readonly serverEnvironment?: ServerEnvironment; // selects the base URL + readonly serverOptions?: ServerOptions; // per-server, per-environment baseUrl override + readonly retry?: RetryOptions | undefined; // retry policy + per-attempt timeout (MILLISECONDS). + // Retries ON by default + readonly logging?: LoggingOptions | undefined; // request/response logging — OFF by default + readonly eventStream?: EventStreamOptions | undefined; // event-stream idle timeout (MILLISECONDS) — + // read only by an EventStream operation + readonly fetch?: FetchLike | undefined; // the ONE transport extension point — + // see typescript-configuration-resilience // + one OPTIONAL credential member per auth scheme the API declares, and — for an OAuth2 scheme — // a {scheme}Strategy member alongside it (see typescript-authentication) }; ``` -Those five names are minted by the generator and cannot move; a credential spelled like one of them is -the member that takes a suffix instead. **Every member is `readonly`**, and the client captures your -options once, at construction — a different configuration means a new client. Each default is -applied where the value is read: a server variable takes the `@default` on its member in -`src/client-options.ts`, `fetch` takes its in `src/core/client-options.ts`, every `retry` field -takes its in `src/core/retry.ts`, and every `logging` field its in `src/core/logging.ts`. Read them -there rather than trusting the numbers on this page. -Note in particular that the default `serverEnvironment` is the **first** environment the spec -declares, which is not necessarily the production one. - -**Retries are on by default.** With `retry` left out, a `GET`, `HEAD`, `PUT` or `OPTIONS` call that -gets a `408`, `429`, `500`, `502`, `503` or `504`, or loses its connection, or times out, is re-sent -up to **3** more times with exponential backoff and jitter, honouring `Retry-After`. A `POST`, -`PATCH` or `DELETE` is sent once unless you name its method in `httpMethodsToRetry`. Every one of -those numbers is a `RetryOptions` field you can change, and `retry: { maxRetries: 0 }` turns retrying -off. So **a failed idempotent call surfaces only after its retries are spent** — seconds later than the -first failure, not at it. **typescript-configuration-resilience** owns the policy: the field table, -what is and is not retried, and per-call overrides. - -**`fetch` is not a niche escape hatch — it is the only transport seam there is.** The SDK carries -**no hooks, middleware or interceptors**, **no pagination** and **no streaming**. Each of those is -something you build by wrapping `fetch` — including a header you want on every request. -**typescript-configuration-resilience** carries the wrappers. **Logging is built in and off by -default**: `logging` turns it on, and so does the `{APICLIENTTYPENAME}_LOG` environment variable (the -client class name in upper snake case, plus `_LOG`) when code sets neither a `logger` nor a `level` — so a -deployment can start writing request lines with no code change. `retry.onRetry` is the one built-in -callback, and it sees only retries. A replacement `fetch` is called with one `Request` and no `init`, -and **must forward that `Request`, or its `signal`,** to whatever performs the request; drop the signal -and both cancellation and every attempt's timeout go inert. - -`retry.timeout` has its own trap: it is in **milliseconds**, it bounds **one attempt** — up to -its response headers — not the whole call, and a value the platform cannot honour is **not** "no timeout" — it is -resolved once when the client is built, and a negative, fractional, `NaN`, `Infinity` or out-of-range -value silently falls back to the default (`60_000`) rather than failing. A usable value reaches the -timer verbatim, so `timeout: 0` aborts every attempt instead of lifting the deadline. A single call -may override `maxRetries`, `timeout` and `statusCodesToRetry`, and its log level, through -`RequestOptions` = `{ signal, retry, logging }`; nothing else is per call. +Those six names are fixed in every SDK; a credential named like one of them carries a suffix +instead. **Every member is `readonly`**, and the client captures your options once, at construction — +a different configuration means a new client. Each default is applied where the value is read: a +server variable takes the `@default` on its member in `src/client-options.ts`, `fetch` takes its in +`src/core/client-options.ts`, every `retry` field takes its in `src/core/retry.ts`, every +`logging` field its in `src/core/logging.ts`, and `eventStream.idleTimeout` its in +`src/core/event-stream.ts`. Read them there rather than trusting the numbers on this +page. The default `serverEnvironment` is the **first** `ServerEnvironment` member, which is not +necessarily the production one. + +**Retries are on by default**: an idempotent call (`GET`, `HEAD`, `PUT`, `OPTIONS`) that fails +retryably is re-sent up to 3 more times with backoff, so its failure surfaces seconds late, and +`retry.timeout` (milliseconds) bounds each attempt, not the call; `retry: { maxRetries: 0 }` turns +retrying off. **typescript-configuration-resilience** owns the policy. + +**`fetch` is the only transport extension point.** The SDK has no hooks or middleware, and streams +only a `text/event-stream` response, through an operation that resolves to an `EventStream` +(**typescript-event-streams**) — build anything else by wrapping `fetch` +(**typescript-configuration-resilience**). A replacement must +forward the `Request` it is handed, or its `signal`, or cancellation and timeouts go inert. **Logging is +built in and off by default**, and the `{APICLIENTTYPENAME}_LOG` environment variable (the client class +name in upper snake case, plus `_LOG`) can turn it on with no code change +(**typescript-configuration-resilience**). ## Direct instantiation @@ -148,9 +131,9 @@ accepted and fails later, one layer from its cause: | Passed at construction | When it actually fails | | --- | --- | -| a `retry` field out of range — a negative or fractional `timeout`, a `maxJitter` above `1`, a lower-cased `"get"` in `httpMethodsToRetry` | never — that field silently falls back to its default. `timeout: 0` is the exception: it is kept, and aborts every attempt. There is no `ValueError` equivalent here | +| a `retry` field out of range — a negative or fractional `timeout`, a `maxJitter` above `1`, a lower-cased `"get"` in `httpMethodsToRetry` | never — that field silently falls back to its default. `timeout: 0` is the exception: it is kept, and aborts every attempt | | a `baseUrl` override | first call — as a connection error, or as a `401` against the wrong host | -| wrong credentials | first call — and under OAuth2, first *token* request, so the error names the token endpoint rather than the operation you wrote | +| wrong credentials | first call — under OAuth2 as an `AuthError` from that operation, with the token endpoint's `ApiError` on `.cause` (**typescript-error-handling**) | | a misspelled or extra credential field | never at run time. Credentials are plain objects checked only by TypeScript; nothing re-validates them at construction | | **an omitted** credential | first call, as a `401`. An unset credential configures the client for **no auth** — the operation sends no credential rather than erroring. See **typescript-authentication** | @@ -159,74 +142,36 @@ before constructing. ### Client and fetch lifetime -The SDK does **not** own a connection pool — `fetch` does. On Node the global `fetch` shares one -process-wide dispatcher, so the reason to keep one client is not the socket pool; it is everything the -constructor resolved and cached. - -**Keep the SDK client long-lived — it is not a stateless wrapper.** The only thing you hand it is -configuration; its constructor resolves the rest and then owns it: - -- the **transport** — a `RawClient` built over the resolved `fetch` implementation. If no `fetch` is - reachable, **the constructor throws `ConfigurationError`**, not the first call; -- the **server groups** — `buildServers(options)` runs here and resolves every group **once**: the - environment and each override are read and decoded as the client is built, and every call afterwards - only attaches its own sub-path. So assigning `serverEnvironment` or mutating an override on the - object you passed in does nothing, and a bad value throws from the constructor rather than from a - call. Configure the server before you construct, and construct a new client to change environment. - See **typescript-configuration-resilience**, *What is captured when*; -- the **auth schemes** — validated at construction (a basic-auth username containing `:` throws - `ConfigurationError` from the constructor), and for an OAuth2 SDK the auth scheme *is* the access-token - cache, closed over by the scheme object. - -That last one is the reason a per-request client is a real cost rather than a stylistic one: a fresh -client starts with an empty token cache, so **every construction pays a token request on its first -call**. Three calls through three throwaway clients is three token round-trips where a shared client -makes one — and the shared one also collapses concurrent callers onto a single in-flight token -acquisition, which the throwaway ones cannot. - -Resource getters are memoized per client (`client.{resource}` builds once, behind `??=`, and is -cached), so they are part of the same bargain. Never construct a resource class yourself: they are -exported only for their merged namespaces and for `instanceof`, and their constructors take engine -internals that are not exported. +**Keep the SDK client long-lived.** `fetch` owns the connection pool, but the constructor resolves and +then owns the rest: the `fetch` implementation, every server group (mutating the options object +afterwards does nothing; construct a new client to change environment — +**typescript-configuration-resilience**, *What is captured when*), the memoized resource getters, and +the auth schemes — for an OAuth2 SDK the scheme *is* the access-token cache. A fresh client starts with +an empty token cache, so **every construction pays a token request on its first call**, and +throwaway clients cannot share one in-flight token acquisition the way a shared client does. Construct per request only where you genuinely need different credentials per request — and then expect the token fetch. For rotating a secret without rebuilding, a credential member accepts a **function** instead of a string; see **typescript-authentication**. -**There is nothing to close.** `src/core/` declares no `close()`, no `dispose()`, and no -`Symbol.dispose` / `Symbol.asyncDispose`, so the client holds no releasable resource and needs no -shutdown hook — the connection pool belongs to the runtime's `fetch`, not to you. The flip side is -that there is no drain either: to stop in-flight requests at shutdown you abort them yourself through -each call's `signal`. +**There is nothing to close** — no `close()`, `dispose()` or `Symbol.dispose`, and no shutdown hook to +register. There is no drain either: to stop in-flight requests at shutdown, abort each call's +`signal`. -**The `fetch` implementation is resolved once, in the constructor** (`config.fetch ?? globalThis.fetch`, -then stored). Two consequences that fail silently: - -- **Monkey-patching `globalThis.fetch` after a client exists has no effect on that client.** A test - that swaps the global and reuses a module-level client is still calling the original. Pass the fake - through `ClientOptions.fetch` and build the client after — see **typescript-testing**. -- **A replacement must satisfy `typeof fetch`** — it is called as `fetch(request)`, one `Request` and - no `init`, with `this` set to `undefined`, so a transport method that depends on its receiver must be - bound before you pass it. It must forward that `Request`, or its `signal`, and resolve to a - `Response` the decoder can read `status`, `headers` and a body from. - **typescript-configuration-resilience** owns the wrappers. +**The `fetch` implementation is resolved once, in the constructor** — yours, else `globalThis.fetch`; +with neither, the constructor throws `ConfigurationError`. Patching `globalThis.fetch` after a client +exists does not reach it, so pass a fake through `ClientOptions.fetch` and build the client after it +(**typescript-testing**). A replacement is called as `fetch(request)` — one `Request`, no `init` — with +`this` set to `undefined`, so bind a method before passing it; **typescript-configuration-resilience** +owns the rest of its contract. ## Choosing the server / base URL -**The shape does not vary with the spec.** However many servers or environments the API declares — one -of each, or several of both — you always get a `ServerEnvironment` object and a `serverOptions` bag -keyed by server group; a single-server, single-environment API simply gets a one-member enum and a -one-group bag. There is no arm where the constructor takes a bare `baseUrl` instead. - -Environments are modeled as a `ServerEnvironment` const object plus a matching type alias, with one -member per environment the API defines (e.g. `ServerEnvironment.Production`, or region members). -Unlike model enums it is **closed** — no `| (string & {})` tail — so only declared members type-check. -Select one on `serverEnvironment`. - -Overriding the base URL is nested **per server group AND per environment** — -`serverOptions.{group}.{environment}.baseUrl`, NOT directly on `serverOptions`. Any **templated -server variables** sit at that same level, beside `baseUrl`, one key per variable the URL template -names: +Select an environment with `serverEnvironment: ServerEnvironment.{Environment}` — a **closed** const +object (no `| (string & {})` tail), one member per environment the API defines, even when there is only +one. There is no bare `baseUrl` option: an override is nested **per server group AND per environment** +— `serverOptions.{group}.{environment}.baseUrl` — with any template variables beside `baseUrl`, and it +merges key-wise over that environment's defaults: ```ts const client = new {Api}Client({ @@ -237,16 +182,10 @@ const client = new {Api}Client({ }); ``` -An override is merged key-wise over that environment's defaults, so setting `baseUrl` alone leaves the -template variables in place, and naming one group leaves the other groups alone. **That last part is a -trap when an OAuth token endpoint lives on its own group**: redirecting the `default` group at a mock -does not move the token request, which still reaches the real host. Override every group the run -touches. - -The group keys, the environment members, and the URL each resolves to are all in -`DEFAULT_SERVER_OPTIONS` in `src/servers.ts`, and tabulated under **Servers & auth** in the contract -sheet — **read them there**, because a member's name does not reliably tell you its host. -**typescript-configuration-resilience** owns server and base-URL configuration in full. +The group keys, the environment members, and the URL each resolves to are in `DEFAULT_SERVER_OPTIONS` +in `src/servers.ts` and under **Servers & auth** in the contract sheet — **read them there**, because a +member's name does not reliably tell you its host. **typescript-configuration-resilience** owns server +and base-URL configuration, including an OAuth token endpoint on its own server group. ## Wiring into an application @@ -265,14 +204,11 @@ export const client = new {Api}Client({ }); ``` -⚠ **A module-level client is constructed at import time, and that has a consequence worth planning -for.** It reads `process.env` when the module is first imported — which, with ESM hoisting, can be -*before* your config loader, `dotenv`, or secret fetch has run. The credential then resolves to -`undefined`, and because **an unset credential is not an SDK error** (the operation simply sends no -credential), you do not get a startup failure. You get a `401` from the API on the first call, at -runtime, in whichever code path happens to run first — which reads like an expired token rather than -a load-order bug. Two ways out: load config before anything imports this module, or build the client -in a factory called from your startup path (below). +⚠ **A module-level client reads `process.env` at import time**, which under ESM hoisting can precede +your config loader, `dotenv` or secret fetch. The credential is then `undefined`, which the SDK treats +as no auth: no startup error, just a `401` on the first call, reading like an expired token. Load +config before anything imports this module, or build the client in a factory called from your startup +path (below). ### Building it in a factory @@ -284,27 +220,16 @@ import { {Api}Client, ServerEnvironment } from "{package-name}"; export function build{Api}Client(): {Api}Client { const token = process.env.API_TOKEN; - - // SET THIS. An unset credential is NOT an SDK error — it sends no credential and 401s later. - if (!token) throw new Error("API_TOKEN is not set"); + if (!token) throw new Error("API_TOKEN is not set"); // fail at startup, not as a 401 later return new {Api}Client({ serverEnvironment: ServerEnvironment.{Environment}, - - // SET THIS. Default 60_000 ms. Bounds ONE attempt, and an idempotent call gets up to - // 4 of them. See typescript-configuration-resilience > Retries. - retry: { timeout: 10_000 }, - + retry: { timeout: 10_000 }, // per attempt; default 60_000 ms {scheme}: token, }); } ``` -Both flagged lines are load-bearing and they answer different failures: the credential check turns a -silent `401` into a startup failure, and `retry.timeout` stops a hung provider from holding the caller -open for the full default minute on every attempt — up to four of them on an idempotent call. Setting -only the timeout is the common mistake — it looks like the configuration box is ticked. - Then register the result once, however your framework shares singletons, and inject it: ```ts @@ -335,9 +260,6 @@ what makes the service testable — a test passes a client built over a fake `fe | CLI / script | one at the top, or one per run | the process is short-lived; the cache never pays back | | Browser / edge runtime | wherever your bundle initialises | the package ships `dist/esm` and `dist/commonjs` only — no bundle, no UMD, no CDN artifact — so it goes through a bundler. Deno, Bun, Workers and Vercel Edge need only the globals the map lists, but none is a tested target | -There is no fork-safety hazard to design around the way a pooled-socket SDK has: the client owns no -pool. The cost of building one per worker is the token cache, not a corrupt connection. - ## ESM and CommonJS The package ships both dialects from a single entry, so `require` works with full types. In a @@ -350,11 +272,8 @@ import sdk = require("{package-name}"); const client = new sdk.{Api}Client({ serverEnvironment: sdk.ServerEnvironment.{Environment} }); ``` -⚠ **A process that loads both dialects gets two independent copies of every class**, including every -error class, and `instanceof` across that boundary is `false`. It is a real hazard in a mixed -codebase, and it fails silently — a `catch` arm simply never matches. Pick one dialect per process -where you can; where you cannot, narrow on `err.kind` or `err.payload.kind` instead of `instanceof`. -See **typescript-error-handling**. +⚠ **A process that loads both dialects gets two copies of every class**, so `instanceof` is `false` +across them — pick one dialect per process, or narrow on `err.kind` (**typescript-error-handling**). Two consumer compiler settings change what you type at the construction site. Under `exactOptionalPropertyTypes`, **omit or spread** an absent option rather than assigning `undefined` to @@ -364,26 +283,16 @@ are imported normally. ## Inbound webhooks — what the emitted package does and does not give you -**There is no webhook surface at all** — no webhook tree, no event parser, no signature verifier, on -any generated TypeScript SDK. Nothing under `src/core/` computes any part of an inbound webhook for -you, and no member of `ClientOptions` turns one on. +**There is no webhook surface at all** — no event parser, no signature verifier, and no member of +`ClientOptions` that turns one on. So verifying an inbound webhook is entirely yours to write, against the provider's published scheme: capture the raw body before any JSON parsing, compute the signature yourself, and compare in constant time. The SDK's model types stay useful for *deserializing* an event body once you have verified it — but do not read "the SDK parses this" as "the SDK verified this". See **typescript-models**. -Testing is a different matter and needs no shipped helpers — inject a fake `fetch`; see -**typescript-testing**. - -> **Not settled by the generator's current version.** The transport carries default header, query and -> path-parameter channels that the generated client currently wires as empty arrays — a source comment -> says nothing in the spec reaches them *yet*. If a later version starts populating them, a -> client-wide header option could appear on `ClientOptions`, so read `src/client-options.ts` rather -> than assuming the option list above is complete for your SDK. - ## Next - Configure authentication → **typescript-authentication** - Make your first call → **typescript-calling-endpoints** -- Tune timeouts, retries, logging, base URL → **typescript-configuration-resilience** +- Tune timeouts, retries, logging, base URL, paging → **typescript-configuration-resilience** diff --git a/plugins/slack/skills/typescript/typescript-configuration-resilience/SKILL.md b/plugins/slack/skills/typescript/typescript-configuration-resilience/SKILL.md index 480ee8e7..ca7e3480 100644 --- a/plugins/slack/skills/typescript/typescript-configuration-resilience/SKILL.md +++ b/plugins/slack/skills/typescript/typescript-configuration-resilience/SKILL.md @@ -1,31 +1,20 @@ --- name: typescript-configuration-resilience -description: Client configuration and resilience for an APIMatic-generated TypeScript SDK — the five ClientOptions fields, server/base-URL selection and template variables, the retry policy (on by default — what it retries, what it never does, per-call overrides) and the per-attempt timeout, cancellation, the built-in logging (off by default — levels, redaction, the environment variable), proxies, TLS and connection pooling, and what the SDK does not do for you (pagination, streaming) built on the one `fetch` seam. Load before you construct or tune the client — the field list alone does not reveal that idempotent calls are retried by default and writes are not, that the timeout bounds one attempt rather than the call, that an environment variable turns logging on with no code change, that the default environment is whichever the spec listed first, that `fetch` is handed one `Request` it must forward, that Node's fetch ignores HTTP_PROXY, or that a hand-written page loop is unbounded by default. +description: Load before constructing or tuning an APIMatic-generated TypeScript SDK client — picking a server environment or overriding a base URL, changing the on-by-default retries or `retry.timeout`, adding cancellation or a deadline, turning the built-in logging on or off, making a write safe to retry, paging through results, or wrapping `fetch` for header injection, proxies, TLS or connection pooling. --- # Configuration & resilience for an APIMatic TypeScript SDK -> **One skill, every shape.** This file covers every configuration surface the TypeScript generator -> emits. Which parts YOUR SDK exercises — how many server groups and environments it declares, which -> template variables those carry, whether an operation takes a page or cursor field, whether the API -> offers an idempotency key — are facts of the API definition, not of this skill: take them from -> `sdk-map.md` and `map/operations/{resource}.md` at the package root, and **apply only the guidance -> that matches**. - -> `{...}` is a placeholder for a name you take from your SDK — `{Api}Client` (the one public client -> class, declared in `src/client.ts`), `{resource}`/`{Resource}`, `{operation}`/`{Operation}`, -> `{group}`, `{environment}`, `{variable}`, `{items}`, `{nextCursor}`. Replace each with the concrete -> identifier from the source; none of them is a name the generator emits literally. -> -> `{APICLIENTTYPENAME}_LOG` is the logging environment variable: the client class name in upper snake -> case, plus `_LOG`, so `AcmeClient` reads `ACME_CLIENT_LOG`. The getting-started skill's identity table -> names yours. +> Which server groups, environments, template variables, page/cursor fields and idempotency-key +> fields YOUR SDK has comes from `sdk-map.md` and `map/operations/{resource}.md` at the package root — +> **apply only the guidance that matches**. `{...}` marks a name to take from your SDK; `{Api}Client` +> is the one public client class, in `src/client.ts`. `{APICLIENTTYPENAME}_LOG` is the logging +> environment variable: the client class name in upper snake case, plus `_LOG`, so `AcmeClient` reads +> `ACME_CLIENT_LOG`. The getting-started skill's identity table names yours. Everything configurable is a field on `ClientOptions` (`src/client-options.ts`), passed to the one constructor. There is no `Configuration` class, no builder, and no per-request override beyond `{ signal, retry, logging }`. Server groups, environments and their URL templates live in `src/servers.ts`. -Everything under `src/core/` is vendored static code that is **byte-identical in every generated -TypeScript SDK**, so the engine behaviours below hold without checking your SDK. ## The whole configuration surface @@ -35,6 +24,7 @@ TypeScript SDK**, so the engine behaviours below hold without checking your SDK. | `serverOptions` | `ServerOptions` | `{}` | per-group, per-environment `baseUrl` and template-variable overrides | | `retry` | `RetryOptions` | retries **on** — see *Retries* | the retry policy, and `retry.timeout` (**ms**, `60_000`) bounding each attempt | | `logging` | `LoggingOptions` | **off** — see *Logging* | the built-in request/response logger, its levels and its redaction | +| `eventStream` | `EventStreamOptions` | `idleTimeout` `60_000` (**ms**) | how long an event stream may stay silent; read only by an operation that resolves to an `EventStream` — see **typescript-event-streams** | | `fetch` | `FetchLike` (`typeof fetch`) | global `fetch` | **the one transport extension point** | | `{scheme}` / `{scheme}Strategy` | per scheme | unset | credentials — see **typescript-authentication** | @@ -43,13 +33,10 @@ default environment are per-SDK. ## Not on this SDK -Absent **by design**, not undocumented. This list ships with `src/core/` and is versioned with it: - | You might reach for | Reality | | --- | --- | | hooks, middleware, interceptors, `onRequest`/`onResponse` | none. `fetch` is the one transport extension point; `retry.onRetry` is the one callback, and it sees only retries | -| pagination, `for await`, auto-paging helpers | no operation is paginated and nothing is async-iterable | -| SSE, `text/event-stream` | no event streams. Every decoder reads the body to completion, bar a binary success, which hands its stream over unread | +| SSE request bodies, WebSockets | none. `text/event-stream` is a response media type only — an operation whose success is one resolves to an `EventStream` you iterate with `for await` (**typescript-event-streams**). Every other decoder reads the body to completion, bar a binary success, which hands its stream over unread | | multipart responses, XML bodies | none. Body kinds are empty, JSON, form-urlencoded, text, multipart and binary | | per-request `headers`, `baseUrl`, idempotency key | none. `RequestOptions` is `{ signal, retry, logging }`; `retry` takes only `maxRetries`, `timeout` and `statusCodesToRetry`, and `logging` only `level` | | a circuit breaker, a rate limiter | none. The retry loop honours `Retry-After`, but nothing limits how many calls you start | @@ -60,9 +47,9 @@ those patterns and the traps in them. **What the SDK does own**, so that you do not rebuild it: URL and server resolution, request encoding and schema validation on the way out, auth application and OAuth token caching, response -decoding, the two-family error mapping, the `Idempotency-Key` on every non-GET call, the retry -loop with its per-attempt timeout, and request/response logging with redaction. Connection pooling -belongs to `fetch`, not to the client. +decoding, the two-family error mapping, the `Idempotency-Key` on every non-GET call, fetching and +advancing the pages of a paged operation, the retry loop with its per-attempt timeout, and +request/response logging with redaction. ## The `fetch` seam @@ -71,23 +58,20 @@ type FetchLike = typeof fetch; ``` The SDK calls it with **one argument, the attempt's `Request`, and no `init`**. The method, the -headers (the credential included), the body and the signal are all on that `Request`. One rule, and it -is the one that breaks things when missed: **forward that `Request`, or at least its `signal`**, to -whatever performs the request. Drop the signal and both each attempt's `retry.timeout` and per-call -cancellation go inert — the call neither aborts nor times out, because the transport enforces both -through that signal. A wrapper written against `(input, init)` still type-checks, but `init` is always -`undefined`: whatever it reads from `init` is nothing, and whatever it passes as `init` **replaces** -what the `Request` carries, so `fetch(input, { headers })` drops every header the SDK set. On an abort -a replacement may reject with whatever it likes: the SDK reads the reason off the signal it built the -`Request` with, so a deadline is still a `TimeoutError` the retry loop retries, and a caller abort -still rejects with the caller's own `reason`. +headers (the credential included), the body and the signal are all on that `Request`. **Forward that +`Request`, or at least its `signal`**, to whatever performs the request: drop the signal and both each +attempt's `retry.timeout` and per-call cancellation go inert — the call neither aborts nor times out. A +wrapper written against `(input, init)` still type-checks, but `init` is always `undefined`: whatever it +reads from `init` is nothing, and whatever it passes as `init` **replaces** what the `Request` carries, +so `fetch(input, { headers })` drops every header the SDK set. On an abort a replacement may reject with +whatever it likes: a deadline is still a `TimeoutError` the retry loop retries, and a caller abort still +rejects with the caller's own `reason`. Four facts that decide how you write a wrapper: -- **It sees every request the client makes, including the OAuth token request.** The auth schemes are - built over the same transport as the operations (`buildAuthSchemes(options, servers, rawClient)` in - the constructor), so a wrapper that logs requests logs the token POST — `client_secret` and all. The - built-in logger (*Logging*) masks it; a hand-rolled one does not. Filter by URL where that matters. +- **It sees every request the client makes, including the OAuth token request** — a wrapper that logs + requests logs the token POST, `client_secret` and all, where the built-in logger (*Logging*) masks it. + Filter by URL where that matters. - **It sits under the retry loop, so it sees every attempt.** A call retried three times is four requests through your wrapper, each a fresh `Request` with its own signal, and a wrapper that logs writes four lines. To see one line per logical call, log around the SDK call instead; to see why an @@ -115,8 +99,8 @@ export type ServerOptions = { ``` Each environment's entry exposes what the SDK substitutes into that group's URL: the **`baseUrl` -template** (always present and settable) plus any **template variables** the spec declares for that -server — a region, a subdomain, a port, an API version. Names and counts vary per API and per +template** (always present and settable) plus any **template variables** that server's URL declares +— a region, a subdomain, a port, an API version. Names and counts vary per API and per environment; a group with no variables exposes `baseUrl` alone. Read the real group keys, environment keys, URL templates and variable defaults from `DEFAULT_SERVER_OPTIONS` in `src/servers.ts`, or from the **Base URLs and overrides** table in `sdk-map.md`. @@ -136,7 +120,7 @@ const client = new {Api}Client({ }); ``` -Four things about how this resolves: +How this resolves: - **Overrides merge with the declared defaults per group-and-environment pair, key by key** (`{ ...DEFAULT_SERVER_OPTIONS.{group}.{environment}, ...yours }`). Setting `{variable}` alone keeps @@ -148,25 +132,17 @@ Four things about how this resolves: request time. A placeholder in a `baseUrl` you supply is only substituted if a declared variable of that exact name exists — otherwise it survives into the URL verbatim, and nothing rejects it the way an unfilled path parameter is rejected. -- **An environment value the SDK does not know throws `ConfigurationError` from the constructor** — - every server group is resolved once, as the client is built, so no operation method throws - synchronously. ### ⚠▶▶ Always pass `serverEnvironment` explicitly -`serverEnvironment` has a default, so `new {Api}Client()` compiles and reaches a real host. **That -default is whatever environment the spec listed first** — the first member `ServerEnvironment` -declares in `src/servers.ts`, and the one whose arm every resolver in that file labels `case -undefined:` alongside its own. For many providers the spec lists sandbox first. Nothing announces it. - -A deployment that believes it configured production and did not gets sandbox behaviour with -production credentials, which fails auth in a way that reads like a credentials problem rather than an -environment one. **Pass it in every environment, production included**, so the host a call reaches is -visible where the client is built. +`serverEnvironment` has a default, so `new {Api}Client()` compiles and reaches a real host: the +**first** member of `ServerEnvironment` in `src/servers.ts` — often sandbox. Production credentials +then fail against it as if they were wrong. **Pass it in every environment, production included.** -`ServerEnvironment` is a **closed** union — no `| (string & {})` tail — so a literal typos out at -compile time. A value arriving from configuration does not. Map it explicitly and **fail on an unknown -value** rather than falling through to the default: +`ServerEnvironment` is a **closed** union — no `| (string & {})` tail — so a mistyped literal fails to +compile; a value read from configuration does not. An unknown string throws `ConfigurationError` from +the constructor, but `undefined` silently selects the default — so map configuration values explicitly +and **fail on a miss**: ```ts const ENVIRONMENTS: Record = { @@ -178,20 +154,11 @@ const serverEnvironment = ENVIRONMENTS[process.env.API_ENV ?? ""]; if (!serverEnvironment) throw new Error(`unknown API_ENV: ${process.env.API_ENV}`); ``` -Without the guard, a typo in a deployment variable becomes `undefined`, and an `undefined` -environment is read as *none selected*: every resolver's default arm answers to `case undefined:` -alongside its own label, so the client runs quietly against the default environment instead of the -one you asked for. Nothing throws, and nothing is logged. An unknown *string* is the loud case — the -constructor rejects it with `ConfigurationError` (above) — so it is the value your own -configuration turns into `undefined` that fails silently, which is what the guard is for. - ### What is captured when -`serverEnvironment` and `serverOptions` are both read **once**, as the client is built. The constructor -calls `buildServers(options)`, which resolves every server group — the environment, its `baseUrl` and -each variable, decoded through its schema — into a value that every call afterwards only attaches its -own sub-path to. So mutating the `serverOptions` object you passed in, replacing a whole group -(`serverOptions.{group} = …`), or assigning `serverEnvironment` afterwards has no effect on the client. +`serverEnvironment` and `serverOptions` are resolved **once**, in the constructor — so a bad value +throws there, never from a call, and mutating the `serverOptions` object you passed in, replacing a +whole group (`serverOptions.{group} = …`) or assigning `serverEnvironment` afterwards has no effect. **Configure the server before you construct, and construct a new client to change environment.** ### Redirecting at a mock @@ -212,12 +179,11 @@ For a proxy, see *Proxy or custom agent* below. backing off roughly 1 s, 2 s and 4 s, and honouring `Retry-After`. - A `POST`, `PATCH` or `DELETE` is sent **once**, whatever went wrong. The method gate covers every failure, faults included. -- **A `401` is not in the default status set.** The transport invalidates whatever that operation's - auth scheme had cached, so the *next* call re-acquires; the failing call rejects. You see one `401`, - then recovery. +- **A `401` is not in the default status set**: the failing call rejects, and the *next* call + re-acquires a fetched credential (**typescript-authentication**). -The loop lives in `src/core/retry.ts`, and `src/core/raw-client.ts` runs every call through it. -Configure it with any subset of `RetryOptions` — a field you leave out keeps its default: +Its defaults live in `src/core/retry.ts`. Configure it with any subset of `RetryOptions` — a field you +leave out keeps its default: ```ts new {Api}Client({ retry: { maxRetries: 0 } }); // off: every call is sent exactly once @@ -242,66 +208,39 @@ new {Api}Client({ | `maxJitter` | `0.25` | A **fraction**, `0` to `1`, and additive: a wait lands between its delay and `delay × (1 + maxJitter)`. `0` makes every wait exact | | `onRetry` | none | `(attempt: RetryAttempt) => void`, called before each retry's wait | -`0`, `false` and `[]` are values, never misses. Anything else a field cannot honour — a negative or -fractional `timeout`, a `maxJitter` of `50`, a list carrying a lower-cased `"get"` — **silently falls -back to that field's default**, and the client still constructs. `timeout: 0` is kept: it is a -zero-length deadline that fails every attempt, not "no timeout". +`0`, `false` and `[]` are values, never misses. Anything else a field cannot honour — a negative, +fractional, `NaN`, `Infinity` or above-`2_147_483_647` `timeout`, a `maxJitter` of `50`, a list +carrying a lower-cased `"get"` — **silently falls back to that field's default** (on a call, to the +client's value), and the client still constructs. `timeout: 0` is kept: it is a zero-length deadline +that fails every attempt, not "no timeout" — an unbounded attempt is not expressible. The wait before retry *n* (counting from 0) is `min(Retry-After ?? delay × backoffFactor ** n, 60_000) × (1 + random × maxJitter)`, rounded up. The 60-second ceiling is the engine's, not an option, and jitter sits on top of it, so the longest single wait is 75 s at the defaults. -What the loop does and does not do — read these before you rely on it: +What the loop does: -- **The method gate covers every failure.** A status in the set, a dropped connection, a timeout: each - is retried only for a method in `httpMethodsToRetry`. `PUT` is in the default gate — see *Making a - write safe*. - **`Retry-After` is honoured** in both its delta-seconds and HTTP-date forms, capped at 60 s, with - jitter added on top — never subtracted, so the SDK never wakes before the time the server named. A - malformed value falls back to the curve. -- **A caller abort is never retried.** Aborting your `signal` cuts a backoff wait short and rejects - with the signal's own `reason`. -- **A streaming request body is never retried**, whatever the method, because a stream cannot be - replayed. -- **A failure while obtaining a credential is not retried.** It ends the call — once the token - request's own retries are spent, since it is a `POST` under this same policy and retries only when - `httpMethodsToRetry` names `POST`. -- **A rejection from your `fetch` that is not an SDK error counts as a dropped connection.** It - becomes a `ConnectionError` and is retried — including a refusal your own wrapper throws on purpose - (see *The `fetch` seam*). The exception is one that arrives after the attempt's timeout or your - signal fired: the SDK reads the reason off the signal it built, so a caller abort rejects as itself - and is not retried, and a timeout becomes a `TimeoutError` and is retried like any other. What the - replacement rejected with does not change either. -- **A retried-away response is released** — its body's cancel started, not awaited, before the wait, - so a cancel that stalls never holds up the retry — and only its headers reach `onRetry`. When the last attempt fails, the call rejects with **that** attempt's failure: an - `ApiError` (or the operation's subclass) for a status, a `ConnectionError` or `TimeoutError` for a - fault — the same shapes as with retrying off (**typescript-error-handling**). `.asApiResult()` sees - the last response. - -**Do the arithmetic before you accept the defaults.** `retry.timeout` bounds each attempt, not the call, -so an idempotent call's worst case is `(maxRetries + 1) × timeout` plus the waits — four minutes at the -defaults. Nothing in the SDK imposes a wall-clock ceiling on the call; *Bounding a call* below is how -you impose one. + jitter added on top, so the SDK never wakes before the time the server named. A malformed value + falls back to the curve. +- **Never retried:** a caller abort (which also cuts a backoff wait short), a streaming request body + whatever the method, and a failure to obtain a credential — the token request is itself a `POST` + under this policy (**typescript-authentication**). +- **A rejection from your `fetch` that is not an SDK error counts as a dropped connection** — see + *The `fetch` seam*. +- **The call rejects with the last attempt's failure** — an `ApiError` (or the operation's subclass) + for a status, a `ConnectionError` or `TimeoutError` for a fault — the same shapes as with retrying + off (**typescript-error-handling**). Only a retried-away response's headers reach `onRetry`, and + `.asApiResult()` sees the last response. ### Per-call overrides -Three fields can be overridden on one call through `RequestOptions.retry`, typed `RequestRetryOptions`. -Each is merged field by field over the client's policy, so a field you omit keeps the client's value: - -```ts -await client.{resource}.{operation}(request, { retry: { maxRetries: 0 } }); // this call: one attempt -await client.{resource}.{operation}(request, { retry: { timeout: 5_000 } }); // this call: 5 s per attempt -await client.{resource}.{operation}(request, { retry: { statusCodesToRetry: [503] } }); // this call: a narrower set -``` - -The type admits only these three. How many attempts *this* call gets, how long each may take, and which -statuses are worth a second try vary by call site; the backoff curve, the method gate and `onRetry` are -how the client paces itself against one server, so they are set on the client alone. A per-call -`httpMethodsToRetry` would be a second route to retrying a write. The restriction is the type's -alone: an object carrying another `RetryOptions` field — from JavaScript, or through a constant typed -as the wider record — still has it honoured, so do not rely on the type to keep a write out of the -gate for one call. +`RequestOptions.retry` (`RequestRetryOptions`) takes only `maxRetries`, `timeout` and +`statusCodesToRetry`, each merged over the client's value for that one call (syntax: +**typescript-calling-endpoints**). Backoff, the method gate and `onRetry` are client-only — but only by +type: an object carrying another `RetryOptions` field (from JavaScript, or a constant typed as the +wider record) still has it honoured, so do not rely on the type to keep a write out of the gate. ### Observing retries @@ -337,11 +276,8 @@ Rules to hold to: job that re-runs on failure — on top of the SDK's without turning the SDK's off for that path. Attempts multiply (four inside four is sixteen round-trips, and up to sixteen times the timeout), and every attempt of a caller-level layer is a new SDK call that mints a **new** `Idempotency-Key`. -- **Never retry an `EncodeError`, a `DecodeError`, an `AuthError` or a 4xx other than `408`/`429`.** On - an `EncodeError` nothing was sent at all — the fix is in your code. A `DecodeError` means the - response was malformed, which a resend rarely cures. An `AuthError` means a credential could not be - *obtained*, which is configuration, not weather. The loop retries none of them, and neither should - you. See **typescript-error-handling**. +- **Never retry an `EncodeError`, a `DecodeError`, an `AuthError` or a 4xx other than `408`/`429`** — + the loop retries none of them, and what each means is in **typescript-error-handling**. When a decision genuinely needs something the policy cannot express — a retry that depends on the decoded error payload, or on which operation it is — turn the SDK's loop off for that call and own @@ -369,15 +305,13 @@ function isTransient(err: unknown): boolean { await withRetry(() => client.{resource}.{operation}(request, { retry: { maxRetries: 0 } })); ``` -`{Api}Error` is the whole error family, narrowed on its closed `kind`. The runtime declares it as `CoreError`, and the -package exports it **only** under the SDK-branded alias — read the real name off the -`CoreError as …Error` line in `src/index.ts`. See **typescript-error-handling**. +`{Api}Error` is the whole error family, narrowed on its closed `kind`; its real name is in +**typescript-error-handling**. ### Making a write safe under retries -**Start from what you have.** With the default gate a `POST`, `PATCH` or `DELETE` is sent once. The -exposure arrives when you widen `httpMethodsToRetry` or add a retry layer of your own, and with two -things no setting fixes: +A write is exposed to a resend only when you widen `httpMethodsToRetry` or add a retry layer of your +own — and through two things no setting fixes: - **`PUT` is in the default gate — idempotent by HTTP's definition, not necessarily by your provider's.** A `PUT` can still carry a per-call side effect — an audit row, an outbound webhook, a @@ -445,17 +379,15 @@ read the numbering as a recommendation order: Three details decide whether it works: - - **A `fetch` wrapper sees every attempt of the SDK's loop by construction**, because the loop sits - above `fetch`. But its refusal reaches the loop as a `ConnectionError`, which **is retried** for a - method in the gate — each retry is refused again, and the call rejects only after the backoff, - with your error on `.cause`. Pair the guard with option 3 on the guarded write, so the refusal is - immediate, and recognise it with `err.cause instanceof YourRefusal`. + - **A `fetch` wrapper sees every attempt of the SDK's loop**, and its refusal is retried as a + `ConnectionError` (*The `fetch` seam*). Pair the guard with option 3 on the guarded write, so the + refusal is immediate, and recognise it with `err.cause instanceof YourRefusal`. - **Keep the "already sent" marker in state that outlives one attempt** — an `AsyncLocalStorage` scope the caller opens around the write, or a closure created per unit of work. A marker hung off `init` is per-attempt bookkeeping only, and a caller-level retry (a job re-running after a timeout) creates a fresh one either way. - - **Key it on method and URL.** The guard also sees the OAuth token request, and a token - acquisition must not be counted as the write. + - **Key it on method and URL**, so the OAuth token request it also sees is not counted as the + write. Count the send **before** it goes out. A request that failed on the way out may still have been received, so "this may already have taken effect" is the only safe reading — surface it as an @@ -483,42 +415,18 @@ permanent refusal. Clear it once the outcome is settled, and expire it when it n ### `retry.timeout` -In **milliseconds**, bounding **one attempt** — enforced with an `AbortController` inside the -transport, surfacing as a `TimeoutError` (`err.kind === "timeout"`) once no retry is left. Each attempt -gets its own deadline. What the field list does not tell you: - -- **It stops at the response headers.** The timer starts once the credential is in hand, so obtaining - a credential and reading the body are bounded only by your `signal`. A built-in OAuth token request - runs on its own timer. -- **A value the platform cannot honour is not "no timeout".** Negative, fractional, `NaN`, `Infinity` - and anything above `2_147_483_647` ms — the largest value a timer can hold — all fall back to the - SDK's default (on a call, to the client's value), silently, and the client still constructs. A usable - value is installed **verbatim**, `0` included, so `timeout: 0` is a zero-length deadline that fails - every attempt rather than lifting it. An unbounded attempt is not expressible. -- **One call can take its own.** `{ retry: { timeout: 5_000 } }` on the call replaces the client's - value for that call — still per attempt. For a budget on the whole call, use a signal. -- **A `fetch` replacement that does not forward the `Request`'s `signal` makes it inert.** Pass the - `Request` on, or copy it with `new Request(request)`, which keeps the signal. +In **milliseconds**, bounding **one attempt**, each with its own deadline; the last attempt's expiry +rejects as a `TimeoutError` (`err.kind === "timeout"`). It starts once the credential is in hand and +stops at the response headers, so obtaining a credential and reading the body are bounded only by your +`signal` (a built-in OAuth token request runs on its own timer). A per-call value replaces the +client's for that call, still per attempt. A value a timer cannot hold silently falls back to the +default, and `0` fails every attempt (*Retries*). ### Cancellation and real deadlines -`RequestOptions` is `{ signal?: AbortSignal; retry?: RequestRetryOptions; logging?: RequestLoggingOptions }`, -and `signal` is the whole per-call cancellation surface. - -```ts -const controller = new AbortController(); -const t = setTimeout(() => controller.abort(new Error("deadline exceeded")), 2_000); -try { - await client.{resource}.{operation}({ /* ... */ }, { signal: controller.signal }); -} finally { - clearTimeout(t); -} -``` - -A caller abort rejects with whatever you passed to `abort()` — the signal's own `reason`, unwrapped and -outside the `{Api}Error` family — so pass something diagnostic, and rethrow it from a family `catch`. -An already-aborted signal rejects immediately, and an abort during a backoff wait ends the wait and the -call; an abort is never retried. +Per-call cancellation is `RequestOptions.signal` (**typescript-calling-endpoints**). An abort rejects +with the signal's own `reason`, outside the `{Api}Error` family (**typescript-error-handling**) — so +pass something diagnostic, and rethrow it from a family `catch`. For a **deadline across a whole call or unit of work** — one call and its retries, or several calls — `AbortSignal.timeout` and `AbortSignal.any` compose (both on Node 20+): @@ -533,15 +441,10 @@ async function withDeadline(work: (signal: AbortSignal) => Promise, ms: nu That is how you give one operation a ceiling that `retry.timeout` cannot: the deadline covers every attempt and every wait, and the earlier of the two wins. -⚠▶▶ **A per-attempt timeout does not bound a request.** If one handler makes more than one SDK call — -a loop over records, a fan-out, a create-then-confirm pair — the per-call timeouts **add up**, and they -add up *faster* when each failure is caught so the work can continue: every swallowed timeout costs its -full bound and the next call still runs — and an idempotent call spends up to `maxRetries + 1` of -them before it fails. **The check is arithmetic, not judgement:** `calls in this handler × -(maxRetries + 1) × timeout`, plus the waits, must sit under the budget you are willing to make a caller -wait. Count the calls in -the loop, not the calls in the snippet — a handler that processes every record on file makes as many -calls as there are records. +⚠ **Several calls in one handler add up** — a loop over records, a fan-out, a create-then-confirm +pair — and a swallowed timeout still costs its full bound before the next call runs: `calls × +(maxRetries + 1) × timeout`, plus the waits, must fit the budget you make a caller wait. Count the +calls in the loop, not in the snippet, and bound the handler with one signal. **Give the total bound one home, not one per call site.** A controller written out at each call is the layer that gets skipped, so any operation added later silently has no ceiling. Put it at the one @@ -569,111 +472,136 @@ too. > (Chrome 98, Firefox 97, Safari 15.4). The SDK's own module-load floor is lower, so between the two > the engine still aborts the request but **produces no typed error at all**. -## Pagination — drive it yourself +## Pagination -Nothing is paginated and nothing is async-iterable. When an operation returns a page, advance its page -or cursor field in a loop and stop on the API's own end signal: +An operation the API pages returns **`Pageable<{PageResponse}, {Item}, E>`** in place of `ApiPromise`, +and its **Returns** bullet on the map names the strategy and the condition that ends its walk. The +walk is **lazy**: calling the operation sends nothing, the first page goes out when a loop starts, and +each new loop starts again from the first page. `Pageable` implements `AsyncIterable<`**`{Item}`**`>`, so a plain `for await` walks +**individual items** across every page; `.pages()` walks the decoded pages instead. The SDK fetches each +page and advances the paging state for you — one of four strategies (offset, page-number, cursor or +`Link`), chosen per operation. ```ts -// Offset/page style: -const PER_PAGE = 100; -for (let page = 1; ; page++) { - const result = await client.{resource}.{operation}({ page, perPage: PER_PAGE }); - for (const item of result.{items}) process(item); - if (result.{items}.length < PER_PAGE) break; // short page — usually the last +// The paging fields on the request (page/limit, offset/limit, or cursor) seed the FIRST page, +// with their declared defaults applied; the SDK advances the page, offset or cursor and stops when +// the API signals the end. +for await (const item of client.{resource}.{operation}({ /* limit: 100, ... */ }, { signal })) { + process(item); +} + +// Pages, not items — also where any total, cursor or link metadata on the page response lives: +for await (const page of client.{resource}.{operation}({ /* ... */ }).pages()) { + for (const item of page.{items}) process(item); } +``` + +Every page is its own request: `options` — the `signal`, the per-call `retry` and `logging` — applies to each one, +and each one goes through the retry policy on its own. Where the walk stops is the strategy's rule: + +| Strategy | Advances by | Stops when | +| --- | --- | --- | +| offset | the item count of each page | the next offset reaches the total, a page is empty, `hasMore` is `false`, or — when the page carries neither a total nor `hasMore` — a page is shorter than the limit | +| page-number | one page | the page number reaches the total pages, `hasMore` is `false`, or — when the page carries no `hasMore` — a page is empty, or is shorter than the limit with no total | +| cursor | the next cursor the response carries | the response carries no next cursor, the cursor did not change, or `hasMore` is `false` | +| `Link` | the next link the response carries, resolved against the page's own URL | the response carries no next link, or the link did not change | -// Cursor style: -let cursor: string | undefined; -do { - const result = await client.{resource}.{operation}({ ...(cursor ? { cursor } : {}) }); - for (const item of result.{items}) process(item); - cursor = result.{nextCursor}; -} while (cursor); +Two consequences of the `Link` strategy worth knowing: after the first page the request's own query +is dropped, because the link the API sent carries it; and a link is followed only to the **same origin** +as the API — another origin, or a link that is not a URL, raises `PaginationError` between pages rather +than sending a credential elsewhere (see **typescript-error-handling**). + +**A failed page throws mid-walk** — `E` for an error status, and every other failure exactly as an +awaited call would reject with it: a `{Api}Error` member, or a caller abort's own `reason`. The pages already delivered stay delivered. For the +form that turns an error status into a value, call `.asApiResult()` **on the walk**: + +```ts +for await (const result of client.{resource}.{operation}({ /* ... */ }).asApiResult().pages()) { + if (result.ok) { + // result.value is the page; result.status and result.headers are its own + } else { + // result.status, result.message, result.payload — and this is the LAST element the walk yields + } +} ``` -Read the actual page/cursor field names off the operation's **Fields** table and its response model — -they are spec-specific, and the SDK sends a defaulted `page`/`perPage` whether or not you set it. Prefer -the API's explicit end signal (a null next-cursor, a `hasMore` flag) over inferring from a short page -where one exists. +Its item loop (`for await (const item of walk.asApiResult())`) ends silently at an error status and +contributes no items for it, so an item loop that ends cannot tell the last page from a failed one — +use `.pages()` when the distinction matters. Everything else still throws from either form, as it +would from an awaited call. -### ⚠⚠ Never leave a page loop unbounded +### ⚠⚠ Never leave a page walk unbounded -**Both loops above are wrong as written**, and the reason is the same one that makes hand-driven paging -riskier than the auto-paging this SDK does not have: *the only stop condition is the provider's -cooperation*. A provider that keeps returning a next cursor, a cursor that fails to advance, a filter -the provider quietly ignores, or a `perPage` it silently caps below what you asked for will each spin -forever. The failure does not look like a slow request. It looks like a request that **never returns**, -with tens of thousands of provider calls billed behind it and no error the provider can be blamed for. +**"The SDK stops when the API signals the end" describes the happy path, not a guarantee.** The walk +ends only when the provider stops handing out a next page. A provider that keeps returning a next +link, or a filter it quietly ignores, will spin until something else kills the request. The cursor +and `Link` strategies stop on a cursor or link that did not change; nothing stops one that keeps +changing. The failure does not look like a slow request. It looks like a request that **never +returns**, with tens of thousands of provider calls billed behind it and no error the provider can be +blamed for. -**Every page loop needs at least one bound that does not depend on the provider.** Pick what matches +**A `limit` the provider silently caps below what you asked for fails the other way.** When a page +carries neither a total nor `hasMore`, an offset or page-number walk takes a page shorter than the +limit as the last one, so it stops after the first page and drops the rest without an error. Ask for +no more than the provider's documented maximum page size. + +**Every page walk needs at least one bound that does not depend on the provider.** Pick what matches the use case; a page cap is the cheapest and is never wrong: | Bound | Use when | Shape | | --- | --- | --- | -| **page cap** | always — the backstop | `if (++pages >= MAX_PAGES) break;` | +| **page cap** | always — the backstop | `if (++pages >= MAX_PAGES) break;` in a `.pages()` loop | | **item cap** | the caller wants "the first N" | `if (out.length >= max) break;` | -| **deadline** | the loop sits behind a request timeout | one `AbortSignal.timeout` passed to every call | -| **no-progress guard** | cursor or offset paging | stop if the cursor did not change between pages | +| **deadline** | the walk sits behind a request timeout | one `AbortSignal.timeout` passed as `options.signal` — it bounds the whole walk, not one page | ```ts const MAX_PAGES = 100; const signal = AbortSignal.timeout(30_000); // bounds the whole walk, not one page -let cursor: string | undefined; -let seen: string | undefined; - -for (let pages = 0; pages < MAX_PAGES; pages++) { - const result = await client.{resource}.{operation}({ ...(cursor ? { cursor } : {}) }, { signal }); - for (const item of result.{items}) process(item); +let pages = 0; - cursor = result.{nextCursor}; - if (!cursor) return; // the provider's end signal — the happy path - if (cursor === seen) throw new Error("cursor did not advance"); - seen = cursor; +for await (const page of client.{resource}.{operation}({ /* ... */ }, { signal }).pages()) { + for (const item of page.{items}) process(item); + if (++pages >= MAX_PAGES) break; // then surface the truncation — see below } -throw new Error(`stopped after ${MAX_PAGES} pages`); // truncating silently is its own defect ``` Prefer to **narrow the query before you page it** — a provider-side date range, status filter, or a -`perPage` matching what the caller needs turns "walk everything" into a handful of pages. And **a bound +`limit` matching what the caller needs turns "walk everything" into a handful of pages. And **a bound that silently truncates is a different defect from one that hangs**: when you hit the cap, surface it or log it; never return a partial set that reads like a complete one. -Wrapping a bounded loop in an async generator gives you the `for await` the SDK does not: - -```ts -async function* all{Items}(signal?: AbortSignal): AsyncGenerator<{Item}> { - let cursor: string | undefined; - for (let pages = 0; pages < MAX_PAGES; pages++) { - const result = await client.{resource}.{operation}({ ...(cursor ? { cursor } : {}) }, { signal }); - yield* result.{items}; - cursor = result.{nextCursor}; - if (!cursor) return; - } - throw new Error(`stopped after ${MAX_PAGES} pages`); -} -``` - -A failed page rejects mid-enumeration like any other call — see **typescript-error-handling**. - -## Event streams — not carried - -There is no SSE support. When the spec declares a `text/event-stream` success response, the generator -**still emits the operation** but gives it the **empty-body decoder**, because the vendored runtime -has no carrier for it. A **binary** success is different and is carried: it resolves to a -`BinaryContent` whose `stream` you read once or release — see **typescript-calling-endpoints**. - -The consequence of the empty decoder is specific and worth knowing before you debug it: it asserts -the body is empty, so such an operation **fails at the call** with `DecodeError` ("Expected an empty -response body") the moment the server sends anything — rather than quietly resolving something the -spec never described. The operation's **Returns** bullet reads `undefined` for these. - -Outbound, only an XML request body has no carrier, so such an operation is emitted with no body field -at all. Multipart and binary bodies are both sent. See **typescript-calling-endpoints**. - -**If you need one of these endpoints, call it with `fetch` directly** — build the URL from the same -base URL, and copy the credential header the SDK would have sent. The SDK cannot carry it, and no -option makes it. +> An operation whose **Signature** returns `ApiPromise` is a plain list call, however list-like its +> response. To page one of those, advance its own page or cursor field in a loop and stop on the API's +> end signal — read the field names off its **Fields** table and its response model — and carry the same +> bound: "fewer than `limit`" and "no next cursor" are both provider-supplied stop conditions, and +> neither is a bound. +> +> ```ts +> let cursor: string | undefined; +> let seen: string | undefined; +> for (let pages = 0; pages < MAX_PAGES; pages++) { +> const result = await client.{resource}.{operation}({ ...(cursor ? { cursor } : {}) }, { signal }); +> for (const item of result.{items}) process(item); +> cursor = result.{nextCursor}; +> if (!cursor) return; // the provider's end signal — the happy path +> if (cursor === seen) throw new Error("cursor did not advance"); +> seen = cursor; +> } +> throw new Error(`stopped after ${MAX_PAGES} pages`); +> ``` + +## Event streams and XML bodies + +An operation with a `text/event-stream` success response **is** carried: its **Returns** bullet reads +`EventStream`, the call resolves at the response headers, and you iterate the stream with +`for await` — load **typescript-event-streams** before you write the loop. Its one setting is +`eventStream.idleTimeout` on the client, which bounds the silence between events; `retry.timeout` +stops at the headers and never reaches the loop. + +Outbound, an operation with an XML request body has no body field. Call it with `fetch` directly — +the same base URL, and the credential header the SDK would have sent; no option makes the SDK carry +it. A **binary** success, and multipart and binary request bodies, **are** carried — see +**typescript-calling-endpoints**. ## Logging @@ -751,14 +679,14 @@ header — `authorization`, `cookie` and every api-key header are not on that li logged as it is. `redactedKeys` and `loggableContentTypes` **replace** their default rather than add to it, so spread `defaultLoggingOptions` to extend one, as above. -⚠▶▶ **`logRequestBody: true` does not redact a JSON body**, and only half-redacts a form body. A JSON -body is logged **verbatim** — truncated at `bodySizeLimit` bytes (32 KB), and only when its media type -is in `loggableContentTypes` (`application/json`, `application/x-www-form-urlencoded`). A form body gets -key masking, but by **deny-list**, not by the allow-list the URL uses: only keys in `redactedKeys` are -masked, so `card_number` in a form body prints in the clear although the same key in a query string -would not. Any other media type is not logged unless you add it to `loggableContentTypes`. On any -endpoint that carries card data, bank details, personal data or a credential in the body, switching -this on writes that data to your logs. Leave it off in production; turn it on for one endpoint at a time +⚠▶▶ **`logRequestBody: true` does not redact a JSON body**, and only half-redacts a form body. A body +is logged only when its media type is in `loggableContentTypes` (`application/json`, +`application/x-www-form-urlencoded`; add others there), truncated at `bodySizeLimit` bytes (32 KB). A +JSON body is logged **verbatim**. A form body gets key masking, but by **deny-list**, not by the +allow-list the URL uses: only keys in `redactedKeys` are masked, so `card_number` in a form body prints +in the clear although the same key in a query string would not. On any endpoint that carries card data, +bank details, personal data or a credential in the body, switching this on writes that data to your +logs. Leave it off in production; turn it on for one endpoint at a time behind a flag you can prove is off. ⚠▶▶ **An environment variable turns logging on without a code change.** When code sets neither a @@ -800,11 +728,9 @@ logging on at `info` for the first execution of any new call — `{APICLIENTTYPE 1. The **verb** matches the operation's **Wire** bullet in `map/operations/{resource}.md`. 2. The **base URL** is fully expanded — no leftover `{region}`-style server variable, which means a `baseUrl` you supplied carries a placeholder no declared variable fills. -3. The **path** is fully formed. Two different failures live here: a path field set to `null` collapses - to **nothing**, leaving a doubled slash (`/orders//confirm`); a path field left `undefined` is - rejected by its schema before anything is sent, as an `EncodeError` whose `uri` still shows the - unfilled marker. The first is silent, so it is the one to look - for. +3. The **path** is fully formed: a path field set to `null` collapses to **nothing**, silently, + leaving a doubled slash (`/orders//confirm`). (One left `undefined` rejects with `EncodeError` + before anything is sent.) 4. Each **path segment** holds the value you meant — for an enum that is the **wire value**, not the member name. 5. The **query parameters** you set are present, spelled as their `Wire` names. A `null` or `undefined` @@ -830,28 +756,22 @@ const client = new {Api}Client({ Set the header on a copy of the `Request` — the SDK has already put the content type and the credential on it, and the copy keeps them, the body and the signal. Passing `{ headers }` as `init` -instead **replaces** every header the SDK set, the credential included. This is also the only -client-wide header mechanism: the -transport carries default header, query and path-parameter channels, but the generated client currently -wires all three as empty arrays. If a later generator version starts populating them, a header option -could appear on `ClientOptions` — read `src/client-options.ts` rather than assuming the field list is -frozen. +instead **replaces** every header the SDK set, the credential included. This is the only client-wide +header mechanism: `ClientOptions` has no header option. ### Rate limiting -There is no built-in limiter. The default policy retries a `429` on an idempotent call and honours -its `Retry-After` (capped at 60 s), which absorbs an occasional limit; it does nothing to stop you -starting more calls than the provider allows. Put a concurrency/rate limiter around your calls for -that. Client-side limiting is the more predictable of the two under load — retrying into a rate limit +There is no built-in limiter. The default `429` retry absorbs an occasional limit but does nothing to +stop you starting more calls than the provider allows. Put a concurrency/rate limiter around your +calls for that. Client-side limiting is the more predictable of the two under load — retrying into a rate limit converts a fast failure into a slow one, and a fan-out of retrying calls keeps the pressure on. ### Circuit breaking Count consecutive `ConnectionError`s, `TimeoutError`s and 5xx `ApiError`s, open the circuit for a -cool-off window, and fail fast while it is open. **Put the breaker around the SDK call, not in `fetch`.** -A plain `Error` thrown from a `fetch` wrapper reaches the loop as a `ConnectionError`, which is retried -with backoff — the opposite of failing fast. Around the call, the breaker sees one outcome per call, -after the retries, and its refusal never enters the loop. +cool-off window, and fail fast while it is open. **Put the breaker around the SDK call, not in `fetch`**, +where its refusal would be retried as a `ConnectionError` (*The `fetch` seam*). Around the call, the +breaker sees one outcome per call, after the retries, and its refusal never enters the loop. ## Proxies and TLS (Node) @@ -914,8 +834,7 @@ nothing extra. Two consequences: - **A dispatcher you create is a pool you own.** Build it once, beside the client, and reuse it. A `new Agent(...)` or `new ProxyAgent(...)` per request opens a fresh pool — and therefore fresh TCP - and TLS handshakes — on every call, which is the same waste as a client per request without looking - like one. + and TLS handshakes — on every call. - **Pool limits live there too** — `connections`, `keepAliveTimeout`, `pipelining` on the `Agent`. Raise `connections` before assuming a provider is slow under a fan-out; the default cap can be the actual bottleneck. @@ -932,21 +851,19 @@ client costs under OAuth — is **typescript-client-initialization**. | request lines in the logs with no logging code | `{APICLIENTTYPENAME}_LOG` is set in that environment — set `logging.level` in code to own it | | a JSON body or a card number in the logs | `logRequestBody`, or a per-call `level`, which turns the body on — see *Logging* | | a failing call takes seconds longer to reject than the first failure | expected on an idempotent call: the default policy retried it — watch it with `retry.onRetry` | -| a `POST` fails on a `503` that a `GET` survives | expected: `POST` is outside the default `httpMethodsToRetry` | -| one handler takes far longer than `retry.timeout` | it is per attempt, and an idempotent call gets up to four — count the calls, then bound the handler with a signal | -| a page loop never returns | no provider-independent bound — see *Never leave a page loop unbounded* | +| a page walk never ends | no provider-independent bound — see *Never leave a page walk unbounded* | +| `PaginationError` naming another origin | the API's next link points off the API's host, and the SDK refuses to follow it — see *Pagination* | | requests still hit the real host under test | the wrong server **group** or **environment** overridden — check `src/servers.ts` | -| auth fails everywhere with credentials you know are right | `serverEnvironment` left to its default, which is the spec's **first** environment — often sandbox | +| auth fails everywhere with credentials you know are right | `serverEnvironment` left to its default, the **first** `ServerEnvironment` member — often sandbox | | the call works locally, fails behind a corporate proxy | Node's `fetch` ignores `HTTP_PROXY` — register `EnvHttpProxyAgent` or pass a `dispatcher` | -| a duplicate write despite an idempotency key | the key is generated inside the retried function — hoist it out; or your own retry layer re-calls the SDK, which mints a new injected key per call | +| a duplicate write despite an idempotency key | the key is generated inside the retried function — hoist it out; or your own retry layer re-calls the SDK, which sends a new `Idempotency-Key` per call | | ~16× the expected round-trips | a retry layer of your own stacked on the SDK's — set `retry: { maxRetries: 0 }` where you own retrying | | a test with one stubbed `503` hangs, or runs out of queued responses | the default policy fetched it four times across ~7 s of backoff — see **typescript-testing** | | a `{placeholder}` survives into the URL | a `baseUrl` you supplied names a variable the group does not declare | | `EncodeError` whose `uri` still shows a `{placeholder}` | a path field was `undefined` — a required field was omitted | | `ConfigurationError` about an unknown environment, thrown by the constructor | `serverEnvironment` is not a declared member | -| `DecodeError` "Expected an empty response body" | an event-stream response with no carrier — call it with `fetch` directly | +| an event-stream loop rejects with `TimeoutError` while the server is still connected | the server stayed silent past `eventStream.idleTimeout` — raise it, or set it to `null` and bound the wait with a `signal` (**typescript-event-streams**) | | a token is fetched on every call | a client built per request — see **typescript-client-initialization** | -| 401 on the first call, fine afterwards | expected: a 401 invalidates the token cache and is not in the default retry set | ## Next diff --git a/plugins/slack/skills/typescript/typescript-error-handling/SKILL.md b/plugins/slack/skills/typescript/typescript-error-handling/SKILL.md index db15dba1..32462fab 100644 --- a/plugins/slack/skills/typescript/typescript-error-handling/SKILL.md +++ b/plugins/slack/skills/typescript/typescript-error-handling/SKILL.md @@ -1,22 +1,17 @@ --- name: typescript-error-handling -description: Error handling for an APIMatic-generated TypeScript SDK — load before writing any try/catch around an SDK call, an error-translation layer, or middleware. Covers the one error family and its closed err.kind, the four throwables that sit outside it, which types actually reach your catch blocks, reading the status and the declared error body safely, the default arm that degrades instead of throwing, the failures the non-throwing form does not convert, the missing field that is silently undefined rather than an error, and the traps that make an otherwise reasonable catch ladder silently wrong. +description: Load before writing a try/catch around an APIMatic-generated TypeScript SDK call, translating its errors into your own, or reading a status code or error body — the SDK's one error family and its closed `err.kind`, the throwables outside it, per-operation typed error arms and the `"undeclared"` arm, and what `.asApiResult()` still rejects. --- # Error handling for an APIMatic TypeScript SDK -> Throughout this skill, `{...}` is a placeholder for a name you take from your SDK (e.g. `{Api}Client`, -> `{Api}Error`, `{package-name}`, `{Resource}`, `{Operation}`, `{arm}`) — replace it with the concrete -> identifier from the source. -> -> **One skill, every error shape.** This file covers every shape the generator can emit. Which shapes -> YOUR SDK uses — whether an operation declares typed arms or rejects with the base error, what each -> arm is called, which status it covers — are facts of the API definition, not of this skill: take -> them from the operation's page in `map/operations/{resource}.md` and **apply only the guidance that -> matches**. An API can declare typed errors on every operation, on none, or on a mix. +> `{...}` marks a name to take from your SDK (`{Api}Client`, `{Api}Error`, `{package-name}`, +> `{Resource}`, `{Operation}`, `{arm}`). Whether an operation has typed error arms, what they are +> called and which statuses they cover is per operation: read its page in +> `map/operations/{resource}.md` and **apply only the guidance that matches**. Operations are **throw-based** (for a non-throwing alternative, see **The non-throwing form** below), -and every **operational** failure belongs to **one family**: `{Api}Error`, a union over six leaves. +and every **operational** failure belongs to **one family**: `{Api}Error`, a union over seven leaves. One `instanceof {Api}Error` sees all of them, and `err.kind` says which one it is. Four throwables sit **outside** the family — a configuration fault, a codec called directly, a bug, and a caller abort — so a `catch` that tests the family has to rethrow whatever is left. @@ -33,7 +28,7 @@ try { // The API answered with an error status — read err.status and err.payload. break; case "decode": - // The answer did not fit the spec — read err.status and err.cause. + // The answer did not fit its declared type — read err.status and err.cause. break; case "encode": // Nothing was sent — err.cause is the SchemaError that rejected the value. @@ -43,6 +38,9 @@ try { case "auth": // No response was produced — err.kind says which. break; + case "pagination": + // A paged walk could not follow the next link the API sent — the pages before it were delivered. + break; } } else { throw err; // outside the family: an abort's reason, a configuration fault, or a bug @@ -55,28 +53,18 @@ opens with that pair — `"POST https://api.example.com/v1/{resource} failed wit ## What to import, and from where -Everything below comes from **one specifier — the package root**. Deep imports -(`{package-name}/core/…`) do not resolve: the `exports` map exposes `.` and `./package.json` and -nothing else. +Everything below comes from **the package root** — deep imports do not resolve +(**typescript-client-initialization**). | import | what it is | | --- | --- | -| `{Api}Error` | the whole family — a type **and** a value. The type is the union of the six leaves; the value is the abstract class they all extend, so `instanceof` and `err.kind` select the same set. It cannot be constructed or extended. The SDK-branded alias of `CoreError`, which is not exported under its own name | +| `{Api}Error` | the whole family — a type **and** a value. The type is the union of the seven leaves; the value is the abstract class they all extend, so `instanceof` and `err.kind` select the same set. It cannot be constructed or extended. Its real name — usually the API name plus `Error` — is on the `CoreError as …Error` line in `src/index.ts`; `CoreError` itself is not exported | | `ResponseError` | the part of the family the server answered on — `ApiError \| DecodeError`, the two that carry `status` and `headers`. A type and a value, like `{Api}Error` | | `ApiError` | `kind: "api"` — the API answered with an error status. The base every operation without declared error bodies rejects with, and the class every per-operation error extends | | `{Resource}.{Operation}Error` | the generated `ApiError` subclass for an operation that declares error bodies, on the **resource class's merged namespace** — not a free-standing export | -| `DecodeError` `EncodeError` `ConnectionError` `TimeoutError` `AuthError` | the other five leaves | +| `DecodeError` `EncodeError` `ConnectionError` `TimeoutError` `AuthError` `PaginationError` | the other six leaves | | `ConfigurationError` `SchemaError` | outside the family: a constructor fault, and a codec called directly | -| `type ErrorKind` `ErrorPayload` `Declared` `Undeclared` `HttpMethod` | type-only helpers, if you name them in your own signatures | - -`{Api}Error` is the SDK-branded name — **read the real one** from the `CoreError as …Error` line in -`src/index.ts`. It is the API name plus `Error` (`Acme` gives `AcmeError`), escalating to -`{Api}ApiError` and then a numeric suffix when that would collide with something the same clause -already re-exports (an API named `Api` cannot take `ApiError`). - -Everything under `src/core/` is vendored static code, **byte-identical in every generated TypeScript -SDK**, so the behaviours below hold without checking yours. What varies per SDK is which operations -declare arms, and what those arms are called. +| `type ErrorKind` `Declared` `Undeclared` `HttpMethod` | type-only helpers, if you name them in your own signatures | ## The family — every `err.kind` @@ -90,6 +78,7 @@ declare arms, and what those arms are called. | `"connection"` | `ConnectionError` | `fetch` rejected before a response line arrived | — | | `"timeout"` | `TimeoutError` | an attempt ran out its `retry.timeout`, and no retry was left | `timeout` — the budget that ran out | | `"auth"` | `AuthError` | a credential could not be **obtained** | — | +| `"pagination"` | `PaginationError` | a paged walk could not follow the next link the API sent — it was not a URL, or it named another origin | — | Every one carries `kind`, `method`, `uri`, `message` and, where there was an underlying failure, `cause`. `uri` is the absolute URL the call dialled, with the server variables expanded and the path @@ -102,8 +91,7 @@ by its schema arrives as an `EncodeError` whose `uri` still shows the unfilled ` a header or a value that failed its schema. That keeps response bodies and secrets out of logs and stack traces by default, which is a sound default and a trap: a handler that logs `err.message` and nothing else records that something failed and discards every diagnostic. Read `err.payload` (or -`err.cause`) explicitly and log the fields you choose — and on a `4xx` the caller caused, also put the -API's reason in your response. +`err.cause`) explicitly and log the fields you choose. `err.headers` is the `fetch` `Headers` object, not a plain object — look a header up with `err.headers.get("x-request-id")` (case-insensitive). Indexing it (`err.headers["x-request-id"]`) is @@ -111,8 +99,7 @@ always `undefined`, and spreading it gives you nothing. ## Four throwables outside the family -`instanceof {Api}Error` is `false` on each of these, so a `catch` that tests the family and then -stops has swallowed nothing — it just has to **rethrow the rest**, as the ladder at the top does. +`instanceof {Api}Error` is `false` on each of these: - **`ConfigurationError`** comes out of the **client constructor**, synchronously and before any call exists: no reachable `fetch`, a basic-auth username containing a colon (RFC 7617 §2), or an @@ -152,54 +139,35 @@ so a `3xx` lands here too. ### Which error does an operation reject with? -Four places give you the answer, in order of preference: - -1. **`map/operations/{resource}.md`** — the operation's **Error** bullet names the case, and for a - typed operation the **Error arms** bullet lists every arm with the status each covers and whether it - has a body. Start here. -2. **The **Signature** bullet on the same page** — the same fact as the second type argument of the - returned `ApiPromise`. -3. **`api-reference.md`** — per-operation prose, when you need what an arm *means* rather than its - shape. -4. **`src/resources/{resource}.ts`** — the source. The subclass's `static readonly errors` table is - the matcher list itself: one row per arm, each spelling `on` (the status, a `[from, to]` range, or - `"default"`), `kind`, and the decoder. - -All of these ship inside `node_modules/{package-name}/`, so read them there rather than the compiled -`dist/`. - -- **Case A — typed arms.** The spec declared failure bodies, so the generator emitted a subclass named - `{Operation}Error`, exported from the **enclosing class's merged namespace** — you catch - `{Resource}.{Operation}Error`, or `{Api}Client.{Operation}Error` for an operation the spec left - untagged. It redeclares `payload` with the operation's own arms. Narrow on `err.payload.kind`. +Take the case from the operation's **Error** bullet in `map/operations/{resource}.md`: for a typed +operation its **Error arms** bullet lists every arm with the status it covers and whether it has a +body, and the **Signature** bullet shows the same as `E` in `ApiPromise`. `api-reference.md` +says what an arm *means*; the source is `src/resources/{resource}.ts`. All of these ship inside +`node_modules/{package-name}/` — read them there, not in the compiled `dist/`. + +- **Case A — typed arms.** The operation has an `{Operation}Error` subclass of `ApiError` on the + **enclosing class's merged namespace** — catch `{Resource}.{Operation}Error`, or + `{Api}Client.{Operation}Error` for an operation that sits directly on the client. It redeclares + `payload` with the operation's own arms; narrow on `err.payload.kind`. - **Case B — no typed arms.** `E` is the **base `ApiError`**, its payload is always the `"undeclared"` arm, and there is no subclass to catch. -Guessing wrong is *sometimes* a compile error and sometimes not, and the direction that looks safe is -the dangerous one. A subclass that does not exist fails to compile — that guess TypeScript catches. But -naming a **neighbouring** operation's error class compiles cleanly, because it is a real type, and then -never matches at runtime: the rejection sails past your `catch` and surfaces somewhere else, or not at -all. Take the case from the map every time; the compiler is not a check on this. +Take the case and the arms from that operation's own page every time, never a neighbour's: a +neighbouring operation's error class compiles cleanly and never matches at runtime. ### Case A — reading the typed payload -> **This section applies only where the operation declares typed arms.** An operation whose **Error** -> bullet names the base `ApiError` has nothing to narrow — its payload is always `"undeclared"`. -> Skip to **Case B**. - -`err.payload` is a discriminated union with **one arm per failure response the spec declared**, plus -`"undeclared"`. Two things about arm names catch people out: +`err.payload` is a discriminated union: one arm per declared failure response, plus `"undeclared"`. +Arm names come from the body's schema, not the status — a model reference gives the model's name in +lower camel (`validationError`, then `validationError2` for a second status returning the same model), +anything else gives `error{Status}` (`error400`, `error4XX`) — so read them off the map. One arm can +cover many statuses: `4XX` covers `[400, 499]`, so check `err.status` for the exact one. -- **The name comes from the body's schema, not from the status.** An arm whose body is a direct model - reference is named after that model in lower camel (`validationError`); anything else — a - primitive, an array, a map, or no content — is named `error{Status}` (`error400`, `error4XX`, - `errorDefault`). So two statuses that return the *same* model give you two arms whose names differ - only by a numeric suffix (`validationError`, `validationError2`). Read the arm names off the map; - do not derive them from the status. -- **One arm can still cover many statuses** — not because two statuses were merged, but because the - spec declared a *range* or a `default:`. A `4XX` arm covers `[400, 499]`; a `default:` arm covers - **every error status no other arm covers**, `3xx` included. Check `err.status` when you need the - specific one. +**A spec's `default:` response is not an arm.** Every status the other arms miss is `"undeclared"` +with its bytes intact — the `520` a CDN, the `502` a gateway or the `403` a WAF answers on the API's +behalf included, whose HTML page the `default` schema never described. The model the spec named under +`default` is still under `src/models/`; decode `rawBody` through its schema by hand when the status is +one the API itself sent. ```ts import { {Resource} } from "{package-name}"; @@ -225,22 +193,12 @@ try { ``` **`"undeclared"` is always an arm, and it is not a catch-all.** It carries -`{ kind: "undeclared"; rawBody: ArrayBuffer }` and fires **only** for a status no declared arm covers -— or, where the operation declares a `default:` arm, for a body that arm could not decode. A status -that has an arm lands in that arm and leaves `"undeclared"` unreached — so a `catch` that handles only -`"undeclared"` silently drops every typed body. Handle every arm the map lists, and put `"undeclared"` -last. There is no operation whose failure is guaranteed typed: the generator emits the `"undeclared"` -arm unconditionally, so any operation can hand you raw bytes for a status it does not document. - -An arm can declare **no body** (`body: undefined`) — the spec named the status but gave it no schema. -It accepts only an **empty** body: any body on a status it covers (a JSON error message is typical) -rejects with `DecodeError`, even through `.asApiResult()`, and `err.status` still names it (see -**`"decode"`**). On a `"default"` arm that body degrades to `"undeclared"` instead. - -**The arms are per operation, and are not one set across the API.** A description that declares a -different error schema per tag gets a different model — and therefore a differently-named arm — per -tag, so a branch written against one operation's arm does not apply to a sibling's. Take the arms from -that operation's **Error arms** bullet every time; never reuse a set from a neighbouring call. +`{ kind: "undeclared"; rawBody: ArrayBuffer }` and fires **only** for a status no declared arm covers, +so any operation can hand you raw bytes, and a `catch` handling only `"undeclared"` drops every typed +body. Handle every arm the map lists, and put `"undeclared"` last. An arm can declare **no body** +(`body: undefined`); it accepts only an **empty** body — any body on a status it covers (a JSON error +message is typical) rejects with `DecodeError`, even through `.asApiResult()`, and `err.status` still +names it (see **`"decode"`**). Where your boundary treats several arms alike, group them with fall-through cases rather than repeating the body — but only over fields they **all** declare: @@ -286,14 +244,12 @@ with HTML or plain text. Decode it to a string before you try to parse it, and e ### Matcher precedence -For a subclass with several arms, the runtime matches in **three passes**: an exact numeric status -across the whole table first, then the first covering range, and last a `"default"` arm where the -spec declared one. So a specific `404` arm beats a `4XX` arm regardless of declaration order, and a -`default:` arm can never shadow a narrower one. +An exact numeric status wins over a covering range, so a specific `404` arm beats a `4XX` arm +regardless of declaration order. -A body that does not fit the arm it matched is a **`DecodeError`** — except on `"default"`, which -describes no status in particular and so **degrades to the `"undeclared"` arm**, raw bytes and all, -rather than throwing. +A body that does not fit the arm it matched is a **`DecodeError`**. A status no arm covers is the +`"undeclared"` arm, which every subclass ends in; a spec's `default:` response is never a row, so +nothing a middleware answers on the API's behalf can fail a schema the API wrote. ### Catch order @@ -332,7 +288,7 @@ Which status it came on matters a lot, and `err.status` tells you: Mapping both onto one 5xx is wrong half the time — it tells a retrying caller to keep retrying something that can never succeed. Only a **declared** arm can decode-fail: the `"undeclared"` arm reads -raw bytes and never decodes, and a `default:` arm degrades instead of throwing. +raw bytes and never decodes. ```ts if (err instanceof DecodeError) { @@ -353,12 +309,9 @@ let a production ladder quietly absorb it — it should fail loudly in developme **`AuthError` is about obtaining a credential, not about being refused one.** A 401 *from the API* is an `ApiError` like any other status, so one `catch` arm cannot absorb the other. -A 401 does have one auth consequence: it **invalidates whatever that operation's scheme had cached**, -so the **next** call re-acquires. `401` is not in the default `statusCodesToRetry`, so the current -request fails and recovery happens on the following call. To have the current call re-sent with a -fresh token instead, add `401` to `statusCodesToRetry`: every attempt resolves its credential again, so -the retry carries the re-acquired token. A static key is re-sent unchanged, so that only helps a scheme -that fetches its credential. +A 401 from the API also invalidates the scheme's cached credential, so the **next** call re-acquires +(**typescript-authentication**). A single `401` is therefore not a permanent credential failure: do not +tear down the client or alert on one. `AuthError` means the token grant failed, every configured branch of an alternatives requirement failed, PKCE was disabled without a client secret, or your own authorization-code prompt rejected. Its @@ -374,20 +327,26 @@ is still an `AuthError` with the endpoint's `ApiError` on `.cause`, never the ba Otherwise it is an `AuthError` whose `cause` is an `AggregateError` holding what each branch threw, in the order tried. An abort or a timeout escapes immediately rather than being collected. -Auth resolves *before* the request is sent, so an `AuthError` means **nothing was sent** — it is an -auth fault, not a rejection. Check it early in your ladder. +⚠ **An `AuthError` means nothing was sent, and it surfaces from an operation call, not from client +construction.** The token is acquired lazily, before the request exists, so an auth misconfiguration +rejects whichever operation ran first — reading like a problem with that operation — and rejects in +`.asApiResult()` mode too. Check it early in your ladder. -⚠ **The token is acquired lazily, on first use — so an auth misconfiguration surfaces from an -operation call, not from client construction.** The rejection points at whichever operation happened to -run first, which reads like a problem with that operation rather than with the credentials you wired -up. It also rejects in `.asApiResult()` mode, for the same reason: the grant happens before a request -exists to return a result for. +## `"pagination"` — a next link could not be followed + +Raised from inside a paged walk, **between two pages**: the page that carried the link has already been +delivered, and a loop that stops after it never sees this. A `Link` strategy follows a link only when it +resolves, against the URL of the page that carried it, to the same scheme, host and port as the API, so +no credential ever leaves the API. A link to another origin is refused, and so is one that is not a +URL. For a link to another origin, `err.uri` names the call that was refused; for a link that is not a +URL there is no such call, so `err.uri` names the page that carried it and `err.cause` holds the +platform's parse failure. It is a `{Api}Error`, so the ladder at the top already catches it; the +offset, page-number and cursor strategies never raise it. ## A missing field is not an error — it is `undefined` -This is the gap the error types leave, and the one most likely to reach production. A model member the -description did not mark **required** is emitted as `member?: T` over an optional schema entry, so a -response that simply **omits** it validates cleanly. No `DecodeError` is thrown, and nothing warns you: +A model member not marked **required** is `member?: T`, so a response that simply **omits** it +validates cleanly. No `DecodeError` is thrown, and nothing warns you: ```ts const value = await client.{resource}.{operation}({ /* ... */ }); // 200, truncated body @@ -436,20 +395,21 @@ no per-status judgement. Reach for it when an error status is an expected outcom found yet", a `409` meaning "already exists") and you would otherwise be using exceptions for control flow, or when you need `status` and `headers` on the *success* path. -Two mechanics to know: the failure branch is a plain object carrying **the error's own members under -their own names** — `status`, `headers`, `message`, `method`, `uri` and `payload` — never the error -instance, so you narrow on `outcome.payload.kind` exactly as you would on `err.payload.kind`, and a -handler moves between the two forms by swapping the prefix; and `.asApiResult()` must be called on the -value the operation returned, **before any `.then()`**, because `ApiPromise` overrides -`Symbol.species` and the method is gone from what `.then()` hands back (see -**typescript-calling-endpoints**). - -⚠ **This mode is not rejection-free, and the cases it does not convert are the ones people assume it -does.** A decode failure is not an API error status, so it propagates in both modes rather than -becoming an `ok: false` value — a `DecodeError` on a `2xx` body, and a `DecodeError` on a **declared -error arm**, both still reject. So does a failed token acquisition, because the credential is resolved -before anything is sent, and so does a caller abort. `try`/`catch` is still required around -`.asApiResult()`; it narrows what you catch, it does not remove the need to catch. +The failure branch is a plain object carrying **the error's own members under their own names** — +`status`, `headers`, `message`, `method`, `uri` and `payload` — never the error instance, so you narrow +on `outcome.payload.kind` exactly as you would on `err.payload.kind`, and a handler moves between the +two forms by swapping the prefix. Call `.asApiResult()` on the value the operation returned, **before +any `.then()`** (**typescript-calling-endpoints**). + +⚠ **Every failure other than an error status still rejects** — a `DecodeError` (on a `2xx` body or on +a **declared error arm**), a failed token acquisition and a caller abort included — so keep the +`try`/`catch` around `.asApiResult()`. + +**On a paged operation**, `.asApiResult()` is called on the walk and returns `PageableApiResult`: its +`.pages()` yields one `ApiResult` per page, and a failed page is the **last** element it yields; its +item loop ends silently at an error status and contributes no items for it, so an item loop that ends +cannot tell the last page from a failed one. Everything the single-call form still throws, the walk +still throws too, with `PaginationError` beside them. ## Transport failures, and guarding every call site @@ -458,23 +418,15 @@ DNS that failed, a connection that dropped, or an attempt's timeout elapsing — `"connection"` and `"timeout"`, and a `catch` whose only arm is `err instanceof ApiError` lets them escape and take down whatever was running the call. -**Every one of them reaches you after the retries are spent.** On a `GET`, `HEAD`, `PUT` or `OPTIONS` -call the default policy re-sends a `408`, `429`, `500`, `502`, `503` or `504`, a connection failure -and a timeout up to -three times before the call rejects, so what you catch is the **last** attempt's failure — an -`ApiError` for the final status, or a `ConnectionError` or `TimeoutError` — in exactly the shape it -would have had with retrying off. A write outside `httpMethodsToRetry` rejects on its first failure. -Do not retry a family error the SDK already retried; see **typescript-configuration-resilience**. - -**Unlike SDKs that let their HTTP library's exceptions through, this one wraps them.** Whatever your -`fetch` rejects with becomes a `ConnectionError`, with the original on `.cause` — so your boundary -never imports the transport's exception types, and it does not need revisiting when you swap `fetch` -for a wrapper. Two things pass through unwrapped: anything that is already in the family (a -`{Api}Error` your own wrapper threw), and a cancellation — the caller's own abort `reason`, or the -SDK's `TimeoutError` when an attempt's timeout fired, whatever your `fetch` rejected with. If you wrap -`fetch` to add a guard (**typescript-configuration-resilience**), throw a family error from it or -accept that yours will arrive as `err.cause` — and know that a plain error thrown there is a -`ConnectionError` the retry loop retries. +**Each reaches you after the SDK's retries are spent** — as the **last** attempt's failure, in the +shape it would have had with retrying off; do not retry it again (**typescript-configuration-resilience** +owns the policy). + +Whatever your `fetch` rejects with becomes a `ConnectionError` with the original on `.cause`, so your +boundary never imports transport exception types. A family error and a cancellation (your abort +`reason`, or the SDK's `TimeoutError` once an attempt's timeout fired, whatever your `fetch` rejected +with) pass through unwrapped — and a plain error your own `fetch` wrapper throws is a `ConnectionError` +the retry loop retries. **Convert the family to your own error type in one place.** If you wrap the SDK behind your own abstraction (a client interface, a service, a repository), do the conversion at that boundary so the @@ -523,11 +475,6 @@ or modify something and overlook the calls that only read — especially reads o a screen, a scheduled job, a startup or health check). A connection failure during a read fails just as hard as one during a write. A call left unguarded next to one that is guarded is the one that breaks. -⚠ **A rejection you never await is an unhandled rejection**, exactly like any other promise's: -`unhandledRejection` on Node — which by default ends the process — and `unhandledrejection` in a -browser. Await every call, or attach your own handler. `.asApiResult()` marks the promise handled as -its first act, so call it on the value the operation returned, in the same turn. - ## Presenting failures at your boundary — coherent, distinct, leak-free The catches above decide what you catch; this decides what the caller (an HTTP response, a UI layer, @@ -573,10 +520,9 @@ unauthenticated or throttled when they are neither. Those belong in the 5xx buck conflict and not-found are the caller's to fix. And keep the default arm at 5xx: a status you have not mapped is an unknown, not a caller error — the provider can add one without warning you. -**An unreadable body is not one case but two — decide which before you map it.** A `DecodeError` on a -**success** status is genuinely unknown: 5xx. One on an **error** status is not — the provider rejected -the request and only the *detail* was lost, so answering 5xx tells a retrying caller to keep retrying -something that can never succeed. `err.status` is what separates them; the type alone does not. +**An unreadable body is not one case but two** (*`"decode"` — the answer did not fit*): a `DecodeError` on a **success** +status is genuinely unknown, so 5xx; one on an **error** status is the provider's rejection with the +detail lost, so map it by `err.status`. **Never map a decode failure onto a domain absence.** "I could not read the answer" is not "the provider said no." It is tempting on a lookup — an unreadable body and a genuine miss both leave you @@ -607,26 +553,10 @@ if (typeof err === "object" && err !== null && "kind" in err && "uri" in err) { ## Notes -- **Retries are on by default.** An idempotent call is retried on `408`, `429`, `500`, `502`, `503`, - `504`, a dropped - connection and a timeout, honouring `Retry-After`, before it rejects; a write is not, unless its - method is in `httpMethodsToRetry`. The error you catch is the last attempt's. See - **typescript-configuration-resilience**. -- **A single `401` is not a permanent credential failure.** It invalidates the cached token and, by - default, is not re-sent; the caller sees that one `401`, and the *next* call acquires afresh. Do not tear down a - client or alert on one. -- **Failures are logged only when you turn logging on.** Logging is off by default; with - `ClientOptions.logging` on, the SDK writes a `warn` line for a non-`2xx` response and an `error` line - for a call that ends on a fault or on a credential it could not obtain (see - **typescript-configuration-resilience**). Neither is a substitute for handling the error: log what - your own code decided in your `catch`. -- **No raw `Response`.** `status` and `headers` are on `ApiResult` and on a `ResponseError`; the - `fetch` `Response` is deliberately unreachable. -- **A missing credential is not an error.** An unset credential member sends no credential, so the - failure surfaces as an `ApiError` `401` from the API rather than anything at construction — which - reads like an expired token instead of a config bug. This holds for composite schemes too: a - partially configured `all`/`any` scheme sends what it has rather than refusing, so there is no local - "auth could not be satisfied" rejection to catch. See **typescript-client-initialization**. +- **The SDK logs a failure only when its logging is on**, which it is not by default + (**typescript-configuration-resilience**) — log what your own code decided in your `catch`. +- **A missing credential is not an error**: the call goes out without it and the API answers `401` + (**typescript-authentication**). - **SDK errors do not survive a worker or process boundary intact.** `structuredClone` and `postMessage` reduce an `Error` subclass to a plain `Error` — `name`, `message` and `cause` survive; `kind`, `method`, `uri`, `status` and `payload` do not. Convert to your own serializable shape diff --git a/plugins/slack/skills/typescript/typescript-event-streams/SKILL.md b/plugins/slack/skills/typescript/typescript-event-streams/SKILL.md new file mode 100644 index 00000000..385baf1e --- /dev/null +++ b/plugins/slack/skills/typescript/typescript-event-streams/SKILL.md @@ -0,0 +1,144 @@ +--- +name: typescript-event-streams +description: Consuming a server-sent-events (text/event-stream) operation on an APIMatic-generated TypeScript SDK — what EventStream yields (each event's decoded data, nothing else), how the loop must end so the connection is released, narrowing a union on the yielded value, what rejects and when (the loop raises the same error family as the call, and there is no SSE error class), and bounding the wait with the client's idleTimeout. Load before writing the loop over an operation that resolves to an event stream, in addition to `typescript-calling-endpoints`. +--- + +# Event streams on an APIMatic TypeScript SDK + +> Throughout this skill, `{...}` is a placeholder for a name you take from your SDK (e.g. `{resource}`, +> `{operation}`, `{Api}Error`) — replace it with the concrete identifier from the source. + +An operation whose success response is `text/event-stream` returns `ApiPromise, E>` +rather than a value. The promise resolves as soon as the response **headers** arrive, before anything +is read — what is deferred is the body, and the stream holds its connection until it is released. +`T` is the type the spec gives every event's `data`: a string, a model, an array, or a union. + +```ts +const stream = await client.{resource}.{operation}({ /* ... */ }); +for await (const event of stream) { + event; // T — one event's data, already decoded +} +``` + +Iterating yields `T` itself, each event's decoded `data` and nothing else: the `event:` name and +`id:` lines of the wire format are not surfaced, so there is no envelope to unwrap and no `kind` +beyond what `T` declares. Nothing is read ahead of your loop, so a slow loop body slows delivery +rather than buffering events in memory. Where the operation declares a terminating event (the map's +**Returns** bullet names it, such as a `[DONE]` data line), the SDK consumes it, closes the stream and +never yields it; a body that closes before that line arrived is a clean end too. + +## Start here + +**Drain the loop.** Reaching the end releases the connection, so the shortest correct code is a plain +`for await`: + +```ts +for await (const event of await client.{resource}.{operation}({ /* ... */ })) { + handle(event); +} +``` + +**Leaving the loop early releases it too** — `break`, `return`, or a `throw` inside the body all +close the stream before control leaves. A stream you decide not to read at all is released with +`await stream.close()`, and where your runtime declares `Symbol.asyncDispose`, `await using` does +the same at block exit: + +```ts +await using stream = await client.{resource}.{operation}({ /* ... */ }); +for await (const event of stream) { + if (done(event)) break; // the stream is released either way +} +``` + +## How the iteration ends + +| You want | Write | Releases | +|---|---|---| +| the whole stream | a plain `for await` | at the end of the stream | +| to stop at a condition | `break` / `return` inside the loop | as the loop exits | +| a stream you will not read | `await stream.close()` | your `close()` | +| release at block exit | `await using stream = …` | the block | +| to stop from elsewhere | abort the `signal` you passed | the SDK cancels its own reader | + +`close()` is idempotent, and a pending `next()` ends with `done` rather than an error. A stream is +**single-use**: a second `for await` over the same `EventStream` throws a `TypeError`, exactly as a +second read of a web `ReadableStream` does. `stream.toReadableStream()` hands you the same values as a +web `ReadableStream` and takes the stream's one iteration. + +## What the loop yields + +| The success schema is | each `event` is | Narrow with | +|---|---|---| +| `type: string` | `string` — the event's text, verbatim | nothing — it is the value | +| an object schema | `{Model}` | nothing — it is the model | +| an array schema | `{Model}[]` — one batch per event, no wrapper model | nothing | +| a `oneOf` with a discriminator | `{Union}` | `switch (event.kind)` | + +Every event decodes through the **one** schema the spec declares for the stream, whatever name the +server gave it, so a union is narrowed on its own discriminant. An error the API reports *inside* the +stream is an event like any other: the spec declares its shape as an arm of the union, the loop +yields it, and the stream goes on unless you `break`. + +## What can go wrong + +| What failed | Direct call | `.asApiResult()` | +|---|---|---| +| a non-2xx status (the headers) | rejects at the call with `ApiError` (or the operation's typed subclass) | resolves `{ ok: false }` — no rejection | +| a 2xx that is not `text/event-stream` | nothing checks the media type: the call resolves and the body is read as event frames, so a JSON body usually ends the loop cleanly with no event | same | +| an event whose `data` does not fit the schema | the loop rejects with `DecodeError`, stream released | same | +| the connection dies mid-read | the loop rejects with `ConnectionError` | same | +| the body closes before the declared sentinel arrived | the loop ends cleanly; every event the server sent was delivered | same | +| the server sends nothing for `idleTimeout` | the loop rejects with `TimeoutError`, `timeout` = the idle bound | same | +| you abort the `signal` | the pending `next()` rejects with the signal's own `reason` — **not** an `{Api}Error` | same | +| a second iteration of one stream | `TypeError` at the `for await`, a bug | same | + +**There is no SSE error class.** Everything the loop raises is a leaf of the one `{Api}Error` family, +the same `DecodeError`, `ConnectionError` and `TimeoutError` the call itself can raise, narrowed on +`err.kind` exactly as `typescript-error-handling` describes. Put that boundary around the **loop**, not +only the call — the call settles as soon as the headers arrive: + +```ts +try { + const stream = await client.{resource}.{operation}({ /* ... */ }); + for await (const event of stream) { + handle(event); + } +} catch (err) { + if (err instanceof {Api}Error) { + // err.kind is "api" before the stream existed, and "decode", "connection" or "timeout" from the loop + } else { + throw err; // a caller abort or a bug — not ours + } +} +``` + +## Resuming + +The SDK does not read the `id:` lines and the stream carries no resume point. Where the spec declares +a `Last-Event-ID` header, the operation's request type carries it as an optional field the SDK sends +verbatim; what to put in it is yours to track, from the data the events carry, because no event id +reaches your loop. + +## Bounding the wait + +The client's `retry.timeout` stops at the response headers; an event stream has its own clock. +`ClientOptions.eventStream.idleTimeout` (default `60_000` ms) is how long the server may stay silent +while your loop waits for the next event — any bytes reset it, a heartbeat comment included, and it +runs only while an iteration is waiting, so time your loop body spends on an event never counts. +`null` turns it off; `0` is a zero-length window. It is resolved once, as the client is built, and no +call overrides it. For a total budget, pass a `signal` and abort it: the SDK cancels its own reader, +so the stream stops whatever your `fetch` does with the body. + +## The non-throwing form + +`.asApiResult()` resolves to `{ ok: true, status, headers, value }` with `value` the `EventStream` +— the only way to read the opening status and headers of a stream — or `{ ok: false, … }` for an +error status. The loop over `result.value` still rejects for the failures in the table above. + +## Testing an event stream + +Fake `fetch` (`typescript-testing`) and hand the SDK a `Response` whose body is a `ReadableStream` of +event frames under `content-type: text/event-stream` — `data: {...}\n\n`, one blank line ending each +event. The SDK reads the body in the transport's own chunks, so split a frame across two `enqueue` +calls to prove the loop does not depend on where the network cuts, and record what the body's +`cancel` receives to prove that `break` released the connection. diff --git a/plugins/slack/skills/typescript/typescript-getting-started/SKILL.md b/plugins/slack/skills/typescript/typescript-getting-started/SKILL.md index e3d4019d..fd2b7f64 100644 --- a/plugins/slack/skills/typescript/typescript-getting-started/SKILL.md +++ b/plugins/slack/skills/typescript/typescript-getting-started/SKILL.md @@ -1,41 +1,36 @@ --- name: "typescript-getting-started" -description: "Slack Web API TypeScript SDK identity and lookup layer (TypeScript/JavaScript only) — install, the single import specifier `slack-web-api`, the server environments and the base-URL knob, the auth pattern, the SDK map that ships inside the installed package (`sdk-map.md` + `map/operations/`) and how to traverse it, and the file table naming the one source file owning each fact the map leaves to the source. Load this before answering any Slack Web API TypeScript SDK contract question or writing any SDK code." +description: "Load before answering any Slack Web API TypeScript SDK question or writing SDK code — the lookup layer for `slack-web-api`: install, imports, environments, auth, and how to read the SDK map that ships in the package (`sdk-map.md`, `map/operations/`). TypeScript/JavaScript only." --- # Getting started with the Slack Web API TypeScript SDK -> **Who this skill is for.** This is the **lookup layer** for anyone writing Slack Web API TypeScript SDK code — it is yours to follow directly and fully. Ground every contract fact here (in the SDK map, and in the source files it names) rather than in recall, and carry those facts onto a contract sheet before you implement. Load `typescript-integrate-slack-web-api` for the workflow that wraps this skill. +> **The lookup layer** for Slack Web API TypeScript SDK code: ground every contract fact here — in the SDK map and the source files it names — never in recall, and carry those facts onto a contract sheet before you implement. `typescript-integrate-slack-web-api` holds the workflow around it. -This is the **SDK-specific** entry point. For general patterns that apply to any APIMatic-generated TypeScript SDK (client construction, auth, calling endpoints, models, error handling, resilience, testing), see the companion API-agnostic skills: `typescript-client-initialization`, `typescript-authentication`, `typescript-calling-endpoints`, `typescript-models`, `typescript-error-handling`, `typescript-configuration-resilience` and `typescript-testing`. - -**This page and those companion skills are complementary — load both.** This page is authoritative for the SDK's *identity and surface* (what to install, what to import, the resources, which file owns which fact); the companion skills are the *usage layer* on top — the best-practice way to call each piece and the gotchas a signature cannot show. Reading a file in the installed package does not remove the need to load the skill for that step, so at each step below, load the companion *and* confirm names against the installed package. +This page is authoritative for the SDK's identity and surface. The API-agnostic companion skills — `typescript-client-initialization`, `typescript-authentication`, `typescript-calling-endpoints`, `typescript-models`, `typescript-error-handling`, `typescript-configuration-resilience` and `typescript-testing` — are the *usage layer* on top: the way to call each piece and the gotchas a signature cannot show. **Load both:** at each **Integration workflow** step, load the companion it names even after reading the file it covers, and confirm names against the installed package. ## SDK identity -Verified against `package.json` and `sdk-map.md` of the generated package at version `1.7.0`. **Re-verify after a version bump** — this page is a snapshot, not a live read. +Verified against `package.json` and `sdk-map.md` of the package at version `1.7.0`. **Re-verify after a version bump** — this page is a snapshot, not a live read. | Fact | Value | | --- | --- | | API | Slack Web API | | Package name (what you install, and what you import) | `slack-web-api` — **not on npm**; built from source (see *Install*) | -| Import specifier | `slack-web-api` — the package root is the **only** entry; deep imports do not resolve | | Source repository | https://github.com/context-plugins/slack-typescript-sdk (branch `main` — the ref this map documents) | | Version | `1.7.0` (API spec version `1.7.0`) | -| Client class | `SlackWebApiClient` (`src/client.ts`) — one class, no sync/async split | -| Options type | `ClientOptions` (`src/client-options.ts`) — types only, no resolver beside it | -| Client construction | `new SlackWebApiClient(options: ClientOptions = {})` — the argument is optional, as is **every** field on it, so `new SlackWebApiClient()` compiles. Fields: `serverEnvironment` · `serverOptions` · `retry` · `fetch` · `slackAuth` · `slackAuthStrategy`. `retry` is the `RetryOptions` policy; its defaults retry a GET, HEAD, PUT or OPTIONS call up to `3` times and bound each attempt by `retry.timeout` = `60_000` ms, and every one of them can be changed | +| Client class | `SlackWebApiClient` (`src/client.ts`) | +| Options type | `ClientOptions` (`src/client-options.ts`) | +| Client construction | `new SlackWebApiClient(options: ClientOptions = {})` — the argument is optional, as is **every** field on it, so `new SlackWebApiClient()` compiles. Fields: `serverOptions` · `retry` · `logging` · `fetch` · `slackAuth` · `slackAuthStrategy`. `retry` is the `RetryOptions` policy | | Auth | **OAuth 2 authorization code** — set `ClientOptions.slackAuth` | -| Environments | 2 environments (`ServerEnvironment.Production` *(default)*, `ServerEnvironment.Environment2`) × 1 server group | -| Base-URL config | `serverOptions.baseUrl` (`src/servers.ts`), defaulting to `https://slack.com/api` | +| Environments | no selector — one environment; 2 server groups | +| Base-URL config | `serverOptions..baseUrl` (`src/servers.ts`) | | Log environment variable | `SLACK_WEB_API_CLIENT_LOG` | | Node floor | `>=20.3` (`engines.node`) | -| Runtime dependency | `zod` (`^4.1.0`), imported as `zod/v4-mini` — the only one | +| Runtime dependency | `zod` (`^4.1.0`) — the only one | | Module format | dual ESM + CommonJS folder dialects (`dist/esm`, `dist/commonjs`) behind one export | -| Typing | the package ships its own `.d.ts` and is generated under strict TypeScript. Callers get full inference — **a type error against this SDK is a real contract violation, not noise** | -| Surface | 253 operations · 56 resources · 357 models · 89 open enums · 253 per-operation error subclasses | - -The table above is **orientation, not a copy-paste recipe** — it gives you the names and facts (install, import specifier, the auth *pattern*, the base-URL knob), while the actual integration code comes from the companion skills. Load each one as you reach its step (see **Integration workflow** below) and confirm its types against the installed package. +| Typing | the package ships its own `.d.ts` — **a type error against this SDK is a real contract violation, not noise** | +| Surface | 253 operations · 56 resources · 357 models · 89 open enums · 0 per-operation error subclasses | ## Install @@ -47,40 +42,32 @@ npm install git+https://github.com/context-plugins/slack-typescript-sdk#main The installed package carries everything its `files` list packs — `src/`, `sdk-map.md` and the pages under `map/operations/` — so **every lookup on this page works as soon as the install finishes**. **Make sure the installed package is built**, as the source on GitHub is not pre-built. -Do not vendor its `src/` into your project, point `tsconfig` `paths` at a throwaway clone, or import from `dist/` directly. Installing the package properly is what makes the `exports` map, the shipped `.d.ts` chain and the dual-dialect resolution behave the way the SDK expects — **and it is what puts the SDK map inside `node_modules`, which is where every lookup below reads it from**. Requires Node `>=20.3` (`engines.node`). +Do not vendor its `src/` into your project, point `tsconfig` `paths` at a throwaway clone, or import from `dist/` directly: the `exports` map, the shipped `.d.ts` chain, the dual-dialect resolution and the SDK map in `node_modules` all depend on a real install. ## Imports — one entry, and only one -**Every** public name is re-exported from the package root — the client, `ClientOptions`, `ServerEnvironment`, 446 model types with the schema value beside each, the error classes, and the runtime types (`ApiPromise`, `ApiResult`, `RequestOptions`, `RetryOptions`, `RequestRetryOptions`, `ErrorPayload`, `Declared`, `Schema`, `EnumSchema`, `Encoded`). +**Every** public name is re-exported from the package root — the client, `ClientOptions`, 446 model types with the schema value beside each, the error classes, and the runtime types (`ApiPromise`, `Pageable`, `PageableApiResult`, `ApiResult`, `RequestOptions`, `RetryOptions`, `RequestRetryOptions`, `Declared`, `Undeclared`, `Schema`, `EnumSchema`, `Encoded`, `JsonValue`). ```ts -import { SlackWebApiClient, ServerEnvironment, ApiError, SlackWebApiError } from "slack-web-api"; +import { SlackWebApiClient, ApiError, SlackWebApiError } from "slack-web-api"; import type { ClientOptions, ApImethodusersGetPresence } from "slack-web-api"; ``` Things the specifier alone will not tell you: - **Deep imports do not resolve.** The `exports` map exposes `.` and `./package.json` and nothing else, so `slack-web-api/models/…` fails (`TS2307`) even though the file exists in the shipped `src/`. Every `Source` path on the SDK map is where to **read** a shape, never what to import. -- **From CommonJS**, the typed spelling is `import sdk = require("slack-web-api")`. A plain `require` destructure runs but yields `any`. -- **`instanceof` is reliable within one dialect.** A process that loads both (`import` in one file, `require` in another) gets two independent copies of every error class, and `instanceof` across that boundary is `false` — narrow on `err.kind` / `err.payload.kind` / `err.name` there. +- **From CommonJS**, the typed spelling is `import sdk = require("slack-web-api")`. A plain `require` destructure runs but yields `any`. A process that loads both dialects gets two copies of every error class, so `instanceof` fails across them (`typescript-error-handling`). Under `verbatimModuleSyntax`, names carrying no runtime value (`ClientOptions`, every model type) must be imported with `import type`. Under `exactOptionalPropertyTypes`, **omit or spread** an absent optional field rather than assigning `undefined` to it. -## Environments - -`ClientOptions.serverEnvironment` selects one environment for the whole client (`src/servers.ts`). `ServerEnvironment` is a `const` object with a derived union type — not a TypeScript `enum` — and unlike the model enums it is **closed**, so only its declared members are assignable. +## Hosts -| Group | Environment | Base URL | Override at | -| --- | --- | --- | --- | -| `default` | `production` *(default)* | `https://slack.com/api` | `serverOptions.baseUrl` | -| `default` | `environment2` | `https://slack.com/oauth` | `serverOptions.baseUrl` | +This SDK has one environment and so **no environment selector** — there is no `ServerEnvironment` type and no field to set (`src/servers.ts`). The base URL of every server group, the only hosts the SDK knows, is in `sdk-map.md` § *Servers & auth*; reaching any other is a `serverOptions` base-URL override — `serverOptions: { default: { baseUrl: "…" } }` — and nothing in the options then records **which** deployment that is, so make the intent explicit where the client is built. Consequences to state on every contract sheet that touches configuration: -- Constructing the client with no options selects **`ServerEnvironment.Production`**, silently. -- An override merges with the built-in default **per group-and-environment pair, key by key**; a `baseUrl` override replaces the template verbatim, template variable values are percent-encoded into it; server variables are filled in once, as the client is built, and only the path parameters expand per request. -- Each operation is bound to one server group at generation time. A map block carries a **Server** bullet only when its group is not `default`. -- An environment value the SDK does not know throws `ConfigurationError` **from the constructor** — every server group is resolved once, as the client is built — so no operation method throws synchronously. +- An override merges with the built-in default **key by key**; a `baseUrl` override replaces the whole template. +- Each operation belongs to one server group; a map block carries a **Server** bullet only when its group is not `default`. ## Auth pattern (1 scheme) @@ -96,96 +83,29 @@ const client = new SlackWebApiClient({ }); ``` -**Every credential field is optional at the type level and that is a trap worth flagging on every sheet.** Omit one and nothing fails at construction — the request simply goes out without that credential and the server decides. Most APIs then answer `401`; one that serves anonymous traffic answers `200` and hides the omission entirely. So a `401` on a call you believed was authenticated is usually an unset field rather than an SDK failure; verify the field is set rather than waiting for a `401` to tell you, and check the operation's **Auth** bullet against what the client was actually given. +**Every credential field is optional.** Omit one and the request goes out without it, with no error at construction; the server answers `401`, or `200` if it serves anonymous traffic. On an unexpected `401`, check the operation's **Auth** bullet against the fields you set. -Three more behaviours the type does not show: - -- **A credential may be a function.** Every field typed `TokenProvider` is re-read on **every** request with no caching, so a key can rotate without rebuilding the client. An empty string counts as absent; a function counts as present without being invoked. -- **Composition is emitted, not configured.** Where the spec puts two schemes in one requirement the SDK sends **both**; where it lists alternatives it sends the **first configured** one, in the order the **Auth** bullet prints them. -- **A 401 invalidates the cached credential.** On a 401 (401 only, not 403) the SDK clears whatever that operation's scheme had cached, so the *next* call re-acquires; the current request still rejects. - -**OAuth 2 fetches and caches its own token.** The token request goes through **the same client** — same `fetch`, same `retry` policy — sends a form-urlencoded body, and decodes the response against a schema rather than casting it. A token is cached until shortly before it expires; a response with no `expires_in` is treated as never expiring (RFC 6749 §5.1); concurrent callers share one in-flight fetch. **A refused token endpoint rejects with `AuthError`**, wrapping the underlying `ApiError` as `cause` — so a bad secret never looks like the business call failing, and `AuthError` is *not* an `ApiError`. The token request is itself a `POST` with its own timeout, retried only when `httpMethodsToRetry` names `POST`. +**OAuth 2 fetches and caches its own token.** The token request goes through **the same client** — same `fetch`, same `retry` policy — as a `POST`, retried only when `httpMethodsToRetry` names `POST`. **A refused token endpoint rejects with `AuthError`**, which is *not* an `ApiError`; the endpoint's `ApiError` is its `cause`. | Flow | Token endpoint | Client credentials travel | | --- | --- | --- | -| `slackAuth` | `default` + `/oauth.access` | as `Authorization: Basic` | - -`slackAuthStrategy` on `ClientOptions` substitutes the whole token request (`getToken(credentials, signal)`, plus `tryRefreshToken(…)` where the grant is refreshable); the caching, expiry buffer and single-flight behaviour still apply. +| `slackAuth` | `default` + `/oauth.v2.access` | as `Authorization: Basic` | -The **token endpoint follows the same base URL** as the operations on its group, so it always tracks the environment or the override — you never configure it separately. Its group is named in the table above, against `src/servers.ts`. +`slackAuthStrategy` on `ClientOptions` substitutes the whole token request. The **token endpoint follows the base URL of its group** (named in the table), so it tracks the environment and any override. -See `typescript-authentication` for the full picture. +Credential functions, scheme composition, 401 invalidation, token caching and the token-request strategy's shape: `sdk-map.md` § *Servers & auth* and `typescript-authentication`. ## Resources -Resources are **memoized lazy getters** on the client (`client.`). Their classes are exported only for their merged namespaces — the per-operation request and error types — and for `instanceof`; their constructors take engine internals that are not exported, so reach a resource only through its getter. - -| Attribute | Class | Ops | Operations | -| --- | --- | --- | --- | -| `client.adminApps` | `AdminApps` | 2 | `adminAppsApprove` · `adminAppsRestrict` | -| `client.admin` | `Admin` | 56 | `adminAppsApprove` · `adminAppsApprovedList` · `adminAppsRequestsList` · `adminAppsRestrict` · `adminAppsRestrictedList` · `adminConversationsArchive` · `adminConversationsConvertToPrivate` · `adminConversationsCreate` · `adminConversationsDelete` · `adminConversationsDisconnectShared` · `adminConversationsEkmListOriginalConnectedChannelInfo` · `adminConversationsGetConversationPrefs` · `adminConversationsGetTeams` · `adminConversationsInvite` · `adminConversationsRename` · `adminConversationsRestrictAccessAddGroup` · `adminConversationsRestrictAccessListGroups` · `adminConversationsRestrictAccessRemoveGroup` · `adminConversationsSearch` · `adminConversationsSetConversationPrefs` · `adminConversationsSetTeams` · `adminConversationsUnarchive` · `adminEmojiAdd` · `adminEmojiAddAlias` · `adminEmojiList` · `adminEmojiRemove` · `adminEmojiRename` · `adminInviteRequestsApprove` · `adminInviteRequestsApprovedList` · `adminInviteRequestsDeniedList` · `adminInviteRequestsDeny` · `adminInviteRequestsList` · `adminTeamsAdminsList` · `adminTeamsCreate` · `adminTeamsList` · `adminTeamsOwnersList` · `adminTeamsSettingsInfo` · `adminTeamsSettingsSetDefaultChannels` · `adminTeamsSettingsSetDescription` · `adminTeamsSettingsSetDiscoverability` · `adminTeamsSettingsSetIcon` · `adminTeamsSettingsSetName` · `adminUsergroupsAddChannels` · `adminUsergroupsAddTeams` · `adminUsergroupsListChannels` · `adminUsergroupsRemoveChannels` · `adminUsersAssign` · `adminUsersInvite` · `adminUsersList` · `adminUsersRemove` · `adminUsersSessionInvalidate` · `adminUsersSessionReset` · `adminUsersSetAdmin` · `adminUsersSetExpiration` · `adminUsersSetOwner` · `adminUsersSetRegular` | -| `client.adminAppsApproved` | `AdminAppsApproved` | 1 | `adminAppsApprovedList` | -| `client.adminAppsRequests` | `AdminAppsRequests` | 1 | `adminAppsRequestsList` | -| `client.adminAppsRestricted` | `AdminAppsRestricted` | 1 | `adminAppsRestrictedList` | -| `client.adminConversations` | `AdminConversations` | 13 | `adminConversationsArchive` · `adminConversationsConvertToPrivate` · `adminConversationsCreate` · `adminConversationsDelete` · `adminConversationsDisconnectShared` · `adminConversationsGetConversationPrefs` · `adminConversationsGetTeams` · `adminConversationsInvite` · `adminConversationsRename` · `adminConversationsSearch` · `adminConversationsSetConversationPrefs` · `adminConversationsSetTeams` · `adminConversationsUnarchive` | -| `client.adminConversationsEkm` | `AdminConversationsEkm` | 1 | `adminConversationsEkmListOriginalConnectedChannelInfo` | -| `client.adminConversationsRestrictAccess` | `AdminConversationsRestrictAccess` | 3 | `adminConversationsRestrictAccessAddGroup` · `adminConversationsRestrictAccessListGroups` · `adminConversationsRestrictAccessRemoveGroup` | -| `client.adminEmoji` | `AdminEmoji` | 5 | `adminEmojiAdd` · `adminEmojiAddAlias` · `adminEmojiList` · `adminEmojiRemove` · `adminEmojiRename` | -| `client.adminInviteRequests` | `AdminInviteRequests` | 3 | `adminInviteRequestsApprove` · `adminInviteRequestsDeny` · `adminInviteRequestsList` | -| `client.adminInviteRequestsApproved` | `AdminInviteRequestsApproved` | 1 | `adminInviteRequestsApprovedList` | -| `client.adminInviteRequestsDenied` | `AdminInviteRequestsDenied` | 1 | `adminInviteRequestsDeniedList` | -| `client.adminTeamsAdmins` | `AdminTeamsAdmins` | 1 | `adminTeamsAdminsList` | -| `client.adminTeams` | `AdminTeams` | 2 | `adminTeamsCreate` · `adminTeamsList` | -| `client.adminTeamsOwners` | `AdminTeamsOwners` | 1 | `adminTeamsOwnersList` | -| `client.adminTeamsSettings` | `AdminTeamsSettings` | 6 | `adminTeamsSettingsInfo` · `adminTeamsSettingsSetDefaultChannels` · `adminTeamsSettingsSetDescription` · `adminTeamsSettingsSetDiscoverability` · `adminTeamsSettingsSetIcon` · `adminTeamsSettingsSetName` | -| `client.adminUsergroups` | `AdminUsergroups` | 4 | `adminUsergroupsAddChannels` · `adminUsergroupsAddTeams` · `adminUsergroupsListChannels` · `adminUsergroupsRemoveChannels` | -| `client.adminUsers` | `AdminUsers` | 8 | `adminUsersAssign` · `adminUsersInvite` · `adminUsersList` · `adminUsersRemove` · `adminUsersSetAdmin` · `adminUsersSetExpiration` · `adminUsersSetOwner` · `adminUsersSetRegular` | -| `client.adminUsersSession` | `AdminUsersSession` | 2 | `adminUsersSessionInvalidate` · `adminUsersSessionReset` | -| `client.api` | `Api` | 1 | `apiTest` | -| `client.appsEventAuthorizations` | `AppsEventAuthorizations` | 1 | `appsEventAuthorizationsList` | -| `client.apps` | `Apps` | 8 | `appsEventAuthorizationsList` · `appsPermissionsInfo` · `appsPermissionsRequest` · `appsPermissionsResourcesList` · `appsPermissionsScopesList` · `appsPermissionsUsersList` · `appsPermissionsUsersRequest` · `appsUninstall` | -| `client.appsPermissions` | `AppsPermissions` | 2 | `appsPermissionsInfo` · `appsPermissionsRequest` | -| `client.appsPermissionsResources` | `AppsPermissionsResources` | 1 | `appsPermissionsResourcesList` | -| `client.appsPermissionsScopes` | `AppsPermissionsScopes` | 1 | `appsPermissionsScopesList` | -| `client.appsPermissionsUsers` | `AppsPermissionsUsers` | 2 | `appsPermissionsUsersList` · `appsPermissionsUsersRequest` | -| `client.auth2` | `Auth` | 2 | `authRevoke` · `authTest` | -| `client.bots` | `Bots` | 1 | `botsInfo` | -| `client.calls` | `Calls` | 6 | `callsAdd` · `callsEnd` · `callsInfo` · `callsParticipantsAdd` · `callsParticipantsRemove` · `callsUpdate` | -| `client.callsParticipants` | `CallsParticipants` | 2 | `callsParticipantsAdd` · `callsParticipantsRemove` | -| `client.chat` | `Chat` | 10 | `chatDelete` · `chatDeleteScheduledMessage` · `chatGetPermalink` · `chatMeMessage` · `chatPostEphemeral` · `chatPostMessage` · `chatScheduleMessage` · `chatScheduledMessagesList` · `chatUnfurl` · `chatUpdate` | -| `client.chatScheduledMessages` | `ChatScheduledMessages` | 1 | `chatScheduledMessagesList` | -| `client.conversations` | `Conversations` | 18 | `conversationsArchive` · `conversationsClose` · `conversationsCreate` · `conversationsHistory` · `conversationsInfo` · `conversationsInvite` · `conversationsJoin` · `conversationsKick` · `conversationsLeave` · `conversationsList` · `conversationsMark` · `conversationsMembers` · `conversationsOpen` · `conversationsRename` · `conversationsReplies` · `conversationsSetPurpose` · `conversationsSetTopic` · `conversationsUnarchive` | -| `client.dialog` | `Dialog` | 1 | `dialogOpen` | -| `client.dnd` | `Dnd` | 5 | `dndEndDnd` · `dndEndSnooze` · `dndInfo` · `dndSetSnooze` · `dndTeamInfo` | -| `client.emoji` | `Emoji` | 1 | `emojiList` | -| `client.filesComments` | `FilesComments` | 1 | `filesCommentsDelete` | -| `client.files` | `Files` | 13 | `filesCommentsDelete` · `filesDelete` · `filesInfo` · `filesList` · `filesRemoteAdd` · `filesRemoteInfo` · `filesRemoteList` · `filesRemoteRemove` · `filesRemoteShare` · `filesRemoteUpdate` · `filesRevokePublicUrl` · `filesSharedPublicUrl` · `filesUpload` | -| `client.filesRemote` | `FilesRemote` | 6 | `filesRemoteAdd` · `filesRemoteInfo` · `filesRemoteList` · `filesRemoteRemove` · `filesRemoteShare` · `filesRemoteUpdate` | -| `client.migration` | `Migration` | 1 | `migrationExchange` | -| `client.oauth` | `Oauth` | 3 | `oauthAccess` · `oauthToken` · `oauthV2Access` | -| `client.oauthV2` | `OauthV2` | 1 | `oauthV2Access` | -| `client.pins` | `Pins` | 3 | `pinsAdd` · `pinsList` · `pinsRemove` | -| `client.reactions` | `Reactions` | 4 | `reactionsAdd` · `reactionsGet` · `reactionsList` · `reactionsRemove` | -| `client.reminders` | `Reminders` | 5 | `remindersAdd` · `remindersComplete` · `remindersDelete` · `remindersInfo` · `remindersList` | -| `client.rtm` | `Rtm` | 1 | `rtmConnect` | -| `client.search` | `Search` | 1 | `searchMessages` | -| `client.stars` | `Stars` | 3 | `starsAdd` · `starsList` · `starsRemove` | -| `client.teamApi` | `TeamApi` | 5 | `teamAccessLogs` · `teamBillableInfo` · `teamInfo` · `teamIntegrationLogs` · `teamProfileGet` | -| `client.teamProfile` | `TeamProfile` | 1 | `teamProfileGet` | -| `client.usergroups` | `Usergroups` | 7 | `usergroupsCreate` · `usergroupsDisable` · `usergroupsEnable` · `usergroupsList` · `usergroupsUpdate` · `usergroupsUsersList` · `usergroupsUsersUpdate` | -| `client.usergroupsUsers` | `UsergroupsUsers` | 2 | `usergroupsUsersList` · `usergroupsUsersUpdate` | -| `client.users` | `Users` | 12 | `usersConversations` · `usersDeletePhoto` · `usersGetPresence` · `usersIdentity` · `usersInfo` · `usersList` · `usersLookupByEmail` · `usersProfileGet` · `usersProfileSet` · `usersSetActive` · `usersSetPhoto` · `usersSetPresence` | -| `client.usersProfile` | `UsersProfile` | 2 | `usersProfileGet` · `usersProfileSet` | -| `client.views` | `Views` | 4 | `viewsOpen` · `viewsPublish` · `viewsPush` · `viewsUpdate` | -| `client.workflows` | `Workflows` | 3 | `workflowsStepCompleted` · `workflowsStepFailed` · `workflowsUpdateStep` | - -Every operation has the same call shape — `op(request, options?)`, one **flat, channel-blind** request object first and `RequestOptions` (`{ signal, retry, logging }`) second — and returns `ApiPromise`. - -⚠ **The request type name is not uniformly `Request`.** A name that collides inside its namespace is promoted to `RequestParams` instead — no operation in this SDK takes that spelling at this version. Take the name from the operation's **Signature** bullet on its map page; never construct it from the method name. +Resources are **memoized lazy getters** on the client (`client.`); reach one only through its getter. Its class is exported for its merged namespace — the per-operation request and error types — and for `instanceof`, not for construction. + +56 resources: `sdk-map.md` § *Operations — by resource* names every operation, with the page that documents it. + +Every operation has the same call shape — `op(request, options?)`, one **flat, channel-blind** request object first and `RequestOptions` (`{ signal, retry, logging }`) second — and returns `ApiPromise`, or `Pageable` for a paged operation. No operation is paged — every one of them is a single request. ## SDK map — look up first, open the file second -The SDK ships a generated map, and `package.json`'s `files` list includes it, so **installing the package gives you the map** — no clone is needed. It sits at the package root, the directory holding `package.json` and the `src/` tree: +The map sits at the package root, the directory holding `package.json` and the `src/` tree: - **`sdk-map.md`** — the index: client construction with the full `ClientOptions` table, the *Not on this SDK* table, the one error family with `ApiResult` and `.asApiResult()`, wire serialization for every channel, servers and auth, runtime and packaging, and the link table into the operations pages. - **`map/operations/.md`** — one page per resource, one `###` block per operation, with bullets in the fixed order **Server**, **Signature**, **Wire** (verb and route), **Auth**, **Request body**, **SDK-sent**, **Returns**, **Error**, **Error arms** — then a **Fields** table giving every request field its channel, wire name, type, required flag and default, and a **Type sources** table naming the declaring file and schema value of every type the operation mentions. @@ -198,19 +118,17 @@ node -e "console.log(require.resolve('slack-web-api/package.json'))" Failing that it is at `node_modules/slack-web-api/`. **If the resolve fails, or the directory it prints carries no `sdk-map.md`, the map is still in the SDK's own repository** — , branch `main`. A registry id is a claim on a shared index rather than proof of identity, so it can resolve to an unrelated package or to a release predating the map; the repository is the copy that is this SDK by construction. Read it there, and if neither route yields a map, mark the fact `UNVERIFIED` and say what would settle it rather than answering from memory. -Every `Source` path on the map is relative to that package root, so `src/models/.ts` opens as written from there — the package ships its `src/` tree, so the path resolves inside `node_modules/slack-web-api/` exactly as the map writes it. An import specifier ending `.js` inside that source is the NodeNext spelling of the sibling `.ts` file. - -**The map is the locator; the source files are the shapes.** Read the map first — signatures, routes, request fields with their channels and defaults, return types, error arms, and which file declares a type are all answered there without opening a single `.ts` file. Then open the one file the map names for what it deliberately does not carry: a model's members, whether each is required, optional or nullable, and an enum's members with their wire values — the `as const` object in the enum's own file (for an enum inside a model, the file the model imports it from). The map says so itself — *"Shapes live only in the source … Do not derive the path from the type name."* +Every `Source` path on the map is relative to that package root (`node_modules/slack-web-api/`). An import specifier ending `.js` inside that source is the NodeNext spelling of the sibling `.ts` file. -**`sdk-map.md` carries the invariants every operation block assumes, so read it before any `map/operations/` page**; the pages are written to be read beside it. And **silence means the default**: the index states what holds for every operation — the call shape, the flat channel-blind request object, the `ApiPromise` return, the default server group, no pagination and no streaming — and a block departs from one only by saying so. Take the default and move on rather than opening the source to confirm it. +**Read `sdk-map.md` before any `map/operations/` page.** It states what holds for every operation, and **silence means the default**: a block departs from it only by saying so — a paged operation's **Signature** returns `Pageable` and its **Returns** bullet names the strategy and what ends the walk — so take the default rather than opening the source to confirm it. **The map carries shapes; what an operation *means* lives elsewhere.** When *what* to pass depends on meaning — which values a field accepts beyond its type, a rule that couples two fields, what a defaulted header actually selects — the map will not settle it. Read that operation's entry in `api-reference.md` at the package root, keyed by the same signature, *before* writing the sheet row, and record what you found. A value you already "know" for a field the map types as a plain `string` is a lookup, not a recall — the memory ban applies to it. ## Contract facts — the map first, then the source file -**Six of these are map lookups — don't open a source file for them:** an operation's signature; its request fields with channel, wire name, required flag and default; its return type; its error subclass and the arms with the status each covers; the `ClientOptions` fields and their defaults; and the environments, base URLs and auth wiring. +**The map is the locator; the source files are the shapes.** These are map lookups — don't open a source file for them: an operation's signature and route; its request fields with channel, wire name, required flag and default; its return type; its error subclass and the arms with the status each covers; the `ClientOptions` fields and their defaults; the environments, base URLs and auth wiring; and which file declares a type. -The table below covers everything else, and the full body behind a map row. Paths are relative to `node_modules/slack-web-api/`: +Open the one file the map's **Type sources** table names — never derive the path from the type name — for what the map does not carry: a model's members and whether each is required, optional or nullable, and an enum's members with their wire values — the `as const` object in the enum's own file (for an enum inside a model, the file the model imports it from). The table below covers that, everything else, and the full body behind a map row. Paths are relative to `node_modules/slack-web-api/`: | Question | File | | --- | --- | @@ -224,6 +142,8 @@ The table below covers everything else, and the full body behind a map row. Path | The transport: the attempt loop, `fetch` resolution, 401 invalidation, 2xx-vs-error split | `src/core/raw-client.ts` | | Error classes and `ErrorKind` | `src/core/errors.ts`, `src/core/api-error.ts` | | `ApiPromise`, `ApiResult`, `.asApiResult()`, the `Symbol.species` behaviour | `src/core/api-promise.ts` | +| `Pageable` and `PageableApiResult` — the lazy walk a paged operation returns, `.pages()`, and `.asApiResult()` on a walk | `src/core/pagination/pageable.ts` | +| The four paging states — offset, page, cursor and link — and the stop rule each applies | `src/core/pagination/states/offset-state.ts`, `src/core/pagination/states/page-state.ts`, `src/core/pagination/states/cursor-state.ts`, `src/core/pagination/states/link-state.ts` | | `RequestOptions` (it is `{ signal, retry, logging }` and nothing else) | `src/core/api-request.ts` | | `RetryOptions` and its defaults, `RequestRetryOptions`, backoff, `Retry-After`, `RetryAttempt` | `src/core/retry.ts` | | `LoggingOptions` and its defaults (`defaultLoggingOptions`), `RequestLoggingOptions`, `Logger`, `LogDetails` | `src/core/logging.ts` | @@ -240,37 +160,44 @@ Keep lookups cheap — the rules that keep a session's context small: - **Never grep, glob or `find` the package to *locate* a type** — the map is the locator, and it says so. Grep only *inside* the file its **Type sources** table names, for the symbol. A sweep for a cross-cutting *shape* is a different question and is fine: "every field typed `unknown`", "every required-nullable member" are things nothing indexes, and one targeted `grep -rn` over `src/models/` is the right tool — record what it found on the sheet. - Trust the compiler over this page: if a name here ever fails to type-check, re-read the file the table above names and report the drift; never patch around it from memory. +## Validation — what `validate` checks + +Every model's schema const — the value export beside its type — carries `encode`, `decode` and `validate`. `validate(value)` runs `encode`'s rules without the conversion and without the throw, and returns `{ success: true }` or `{ success: false, message }`, the message naming every failing field under its full path and why. + +**This SDK enforces the spec's value constraints on `validate`.** A model or union whose spec declares one — `minLength`/`maxLength`, `pattern`, `format` (`email`, `hostname`, `ipv4`, `ipv6`, `uri`, `uri-reference`, `json-pointer`), `minimum`/`maximum`, `exclusiveMinimum`/`exclusiveMaximum`, `multipleOf`, `minItems`/`maxItems`/`uniqueItems`, `minProperties`/`maxProperties`, and the keywords on an array's `items` and a map's `additionalProperties` — carries it on its public schema: `botSchema.validate(value)` reports it and `encode` throws on it. A model that nests a constrained one checks the nested value too and reports its fields under their full path. The operations do **not** apply those constraints: they encode and decode through a structural twin the module keeps for itself, `botInternalSchema`, which the package root does not export, so a value the service would accept is never refused on the way out, and a service ahead of the spec is never refused on the way in. A schema's own file says which it is: a constrained one declares the twin beside the public one. Every other schema is structural only, and its `validate` checks shape alone. + ## Sensitive data — check the request models before you log anything -Whether this API's **request** models carry fields you must never log — card or bank numbers, personal data, message content — is a shape question: each request model's declaring file (the map's **Type sources** table names it) lists every field. If the scope touches such a field, four generator facts decide your logging posture (all in `typescript-configuration-resilience`): a JSON request body is logged **verbatim** when `logRequestBody` is on, with no redaction; a form body is masked only by deny-list; a per-call `RequestOptions.logging` level turns the request body on for that call, whatever the client set; and leaving `ClientOptions.logging` without a `logger` or a `level` arms the `SLACK_WEB_API_CLIENT_LOG` environment variable, which turns logging and both header switches on with no code change and no deploy — though never the body. So on any build that can carry such a field: `logRequestBody` stays off, no call on those paths passes a per-call level, `ClientOptions.logging.level` is set explicitly in production, and your own diagnostics never echo a request body on those paths. +Whether this API's **request** models carry fields you must never log — card or bank numbers, personal data, message content — is a shape question: each request model's declaring file (the map's **Type sources** table names it) lists every field. If the scope touches such a field: `logRequestBody` stays off, because it logs a JSON request body **verbatim** and masks a form body only by deny-list; no call on those paths passes a per-call `RequestOptions.logging` level, which turns the request body on for that call whatever the client set; `ClientOptions.logging.level` is set explicitly in production, because without a `logger` or a `level` the `SLACK_WEB_API_CLIENT_LOG` environment variable turns logging and both header switches on with no code change; and your own diagnostics never echo a request body on those paths (`typescript-configuration-resilience` has the details). The SDK never logs a response body, but your own code may. Responses are often safer — many APIs return masked variants of what requests carry raw — but that too is a model-shape fact: check the response model's file before assuming. ## Integration workflow — load the companion skill at each step -Before you write the code for each step, load the named companion skill — even if you have already read the relevant file. Each step calls out the trap the signature hides (in *parens*). A typical integration reaches them in this order: +Before you write the code for each step, load the named companion skill — even if you have already read the relevant file. A typical integration reaches them in this order: -1. **Client construction & lifetime** — load **typescript-client-initialization** before you write `new SlackWebApiClient(…)`. (*The signature won't tell you:* every option is optional, so a client built with no arguments compiles and talks to the default environment with no credential; the client must be **long-lived and app-scoped**, never rebuilt per request, because the resource getters and the OAuth 2 token cache live on it; there is no `close()` or `dispose()` — it owns no pool, only a `fetch`; and when no `fetch` is reachable the **constructor** throws `ConfigurationError`, not the first call.) -2. **Authentication** — load **typescript-authentication** before you set credentials. The scheme is `slackAuth` on `ClientOptions`. (*The signature won't tell you:* the field is optional — omit it and every request goes out unauthenticated with no failure at construction; the token is fetched lazily and cached on the client; a **failed token fetch** raises `AuthError`, which is not an `ApiError` and **bypasses `.asApiResult()` entirely**; and a 401 invalidates the cache without retrying the current call. Load secrets from the environment or a secret store, never hardcode.) -3. **Calling an endpoint** — load **typescript-calling-endpoints** before the first `client..(…)` call. (*The signature won't tell you:* the request object is **flat and channel-blind** — a field named `body` *is* the whole request body and every other field is fanned out to path, query or header by the SDK, so nothing is nested by channel; **an omitted field that has a default is still sent, with that default**; **no operation resolves to `undefined` — every one of them carries a body**; and `.asApiResult()` must be called on the value the operation returned, because `ApiPromise` overrides `Symbol.species` and `.then()`/`.catch()` hand back a plain `Promise` with the method gone.) -4. **Models** — load **typescript-models** the moment a request/response member is not a plain string or number. (*The signature won't tell you:* models are plain `type`s built from object literals — no constructor, no builder; `f?: T` means omit the key, while `f: T | null` is **required and nullable** and `null` is a distinct value; enums are **open** (`const` companion plus a union admitting `(string & {})`), so the schema validates the base type only and an unknown server value round-trips instead of throwing — use `.values` to test membership yourself; and every type has a schema companion usable in both directions.) -5. **Error handling** — load **typescript-error-handling** before you write any `try/catch`. (*The signature won't tell you:* every operational failure is **one family**, `SlackWebApiError`, narrowed on `err.kind` — `"api"` is an API error status, carried by `ApiError` and its per-operation subclasses — while four throwables sit outside it (`ConfigurationError` from the constructor, `SchemaError` from a codec called directly, a `TypeError` for a bug, and a caller abort's own `reason`), so a `catch` that tests the family has to rethrow the rest; **arm tags are schema-derived, not statuses** (see the sheet checklist below); a malformed 2xx body rejects with `DecodeError`, not `ApiError`, and `.asApiResult()` does not convert it; and a missing response field the schema permits is silently `undefined` rather than any error at all.) -6. **Configuration & resilience** — load **typescript-configuration-resilience** when you set the base URL, timeouts, retries, proxies, TLS, or logging. (*The signature won't tell you:* **retrying is on by default** — the default policy retries a GET, HEAD, PUT or OPTIONS call on `408`, `429`, `500`, `502`, `503` and `504` and on a dropped connection or timeout, and every one of those is a `RetryOptions` field you can change; a write is repeated only when `httpMethodsToRetry` names its method; `retry: { maxRetries: 0 }` turns it off, one call overrides it through `RequestOptions.retry`, and a `401` is not retried by default; `retry.timeout` bounds **one attempt**, up to its response headers, not the whole call, and `0` is a zero-length deadline while a value `setTimeout` cannot honour falls back to the default; **logging is off by default** — `ClientOptions.logging` turns it on with a `logger` or a `level`, and so does the `SLACK_WEB_API_CLIENT_LOG` environment variable when code sets neither, but a request body is logged only when code sets `logRequestBody`, and then a JSON body **verbatim**, with no redaction; **there are no hooks, middleware or interceptors** — `ClientOptions.fetch` is the one transport extension point, `onRetry` being the only built-in callback; and a `fetch` replacement is called with the attempt's `Request` and no `init`, so one that does not forward that `Request`, or its `signal`, makes both each attempt's timeout and every `RequestOptions.signal` inert.) -7. **Testing** — load **typescript-testing** before you stub the SDK. (*The signature won't tell you:* the seam is **`ClientOptions.fetch`**, not the client class and not the resource classes — whose constructors take unexported engine internals, so they cannot be instantiated in a test; stub bodies in **wire shape** and let the SDK decode them; assert on the request the SDK actually built, headers included; and cover the failure kinds an `ApiError`-only test misses, `DecodeError` above all.) +1. **Client construction & lifetime** — load **typescript-client-initialization** before you write `new SlackWebApiClient(…)`. The client is **long-lived and app-scoped**, never rebuilt per request, because the resource getters and the OAuth 2 token cache live on it. +2. **Authentication** — load **typescript-authentication** before you set credentials. The scheme is `slackAuth` on `ClientOptions`. Load secrets from the environment or a secret store, never hardcode. +3. **Calling an endpoint** — load **typescript-calling-endpoints** before the first `client..(…)` call. +4. **Models** — load **typescript-models** the moment a request/response member is not a plain string or number. +5. **Error handling** — load **typescript-error-handling** before you write any `try/catch`. Every operational failure is **one family**, `SlackWebApiError`, narrowed on `err.kind`. +6. **Configuration & resilience** — load **typescript-configuration-resilience** when you set the base URL, timeouts, retries, proxies, TLS, or logging, or walk a paged operation. +7. **Testing** — load **typescript-testing** before you stub the SDK. The seam is **`ClientOptions.fetch`**. ## What a contract sheet must carry for this SDK Beyond the usual signatures and model members, a contract sheet for the Slack Web API TypeScript SDK is incomplete without these, because each one is a decision the implementer cannot make correctly from the signature alone. -1. **Which host each deployment talks to**, and where that is set. The members are `ServerEnvironment.Production`, `ServerEnvironment.Environment2`, defaulting to `ServerEnvironment.Production` when the field is unset. +1. **Which host each deployment talks to**, and where that is set. Any host but the one this SDK knows is a `serverOptions` base-URL override (see *Hosts*) — give the override path on the sheet. 2. **no operation resolves to `undefined` — every one of them carries a body** — `await` gives you nothing to inspect, so **`.asApiResult()` is the only way to observe their status and headers** — decide the mode at write time, not by retrofit. 3. **The exact request type name per operation**, taken from the **Signature** bullet. -4. **Every request field with its channel, wire name and default**, because the request object is flat and channel-blind and the SDK fans fields out. An omitted field that has a default is still sent with that default, so a defaulted header shapes the response whether or not the sheet mentions it. The generator injects an `Idempotency-Key` on every non-GET operation that does not declare that header itself — minted once per call and invisible to you. Every retry of that call re-sends the **same** key, which is what makes naming a write in `httpMethodsToRetry` safe where the provider deduplicates on it; but the next call mints a new one, so a call your own code repeats is two submissions. Any caller-supplied idempotency or request-id field is the only idempotency that spans calls, and `RequestOptions` is `{ signal, retry, logging }` only. -5. **Required vs optional vs required-nullable** for every model member the task sets — `f: T` required, `f?: T` omit the key, `f: T | null` required and nullable. And that under `exactOptionalPropertyTypes` an absent optional is **omitted or spread**, never assigned `undefined`. -6. **The error arms for each operation in scope, with the status each covers — and the warning that arm tags are schema-derived, not status codes.** Every operation rejects with its own `ApiError` subclass narrowed on `err.payload.kind`, and a tag comes from the arm's **body schema**: an arm whose body is a direct model reference is named after that model in lower camel (`"validationError"`), and every other body — a primitive, an array, a map, or no content — is named `"error{Status}"` (`"error400"`, `"error4XX"`, `"errorDefault"`), with a numeric suffix on the second of two arms that would otherwise land on the same name. The same tag means different statuses on different operations, and the same status carries different tags — so a tag is only meaningful beside the arm table it came from, and a shared helper that switches on `kind` across operations is a bug. 253 of 253 operations declare typed error bodies; the rest reject with the base `ApiError`. Every operation also carries an always-present `"undeclared"` arm holding `rawBody: ArrayBuffer`, for which **matcher precedence** matters: an exact numeric status is looked up across the whole table first, then the first covering range, and last a `"default"` arm where the spec declared one — whose body, if it does not fit, falls to `"undeclared"` rather than throwing. -7. **That a malformed or drifted 2xx body rejects with `DecodeError`, not `ApiError`, in both response modes** — `.asApiResult()` converts an HTTP error status, never any other failure. Any sheet row for a call whose result is used must name the members the implementer has to assert on, because a thin or truncated body decodes without complaint and the hole surfaces later. +4. **Every request field with its channel, wire name and default**, because the request object is flat and channel-blind and the SDK fans fields out. An omitted field that has a default is still sent with that default, so a defaulted header shapes the response whether or not the sheet mentions it. Every non-GET operation sends an `Idempotency-Key` header, minted once per call and invisible to you, unless it takes that header as a request field — `typescript-configuration-resilience` has what that key does and does not deduplicate. Any caller-supplied idempotency or request-id field is the only idempotency that spans calls, and `RequestOptions` is `{ signal, retry, logging }` only. +5. **Required vs optional vs required-nullable** for every model member the task sets — `f: T` required, `f?: T` omit the key, `f: T | null` required and nullable. +6. **The error arms for each operation in scope, with the status each covers — and the warning that arm tags are schema-derived, not status codes.** Every operation rejects with its own `ApiError` subclass narrowed on `err.payload.kind`. A tag comes from the arm's body schema and is resolved per operation, so the same tag means different statuses on different operations, and a shared helper that switches on `kind` across operations is a bug — `typescript-error-handling` has the naming rule, the always-present `"undeclared"` arm and the matcher precedence. No operation declares a typed error body, so all 253 reject with the base `ApiError`. +7. **That a malformed or drifted 2xx body rejects with `DecodeError`, not `ApiError`, in both response modes** — and the members the implementer has to assert on, because a thin or truncated body decodes without complaint. 8. **The retry policy this integration needs.** Retrying is on by default — `ClientOptions.retry` sets it for the client and `RequestOptions.retry` overrides it per call — so the sheet says whether the defaults fit, which writes (if any) join `httpMethodsToRetry`, since a write is repeated only when the policy names its method, and the per-attempt timeout. -9. **The logging this integration needs.** Logging is off by default — `ClientOptions.logging` sets it for the client and `RequestOptions.logging` sets one call's level — so the sheet says whether it stays off and, where it is on, the level, the logger, and whether headers and the request body are logged: a JSON request body is logged verbatim, with no redaction. -10. **That the SDK performs no pagination and no streaming at all**, and that `ClientOptions.fetch` is the one seam where either can be added — so whatever the task needs there is yours to build or deliberately omit. Say which. -11. A **REQUIRED READING** block naming the `typescript-*` companions that govern the steps, with inline `MUST load` pointers. +9. **The logging this integration needs.** Logging is off by default — `ClientOptions.logging` sets it for the client and `RequestOptions.logging` sets one call's level — so the sheet says whether it stays off and, where it is on, the level, the logger, and whether headers and the request body are logged (**Sensitive data**, above). +10. **That the SDK performs no streaming at all**, and that `ClientOptions.fetch` is the one seam where it can be added — so whatever the task needs there is yours to build or deliberately omit. Say which. +11. **That no operation is paged** — every call is one request, so any list the task pages is driven by hand, with a bound of its own. +12. A **REQUIRED READING** block naming the `typescript-*` companions that govern the steps, with inline `MUST load` pointers. diff --git a/plugins/slack/skills/typescript/typescript-integrate-slack-web-api/SKILL.md b/plugins/slack/skills/typescript/typescript-integrate-slack-web-api/SKILL.md index 87ba0654..874e0eee 100644 --- a/plugins/slack/skills/typescript/typescript-integrate-slack-web-api/SKILL.md +++ b/plugins/slack/skills/typescript/typescript-integrate-slack-web-api/SKILL.md @@ -1,21 +1,28 @@ --- name: "typescript-integrate-slack-web-api" -description: "MANDATORY FIRST STEP for Slack Web API TypeScript SDK work in a TypeScript or JavaScript project — load this BEFORE you write any code; TypeScript SDK ONLY, never load it for any other language. Applies when asked to integrate Slack Web API in TypeScript/Node — admin apps approve, admin apps restrict, admin apps approved list, admin apps requests list, admin apps restricted list, admin conversations archive, or when the Slack Web API TypeScript SDK errors, fails to compile, or behaves unexpectedly. Knowing the SDK exists is NOT a substitute for loading this, because it carries five binding gates stated NOWHERE else and not inferable from the package — (1) load typescript-getting-started, confirm `slack-web-api` actually resolves and read the SDK map that ships inside it before any lookup, (2) the exact plan-file path (slack-web-api-plan.md at the repo root) and the no-project-file-edits window until a contract sheet with no open lookups exists there and you have read it, (3) the mandatory load of every typescript-* companion skill the sheet names, (4) the host decision, which this SDK forces once and irreversibly — constructing the client with no options silently selects ServerEnvironment.Production, and (5) the memory ban, where every signature, request field, channel, header default, error arm and enum member comes from a lookup and never from recall or runtime introspection." +description: "MANDATORY FIRST STEP for Slack Web API TypeScript SDK (`slack-web-api`) work in a TypeScript or JavaScript project: load before writing any code — integrating Slack Web API (admin apps approve, admin apps restrict, admin apps approved list), or when the SDK errors, fails to compile or behaves unexpectedly. Sets the plan-first workflow, the contract sheet and which companion skills to load. TypeScript/JavaScript only; never load it for another language." --- # Slack Web API TypeScript SDK — Integration workflow (lookup layer + contract sheet) -You do the SDK lookups yourself: `typescript-getting-started` is your **lookup layer** — load it and ground every contract fact in it (and in the source files its table names) before writing code. The `typescript-*` companion skills are a different thing: they are API-agnostic *usage* guidance, they are yours to load, and Step 1c below makes loading them mandatory. - ## Your lookup layer -- **`typescript-getting-started`** is the entry point for every SDK need. It carries the SDK's identity (package name, version, Node floor, how it installs), the single import specifier and what the root exports, the server environments and the base-URL knob, the auth pattern, the resources, and a **file table** naming the one file that owns each kind of fact. Load it first, always. -- **The SDK map is your lookup surface, and you open it yourself.** The SDK ships `sdk-map.md` and `map/operations/` at its package root — and because `package.json`'s `files` list includes them, **installing the package puts the map in `node_modules/slack-web-api/`**. There is nothing to clone and no helper agent to delegate to. `typescript-getting-started` tells you how to traverse it: read `sdk-map.md` once, then the one resource page your operations live on. -- **The installed package is the ground truth; the file table is only the locator.** Confirm it resolves before you rely on a lookup — `node -e "console.log(require.resolve('slack-web-api/package.json'))"`. **If the resolve fails, or the directory it prints carries no `sdk-map.md`, the map is still in the SDK's own repository** — , branch `main`. Read it there, and only if neither route yields a map mark the fact `UNVERIFIED`, say what would settle it, and do not fill the hole from memory. This SDK is **not published to a registry**, so the install is a build from its source — . `typescript-getting-started`'s *Install* section carries what to run. -- **Read scoped.** Search for the one symbol and read the lines around it rather than whole files, and never copy a design comment's rationale onto a contract sheet — the sheet carries facts an implementer must obey, not the reasoning behind them. -- **Write a contract sheet with no open lookups** before you implement: exact signatures with the right request type name, every request field with its channel, wire name and default, required-vs-optional-vs-nullable members, the error arms per operation with the status each covers, and enum members for the operations in scope. `typescript-getting-started` ends with a checklist of what a sheet for this SDK is incomplete without — treat that as the checklist for your own sheet, and collect every in-scope operation in ONE pass rather than re-opening a map page per field. +- **`typescript-getting-started`** is the entry point for every SDK need: identity, install, imports, environments, auth, resources, and a **file table** naming the one file that owns each kind of fact. Load it first, always. +- **The SDK map is your lookup surface.** The SDK ships `sdk-map.md` and `map/operations/` at its package root — and because `package.json`'s `files` list includes them, **installing the package puts the map in `node_modules/slack-web-api/`**. `typescript-getting-started` tells you how to traverse it: read `sdk-map.md` once, then the one resource page your operations live on. +- **The installed package is the ground truth; the file table is only the locator.** Confirm it resolves before you rely on a lookup — `node -e "console.log(require.resolve('slack-web-api/package.json'))"`. **If the resolve fails, or the directory it prints carries no `sdk-map.md`, the map is still in the SDK's own repository** — , branch `main`. Read it there, and only if neither route yields a map mark the fact `UNVERIFIED` and say what would settle it. This SDK is **not published to a registry**, so the install is a build from its source — . `typescript-getting-started`'s *Install* section carries what to run. +- **Write a contract sheet with no open lookups** before you implement: exact signatures with the right request type name, every request field with its channel, wire name and default, required-vs-optional-vs-nullable members, the error arms per operation with the status each covers, which operations are paged and the bound each walk takes, and enum members for the operations in scope. `typescript-getting-started` ends with a checklist of what a sheet for this SDK is incomplete without — treat that as the checklist for your own sheet, and collect every in-scope operation in ONE pass rather than re-opening a map page per field. + +## The planner agent + +`slack-web-api-planner` ships with this plugin. It writes `slack-web-api-plan.md` — the plan and its contract sheet — and revises it in place; it writes no project code. Start it the first of these ways your host allows: + +1. **Your subagent tool lists it.** Some hosts list a plugin's agents under the plugin's name, as `slack:slack-web-api-planner`; start it by whichever of the two names your subagent tool lists. +2. **It isn't listed, or you can't start a subagent.** Tell the user in one line that you are writing the plan yourself, then do so as *Step 1* describes. Don't stop to ask. + +However you start it: -**Scope guard:** the APIMatic-generated Slack Web API **TypeScript SDK** (package and import specifier `slack-web-api`, client `SlackWebApiClient`) in **TypeScript or JavaScript projects only**. Unrelated API, or any language other than TypeScript/JavaScript — do nothing; this skill does not apply. +- **Start it on the same model you are running on.** If your subagent tool takes a model, pass your own model; if it has no model option, leave its default. Tell the user in one line which model you started it on. +- **Start it once per integration.** A plan revision is a follow-up message to that same agent; re-start it, carrying the clarification and the plan path, only where your host cannot message it. Never start a second one for the same integration. ## Workflow @@ -23,26 +30,30 @@ You do the SDK lookups yourself: `typescript-getting-started` is your **lookup l ### Step 1 — Plan first (always, for any implementation work) -Your FIRST action is to load `typescript-getting-started` and work through the user's full request (all features in scope — one plan covers the whole implementation). Load `typescript-error-handling` before you write the plan too: table 1b.4 is decided from it. Then write the plan and its contract sheet to `/slack-web-api-plan.md` — that absolute path, not a location you pick later. +Your FIRST action, once the SDK is installed (installing it is a prerequisite the gate allows, below, and it follows the toolchain check and the baseline), is to start **`slack-web-api-planner`**, as *The planner agent* says, once, with the user's full request — all features in scope; one plan covers the whole implementation — and the name of this skill, `typescript-integrate-slack-web-api`. Dictate in its task the absolute project root and the absolute path it must write to — `/slack-web-api-plan.md`, that absolute path, not a location you pick later. It loads `typescript-getting-started` and `typescript-error-handling` — table 1b.4 is decided from it — writes the plan and its contract sheet as Steps 1 to 1c describe, and returns the file's path. -**Do the read-only prerequisites in the same pass — they need no SDK knowledge and touch no project file:** +**If you couldn't start the planner** (case 2 in *The planner agent*), load both skills yourself, work through the request, and write the file at that path. + +**Do these two read-only prerequisites before you install the SDK — the install changes the tree they read:** -- the repo survey (read-only exploration of conventions, layering, **module format — ESM or CJS, which changes how the SDK is imported and whether `instanceof` on its error classes is trustworthy**, and the runtime: Node, a bundled browser app, or an edge runtime) — capture each convention as *pattern + the ONE exemplar file path to imitate*, NOT inline code snippets: you will read the exemplar at edit time anyway, so a snippet dump gets paid for twice; - **establish the toolchain before you need it**: the package manager, whether `slack-web-api` is already a dependency and at what version, the `tsconfig` flags that change what compiles here (`exactOptionalPropertyTypes`, `verbatimModuleSyntax`, `strict`), and the exact commands that run the project's build, type check, lint and tests. Getting this wrong later costs a broken install mid-implementation — and an uninstalled package costs you the lookup layer itself, since the map ships inside it; -- a baseline run of the project's checks (`tsc --noEmit`, the test runner, the linter — whatever it has) on the UNTOUCHED tree, so later failures are attributable to your changes; -- credentials/environment verification (per the task's secret-handling rules) — **including which host this deployment will actually talk to**, since constructing the client with no options silently selects `ServerEnvironment.Production`, and the other environment is reached only by setting it; -- **a read-only smoke of each in-scope operation against the real credential**, run from your scratchpad, not the project, once the map has given you the signatures and before you finalise the sheet. A plan-, region- or entitlement-gated endpoint answers `403` here — the map presents every operation uniformly and cannot know which ones your credential may call — and learning that now reorders the plan rather than the build. Skip only operations whose side effects you cannot reverse; +- a baseline run of the project's checks (`tsc --noEmit`, the test runner, the linter — whatever it has) on the UNTOUCHED tree, so later failures are attributable to your changes. + +**Do the rest while the planner works — they need no SDK knowledge and touch no project file:** + +- the repo survey (read-only exploration of conventions, layering, **module format — ESM or CJS, which changes how the SDK is imported and whether `instanceof` on its error classes is trustworthy**, and the runtime: Node, a bundled browser app, or an edge runtime) — capture each convention as *pattern + the ONE exemplar file path to imitate*, NOT inline code snippets: you will read the exemplar at edit time anyway, so a snippet dump gets paid for twice; +- credentials/environment verification (per the task's secret-handling rules) — **including which host this deployment will actually talk to**, since this SDK has one environment and no `ServerEnvironment`, so **any other host is a `serverOptions` base-URL override rather than an environment value**; - setting up your task tracking. -Never use the planning phase to get a "head start" on implementation: **creating or editing ANY project file before the gate below is a defect**, no matter how obvious the code seems. +**HARD GATE — no project-file creation or edits until:** the planner has RETURNED, `slack-web-api-plan.md` EXISTS at the repo root (check it — a helper can misreport where it saved), its contract sheet has **no open lookups**, and you have read it. If you wrote the plan yourself, the gate is the same without the return. **Creating or editing ANY project file before then is a defect**, however obvious the code seems; the read-only prerequisite work above is allowed meanwhile. -**HARD GATE — no project-file creation or edits until:** `slack-web-api-plan.md` EXISTS at the repo root, its contract sheet has **no open lookups**, and you have read it. The gate bars coding "meanwhile"; it does not bar the read-only prerequisite work above. Starting to code before the sheet exists defeats the entire plan-first design. +**What the gate does not cover:** installing `slack-web-api` into the project, installing the toolchain, and the files those writes produce (`node_modules/`, a lockfile the installer updates) are **prerequisites, not project-file edits** — the map lives inside the installed package — and they are the only writes permitted before the gate. -**What the gate does not cover:** installing `slack-web-api` into the project, installing the toolchain, and the files those writes produce (`node_modules/`, a lockfile the installer updates) are **prerequisites, not project-file edits**. On a greenfield repo they are the only way to reach the lookup layer at all — the map lives inside the installed package — and they are the only writes permitted before the gate. Nothing you author by hand may change. +**One read-only prerequisite waits for the signatures: a smoke of each in-scope operation against the real credential**, run from your scratchpad, not the project, once the planner has returned and you have read the sheet, with the signatures it records, and before your first project edit — or, if you are writing the plan yourself, once the map has given you the signatures and before you finalise the sheet. A plan-, region- or entitlement-gated endpoint answers `403` here — the map presents every operation uniformly and cannot know which ones your credential may call — and learning that now reorders the plan rather than the build. Send each `403` to the SAME planner as a revision, as *Step 1c* sends a blocker, and implement from its reply; if you wrote the plan yourself, revise the sheet in place. Skip only operations whose side effects you cannot reverse. ### Step 1b — The tables the contract sheet must carry (fill these in before you write any code) -The per-operation rows describe **what each operation is**. The tables below carry what those rows cannot: a write that may reach the provider twice or whose outcome you may not learn, a rule that spans two operations, and a field nobody asked for. Fill in every one that applies before any code exists. +The per-operation rows describe **what each operation is**. The tables below carry what those rows cannot: a write that may reach the provider twice or whose outcome you may not learn, a rule that spans two operations, and a field nobody asked for. Fill in every one that applies. #### 1b.1 — DURABLE WRITES @@ -57,7 +68,7 @@ One row in each table below per operation in scope that creates, sends or change **Where that rejection is caught**: the `catch` for what the store raises on the second claim, recognised by the driver's error code rather than its message; the losing caller then uses the record the winner wrote. -The SDK sends an `Idempotency-Key` minted once per call, and its own retries resend that key — but a second click or a retry of your own is a new call with a new key, so the provider cannot join the two. The key goes beside the claim, never in place of it; where the operation declares its own key, send the reference stored on the claim (see `typescript-configuration-resilience`). +The SDK's own `Idempotency-Key` is new on every call (*Making a write safe under retries* in `typescript-configuration-resilience`), so it goes beside the claim, never in place of it; where the operation declares its own key, send the reference stored on the claim. **UNKNOWN OUTCOMES** — what settles a write the provider may have acted on without your code learning the answer. @@ -66,7 +77,7 @@ The SDK sends an `Idempotency-Key` minted once per call, and its own retries res ⚠⚠ A `ConnectionError` or `TimeoutError` on a write is *unknown*, not *failed*: the provider may already have acted. Reporting a failure is not a legal entry, and neither is leaving the caller to check or retry. Settle it in that write's own `catch`: re-read by the reference you sent — found, settle from what the provider holds; not found, or the re-read itself fails, still unknown, never failed. Telling the caller the outcome is unknown comes after the re-read, never instead of it. If the provider offers no way to find the write, that is a **Blocker** in Assumptions & Blockers, not a row. -A write that never left has nothing to re-read — a credential that could not be obtained (`AuthError`) or a value that would not encode (`EncodeError`) — and must reach a different outcome. Re-reading after every error is not the safe default: "any error might mean it went through" is false for a request that never left, so a refused credential gets its own outcome and no re-read. **The test that fails the connection** asserts the re-read request was made; a second test, a never-sent failure on the same write, asserts it was not. +A write that never left — a credential that could not be obtained (`AuthError`) or a value that would not encode (`EncodeError`) — has nothing to re-read and gets its own outcome. **The test that fails the connection** asserts the re-read request was made; a second test, a never-sent failure on the same write, asserts it was not. Write `TBD` in **Where in the code** and **The test that fails the connection** while you plan — every row. Once the code compiles, replace each `TBD` individually: the claim write, then the SDK call it precedes; the `catch`, then the re-read it makes. ⚠⚠ A `TBD` left behind, a name that is not in the code, or one note covering several rows is **not addressed**; if the code does not do what the row says, fix the code, then the cell. @@ -118,44 +129,42 @@ Logging the reason is not returning it: log it **and** put it in the response. End the contract sheet with a **REQUIRED READING** block whose rows carry inline `MUST load ` pointers. **Load every `typescript-*` skill the sheet names, now, before you start implementing** — not lazily at the step that needs it. The sheet deliberately does *not* carry the how-to: it names the hazard and hands you the skill that resolves it, so an unloaded pointer is a gap in what you know, not a formality. -**A fixed floor applies regardless of what the sheet says** — the sheet can add to it, never remove from it: `typescript-error-handling` always (every integration writes an error boundary, and this SDK's one error family is narrowed on its closed `kind`, with four throwables outside it that a family test has to rethrow); `typescript-client-initialization` before the client is constructed; `typescript-testing` before the first test file you create or edit, *including* a throwaway verification script that fakes `fetch`. A sheet row that excuses one of these ("out of scope", "no test suite requested") is not a substitute for loading it. +**A fixed floor applies regardless of what the sheet says** — the sheet can add to it, never remove from it: `typescript-error-handling` always (every integration writes an error boundary); `typescript-client-initialization` before the client is constructed; `typescript-testing` before the first test file you create or edit, *including* a throwaway verification script that fakes `fetch`. -These are API-agnostic usage skills; loading them is not a substitute for the lookup layer, and reading a file in the installed package does not remove the need to load the skill for that step. Contract *facts* still come only from your sheet or a fresh lookup. +These are API-agnostic usage skills; loading them is not a substitute for the lookup layer, and reading a file in the installed package does not remove the need to load the skill for that step. Before implementing, check the plan's **Assumptions & Blockers** section: -- Blocker or major assumption → surface it to the user in plain language, get their answer, and revise `slack-web-api-plan.md` in place. +- Blocker or major assumption → surface it to the user in plain language, get their answer, and send it to the SAME planner as a follow-up message (re-start it, carrying the clarification and the plan path, only where your host cannot message it). It revises `slack-web-api-plan.md` in place and replies with the changed rows verbatim: work from that reply, not a re-read of the file. If you wrote the plan yourself, revise it in place. - Minor assumptions only → proceed. Full re-planning only on genuine scope change; for a single missing fact mid-implementation, do the lookup, never guess. ### Step 2 — Implement from the contract sheet -1. Read `slack-web-api-plan.md` once. Treat its contracts as authoritative — do not re-derive or "double-check" them from memory. When a lookup revises a row, update the file so the sheet and the code never disagree. -2. **Decide which environment this deployment talks to, explicitly, before the first call.** Constructing the client with no options selects `ServerEnvironment.Production` **silently**, so an unset field is indistinguishable from a deliberate choice of the default. Bind it to configuration and fail startup if the (environment, credential) pair is not the one this deployment intends — a credential pointed at the wrong host is not a defect any call site can correct. -3. **Build the client once and hold it.** Resources are memoized lazy getters on it and the OAuth 2 token cache lives on it, so rebuilding one per request throws that state away. There is no `close()` — it owns a `fetch`, not a pool. -4. **Pick the response mode per call, deliberately.** Every operation returns `ApiPromise`: `await` it and an error status rejects, or call `.asApiResult()` **on the value the operation returned** for the non-throwing `ApiResult` — the only way to see the status and headers of a *success*, and therefore the only way to observe anything at all from an operation whose success carries no body. `ApiPromise` overrides `Symbol.species`, so `.then()`/`.catch()`/`.finally()` hand back a plain `Promise` with the method gone — the mode is chosen at write time, never retrofitted. -5. Implement sequentially, following the repo's own conventions and layering. You loaded the companion skills the sheet named in Step 1c — implement each step in line with the one that governs it. Take every contract *fact* (signatures, field names, channels, error arms, enum members) from the contract sheet or a fresh lookup — never re-derive one from a companion. -6. After every change: run the project's **type checker** (`tsc --noEmit`) as well as its tests. The package ships its own types and is generated under strict TypeScript, so a type error against it is a real contract violation, not noise — it is the compile-time backstop the whole map-first discipline leans on. **Treat a clean type check as the gate you do not skip.** If the project has no type check configured, run `tsc --noEmit` over the files you touched; if you genuinely cannot, say so in your final report rather than silently substituting a smoke run. Fix non-SDK errors yourself. -7. **Any error involving an SDK type or member** — `TS2339` (property does not exist), `TS2345`/`TS2322` (argument or assignment mismatch), `TS2551` (did you mean), `TS2307` (cannot find module — usually a deep import), `TS2739`/`TS2741` (missing required members), or an unexpected rejection at runtime — → go back to `typescript-getting-started`'s map section and file table, and read the one page or file that owns the fact. Do not attempt more than one self-fix of an SDK-name error before doing that lookup: rewriting from the same knowledge that produced the error is guessing. Remember which failures are **not** `ApiError`: a malformed body is `DecodeError`, a value that would not encode `EncodeError`, a dropped connection `ConnectionError`, an attempt's timeout `TimeoutError` (both only after any retries are spent), a credential that could not be **obtained** `AuthError` — every one of them in the `SlackWebApiError` family, told apart by `err.kind` — and an unknown `serverEnvironment` throws `ConfigurationError` out of the client constructor, before any call exists. So an exception that does not look like an API error may still be one of the SDK's failure kinds. +1. Read `slack-web-api-plan.md` once and treat its contracts as authoritative. When a lookup revises a row, update the file so the sheet and the code never disagree. +2. **Decide which host this deployment talks to, explicitly, before the first call.** Nothing in the options records **which** deployment a base-URL override is, so bind it to configuration and fail startup if the (host, credential) pair is not the one this deployment intends. +3. **Build the client once and hold it.** Resources are memoized lazy getters on it and the OAuth 2 token cache lives on it, so rebuilding one per request throws that state away. +4. **Pick the response mode per call, deliberately.** Every operation returns `ApiPromise`: `await` it and an error status rejects, or call `.asApiResult()` on the value the operation returned for the non-throwing `ApiResult` — the only way to see the status and headers of a *success*, and therefore the only way to observe anything at all from an operation whose success carries no body. `typescript-calling-endpoints` has the mechanics. No operation is paged. +5. Implement sequentially, following the repo's own conventions and layering and the companion skill that governs each step. +6. After every change: run the project's **type checker** (`tsc --noEmit`) as well as its tests. The package ships its own types, so a type error against it is a real contract violation, not noise — it is the compile-time backstop the whole map-first discipline leans on. **Treat a clean type check as the gate you do not skip.** If the project has no type check configured, run `tsc --noEmit` over the files you touched; if you genuinely cannot, say so in your final report rather than silently substituting a smoke run. Fix non-SDK errors yourself. +7. **Any error involving an SDK type or member** — `TS2339` (property does not exist), `TS2345`/`TS2322` (argument or assignment mismatch), `TS2551` (did you mean), `TS2307` (cannot find module — usually a deep import), `TS2739`/`TS2741` (missing required members), or an unexpected rejection at runtime — → go back to `typescript-getting-started`'s map section and file table, and read the one page or file that owns the fact. Do not attempt more than one self-fix of an SDK-name error before doing that lookup: rewriting from the same knowledge that produced the error is guessing. A failure that is not an `ApiError` — `DecodeError`, `EncodeError`, `ConnectionError`, `TimeoutError`, `AuthError` — is still in the `SlackWebApiError` family, told apart by `err.kind` (`typescript-error-handling`). 8. Once the code is complete, open each member the **DUPLICATE CLAIMS** and **UNKNOWN OUTCOMES** rows name and confirm it runs when that write runs. Where the code falls short of a row, fix the code, not the row. -9. **Observability and sensitive data.** Logging is **off by default** and is configured through `ClientOptions.logging`: say whether the integration turns it on, at what level, and which correlation id from the provider's error bodies reaches your own logs. A JSON request body is logged **verbatim** when `logRequestBody` is on, and a form body is masked only by deny-list, so a key you have not listed prints in the clear. If the scope carries data you would not want in a log — each request model's declaring file lists every field in scope — `logRequestBody` stays off, no call on those paths passes a per-call level, which turns the body on, **and** `ClientOptions.logging.level` is set explicitly, so the `SLACK_WEB_API_CLIENT_LOG` environment variable cannot switch logging on from outside the code (see `typescript-getting-started`). +9. **Observability and sensitive data.** Logging is **off by default** and is configured through `ClientOptions.logging`: say whether the integration turns it on, at what level, and which correlation id from the provider's error bodies reaches your own logs. If the scope carries data you would not want in a log, follow the **Sensitive data** rules in `typescript-getting-started`. 10. Run the project's tests; verify the integration end to end the way the task demands. Retrying is **on by default**, so if the task needs a different policy, tune it through `ClientOptions.retry` rather than wrapping the call. The SDK has no hooks or middleware, so anything the task needs there is yours to build on the `ClientOptions.fetch` seam or to deliberately omit — say which you did for both. ### Step 3 — Answering pure questions -A standalone Slack Web API question with no code change: look it up in `typescript-getting-started` (and the map page or file its table names), then give the grounded answer, citing where it came from. When several questions arrive batched, answer them in one pass. Never answer from memory, even for "easy" questions. +A standalone Slack Web API question with no code change: look it up in `typescript-getting-started` (and the map page or file its table names), then give the grounded answer, citing where it came from. When several questions arrive batched, answer them in one pass. ## Anti-patterns — never do these -- **Always load `typescript-getting-started` first.** It is your lookup layer, not optional background. (The `typescript-*` companions are the complement: load the ones the sheet names, per Step 1c.) Don't re-derive a contract *fact* from a companion — exact signatures, request fields, channels, error arms and enum members come from the sheet or a fresh lookup. -- **Never write any Slack Web API or SDK fact from memory** — every signature, field name, wire header, enum member, and error arm in your code must come from the contract sheet or a lookup. And **never write a call from memory "to fix later".** -- **Never switch on an error arm tag across operations.** A tag is derived from the arm's **body schema**, never from its status: an arm whose body is a direct model reference is named after that model in lower camel (`"validationError"`), and every other body — a primitive, an array, a map, or no content — is named `"error{Status}"` (`"error400"`, `"error4XX"`, `"errorDefault"`), with a numeric suffix on the second of two arms that would otherwise land on the same name. Tags are resolved **per operation**, so the same tag covers different statuses on different operations — a shared handler keyed on `err.payload.kind` is a bug. Read the status from `err.status`, and narrow on `kind` only against the arm table of that one operation. +- **Never create or edit a project file while `slack-web-api-planner` is running**, and never start a second one for the same integration. +- **Never write or state any Slack Web API or SDK fact from memory** — every signature, field name, wire header, enum member, and error arm must come from the contract sheet or a fresh lookup, never from recall or from a companion skill. And **never write a call from memory "to fix later".** +- **Never switch on an error arm tag across operations.** A tag comes from the arm's **body schema**, not its status, and is resolved **per operation**, so the same tag covers different statuses on different operations — a shared handler keyed on `err.payload.kind` is a bug (`typescript-error-handling` has the naming rule). Read the status from `err.status`, and narrow on `kind` only against the arm table of that one operation. +- **Never hand-advance a paging field on a paged operation, and never leave a walk unbounded.** An operation whose **Signature** returns `Pageable` is walked with `for await` or `.pages()`: the SDK seeds the first page from the request and advances the state itself, so a loop that re-calls the operation with the next page number walks the rest of the list again on every call and repeats its items. A walk ends only when the API stops handing out pages, so it carries a bound of your own — a page cap, an item cap or a deadline. - **Don't web-search Slack Web API topics to find an implementation detail** — the installed package's own map and source are the ground truth, and the file table tells you where to look. Public Slack Web API docs describe the HTTP API, not this SDK's generated surface, and the two disagree on names, on which fields are required, and on what the SDK sends by default. - **Never introspect the SDK at run time to discover its shape.** `Object.keys`, logging a client instance, or a REPL poke is the TypeScript-flavoured version of decompiling the package: it answers what exists, never what is *supported*, and it invites `#`-private fields and unexported engine types into your code. Read the map, then the file it names. -- **Don't grep the package to *locate* a type** — the SDK map is the locator (and says so: *"Do not derive the path from the type name"*); grep only *inside* the file its **Type sources** table names, for the symbol. A sweep for a *shape* is a different thing, and is fine: "every field typed `unknown`", "every required-nullable member" are cross-cutting questions nothing indexes, and one targeted `grep -rn` over `src/models/` is the right tool for them — record what it found on the sheet. -- **Don't deep-import from the package** (`slack-web-api/models/…`). The package root is the only entry and deep specifiers do not resolve; the map's `Source` paths are for reading, not importing. +- **Don't grep the package to *locate* a type, deep-import from it (`slack-web-api/models/…`), or vendor its `src/`** — `typescript-getting-started`'s *Contract facts*, *Imports* and *Install* sections say what to do instead. - **Don't assume a name is a global.** The package root re-exports every public type, so an unaliased import shadows any same-named global for the rest of the file — check the name against the map before importing it plain. -- **Don't vendor the SDK's `src/` into the project, point `tsconfig` `paths` at a throwaway clone, or import from `dist/` directly** to make a lookup possible. Install it properly (see `typescript-getting-started`); a clone-based shortcut breaks every import the moment the clone is deleted, and it does not put the map where the lookups expect it. -- **Don't create or edit project files before the HARD GATE** in Step 1 — plan and contract sheet first, code second. diff --git a/plugins/slack/skills/typescript/typescript-models/SKILL.md b/plugins/slack/skills/typescript/typescript-models/SKILL.md index ca6fed29..9a0168d8 100644 --- a/plugins/slack/skills/typescript/typescript-models/SKILL.md +++ b/plugins/slack/skills/typescript/typescript-models/SKILL.md @@ -1,6 +1,6 @@ --- -name: typescript-models -description: Working with models in an APIMatic-generated TypeScript SDK — building request bodies from plain object literals, required members and optional-versus-nullable fields, open enums, discriminated and undiscriminated unions, the four date codecs, and the schema companion beside every type. Load before constructing a request payload or mapping SDK models onto your own domain types. +name: "typescript-models" +description: "Load before building a request payload for an APIMatic-generated TypeScript SDK or mapping its models onto your own types — object-literal models, optional versus nullable fields, open enums, discriminated and plain unions, date codecs, bytes, unknown fields, and the schema companion beside every type." --- # Working with models in an APIMatic TypeScript SDK @@ -14,19 +14,15 @@ import { type {Model}, {model}Schema } from "{package-name}"; const body: {Model} = { {requiredField}: "..." }; ``` -**There is exactly one spelling.** No companion dict type, no builder, no factory and no static -helper: an object literal is how every model is built, at every nesting level. And **nothing is -frozen** — no property is emitted `readonly`, so a decoded response is an ordinary mutable object. -Mutating one is allowed but is not a wire operation: what you changed reaches the API only by passing -the value to an operation, or by re-encoding it yourself. +An object literal is how every model is built, at every nesting level. **Nothing is `readonly` or +frozen**: a decoded response is an ordinary mutable object, and a change reaches the API only when you +pass the value to an operation, or re-encode it yourself. -Two exports per model — the type and a `{model}Schema` value — and both come from the **package -root**; deep imports do not resolve. This skill covers the **non-obvious model shapes** that trip -integrations up. The patterns are generic across APIMatic TypeScript SDKs; take the real type and -field names from the contract sheet — the **Models** section of `sdk-map.md` and the **Type sources** -table on the operation's block in `map/operations/*.md`, both grounded in the `src/models/` the -package ships — never from a compiled `dist/`, and never from a path derived off the type name. The -`Source` column is where to **read** a shape, never what to import. +Two exports per model — the type and a `{model}Schema` value — both from the **package root** +(**typescript-client-initialization**). Take the real type and field names from the **Models** section +of `sdk-map.md` or an operation's **Type sources** table in `map/operations/*.md` — never from a +compiled `dist/`, and never from a path derived off the type name. The `Source` column is where to +**read** a shape, never what to import. > Throughout this skill, `{...}` is a placeholder for a name you take from your SDK (e.g. `{Model}`, > `{Union}`, `{Variant}`, `{Enum}`, `{package-name}`) — replace it with the concrete identifier from @@ -34,18 +30,17 @@ package ships — never from a compiled `dist/`, and never from a path derived o ## Where a model lives -| Group (as `sdk-map.md` names it) | Directory | What is emitted | +| Group (as `sdk-map.md` names it) | Directory | What it is | | --- | --- | --- | | Objects, and `allOf` (flattened) | `src/models/` | one `type` with the properties, plus its schema | | Enums (open; const companion plus schema) | `src/models/` | `as const` object + open type alias + schema | | Discriminated unions (`oneOf`) | `src/models/unions/` | union of tag-narrowed arms + dispatching schema | | Unions without a discriminant (`anyOf`) | `src/models/unions/` | a bare union type + an accepting schema | -Two consequences worth internalising. **`allOf` is flattened** into one plain object type — every -constituent's properties restated on one type, with no inheritance, no base type to assign to and -nothing recording the composition. And **an object schema that `allOf` subtypes made a polymorphic -base is emitted as a discriminated union**, not as a base type, so it lands under `unions/` too: -there is nothing to upcast to, and you narrow on the tag instead. +**`allOf` is flattened** into one plain object type — every constituent's properties on one type, with +no inheritance and no base type to assign to. **A polymorphic base** (an object that `allOf` subtypes +derive from) is a discriminated union under `unions/`, not a base type: there is nothing to upcast to, +and you narrow on the tag instead. ## Required, optional, nullable @@ -68,29 +63,27 @@ const ok: {Model} = { id: "1" }; // const also: {Model} = { id: "1", ...(label !== undefined ? { label } : {}) }; // conditional ``` -At run time an explicit `undefined` is dropped from the JSON anyway (a property with a spec default -sends its default instead, below), so that one is a type-level constraint. `null` is not: a nullable field set to `null` sends JSON `null`, which is a different +At run time an explicit `undefined` is treated as omitted anyway, so that one is a type-level +constraint. `null` is not: a nullable field set to `null` sends JSON `null`, which is a different request from an absent key — the distinction that matters on a PATCH. -**A model property with a spec default is optional in the type and `s.defaulted(...)` in its schema.** -Omitting it, or passing `undefined`, still sends the default (on a partial update, send its current value +**A model property whose schema is `s.defaulted(...)` has a default.** It is optional in the type; +omitting it, or passing `undefined`, still sends the default (on a partial update, send its current value instead), and a response that omits it reads back as the default. ### Reading one back -An absent optional is simply `undefined` (one with a spec default reads back that default) — there -is no sentinel value to import and nothing to -compare against, so `?.` and `??` are the whole toolkit, and, on a property without a spec default, `!== undefined` is the precise test when -"present but empty" and "absent" are different facts. Under `noUncheckedIndexedAccess` an array index -is `T | undefined` too, so guard `items[0]` before reaching through it. +An absent optional is simply `undefined` — there is no sentinel value to import and nothing to +compare against, so `?.` and `??` are the whole toolkit, and, on a property with no default, +`!== undefined` is the precise test when "present but empty" and "absent" are different facts. Under +`noUncheckedIndexedAccess` an array index is `T | undefined` too, so guard `items[0]` before reaching +through it. -⚠ **A response type whose spec marks nothing required decodes an empty body without complaint** — -every property reads back `undefined`, or its default, and nothing throws. A truncated or partial body is therefore -not an error, it is a model full of `undefined`; check the properties you actually depend on. A -property that is required on a request type and optional on the response type is normal and -intentional — two schemas for one concept — so never infer the response shape from the request shape. -Both are in the map: the operation's **Fields** table for the request, the **Type sources** file for -the response. +⚠ **A response type with no required properties decodes an empty or truncated body without +complaint** — every property reads `undefined`, or its default, and nothing throws; check the properties +you depend on. Request and response types for one concept can differ in requiredness, so never infer the +response shape from the request shape: read each from the map (the operation's **Fields** table for the +request, the **Type sources** file for the response). ## Polymorphic union types: discriminated and undiscriminated @@ -111,13 +104,10 @@ An `anyOf` becomes a bare union with nothing to switch on — `export type {Unio — and its schema tries the arms in **declaration order**, first match winning, so overlapping arms are resolved by order. -⚠ **A payload matching no arm throws.** Both kinds fail the decode — through an operation as a -`DecodeError` whose `cause` is the `SchemaError`, through a schema you call directly as the -`SchemaError` itself — an unrecognized tag has no arm to dispatch to, and an undiscriminated union that matches nothing has no -arm to fall back on. You do not get a null union or an unset variant. A provider that adds a variant -your SDK predates turns into a decode failure on a call that was previously fine, so a union field is -a place to expect regeneration pressure. See **typescript-error-handling** for where that surfaces in -a catch ladder. +⚠ **A payload matching no arm throws** — through an operation as a `DecodeError` whose `cause` is the +`SchemaError`, through a schema you call directly as the `SchemaError` itself. There is no null or +unset variant, so a variant the provider adds later breaks a call that used to work. See +**typescript-error-handling** for where that surfaces in a catch ladder. ### Construct @@ -151,8 +141,7 @@ that renamed it has the rename applied on the way out, so the type alias spells the schema names what was sent. Take the exact tag and arm names from the **Unions** table in `sdk-map.md` (`Union` · `Variants` · `Narrow with` · `Source`) rather than deriving them. -A union the spec left unconstrained degrades to `unknown`. That is the generator reporting that the -spec constrained nothing, not a bug. +A union with nothing constrained is typed `unknown`. ## Collections @@ -162,7 +151,7 @@ convert. | Value | On the wire | | --- | --- | -| omitted / `undefined` | key absent, or the spec default if it has one | +| omitted / `undefined` | key absent, or its default if it has one | | `null` on a nullable field | `null` | | `[]` | `[]` | | `{}` | `{}` | @@ -197,7 +186,7 @@ convert. money as a **`string`** scaled to the currency (`"10.00"`) — where yours does, keep it a string end to end: formatting it through `Number` and back is what silently turns `"10.10"` into `10.1`. -- **A field the spec pinned to one value** is typed as that literal and checked with +- **A field pinned to one value** is typed as that literal and checked with `s.literal(...)`: `status: "accepted"` admits that one value and nothing else, in either direction. ## Bytes @@ -210,38 +199,31 @@ const body: {Model} = { payload: new TextEncoder().encode("hello") }; const text = new TextDecoder().decode(model.payload); ``` -That is for base64-in-JSON fields only, and it is **not** the file-upload carrier. The engine does -send raw-binary and multipart bodies, but a file there is a `FileInput` — bytes the transport frames -rather than a value a schema encodes — and the two deliberately never unify: a decoded `Uint8Array` -field is not assignable to a file field, and `new Uint8Array(value)` is the one-copy bridge (see -**typescript-calling-endpoints**). +That is for base64-in-JSON fields only, and it is **not** the file-upload carrier: a raw-binary body +or multipart file takes a `FileInput` (**typescript-calling-endpoints**), and a decoded `Uint8Array` +field is not assignable to one — `new Uint8Array(value)` is the one-copy bridge. ## What the schema checks — and what it does not -Model schemas are built on `zod/v4-mini`, and what they verify is much narrower than what the API -definition said. Checked: the **primitive type** of each property, the presence of required keys, the -four date formats, base64, a pinned literal, and a union's arms. Not checked — because the generator -does not transcribe these at all, so there is no attribute to read and no validator to invoke: +Checked by an operation, in both directions: the **primitive type** of each property, the presence of +required keys, the four date formats, base64, a pinned literal, and a union's arms. **Never checked by +an operation**: - **String formats.** A uuid, email, uri, hostname, ip, password, json-pointer, regex-constrained - string and a bare `time` are all emitted as plain `string` with `s.string()`. Nothing validates the - shape in either direction: an email field accepts `"not an email"` and sends it. -- **Bounds and lengths.** No `minLength`, `maxLength`, `minimum`, `maximum`, `multipleOf`, - `uniqueItems` or `pattern` reaches the generated code. -- **`additionalProperties: false`.** Not enforced; see *Unknown / future fields* below. - -The provider is therefore the only enforcer of those, and it enforces them as a `400` you have to -interpret. Where you want a client-side guard — worth it on user-supplied input before a write, where -a rejected request costs a round-trip and an error path — write it at your own boundary and read the -constraints from `api-reference.md`, which does carry the API's documented contract. - -What the schema *does* check, it checks in **both** directions: encoding runs before the request is -built, so an invalid model rejects the call with an `EncodeError` — its `cause` the `SchemaError` -naming the field — and **nothing is sent**. Read that failure as the SDK -catching your mistake at the point you made it, not as an upstream fault — the compiler catches the -shape and the schema catches the values, and between them very little reaches the network wrong. In -production, catch it at the boundary where *you* assemble a payload from external input and treat it -as a 4xx on your own API. + string and a bare `time` travel as plain `string`: an email field is sent as `"not an email"`. +- **Bounds and lengths** — `minLength`, `maxLength`, `minimum`, `maximum`, `multipleOf`, + `uniqueItems`, `pattern`. +- **`additionalProperties: false`** — see *Unknown / future fields* below. + +An operation never refuses a value for one of those; the provider does, as a `400` you have to +interpret. **`{model}Schema.validate` does check the formats, bounds and lengths the spec declares** — +see *Checking a value before you send it* below — so pass user-supplied input through it before a +write, where a rejected request costs a round-trip and an error path. `api-reference.md` carries the +documented contract either way. + +An invalid model rejects the call with `EncodeError` — its `cause` the `SchemaError` naming the field — +and **nothing is sent**. In production, catch it at the boundary where *you* assemble a payload from +external input and treat it as a 4xx on your own API. ## Enums @@ -256,14 +238,14 @@ export const {enum}Schema = s.enumOf<{Enum}>({Enum}); - **The name is a value and a type at once.** Import it *without* `type` wherever you use its members — `import { {Enum}, {enum}Schema } from "{package-name}"` — since a type-only import makes - `{Enum}.Active` a compile error. Prefer the member over the bare literal: a spec change that + `{Enum}.Active` a compile error. Prefer the member over the bare literal: an SDK update that renames the value then fails to compile instead of failing in production. - **The type is open.** The `(string & {})` tail — `(number & {})` on a number enum — means any value of the base type is assignable. - **The schema validates the base type only, never membership.** A string enum accepts any string, a - number enum any number, so a value the provider added after generation round-trips instead of - throwing. That is deliberate, and it is why a `switch` over a **received** enum value needs a - `default` arm — the opposite of a discriminated union, whose unrecognized tag does throw. + number enum any number, so a value newer than the SDK round-trips instead of throwing. That is + deliberate, and it is why a `switch` over a **received** enum value needs a `default` arm — the + opposite of a discriminated union, whose unrecognized tag does throw. ```ts if ({enum}Schema.values.includes(received)) { /* a member this SDK knows */ } @@ -296,29 +278,27 @@ divergences are listed once, in the **Wire-name divergences** table in `sdk-map. ## Unknown / future fields -Model schemas are built on a **loose** object, so keys the model does not declare are **kept**, not -stripped, in both directions — a field the provider added after this SDK was generated survives -decoding and round-trips back out on encode. `additionalProperties: false` changes nothing about -this. - -There is no typed bag to read them from, though, and no member on the type: +A model whose spec schema is open — `additionalProperties` absent, `true`, or a schema — keeps the +keys it does not declare in one optional field, `additionalProperties?: Record`. `T` is +`JsonValue` when the spec gave no value schema, otherwise the declared type, and each value is +validated against it. The field is present only when the wire carried an extra, and its keys are +**wire** names — nothing maps the casing here: ```ts -// Decoding: the key is on the object but not in the type. -const extra = (model as Record)["x_experimental"]; - -// Encoding: extra keys on a value you pass are sent. Excess-property checking catches them on a -// fresh object literal, but not on a value that arrived through a variable. +const extra = model.additionalProperties?.x_experimental; ``` -The keys are **wire names** — there is no property, so nothing maps the casing for you here. And a -field you depend on that has no typed property is a regeneration signal: prefer regenerating the SDK -from a spec that describes it over building program logic on stringly-typed lookups. +On the way out, extras you write into the record are sent beside the declared fields; a value that +is not a `T`, or a key the model already declares, is an `EncodeError` before any request is sent. +Read the field's name off the model: a spec that declares its own `additionalProperties` property +keeps it, and the record is `additionalProperties2`. A model whose spec says +`additionalProperties: false` has no record, yet an unknown key on it still passes through both +directions, invisible to the type. -The same symmetry is a debugging trap on the way out: a **misspelled** property is not an error -either, it is an extra key that gets sent and ignored. So when a value you set is not taking effect, -check the spelling against the type before suspecting the API — excess-property checking only catches -it on a fresh object literal, never on a value that reached the call through a variable. +A **misspelled** property is not an error either: it is an extra key that is sent and ignored. +Excess-property checking catches it only on a fresh object literal, never on a value that reached the +call through a variable — so when a value you set is not taking effect, check the spelling against +the type before suspecting the API. ## The schema companion @@ -333,7 +313,35 @@ const back = {model}Schema.decode(JSON.parse(JSON.stringify(wire))); Both directions throw `SchemaError` on mismatch and produce nothing partial. Using a schema on inbound data the SDK did not hand you — a webhook body, a queue message, a cached blob — is the -intended use, and gives you exactly the validation the SDK applies to a response. +intended use. For a model whose spec declares value constraints it is stricter than a response, not +the same: `{model}Schema` enforces them on `decode` as it does on `encode`, while an operation +decodes through the structural twin, so a payload that breaks a `pattern` or a bound passes through +an operation and throws here. Catch `SchemaError` on that path if a payload the service already +accepted should not be dropped for a constraint. + +### Checking a value before you send it + +```ts +const result = {model}Schema.validate(model); +if (!result.success) { + // "name: Invalid input; dispatch.lockerCode: expected regex format" + console.error(result.message); +} +``` + +`validate` runs `encode`'s rules without the conversion and without the throw, and is the **only** +place a value constraint the spec declares (`minLength`, `pattern`, `minimum`, `uniqueItems`, a +checked `format`, …) is applied — a keyword on an array's `items` or a map's +`additionalProperties` included, checked on each item or value and reported under its index or +key (`tags.0`, `attributes.carrier`). An operation never applies one: it sends and receives +through a structural twin, `{model}InternalSchema`, so a value the service would accept is never +refused on the way out, and a service that is ahead of the spec is never refused on the way in. A +model that +nests a constrained one validates the nested value too and reports its fields under their full +path. + +No operation exports a `{operation}RequestSchema`: no request field carries a constraint of its own, +so a request object is checked by the operation alone, by type and presence. Do **not** `JSON.stringify` a model directly for storage, or hand a raw model to anything that will encode it — a web framework's response serializer, a cache, a queue. `JSON.stringify` writes @@ -349,3 +357,4 @@ schema surface, and the failures each date codec produces. - Pass models to an operation → **typescript-calling-endpoints** - `SchemaError`, and the `DecodeError` or `EncodeError` it arrives on → **typescript-error-handling** + diff --git a/plugins/slack/skills/typescript/typescript-models/reference.md b/plugins/slack/skills/typescript/typescript-models/reference.md index e6dc98c6..5c881b1a 100644 --- a/plugins/slack/skills/typescript/typescript-models/reference.md +++ b/plugins/slack/skills/typescript/typescript-models/reference.md @@ -1,49 +1,27 @@ # Models reference (APIMatic TypeScript) -Condensed reference for the shapes in **typescript-models**. The schema combinators live in -`src/core/validation/` — vendored static code, identical in every generated TypeScript SDK — and are -reached through the `s` namespace inside generated model modules. `s` re-exports `zod/v4-mini` -(`string`, `number`, `boolean`, `array`, `record`, `union`, `nullable`, `optional`, `literal`, -`unknown`) plus the SDK's own entries (`object`, `enumOf`, `discriminatedUnion`, `of`, `lazy`, -`optionalNullable`, `defaulted`, `dateTime`, `rfc1123DateTime`, `unixSecondsDateTime`, `dateOnly`, `bytes`). +Lookup tables beside **typescript-models**, which carries the rules. Model modules build their +schemas from the `s` namespace (`src/core/validation/`, the same in every APIMatic TypeScript SDK): +`zod/v4-mini`'s `string`, `number`, `boolean`, `array`, `record`, `union`, `nullable`, `optional`, +`literal`, `unknown`, plus the SDK's `object`, `enumOf`, `discriminatedUnion`, `of`, `lazy`, +`optionalNullable`, `defaulted`, `dateTime`, `rfc1123DateTime`, `unixSecondsDateTime`, `dateOnly` and +`bytes`. Confirm concrete type and field names in `src/models/`. -## The two exports per model - -```ts -import { type {Model}, {model}Schema } from "{package-name}"; -``` - -One `type` and one schema value, both re-exported from the package root. Take the pair from an -operation's **Type sources** table (`Type` · `Schema value` · `Source`) in `map/operations/*.md`, or -from the **Models** section of `sdk-map.md`. The type-name-to-path transform is not reversible, so do -not guess the path. - -**An enum is the exception to the `type` import.** Its name is a value *and* a type, so -`import { {Enum}, {enum}Schema }` — with `type`, `{Enum}.Active` does not compile. Every other model -type carries no runtime value, so under `verbatimModuleSyntax` it must be imported as -`import { type {Model} }` or `import type { {Model} }`; the schema const is always a value import. - -The package ships `dist` (with declaration files), `src`, `README.md`, `api-reference.md`, -`sdk-map.md` and `map`, so the readable TypeScript and the contract sheets are all inside -`node_modules/{package-name}/`. - -No property is emitted `readonly` and no model is frozen: a decoded response is a plain mutable -object, and mutating it changes nothing on the wire by itself. - ## Spec kind to TypeScript type | API definition kind | Model type | Schema entry | | --- | --- | --- | -| string, password, regex-constrained, email, uri, ip, hostname, json-pointer, uuid | `string` | `s.string()` — **format unchecked** | -| `time` | `string` | `s.string()` — unchecked | +| string, password, uuid, regex-constrained | `string` | `s.string()` | +| email, uri, ip, hostname, json-pointer | `string` | `s.string()` — the format is a value check, see *Deriving a changed copy* | +| `time` | `string` | `s.string()` | | `date` | `string` | `s.dateOnly()` | | `date-time` (ISO 8601 / RFC 1123 / unix) | `Date` | `s.dateTime()` / `s.rfc1123DateTime()` / `s.unixSecondsDateTime()` | | int32, int64 | `number` | `s.int()` | | float, double, big-decimal | `number` | `s.float64()` | | boolean | `boolean` | `s.boolean()` | | binary, file — as a declared field | `Uint8Array` | `s.bytes()` (base64) | -| a value the spec fixed | that literal type | `s.literal(value)` | +| a pinned value | that literal type | `s.literal(value)` | | free-form object | `Record` | `s.record(s.string(), s.unknown())` | | array of `T` | `T[]` | `s.array(...)` | | map of `T` | `Record` | `s.record(s.string(), ...)` | @@ -53,66 +31,58 @@ object, and mutating it changes nothing on the wire by itself. Nullability folds onto whatever the row produced: `T | null` with `s.nullable(...)`. It is never folded onto `unknown`, which already admits `null`. +A value constraint the spec declares on a row — a length, a pattern, a checked format, a numeric +bound — never changes the type; where it is enforced is stated under *Deriving a changed copy*. + ## Field declaration cheat sheet | Declared | Schema entry | Building it | | --- | --- | --- | | `f: T` | the entry itself | always provide | | `f?: T` | `s.optional(...)` | **omit the key** (not `f: undefined`) | -| `f?: T` | `s.defaulted(...)` | omitting it sends the spec default; set the value you mean | +| `f?: T` | `s.defaulted(...)` | omitting it sends its default; set the value you mean | | `f: T \| null` | `s.nullable(...)` | provide `null` to send JSON `null` | | `f?: T \| null` | `s.optionalNullable(...)` | omit, or provide `null` | -```ts -// Conditional optional field, exactOptionalPropertyTypes-safe: -const body: {Model} = { id, ...(note !== undefined ? { note } : {}) }; -``` - -Run time is more forgiving than the type system — an explicit `undefined` is dropped from the JSON, except where a spec default is sent instead — -but do not rely on it: the SDK's own tsconfig sets `exactOptionalPropertyTypes` (and -`verbatimModuleSyntax`, `noUncheckedIndexedAccess`, `strict`), and a consumer that does the same will -not compile. - -`s.defaulted(entry, value)` marks a model property or a request field with a spec default; the SDK fills -the default on encode and decode. - ## Deriving a changed copy ```ts const updated = { ...model, {field}: "..." }; ``` -Nothing validates a spread — the schema runs when you pass the value to an operation or call `encode` -yourself, and that is where a bad value surfaces. The copy is **shallow**: nested models and arrays -are shared with the original, so mutating one mutates both. Undeclared keys the source carried are -copied along, which is what keeps a read-modify-write round-trip from dropping server-side state the -SDK does not model. - -## Reading a response model - -- **An absent optional is `undefined`**, unless it has a spec default. No sentinel, no wrapper, so `?.` / `??` are enough, and, - without a default, `!== undefined` is the precise test where "absent" and "present but empty" differ. -- **A response type whose spec marks nothing required accepts `{}`.** `{model}Schema.decode({})` - succeeds and every property is `undefined` or its default; a truncated body raises nothing. Check the properties - you depend on. -- **Required on the request, optional on the response is normal.** Two schemas, one concept — read - each from its own place in the map rather than assuming they match. -- Under `noUncheckedIndexedAccess`, `items[0]` is `T | undefined`; guard it before reaching through. -- An undeclared key that arrived on the wire is on the object but not in the type — reach it with a - widening cast, and only when you must. +Nothing validates a spread — the shape is checked when you pass the value to an operation or call +`encode` yourself, and that is where a wrong type surfaces. A value constraint the spec declares +(`minLength`, `pattern`, `minimum`, a checked `format`, …) is **not** checked by an operation; +`{model}Schema` checks it — `validate(value)` reports it, `encode` and `decode` throw on it. The copy +is **shallow**: nested models and arrays are shared with the original, so mutating one mutates both. +Undeclared keys the source carried are copied along, which is what keeps a read-modify-write +round-trip from dropping server-side state the SDK does not model. ## Schema surface ```ts type Schema> = { - readonly decode: (value: unknown) => T; // wire shape -> model - readonly encode: (value: unknown) => W; // model shape -> wire + readonly decode: (value: unknown) => T; // wire shape -> model + encode(value: T): W; // model shape -> wire + validate(value: T): ValidationResult; // encode's rules, no conversion, no throw }; +type ValidationResult = { success: true } | { success: false; message: string }; + type EnumSchema = Schema & { readonly values: readonly T[] }; ``` -`Schema`, `EnumSchema` and `Encoded` are re-exported from the package root as types. +`Schema`, `EnumSchema`, `Encoded` and `ValidationResult` are re-exported from the package root as +types. + +`validate` runs the same rules `encode` runs and reports instead of throwing: `message` lists every +failing field with its reason (`code: expected regex format; attributes: must have at most 10 +properties`), the same list a `SchemaError` from `encode` carries after its leading sentence. On a +model whose spec declares value constraints, `{model}Schema` enforces them and `validate` is how you +check a value before sending it; the operations encode and decode through a structural twin, +`{model}InternalSchema`, exported from the model's module but not from the package root, so a +constraint is never applied on the way out or on the way in. On every other model `validate` checks +shape alone. `Encoded` — the wire projection: @@ -124,228 +94,33 @@ type EnumSchema = Schema & { readonly values: readonly T[] }; | object | each property projected | | anything else | itself | -Both directions throw `SchemaError` on mismatch and produce nothing partial. The message is prefixed -`Wire value could not be decoded.` or `Type could not be encoded for the wire.`, followed by -`path: expected X, received T` per issue — `T` the type that arrived, never the value (`` -where there is no path). It keeps no copy of the offending value; `.cause` is the underlying zod error -with the structured issue list. Through an operation it arrives one level down, on the `cause` of a -`DecodeError` or an `EncodeError`. Request encoding runs before the HTTP call, so an encode failure -means **nothing was sent**. - -## Key renaming - -The `_keysMap` entry inside a generated `s.object({ ... })` literal maps TypeScript property names -to wire keys, and is applied on decode and encode both. Only properties that moved appear: - -```ts -export const {model}Schema = s.object<{Model}>({ - createdAt: s.dateTime(), - isActive: s.optional(s.boolean()), - _keysMap: { createdAt: "created_at", isActive: "is_active" }, -}); -``` - -You never write wire keys. Reach for `_keysMap` — or the **Wire-name divergences** table in -`sdk-map.md` — only when reading a captured HTTP body. +A `SchemaError` message is prefixed `Wire value could not be decoded.` or `Type could not be encoded +for the wire.`, followed by `path: expected X` per issue — `X` the type, format or set of values the +schema expected; neither the value nor its type is named (`` where there is no path). `.cause` +is the underlying zod error with the structured issue list. ## Enums -```ts -export const {Enum} = { Active: "active", Retired: "retired" } as const; -export type {Enum} = (typeof {Enum})[keyof typeof {Enum}] | (string & {}); -export const {enum}Schema = s.enumOf<{Enum}>({Enum}); -``` - -| Property | Behaviour | -| --- | --- | -| Type | **open** — the `(string & {})` / `(number & {})` tail admits any value of the base type | -| Wire value | the member's value, verbatim (`"active"`, or `1` for a number enum) | -| Decoding | checks the **base type only** — `s.enumOf` builds a string or a number check from the members and validates nothing else, so an unknown member is accepted | -| Known set | `{enum}Schema.values` — `readonly {Enum}[]`, in declaration order | -| Member names | generated identifiers; a number enum's members are `_0`, `_1`, … | - -```ts -import { {Enum}, {enum}Schema } from "{package-name}"; - -body.status = {Enum}.Active; // preferred -body.status = "active"; // compiles, but survives a rename -const known = {enum}Schema.values.includes(fromServer); // runtime membership test -``` - -Because unknown members decode, a `switch` over a received enum value **needs a `default` arm**, and -an `if`/`else if` chain over the members with no final `else` silently does nothing for a value newer -than the SDK. - -There is **no coercion helper** — no `fromValue`, no closed lookup that raises — because a member *is* -its wire value: - -```ts -{Enum}.Active === "active"; // true -`${{Enum}.Active}`; // "active" — safe in a log line, a URL, a query string -type Known = (typeof {Enum})[keyof typeof {Enum}]; // the closed set, at type level -``` - -Mapping an SDK enum onto your own, tolerating the open arm: - -```ts -function toDomain(value: {Enum}): MyEnum { - switch (value) { - case {Enum}.Active: return MyEnum.A; - case {Enum}.Retired: return MyEnum.B; - default: return MyEnum.Unknown; // covers values newer than this SDK - } -} -``` - -## Discriminated unions (`oneOf`, and a polymorphic base) - -```ts -// src/models/unions/{union}.ts -export type {Union} = ({ArmA} & { {tag}: "a" }) | ({ArmB} & { {tag}: "b" }); - -export const {union}Schema = s.discriminatedUnion<{Union}>("{wire_tag}", { - a: {armA}Schema, - b: {armB}Schema, -}); -``` - -- The arms are the variant types **intersected with the tag literal**; the variant type itself does - not declare the tag, so a value typed `{ArmA}` is not assignable to `{Union}`. -- **Narrow with `switch` on the tag.** The arms are exhaustive, so no fallback arm is needed. -- **Build by writing the arm's literal, tag included** — the schema writes the tag onto the wire from - the value you pass, and dispatches on it when decoding. -- The schema's key is the **wire** discriminator and each entry's key is the wire tag **value**. The - tag name on the **decoded** object can differ, where a variant renamed the discriminator; the type - alias spells what arrives. -- A polymorphic base (an object schema that `allOf` subtypes with a discriminator derive from) is - emitted here **as a discriminated union**, not as a base type. There is nothing to upcast to. -- ⚠ A tag matching no arm is a decode failure — a `SchemaError`, on a `DecodeError`'s `cause` through - an operation — not an unset variant. - -```ts -switch (value.{tag}) { - case "a": return handleA(value); // narrowed to the {ArmA} arm - case "b": return handleB(value); -} -``` - -## Undiscriminated unions (`anyOf`) - -```ts -export type {Union} = string | {Model}; -export const {union}Schema = s.of<{Union}>(s.union([s.string(), s.lazy(() => {model}Schema)])); -``` - -- Nothing narrows the arms — use `typeof`, `in`, or `Array.isArray`. -- Decoding accepts a value matching **any** arm, and **the first match in declaration order wins**, - so overlapping arms resolve by order. -- Build by passing a value of any arm directly. There is no wrapper and no factory. -- A union the spec left unconstrained degrades to `unknown`. -- ⚠ A value matching no arm is a decode failure — a `SchemaError`, on a `DecodeError`'s `cause` - through an operation. +An `if`/`else if` chain over the members with no final `else` silently does nothing for a value newer +than the SDK. `type Known = (typeof {Enum})[keyof typeof {Enum}]` is the closed set at type level. ## Dates -| Schema | Model type | Wire | Notes | -| --- | --- | --- | --- | -| `s.dateTime()` | `Date` | `"2024-06-17T15:30:00Z"` | ISO 8601, **offset required**; encodes via `toISOString()` | -| `s.rfc1123DateTime()` | `Date` | `"Mon, 17 Jun 2024 15:30:00 GMT"` | strict IMF-fixdate (two-digit day, `GMT`); encodes via `toUTCString()` | -| `s.unixSecondsDateTime()` | `Date` | `1718638200` | epoch **seconds**; a numeric string also decodes; encodes floored to whole seconds | -| `s.dateOnly()` | `string` | `"2024-06-17"` | a **string**, not a `Date`; the `YYYY-MM-DD` shape is checked | - -```ts -body.createdAt = new Date("2024-06-17T15:30:00Z"); // Date-typed fields -body.birthDate = "1990-04-02"; // dateOnly field — a string -``` +- `s.dateTime()` requires an offset on decode; encodes via `toISOString()`. +- `s.rfc1123DateTime()` is strict IMF-fixdate (two-digit day, `GMT`); encodes via `toUTCString()`. +- `s.unixSecondsDateTime()` also decodes a numeric string; encodes floored to whole seconds. +- `s.dateOnly()` checks the `YYYY-MM-DD` shape. `s.bytes()` rejects non-base64 input on decode. Failures to expect: -- `"2024-06-17"` into an `s.dateTime()` field → `SchemaError` (date-only, no offset). -- `"2024-06-17T15:30:00"` into an `s.dateTime()` field → `SchemaError` (no offset). +- `"2024-06-17"` or `"2024-06-17T15:30:00"` into an `s.dateTime()` field → `SchemaError` (no offset). - `"Mon, 7 Jun 2024 15:30:00 GMT"` into `s.rfc1123DateTime()` → `SchemaError` (day must be two digits). - Epoch **milliseconds** into `s.unixSecondsDateTime()` → no error; it decodes to a date ~50,000 years out. Divide by 1000, or pass a `Date`. -Read the field's combinator in `src/models/{model}.ts` to know which applies — the `Date` type alone -does not say. - -## Bytes - -```ts -// Field declared: payload: Uint8Array (schema: s.bytes()) -body.payload = new TextEncoder().encode("hello"); // encoded to base64 on the wire -const text = new TextDecoder().decode(model.payload); // decoded from base64 for you -``` - -Base64-in-JSON fields only. Non-base64 input fails on decode. This is not the file-upload carrier: -a raw-binary body and a multipart file part both take a `FileInput`, which is framed rather than -encoded, and a decoded `Uint8Array` is deliberately not assignable to one. - -## Collections - -| Field | Type | Pass | -| --- | --- | --- | -| array | `T[]` | a plain array | -| map / free-form object | `Record` | a plain object | -| unconstrained value | `unknown` | anything; nothing is checked | - -| Value | On the wire | -| --- | --- | -| omitted / `undefined` | key absent, or the spec default if it has one | -| `null` on a nullable field | `null` | -| `[]` | `[]` | -| `{}` | `{}` | - ## Recursive and self-referential models -Generated schemas wrap a reference that nests inside another validator in `s.lazy(() => otherSchema)`, -so a model that refers to itself (a tree node, a nested comment) works with no special handling. -Nothing is required of you; the type is just a normal recursive `type`. - -## Undeclared keys (passthrough) - -Model schemas are built on a **loose** object, so undeclared keys survive both directions: - -```ts -// Decoding: an undeclared response key is on the object but not in the type. -const extra = (model as Record)["x_experimental"]; - -// Encoding: extra keys on a value you pass are sent. -// (Excess-property checking catches this on a fresh literal, not on a variable.) -``` - -There is no typed `additionalProperties` bag, and `additionalProperties: false` is not enforced — it -has no visible effect at all. A key you need but the type lacks means the spec does not describe it. - -## What is never validated - -`s.string()` carries no format check and no length or pattern check; `s.int()` and -`s.float64()` carry no `minimum`, `maximum` or `multipleOf` check; arrays carry no `uniqueItems` check. -The generator does not transcribe those -constraints, so there is nothing to read and nothing to invoke — they are enforced only by the -provider, as a `400`. `api-reference.md` carries the documented contract; put your own guard at your -own boundary if you want one before the round-trip. - -## Round-tripping - -```ts -const wire = {model}Schema.encode(model); // wire-shaped plain object -const json = JSON.stringify(wire); -const back = {model}Schema.decode(JSON.parse(json)); -``` - -`JSON.stringify(model)` directly is **not** the wire shape: - -| Model value | Through `encode` | Through `JSON.stringify` directly | -| --- | --- | --- | -| a renamed property | the wire key | the TypeScript key | -| a `Date` on an RFC-1123 or unix-seconds field | that field's format | an ISO string — wrong format | -| a `Uint8Array` | base64 `string` | `{"0":104,"1":105}` — the bytes are gone | - -So decoding a directly-stringified model fails on the renamed keys and the date formats, silently. The -same applies to handing a raw model to anything else that encodes — a framework's response -serializer, a cache, a queue: map it to your own type at the boundary, or hand out `encode`'s result. +A self-referential model (a tree node, a nested comment) needs no special handling: generated schemas +wrap a nested reference in `s.lazy(() => otherSchema)`. -Using a schema on inbound data you did not get from the SDK — a webhook body, a queue message, a -cached blob — is the intended use, and gives you the same validation the SDK applies to responses. diff --git a/plugins/slack/skills/typescript/typescript-testing/SKILL.md b/plugins/slack/skills/typescript/typescript-testing/SKILL.md index 2475f409..1a11d09c 100644 --- a/plugins/slack/skills/typescript/typescript-testing/SKILL.md +++ b/plugins/slack/skills/typescript/typescript-testing/SKILL.md @@ -1,6 +1,6 @@ --- name: typescript-testing -description: Testing code that calls an APIMatic-generated TypeScript SDK — which seam to fake (`ClientOptions.fetch`, or an interceptor at the global-fetch layer), stubbing bodies in wire shape, asserting the request the SDK actually built, covering the error and decode-failure paths, turning the on-by-default retry policy off (or testing it deliberately), and keeping tests independent of SDK internals. Load before writing tests for the integration layer. +description: Load before writing tests for code that calls an APIMatic-generated TypeScript SDK — faking `ClientOptions.fetch` or intercepting global `fetch`, wire-shaped stub bodies, asserting the request the SDK built, error, decode and auth failure paths, OAuth token stubs, paged walks, and the on-by-default retries. --- # Testing code that uses an APIMatic TypeScript SDK @@ -95,16 +95,15 @@ matters, or pass a `logger` that records its calls when the test is *about* what `Response` is global on Node 18+. Credentials can be dummy values, or omitted entirely — nothing validates them when the transport is stubbed, unless the test is *about* the credential. -**Do not mock the client, its resource classes, or reach for its internals.** `#rawClient` and the -other private fields are genuinely unreachable, and a hand-rolled double of `{Api}Client` cannot catch -the mistakes that actually happen — a wrong path parameter, a body that does not encode, a header you -forgot. Faking `fetch` exercises the real request-building pipeline; that is the whole point. Never -construct a resource class either: it is exported only for its merged namespace and for `instanceof`, -and its constructor takes engine internals that are not exported. +**Fake `fetch`, not the client.** A hand-rolled double of `{Api}Client` or a resource class (which you +cannot construct — **typescript-calling-endpoints**) cannot catch the mistakes that actually happen — a +wrong path parameter, a body that does not encode, a header you forgot; a fake `fetch` runs the real +request pipeline. -> **If your client has an OAuth 2 scheme, the first request your stub sees is the token request**, not -> your operation. See **Fake an OAuth token endpoint** below before writing the first test — a -> single-response fake fails there in a confusing way. +> **With an OAuth 2 scheme, the first request your stub sees is the token request**, not your +> operation. A single-response fake hands your operation's body to the token decoder, and the call +> fails with an `AuthError` (cause: a `DecodeError` about `access_token`) that reads like bad +> credentials. See **Fake an OAuth token endpoint** below. ## Stub bodies are in WIRE shape, not model shape @@ -130,7 +129,7 @@ expect(() => {model}Schema.decode(fixture)).not.toThrow(); // validate a hand- Prefer the first: build the fixture as a typed model and encode it, so a member rename breaks the fixture instead of passing a stale test. Validate any fixture you hand-write and reuse — it catches -fixture rot when the SDK is regenerated. Both schema consts are exported from the package root. +fixture rot when the SDK is updated. Both schema consts are exported from the package root. ## Test a success path @@ -194,9 +193,9 @@ if ("rawBody" in e.payload) expect(new TextDecoder().decode(e.payload.rawBody)). ``` **Take the arm union from the contract sheet per operation.** `"undeclared"` is reachable in Case A -too — any status the operation's matchers do not cover falls to it — so an error test copied from a -sibling operation can pass for the wrong reason, landing in the `"undeclared"` branch and asserting -nothing about the typed body you meant to check. +too — any status the operation's matchers do not cover falls to it, a spec's `default` response +being no matcher — so an error test copied from a sibling operation can pass for the wrong reason, +landing in the `"undeclared"` branch and asserting nothing about the typed body you meant to check. Use `try`/`catch` rather than a rejection matcher: matcher support for narrowing a rejected value differs between runners, and the `catch` form reads the same everywhere. @@ -225,11 +224,9 @@ it("reports the failure without throwing", async () => { }); ``` -On success the value is `outcome.value` (not `.data`), and `outcome.headers` is the only way to read -**response headers** — so this is also the mode to test in when your code depends on a header on the -*success* path. `.asApiResult()` does **not** make the call non-throwing: everything in the next -section still rejects, and it must be called on the value the operation returned, before any -`.then()`. +`outcome.headers` is the only way to read **response headers** on the *success* path, so test in this +mode when your code depends on one. Everything in *Cover the failures that are not an `ApiError`* +still rejects in this mode. ## Assert the outgoing request @@ -254,21 +251,20 @@ it("sends the right request", async () => { - **The SDK hands the fake one `Request` and no `init`.** Its `url` is absolute, so `new URL(request.url)` gives you `pathname` and `searchParams` for free rather than substring-matching a URL string. A fake that reads `init` reads nothing. -- **Header names are lowercased.** The SDK normalizes every layer — the endpoint's, the auth scheme's - and the client's defaults — before merging, which is what makes the merge case-insensitive, and - `request.headers` is a `Headers`. Read it through `request.headers.get(...)`; a plain - `request.headers["Authorization"]` is both the wrong type and the wrong case. +- **Read headers through `request.headers.get(...)`** — `request.headers` is a `Headers` with + lowercased names, so a plain `request.headers["Authorization"]` is both the wrong type and the wrong + case. - **The body is already serialized by the time the fake sees it.** The captured `body` is the request - body's **text** (or `undefined`), which is all a JSON, form-urlencoded or text body needs, and it - uses **wire aliases**, because that is what encoding produces. Assert on the parsed string; do not + body's **text** (or `undefined`), which is all a JSON, form-urlencoded or text body needs, with **wire + aliases** and wire dates, because that is what encoding produces — assert on the parsed string; do not "fix" the aliases in the test. Read a multipart or binary body back off the captured `request` instead: a multipart one with `await request.formData()`, and a binary one with `new Uint8Array(await request.arrayBuffer())` — its text is lossy. A multipart `content-type` carries a generated boundary, so match it as a prefix, never with `toBe`. Compare a file part by its contents, `await new Response(form.get("{field}")).text()`: one sent without a file name may come back as a string or a `File`. -- **A list-valued query or form parameter has a per-parameter wire style.** The `StyledParam` the - generator emitted for it in `src/resources/{resource}.ts` carries a `style`: `plain` (the default — +- **A list-valued query or form parameter has a per-parameter wire style.** Its `StyledParam` in + `src/resources/{resource}.ts` carries a `style`: `plain` (the default — `name=a&name=b`), `indexed` (`name[0]=a`, percent-encoded in the raw URL as `name%5B0%5D=a`), `unindexed` (`name[]=a`), or `csv` / `tsv` / `psv` (one joined value). Read it before asserting: @@ -290,14 +286,48 @@ Worth asserting once, somewhere, because they are silent when wrong: - **The value actually reached the wire.** Request models encode loosely too, so an extra or misspelled optional member is carried into the body rather than rejected. Only an assertion on the captured `body` catches it. -- **A body that cannot encode never reaches your fake.** Encoding happens *before* the request is - dispatched, so the call rejects with `EncodeError` and `stub.calls` stays **empty**. Same for a path - parameter left `undefined` — its schema rejects it, also as an `EncodeError`, before anything is - sent. Assert `stub.calls` is empty in those tests. -- **`retry.timeout` never rides the request.** It is a per-attempt budget in **milliseconds**, set on - the client or on one call through `RequestOptions.retry`, and it reaches the wire only as the - `Request`'s `signal`. A test asserting a timeout on a captured request is asserting something that - was never there. +- **An encode failure never reaches your fake** — a bad body and an `undefined` path parameter alike + reject with `EncodeError` and leave `stub.calls` **empty**; assert that in those tests. +- **`retry.timeout` never rides the request**; the fake sees it only as the `Request`'s `signal`. + +## Test a paged operation + +A paged operation sends one request per page, so queue one response per page and let the walk run. +`retry: { maxRetries: 0 }` keeps it to one request per page, and a queue that runs out is the signal +that a walk did not stop where you expected: + +```ts +it("walks every page", async () => { + const { client, stub } = clientReturning( + jsonResponse(200, { items: [{ id: "1" }, { id: "2" }], nextCursor: "c2" }), + jsonResponse(200, { items: [{ id: "3" }], nextCursor: null }), + ); + + const ids: string[] = []; + for await (const item of client.{resource}.{operation}({ limit: 2 })) ids.push(item.id); + + expect(ids).toEqual(["1", "2", "3"]); + expect(stub.calls).toHaveLength(2); + expect(stub.calls[1]!.url.searchParams.get("cursor")).toBe("c2"); // the SDK advanced the state +}); +``` + +Stub the stop signal the operation's strategy reads — a `null` or absent next cursor, a `hasMore` of +`false`, a page shorter than its `limit`, or an empty page — in **wire shape**, like any other body; +the operation's **Returns** bullet names the strategy and the condition that ends its walk. A `Link`-header +strategy reads the `Link` response header, and the SDK follows a link only on the client's own origin: + +```ts +new Response(JSON.stringify(body), { + status: 200, + headers: { Link: '<{baseUrl}/{path}?cursor=c2>; rel="next"' }, // the base URL the client was built with +}) +``` + +A failed page is tested like any failed call: queue an error status in the position of the page that +fails, and the walk throws `ApiError` (or the operation's own subclass) after yielding the pages before +it. Nothing is sent until a loop starts, so a test that calls the operation and never iterates asserts +that `stub.calls` is empty. ## Cover the failures that are not an `ApiError` @@ -312,9 +342,7 @@ reachable from the fake, which makes these paths genuinely testable rather than | `kind: "decode"` | return a body that violates the schema (wrong type, bad date, a non-empty `200` where `undefined` is expected) | | `kind: "encode"` | pass a request value its schema refuses — nothing reaches the fake | | `kind: "auth"` | answer the **token** request with an error status (see below) | - -A caller abort is **not** a `kind`: aborting the signal you passed in `RequestOptions` rejects with that -signal's own `reason`, outside the family. +| `kind: "pagination"` | answer a page of a `Link`-strategy walk with a next link on another origin — a `Link` header naming a host that is not the client's base URL | ```ts import { {Api}Error } from "{package-name}"; @@ -335,11 +363,9 @@ it("maps a transport failure", async () => { }); ``` -⚠ **A timeout or abort test needs a fake that honours the `Request`'s `signal`.** The SDK aborts the -signal it put on the `Request` and relies on `fetch` to settle; a fake that returns a never-resolving -promise and ignores the signal simply hangs the test until the runner kills it. What the fake rejects -with does not matter — the SDK reads the reason off its own signal — so a timeout is a `TimeoutError` -the retry loop retries, which is why the test below sets `maxRetries: 0`. +⚠ **A timeout or abort test needs a fake that honours the `Request`'s `signal`**: one that ignores it +hangs the test until the runner kills it. What the fake rejects with does not matter — a timeout is a +`TimeoutError` the retry loop retries, which is why the test below sets `maxRetries: 0`. ```ts const hangingFetch: typeof globalThis.fetch = (input, init) => @@ -356,10 +382,8 @@ it("times out", async () => { }); ``` -That is faster and more deterministic than fake timers, and it exercises the real abort path. For a -caller abort, keep the default timeout, abort your own `AbortController` passed in `RequestOptions`, and -assert the call rejects with exactly the `reason` you passed — it is not an `{Api}Error`, and it is -never retried. +A caller abort is **not** a `kind`: abort your own `AbortController` passed in `RequestOptions` and +assert the call rejects with exactly the `reason` you passed — not an `{Api}Error`, and never retried. **A decode failure bypasses *both* response modes.** A 2xx body that does not satisfy the schema rejects with `DecodeError`; `.asApiResult()` does **not** turn it into an `ok: false` result. Test that your @@ -427,7 +451,7 @@ const stub = stubFetch((url) => ); ``` -Or bypass acquisition entirely with a stub token strategy — the generator's supported injection point +Or bypass acquisition entirely with a stub token strategy — a supported extension point (**typescript-authentication**) — so the fake only ever sees your operation: ```ts @@ -449,18 +473,12 @@ needs `redirectUri` and `promptForAuthorizationCode` (e.g. `async () => "code"`) Facts that make these tests behave: -- **Forgetting the token request is the most common way a first test fails confusingly.** A - single-response fake hands your operation's body to the *token* decoder, and you get an `AuthError` - whose `cause` is a `DecodeError` about a missing `access_token` — which reads like wrong credentials - when the fake simply answered the wrong request. - The token **response** is wire-shaped (`access_token`, `token_type`, `expires_in`); the token - **request** is a `POST` with a form-urlencoded string body, and by default the client id and secret - ride in a Basic `Authorization` header rather than in that body. + request's shape is in **typescript-authentication**. - The token endpoint may live on a **different server group**, so match on the path, not the host — read the group's URL from `DEFAULT_SERVER_OPTIONS` in `src/servers.ts`. - The token is **cached on the scheme**, so only the first call fetches one: a test making two calls - against one client sees three requests, not four. Build a fresh client per test to reset it. A - missing or non-positive `expires_in` means the cached token never expires. + against one client sees three requests, not four. Build a fresh client per test to reset it. - The token request and the operation each run on their own `retry.timeout`, so a tiny timeout in an OAuth test can fire on the token request — which ends the call with a `TimeoutError` for the token endpoint, not retried unless `httpMethodsToRetry` names `POST`. @@ -480,18 +498,13 @@ agent.get("{base-origin}").intercept({ path: "{operation-path}", method: "POST" .reply(201, { id: "1" }, { headers: { "content-type": "application/json" } }); ``` -Pick one and be consistent. An interceptor asserts on real URLs and is closer to the wire; the fake -`fetch` is dependency-free, faster, and does not care what HTTP stack is underneath. Two constraints: -an interceptor works **only while no `fetch` option is supplied** — a custom `fetch` bypasses it -entirely — and the client resolves `globalThis.fetch` **in its constructor**, so patching the global -after the client is built has no effect. +Pick one approach. An interceptor sees nothing once a `fetch` option is supplied, and one that patches +`globalThis.fetch` must be installed before the client is built (**typescript-client-initialization**). ## Keeping tests independent of SDK internals -- **Never deep-import.** The package's `exports` map exposes `.` and `./package.json` and nothing else, - so `{package-name}/models/…` does not resolve at all. Everything you need — the client, the options, - every model type and its `{model}Schema`, the error classes, `ServerEnvironment` — is re-exported - from the package root. Reading a file under `src/` is for *learning* the shape, never for importing. +- **Import only from the package root** (**typescript-client-initialization**); read `src/` to learn a + shape, never to import from it. - **Never assert on an error's `message`.** An `ApiError`'s is the call and its status — `POST https://… failed with 400` — which moves whenever the base URL or the route does. It is not a contract. Assert `err.status` and the narrowed `err.payload`. @@ -515,9 +528,9 @@ const client = new {Api}Client({ }); ``` -**Override every group the test touches.** Redirecting `default` does not move a token endpoint that -lives on its own group — it will reach for the real host and the test will either fail slowly or, -worse, succeed against production. `src/servers.ts` lists the groups and their environments. +**Override every group the test touches** — a token endpoint on its own group otherwise reaches the +real host (**typescript-configuration-resilience**). `src/servers.ts` lists the groups and their +environments. Against a **live sandbox**, keep those tests separate from unit tests, skip them when credentials are absent, and never assert on ids or timestamps the provider generates: @@ -547,17 +560,10 @@ unless you mean to. `Response` needs no `content-type` header; setting one is harmless documentation. What matters is that the body parses and satisfies the schema. A binary response is the exception: its result reports `content-type` and the `content-disposition` file name, so stub them when your code reads them. -- **Matcher precedence:** an exact-status arm wins over a range or `"5XX"` wildcard arm. A test that - stubs a status covered by both is asserting the exact one. -- **A `401` invalidates the cached OAuth token and is not retried by default.** A test that stubs a - `401` sees one failed operation — and the *next* call in the same test re-fetches a token, so queue - another `tokenResponse()` for it. -- **Retries are on by default, and silent unless logging is on.** On a client built without - `retry: { maxRetries: 0 }`, a stubbed `408`, `429`, `500`, `502`, `503` or `504` — or a thrown - error — on a `GET`, `HEAD`, - `PUT` or `OPTIONS` call is fetched up to four times, across about 7 s of backoff. A queue that runs out - throws, and that throw is itself a connection failure the loop retries. When the test *is* about - your retry policy, queue one response per attempt, pass `delay: 0` so it runs at once, and count +- A stubbed `401` invalidates the cached OAuth token, so the *next* call in the same test fetches a new + one — queue another `tokenResponse()` for it. +- **Testing the retry policy itself**: drop `maxRetries: 0`, queue one response per attempt (a queue + that runs out throws, and the loop retries that as a connection failure), pass `delay: 0`, and count requests: ```ts const stub = stubFetch(queue(jsonResponse(503, {}), jsonResponse(503, {}), jsonResponse(200, { id: "1" }))); @@ -566,24 +572,12 @@ unless you mean to. await client.{resource}.{operation}({ /* ... */ }); // an operation whose method is in the gate expect(stub.calls).toHaveLength(3); ``` - A stubbed `Retry-After` header overrides `delay`, so leave it off unless the test is about it; a test - about the backoff itself wants `maxJitter: 0` and fake timers. Cover the cases that are easiest to get - wrong: a write outside the gate is sent **once**, a widened write re-sends the **same** - `Idempotency-Key` on every attempt, and an aborted request stops retrying. -- **A test environment with no global `fetch` fails in the constructor**, not on the first call — the - client throws `ConfigurationError` when it can resolve no implementation. Passing a fake avoids this entirely. -- **`instanceof` is dialect-scoped.** If the test setup loads the SDK through `require` and the code - under test through `import` (or vice versa), `instanceof` is `false` across that boundary. Narrow on - `err.kind` / `err.payload.kind` there, or fix the config to use one dialect. + A stubbed `Retry-After` overrides `delay`; a backoff test wants `maxJitter: 0` and fake timers. Worth + covering: a write outside the gate is sent **once**, a widened write re-sends the **same** + `Idempotency-Key`, and an abort stops retrying. - **Never guess a base URL.** With a fake `fetch` nothing is dialled and the host is irrelevant; if you match on URLs, take the prefix from `DEFAULT_SERVER_OPTIONS` rather than from memory — environments - differ per API, and some SDKs ship a sandbox environment that already points at localhost. + differ per API. - Mocking libraries work too — the seam is a plain function, so a `vi.fn()` / `jest.fn()` returning a `Response` satisfies it. The hand-written stub above gives you typed captured requests and ordered responses for free. -- **Keep one client across the calls of a test** as in production, so the token cache and the memoized - resource getters behave the same shape they will at runtime - (**typescript-client-initialization**). -- To look up an operation's signature, its field channels, route or error arms, take them from the - contract sheet — `map/operations/{resource}.md` inside `node_modules/{package-name}/`, which carries - all four — not the compiled `dist/`, and not memory. diff --git a/plugins/spotify/.claude-plugin/plugin.json b/plugins/spotify/.claude-plugin/plugin.json index 6a7204ff..f6f509d5 100644 --- a/plugins/spotify/.claude-plugin/plugin.json +++ b/plugins/spotify/.claude-plugin/plugin.json @@ -1,8 +1,8 @@ { "name": "spotify", "displayName": "Spotify Web API", - "version": "0.2.0", - "description": "Integrate and consume the APIMatic-generated Spotify Web API SDK — bundled skills for C#/.NET, python, TypeScript.", + "version": "0.2.1", + "description": "Integrate and consume the APIMatic-generated Spotify Web API SDK — bundled skills for C#/.NET, Python, TypeScript.", "author": { "name": "APIMatic", "email": "developer@apimatic.io" @@ -14,5 +14,8 @@ "./skills/dotnet", "./skills/python", "./skills/typescript" + ], + "agents": [ + "./scoped/agents/spotify-web-api-planner.md" ] } diff --git a/plugins/spotify/.codex-plugin/plugin.json b/plugins/spotify/.codex-plugin/plugin.json new file mode 100644 index 00000000..bfe3ee68 --- /dev/null +++ b/plugins/spotify/.codex-plugin/plugin.json @@ -0,0 +1,10 @@ +{ + "name": "spotify", + "version": "0.2.1", + "description": "Integrate and consume the APIMatic-generated Spotify Web API SDK — bundled skills for C#/.NET, Python, TypeScript.", + "skills": "./skills", + "interface": { + "displayName": "Spotify Web API", + "developerName": "APIMatic" + } +} diff --git a/plugins/spotify/.cursor-plugin/plugin.json b/plugins/spotify/.cursor-plugin/plugin.json index 6a7204ff..16465956 100644 --- a/plugins/spotify/.cursor-plugin/plugin.json +++ b/plugins/spotify/.cursor-plugin/plugin.json @@ -1,8 +1,8 @@ { "name": "spotify", "displayName": "Spotify Web API", - "version": "0.2.0", - "description": "Integrate and consume the APIMatic-generated Spotify Web API SDK — bundled skills for C#/.NET, python, TypeScript.", + "version": "0.2.1", + "description": "Integrate and consume the APIMatic-generated Spotify Web API SDK — bundled skills for C#/.NET, Python, TypeScript.", "author": { "name": "APIMatic", "email": "developer@apimatic.io" diff --git a/plugins/spotify/README.md b/plugins/spotify/README.md index 62afe39d..2373ab14 100644 --- a/plugins/spotify/README.md +++ b/plugins/spotify/README.md @@ -1,6 +1,6 @@ # Spotify Web API SDK Plugin -A plugin whose skills teach a coding agent to install and use the APIMatic-generated **Spotify Web API SDK**, in C#/.NET, python, TypeScript. Every SDK fact the skills state is grounded in the SDK's own source and generated documentation, not in what a model remembers about this API. +A plugin whose skills teach a coding agent to install and use the APIMatic-generated **Spotify Web API SDK**, in C#/.NET, Python, TypeScript. Every SDK fact the skills state is grounded in the SDK's own source and generated documentation, not in what a model remembers about this API. ## What's inside @@ -9,5 +9,16 @@ One skill set per language. The entry point is that language's getting-started s | Language | Skill prefix | Skills | | --- | --- | --- | | C#/.NET | `dotnet-` | `dotnet-authentication`, `dotnet-calling-endpoints`, `dotnet-client-initialization`, `dotnet-configuration-resilience`, `dotnet-error-handling`, `dotnet-getting-started`, `dotnet-integrate-spotify-web-api`, `dotnet-models`, `dotnet-testing` | -| python | `python-` | `python-authentication`, `python-calling-endpoints`, `python-client-initialization`, `python-configuration-resilience`, `python-error-handling`, `python-getting-started`, `python-integrate-spotify-web-api`, `python-models`, `python-testing` | -| TypeScript | `typescript-` | `typescript-authentication`, `typescript-calling-endpoints`, `typescript-client-initialization`, `typescript-configuration-resilience`, `typescript-error-handling`, `typescript-getting-started`, `typescript-integrate-spotify-web-api`, `typescript-models`, `typescript-testing` | +| Python | `python-` | `python-authentication`, `python-calling-endpoints`, `python-client-initialization`, `python-configuration-resilience`, `python-error-handling`, `python-event-streams`, `python-file-handling`, `python-getting-started`, `python-integrate-spotify-web-api`, `python-models`, `python-testing` | +| TypeScript | `typescript-` | `typescript-authentication`, `typescript-calling-endpoints`, `typescript-client-initialization`, `typescript-configuration-resilience`, `typescript-error-handling`, `typescript-event-streams`, `typescript-getting-started`, `typescript-integrate-spotify-web-api`, `typescript-models`, `typescript-testing` | + +## Agents + +| Agent | What it does | +| --- | --- | +| `spotify-web-api-planner` | Writes `spotify-web-api-plan.md`, the plan and its contract sheet, before any project code is written, and revises it in place. `dotnet-integrate-spotify-web-api`, `typescript-integrate-spotify-web-api` and `python-integrate-spotify-web-api` each start it once the SDK is installed or its source reached, on the main agent's own model. | + +How each host gets it: + +- **Claude Code** loads it from `scoped/agents/` with the plugin and lists it as `spotify:spotify-web-api-planner`. Its file sets `model: inherit`, so it runs on the main agent's model. +- **Where no subagent tool lists it** (a host that doesn't load a plugin's agents, or subagents turned off), the main agent says so in one line and writes the plan itself before any code. diff --git a/plugins/spotify/plugin.json b/plugins/spotify/plugin.json index 6a7204ff..16465956 100644 --- a/plugins/spotify/plugin.json +++ b/plugins/spotify/plugin.json @@ -1,8 +1,8 @@ { "name": "spotify", "displayName": "Spotify Web API", - "version": "0.2.0", - "description": "Integrate and consume the APIMatic-generated Spotify Web API SDK — bundled skills for C#/.NET, python, TypeScript.", + "version": "0.2.1", + "description": "Integrate and consume the APIMatic-generated Spotify Web API SDK — bundled skills for C#/.NET, Python, TypeScript.", "author": { "name": "APIMatic", "email": "developer@apimatic.io" diff --git a/plugins/spotify/scoped/agents/spotify-web-api-planner.md b/plugins/spotify/scoped/agents/spotify-web-api-planner.md new file mode 100644 index 00000000..d45ad639 --- /dev/null +++ b/plugins/spotify/scoped/agents/spotify-web-api-planner.md @@ -0,0 +1,21 @@ +--- +name: "spotify-web-api-planner" +description: "The Spotify Web API planner. It writes spotify-web-api-plan.md, the plan and its map-grounded contract sheet, before any project code is written, and revises it in place when the main agent sends a clarification. Main agent: start it when an integrate skill of this plugin tells you to, once per integration, with the user's whole request, the name of the integrate skill you loaded, the absolute project root and the absolute path to write spotify-web-api-plan.md to, plus the SDK source's path where that skill says to pass it; edit no project file until it has returned and you have read that file; send revisions to the same agent rather than starting a second." +model: "inherit" +tools: "Read, Grep, Skill, Write, Edit, Bash" +--- + +You are the Spotify Web API planner. You write `spotify-web-api-plan.md` — the plan and its contract sheet — before any project code is written, and you revise it when the main agent sends a clarification. You never write or fix project code, and you never start another agent: you are the planner the workflow asks for. + +**Your instructions are the integrate skill your task names** — this plugin's `-integrate-spotify-web-api` skill for the project's language. Load it, and the getting-started skill it has you load first. Your job is everything that skill puts in `spotify-web-api-plan.md`: the plan, its contract sheet and every table and block the sheet carries, wherever the skill describes them, grounded exactly as the skill says. Skip what belongs to the main agent: *The planner agent* (you are that agent), the read-only prerequisites, the required reading it does before implementing, and the implementation itself. Where your task gives the path of the SDK source the main agent reached, read the map and the source there; reach the SDK source yourself only when it gives none. + +## Plan mode + +Your task gives you the user's whole request, the integrate skill to follow, the absolute project root, the absolute path to write to and, where the integrate skill has the main agent reach the SDK source first, the absolute path to it. Write `spotify-web-api-plan.md` at exactly the path to write to; if none was given, use `/spotify-web-api-plan.md` and say so when you return. It is the only project file you write. Read the project's code only where a table needs it, such as where the codebase already keeps its records, and only read it: do not edit project code, install anything into the project, or run its build or tests. + +Return the plan's path, a one-paragraph summary, and its **Assumptions & Blockers** section verbatim. + +## Revision mode + +When the main agent sends a clarification, a correction or a gap, revise `spotify-web-api-plan.md` in place with targeted edits — edit the changed rows, append a new section; never rewrite the whole file to change a few rows. Reply with ONLY the changed or added rows, verbatim, plus one sentence of context: the main agent works from your reply and does not re-read the file. + diff --git a/plugins/spotify/skills/dotnet/dotnet-authentication/SKILL.md b/plugins/spotify/skills/dotnet/dotnet-authentication/SKILL.md index 8c5d9763..3f110ba9 100644 --- a/plugins/spotify/skills/dotnet/dotnet-authentication/SKILL.md +++ b/plugins/spotify/skills/dotnet/dotnet-authentication/SKILL.md @@ -1,37 +1,18 @@ --- name: "dotnet-authentication" -description: "Authentication for the Spotify Web API .NET SDK in C# — this API authenticates with OAuth 2.0 client credentials and the OAuth 2.0 authorization-code grant, and this skill gives the credential each scheme takes, the SpotifyWebApiClientOptions property to set it on, and the startup check that keeps a missing secret from surfacing as a 401. Load before wiring credentials into the client, or when a call comes back 401/403." +description: "Load before wiring credentials into the Spotify Web API .NET SDK client in C#, or when a call throws AuthSchemeException or comes back 401/403. Covers the OAuth 2.0 authorization-code grant and OAuth 2.0 client credentials: the credential each scheme takes, the SpotifyWebApiClientOptions property it goes on, the environment variable that fills it when unset, and a startup check that fails fast on a missing secret." --- # Authenticating the Spotify Web API .NET SDK client -This API authenticates with OAuth 2.0 client credentials and the OAuth 2.0 authorization-code grant. APIMatic surfaces each scheme as a **nullable credentials property** on `SpotifyWebApiClientOptions`; set the ones below, then construct the client (see `dotnet-client-initialization`). +This API authenticates with the OAuth 2.0 authorization-code grant and OAuth 2.0 client credentials. Each scheme is a **nullable credentials property** on `SpotifyWebApiClientOptions`; set the ones below, then construct the client (see `dotnet-client-initialization`). | Scheme | Property on `SpotifyWebApiClientOptions` | Credential | | --- | --- | --- | -| OAuth 2.0 client credentials | `Oauth20ClientCredentials` | `OAuth2ClientCredentials` | -| OAuth 2.0 authorization code | `Oauth20` | `OAuth2AuthorizationCodeCredentials` | +| OAuth 2.0 authorization code | `Oauth20` | `OAuth2AuthorizationCodeCredentials?` | +| OAuth 2.0 client credentials | `Oauth20ClientCredentials` | `OAuth2ClientCredentials?` | -**That table is the entire authentication surface of this SDK.** `SpotifyWebApi.Core.Authentication` ships *every* scheme class APIMatic supports as shared runtime code, including kinds this API does not use, so read what is configurable off the properties above rather than off that folder. - -## OAuth 2.0 — client credentials (machine-to-machine) - -**API Provider Notes:** - -> Server-to-server OAuth 2.0 client credentials flow. Tokens obtained this way carry no user context and no scopes, so they only work on endpoints that read public catalog data. Verified against the live token endpoint. - -```csharp -using SpotifyWebApi.Core.Authentication.OAuth2.ClientCredentials; - -options.Oauth20ClientCredentials = new OAuth2ClientCredentials -{ - ClientId = "...", - ClientSecret = "...", - Scope = "..." // optional -}; -``` - -The SDK fetches the token from `https://api.spotify.com/v1/api/token` and caches it, acquiring a fresh one when it expires; on a `401` it invalidates the cached token and re-acquires. The token request carries the client id and secret as HTTP Basic credentials, so `ClientSecret` is required. +**That table and the environment variables below are the entire authentication surface of this SDK.** `SpotifyWebApi.Core.Authentication` also holds scheme classes this API does not use, so read what is configurable off the properties above rather than off that folder. ## OAuth 2.0 — authorization code (3-legged, with PKCE) @@ -59,53 +40,73 @@ options.Oauth20 = new OAuth2AuthorizationCodeCredentials }; ``` -The SDK sends the user to `https://api.spotify.com/v1/authorize`, exchanges the returned code for a token at `https://api.spotify.com/v1/api/token`, and refreshes it when it expires; if the refresh fails, it invokes `PromptForAuthorizationCode` again to re-authorize. +The SDK sends the user to `https://accounts.spotify.com/authorize`, exchanges the returned code for a token at `https://accounts.spotify.com/api/token`, and refreshes it when it expires; if the refresh fails, it invokes `PromptForAuthorizationCode` again to re-authorize. -`PromptForAuthorizationCode` runs inside the call that needs a new token, under the scheme's fetch lock, so it must not make an SDK call that uses this scheme. It counts against the per-attempt `options.Retry.Timeout`, 100 s by default, and when the call is retryable (by default a `GET`, `HEAD`, `PUT` or `OPTIONS`) a timed-out attempt is retried and prompts again. A prompt that throws anything but `OperationCanceledException` fails the call with `AuthSchemeException`. `State` is sent as you set it and never checked, so your redirect handler must verify it. +`PromptForAuthorizationCode` runs inside the call that needs a new token, so it must not make an SDK call that uses this scheme. It counts against the per-attempt `options.Retry.Timeout`, 100 s by default, and a timed-out attempt on a retryable call is retried and prompts again. A prompt that throws anything but `OperationCanceledException` fails the call with `AuthSchemeException`. `State` is sent as you set it and never checked, so your redirect handler must verify it. -⚠ **`ClientSecret` is required here — PKCE does not make it optional.** This SDK builds the token request with `OAuth2AuthorizationCodeStrategy.ForBasicAuthRequest`, which sends the client id and secret as HTTP Basic credentials on the exchange. Omit it and the call fails with an `AuthSchemeException` wrapping an `InvalidOperationException`, at one of two very different moments: +⚠ **`ClientSecret` is required here — PKCE does not make it optional.** The code exchange sends the client id and secret as HTTP Basic credentials. Omit it and the call fails with an `AuthSchemeException` wrapping an `InvalidOperationException`: -- **PKCE disabled** (`Pkce = null`) — throws *before* `PromptForAuthorizationCode` runs. -- **PKCE enabled** (the default `S256`) — throws *after* the prompt has already run. The user completes a full browser round-trip, and only then does the exchange fail. This is the expensive one. +- **PKCE disabled** (`Pkce = null`) — *before* `PromptForAuthorizationCode` runs. +- **PKCE enabled** (the default `S256`) — *after* the user has completed the browser round-trip. -The public-client carve-out — a secret-less PKCE flow — belongs to the form-body token request, which this SDK does not use. Do not plan around it here. +## OAuth 2.0 — client credentials (machine-to-machine) + +**API Provider Notes:** + +> Server-to-server OAuth 2.0 client credentials flow. Tokens obtained this way carry no user context and no scopes, so they only work on endpoints that read public catalog data. Verified against the live token endpoint. + +```csharp +using SpotifyWebApi.Core.Authentication.OAuth2.ClientCredentials; + +options.Oauth20ClientCredentials = new OAuth2ClientCredentials +{ + ClientId = "...", + ClientSecret = "...", + Scope = "..." // optional +}; +``` + +The SDK fetches the token from `https://accounts.spotify.com/api/token` and caches it, acquiring a fresh one when it expires; on a `401` it drops the cached token, acquires a new one and re-sends the call once (the upload exception is under **Token caching & refresh**). The token request carries the client id and secret as HTTP Basic credentials, so `ClientSecret` is required. ## Token caching & refresh - Tokens are cached in-memory, **per client instance**, and reused until **30s** before expiry. -- **Only the authorization-code grant refreshes.** It is the one grant wired to `IOAuth2RefreshableTokenStrategy` / `OAuth2RefreshableScheme`. The other grants above re-run in full when the token expires — and a `refresh_token` in their token response is discarded, because the non-refreshable `OAuthToken` has no binding for it. Do not infer refresh behaviour from what the provider returns. -- On `401`, the cached token is invalidated and re-acquired on the next call — the failing request is **not** retried. For the authorization-code grant, invalidation drops the refresh token along with the access token, so "re-acquired" means the *full* grant runs again and `PromptForAuthorizationCode` fires: a `401` there is an interactive re-authorization, not a silent refresh. **Plan for that in a non-interactive host** — a background worker will block on a prompt nobody can answer. -- **Invalidation is a hint, not a barrier.** `Invalidate()` clears the cache without taking the fetch lock, so a token fetch already in flight can complete and re-populate it. That is deliberate — the refreshed token post-dates the invalidation — but it means "invalidate then immediately read" is not a guarantee of a fresh token. +- **`options.Oauth20` requests the whole catalogue (`app-remote-control playlist-read-private playlist-read-collaborative playlist-modify-public playlist-modify-private user-library-read user-library-modify user-read-private user-read-email user-follow-read user-follow-modify user-top-read user-read-playback-position user-read-playback-state user-read-recently-played user-read-currently-playing user-modify-playback-state ugc-image-upload streaming`) on every token request**, so one token — and one consent — covers every operation. +- **`options.Oauth20ClientCredentials` mints one token per scope set.** An operation that declares scopes gets a token requested with exactly those scopes (the SDK map's **Auth** bullet lists them); operations that declare none share one token requested without a scope. +- **Only the authorization-code grant refreshes.** The SDK keeps the `refresh_token` the server issues and renews silently; when the refresh fails the full grant runs again. Client credentials re-run in full when the token expires, and a `refresh_token` in that response is ignored. +- On `401`, the rejected token is dropped, a new one is obtained and the failing request is **re-sent once** — under every retry setting, including `RetryOptions.Disabled()`; a second `401` is returned to you. A request whose body cannot be re-sent (a binary or file upload) is not re-sent, but its `401` still drops the cached token, so the next call recovers. For the authorization-code grant the refresh token is tried first, so the re-send is silent unless the refresh itself fails — then `PromptForAuthorizationCode` fires inside the call. **Plan for that in a non-interactive host** — a background worker will block on a prompt nobody can answer. +- After a `401` clears the cache, a token fetch already in flight can still re-populate it, so the next call is not guaranteed a newly fetched token. -⚠ **If the token response omits `expires_in`, the token never expires as far as the SDK is concerned.** `expires_in` is RECOMMENDED but not required by RFC 6749, and the SDK's expiry check short-circuits to "not expired" when it is absent — so the first token is cached for the life of the client and the only thing that ever replaces it is a `401`. That is usually fine and occasionally not: a token revoked server-side keeps being sent until a request fails with it. If your provider omits `expires_in` and you need proactive rotation, supply your own token strategy (below) rather than trying to bound the cache. +Setting `Scope` on the credentials replaces the per-scheme behaviour above with one token requested with that value; an empty `Scope` requests none. Set it to the scopes your client is registered for when the API declares more than it grants you: the default asks for the whole catalogue, and an authorization server that enforces per-client scope registration answers `invalid_scope` to that request. -### Supplying your own token source +⚠ **If the token response omits `expires_in`, the SDK treats the token as never expiring**: it is cached for the client's lifetime and replaced only after a `401`, so a token revoked server-side keeps being sent until a request fails with it — a failure the one re-send above recovers, at the cost of a round trip. -The token strategy is a public extension point: `SpotifyWebApiClientOptions` exposes a strategy property beside each credentials property, and the generated client falls back to the built-in strategy only when you leave it null. The strategy is used only when the credentials property beside it is also set, and `GetToken` receives that object. +## Combining the schemes -| Grant | Strategy property on `SpotifyWebApiClientOptions` | Type | -| --- | --- | --- | -| Client credentials | `Oauth20ClientCredentialsTokenStrategy` | `IOAuth2TokenStrategy` | -| Authorization code | `Oauth20TokenStrategy` | `IOAuth2RefreshableTokenStrategy` | +This SDK has more than one credentials property, and its operations compose them; you choose by which properties on `SpotifyWebApiClientOptions` you set. -```csharp -options.Oauth20ClientCredentials = new OAuth2ClientCredentials { /* its required members */ }; -options.Oauth20ClientCredentialsTokenStrategy = new MyTokenStrategy(); // Task GetToken(creds, ct) -``` +**OR — alternatives, in the order the API lists them.** Schemes with **no credentials configured are skipped, not tried**; the first configured scheme that applies wins, and `AuthSchemeException` is thrown when none is configured, naming every alternative, or when every configured one fails. Configure exactly the one you intend to use — an extra credential set "just in case" changes which scheme authenticates the call. **Which one that is, is not a preference:** each scheme's **API Provider Notes** above are where the provider states when its scheme applies. -Reach for it when the token must come from somewhere other than the SDK's own call to the token endpoint — a shared cache across processes, a secrets broker, a sidecar that already holds a valid token, or a test double. The per-client in-memory cache above still wraps whatever you return. +## Environment variables -## Combining the schemes +A credentials property left `null` is read from an environment variable when the client is constructed — the SDK name in upper snake case, the property name in upper snake case, and for a multi-member credential the member: -This SDK generates more than one credentials property, and its operations compose them. You configure the composition by setting the relevant properties on `SpotifyWebApiClientOptions` — the generated client wires the rest. +| Property on `SpotifyWebApiClientOptions` | Environment variables | +| --- | --- | +| `Oauth20ClientCredentials` | `SPOTIFY_WEB_API_OAUTH20_CLIENT_CREDENTIALS_CLIENT_ID`, `SPOTIFY_WEB_API_OAUTH20_CLIENT_CREDENTIALS_CLIENT_SECRET`, `SPOTIFY_WEB_API_OAUTH20_CLIENT_CREDENTIALS_SCOPE` (optional) | -**OR (`AuthSchemeAny`) — alternatives, tried in order.** Schemes with **no credentials configured are skipped, not tried**; the first configured scheme that succeeds wins, and `AuthSchemeException` is thrown only if every *configured* scheme fails. Configure exactly the one you intend to use — an extra credential set "just in case" changes which scheme authenticates the call. **Which one that is, is not a preference:** each scheme's **API Provider Notes** above are where the provider states when its scheme applies. +`options.Oauth20` has no environment default. -## ⚠ Missing credentials must stop the app from starting +- A value set in code always wins over the environment. +- A variable that is unset, empty or whitespace counts as not configured. +- A multi-member credential is used only when every required variable is set. If some are missing the property stays `null`; constructing the client never throws, and a call that requires that credential fails before anything is sent. +- Variables are read once, when the client is constructed. Changing them afterwards has no effect on an existing client. -⚠ **Configure nothing and the request goes out unauthenticated — no exception.** An unset credentials property on `SpotifyWebApiClientOptions` yields a no-op scheme, not an error, so the call reaches the provider with no credential and comes back `401`. The SDK will never tell you that you forgot to supply one; only the provider will, one round-trip later and one layer away from the cause. +Binding `SpotifyWebApiClientOptions` from `IConfiguration` keeps both paths: a property the binding leaves `null` still falls back to its variable. The README's **Credentials from environment variables** section shows the binding. -**A required credential that is not configured is a deployment fault, not a request fault.** If the app boots with a blank secret, an operator sees a provider outage, retry logic hammers a call that can never succeed, and the actual cause — an unset environment variable — is two layers away from the symptom. +## ⚠ Missing credentials must stop the app from starting + +⚠ **Configure nothing and the first call that needs the credential throws.** A credentials property on `SpotifyWebApiClientOptions` that nothing fills — code or an environment variable — fails the call with `AuthSchemeException` before anything is sent, naming the scheme. That is a request-time failure for a deployment fault: catch it at startup instead. **Validate at startup and refuse to boot.** Bind the credentials into your own options type and make the host check it before the app serves anything: @@ -126,24 +127,26 @@ if (string.IsNullOrWhiteSpace(settings.ClientId)) "user-secrets, or your secret store before starting the app."); ``` +**If the SDK's environment variables supply the credential**, `ValidateOnStart()` sees nothing: the SDK reads the variable itself, and a settings type bound from `IConfiguration` would refuse to boot a host the SDK authenticates. Check the variable instead, with the same guard before the host is ready — the **Or environment variable** column below names it. + Three rules for the message it fails with: -- **Name the missing config key**, so the operator knows what to set — `"SpotifyWebApiClient:ClientId is not configured"`, not `"authentication failed"`. +- **Name the missing config key or variable**, so the operator knows what to set — `"SpotifyWebApiClient:ClientId is not configured"`, not `"authentication failed"`. - **Never echo the value**, present or absent — no length, no prefix, no masked form. A "configured: AC1234…" line is a secret in a log. - **Do not fall back to a default, a placeholder, or an unauthenticated client.** Booting degraded hides the fault and pushes it to the first caller. Check every value **the scheme you chose** needs. The rows below are not one checklist: the schemes above are alternatives, so a row belonging to a scheme you are not using needs no value at all, and demanding one at startup blocks a boot that would have worked. Validate the rows whose property you set, and no others: -| Value to validate | Feeds `SpotifyWebApiClientOptions` property | -| --- | --- | -| `ClientId` | `Oauth20ClientCredentials` | -| `ClientSecret` | `Oauth20ClientCredentials` | -| `ClientId` | `Oauth20` | -| `ClientSecret` | `Oauth20` | -| `RedirectUri` | `Oauth20` | +| Value to validate | Feeds `SpotifyWebApiClientOptions` property | Or environment variable | +| --- | --- | --- | +| `ClientId` | `Oauth20` | — | +| `ClientSecret` | `Oauth20` | — | +| `RedirectUri` | `Oauth20` | — | +| `ClientId` | `Oauth20ClientCredentials` | `SPOTIFY_WEB_API_OAUTH20_CLIENT_CREDENTIALS_CLIENT_ID` | +| `ClientSecret` | `Oauth20ClientCredentials` | `SPOTIFY_WEB_API_OAUTH20_CLIENT_CREDENTIALS_CLIENT_SECRET` | ## Notes - Set credentials **before** constructing the client, or inside the `AddSpotifyWebApiClient(options => ...)` callback when registering via DI. `SpotifyWebApiClientOptions` is read at construction; mutating it afterwards does not re-wire an existing client. -- Keep secrets out of source — load them from configuration (environment variables, a secret store, or any other `IConfiguration` source) instead of hardcoding, either inside the `AddSpotifyWebApiClient(options => ...)` callback for a host or via a `ConfigurationBuilder()...Build()` chain for a console app. +- Keep secrets out of source — load them from configuration (environment variables, a secret store, or any other `IConfiguration` source) instead of hardcoding, either inside the `AddSpotifyWebApiClient(options => ...)` callback for a host or via a `ConfigurationBuilder()...Build()` chain for a console app — or leave the property unset and let the SDK read its environment variable (see **Environment variables**). diff --git a/plugins/spotify/skills/dotnet/dotnet-calling-endpoints/SKILL.md b/plugins/spotify/skills/dotnet/dotnet-calling-endpoints/SKILL.md index fb0db712..866cee13 100644 --- a/plugins/spotify/skills/dotnet/dotnet-calling-endpoints/SKILL.md +++ b/plugins/spotify/skills/dotnet/dotnet-calling-endpoints/SKILL.md @@ -1,6 +1,6 @@ --- name: dotnet-calling-endpoints -description: Calling operations on an APIMatic-generated .NET SDK in C# — finding the controller that owns an operation, required vs optional parameters, request and response envelope shapes, async usage, and cancellation. Load before writing the first call to an SDK operation, or when an operation's shape or return type is unclear. +description: Load before writing the first call to an operation on an APIMatic .NET SDK in C#, or when an operation's input or return type is unclear — finding the controller that owns an operation, the per-operation request record, the requestOptions and cancellationToken arguments, response shapes and cancellation. --- # Calling endpoints on an APIMatic .NET SDK @@ -16,7 +16,8 @@ names follow no fixed verb/resource pattern, so take the real name from the shee ## Method signature convention -Every endpoint method is `async` (returns a `Task`) and takes at most three parameters, in a fixed order: +Every endpoint method is `async` (returns a `Task`; there are no sync overloads) and takes at most three +parameters, in a fixed order: ```csharp public Task<{ReturnType}> {Operation}( @@ -44,13 +45,7 @@ public Task<{ReturnType}> {Operation}( positional call that skips it puts your `CancellationToken` where a `RequestOptions?` is expected, and the call fails to compile with `CS1503: Argument N: cannot convert from 'System.Threading.CancellationToken' to '{RootNamespace}.Core.RequestOptions?'`. Pass `cancellationToken:` by name and the problem cannot arise. -- **The contract sheet is the source of truth for the record.** Which members are `required`, which are - nullable, which carry a default — and whether there is a `Body` — varies per operation. Take each - operation's record from the contract sheet (grounded from the SDK map/source), not from memory. - **Return type** varies by operation — see [Reading the response](#making-the-call-and-reading-the-response). -- Methods are **async-only** (no sync overloads) and **throw `ApiException`** on API errors — one leaf - of the SDK's `SdkException` family, which also covers connection failures and timeouts — see - `dotnet-error-handling`. ## Building the request record @@ -59,10 +54,10 @@ what you owe it: | Property | Meaning | You | |---|---|---| -| `public required T X { get; init; }` | required, no spec default | **must** set it — the compiler enforces this | -| `public T X { get; init; } = value;` | the spec declares a default | set it only to override; leaving it sends the default | +| `public required T X { get; init; }` | required, no default | **must** set it — the compiler enforces this | +| `public T X { get; init; } = value;` | has a default | set it only to override; leaving it sends the default | | `public T? X { get; init; }` | optional, no default | leave it unset to omit it from the request | -| `public T X { get; } = value;` | the spec fixes the value (`const`) | cannot set it — it is sent as declared | +| `public T X { get; } = value;` | a fixed value (`const`) | cannot set it — it is always sent | ```csharp var response = await client.{ApiGroup}.{Operation}( @@ -79,34 +74,25 @@ var response = await client.{ApiGroup}.{Operation}( - **Property names are PascalCase C# names, not wire names.** `per_page` on the wire is `PerPage` on the record. The wire keys appear only inside the generated method body, as `new Param("per_page", request.PerPage)` — read names off the record, never off that list. -- **The record is never serialized**, so it carries no `[JsonPropertyName]`. Its members may carry constraint - attributes (`[Minimum(0)]`, `[MaxLength(256)]`); they document the API's limits and nothing in the SDK - enforces them before the call. +- **The record is never serialized**, so it carries no `[JsonPropertyName]`. Constraint attributes on its + members (`[Minimum(0)]`, `[MaxLength(256)]`) are not enforced — see **dotnet-models**. - **A JSON, plain-text or binary body is always the member `Body`** (`Body_` in the rare API that also has a parameter literally named `body`). A `application/x-www-form-urlencoded` or multipart form has **no** `Body`: each - form field is its own property on the record, and the generator assembles the form itself. + form field is its own property on the record, and the SDK assembles the form itself. ## Files A file is a `BinaryContent`, built with an object initializer that sets all three: a `Stream`, a `FileName` -(may be `null`) and a `ContentType` -(a `MediaTypeHeaderValue`). A `Stream` or `byte[]` also converts to one, typed `application/octet-stream` and -named only for a `FileStream`; the SDK does not apply the spec's media type, so set `ContentType` whenever the spec -declares one, and `FileName` when the API needs a name. The SDK never disposes or rewinds your stream, and never retries a call -that sends a file. +(may be `null`) and a `ContentType` (a `MediaTypeHeaderValue`). A `Stream` or `byte[]` also converts to one, +typed `application/octet-stream` whatever media type the operation documents, and named only for a +`FileStream` — so set `ContentType` whenever the API expects a specific type, and `FileName` when it needs a +name. The SDK never disposes or rewinds your stream, and never retries a call that sends a file. ## Building request models -**A form-bodied operation has no `Body` member.** Where the API declares a -`application/x-www-form-urlencoded` or multipart request, the generator emits the fields as *individual -members of the request record* and assembles the form itself — there is no body model to construct and no -`Body` to set. -In an API built that way this is the majority shape, not an exception. The contract sheet says -which you are looking at; the record settles it. - -For the JSON case: request bodies are immutable `record`s built with object-initializer syntax (no -builders). `required` members must be set; optional ones are nullable and are omitted from the JSON when -left null. The body model is the type of the request record's `Body` member — a different type from the +A JSON request body is an immutable `record` built with object-initializer syntax (no builders). +`required` members must be set; optional ones are nullable and are omitted from the JSON when left null. +The body model is the type of the request record's `Body` member — a different type from the request record itself — so take its exact name from the contract sheet (grounded from the SDK map/source): ```csharp @@ -134,21 +120,14 @@ var body = new {RequestType} ## Enums -Enums are type-safe string- **or int-**enums (`OpenStringEnum` / `OpenIntEnum`), not C# enums — use -the static constants. There is no `FromValue`: a value the spec does not declare cannot be constructed, and -a raw value resolves through `{EnumType}.TryGetKnownValue(value, out var known)`. See **dotnet-models** for -read-back semantics (implicit conversion to the underlying value, `==` / `Is` against raw values, and the -generated `Match`). - -```csharp -SomeProp = {EnumType}.SomeConstant; -SomeProp = {EnumType}.TryGetKnownValue(configured, out var known) ? known : {EnumType}.SomeConstant; -``` +Enums are `OpenStringEnum` / `OpenIntEnum` records, not C# enums: use the static constants +(`{EnumType}.SomeConstant`). There is no `FromValue`; resolve a raw value with +`{EnumType}.TryGetKnownValue(value, out var known)`. See **dotnet-models**. ## Union types, collections, and dates Some properties are not plain scalars: polymorphic `OneOf`/`AnyOf` unions (built with **factory methods**, -not object-initializers, and read via `TryGet…`), `IReadOnlyList`/`IReadOnlyDictionary` collections, and +not object-initializers, and read via `TryGet…` or `Match`), `IReadOnlyList`/`IReadOnlyDictionary` collections, and `DateTimeOffset` dates. If a request property or response field is one of these, see **dotnet-models** for how to construct and read it. @@ -189,20 +168,12 @@ contract sheet's response-envelope column names the return type and the inner fi bounds the read, and a drop while you read throws a raw `IOException` from your read, not `SdkConnectionException`. -Endpoints in the same family can differ — one nests the resource, another returns it directly — so let each -method's return type guide how you read it. - -An operation may also expose an optional **`{Operation}Result`** sibling that returns -`ApiResult` — the outcome (the response, or a typed/`RawError` error) instead of -throwing, with the HTTP status and headers available on both. It's optionally generated, so it may not -exist. See **dotnet-error-handling**. +A non-throwing **`{Operation}Result`** sibling may exist — see **dotnet-error-handling**. ## Cancellation -Every operation takes a `CancellationToken` as its last argument, passed as `cancellationToken:`, with -`RequestOptions? requestOptions = null` immediately before it — so the token is last, never second-to-last. To bound an individual call with a -timeout, use the per-request cancellation pattern in **dotnet-configuration-resilience** (it owns -timeouts). +Pass the token as `cancellationToken:` (see the signature above). To bound a call with a timeout, see +**dotnet-configuration-resilience** § *Bounding a call*. ## Worked example — a list/GET call @@ -223,7 +194,7 @@ var results = await client.{ApiGroup}.{Operation}( Filter = {EnumType}.SomeConstant, Q = "search text", PerPage = 20 // literal must match the member's type — a `20d` against an `int` is CS0266 - }, // StartDate is left unset and omitted; Page keeps the spec default + }, // StartDate is left unset and omitted; Page keeps its default cancellationToken: ct); foreach (var item in results) diff --git a/plugins/spotify/skills/dotnet/dotnet-client-initialization/SKILL.md b/plugins/spotify/skills/dotnet/dotnet-client-initialization/SKILL.md index 948c68eb..494ded7a 100644 --- a/plugins/spotify/skills/dotnet/dotnet-client-initialization/SKILL.md +++ b/plugins/spotify/skills/dotnet/dotnet-client-initialization/SKILL.md @@ -1,6 +1,6 @@ --- name: dotnet-client-initialization -description: Creating and registering an APIMatic-generated .NET SDK client in C# — construction, the builder/options shape, HttpClient ownership and lifetime, and dependency-injection registration in ASP.NET Core. Load before wiring the client into an application's service container or writing the factory that builds it. +description: Load before constructing an APIMatic .NET SDK client in C#, registering it in a service container, or writing the factory that builds it — the client options class, HttpClient ownership and lifetime, dependency-injection registration in ASP.NET Core, and inbound webhooks. --- # Initializing an APIMatic .NET SDK client @@ -22,12 +22,9 @@ object: public {Api}Client(HttpClient httpClient, {Api}ClientOptions options) ``` -Operations are exposed on the client. Most are grouped under **controller properties** (one per API resource -group) and called `client.{ApiGroup}.{Operation}(...)` — for example, a `Widgets` controller's -`ListWidgets` operation is `client.Widgets.ListWidgets(new ListWidgetsRequest { ... })`. An operation that belongs to no group sits -**directly on the client**, called `client.{Operation}(...)`. The available controller properties (and any -direct operations) come from the contract sheet (grounded from the SDK map/source), -not a decompiled or reflected view of the installed package. See `dotnet-calling-endpoints`. +Operations hang off **controller properties** (`client.{ApiGroup}.{Operation}(...)`) or sit directly on the +client (`client.{Operation}(...)`). Take them from the contract sheet (grounded from the SDK map/source), not +a decompiled or reflected view of the installed package — see `dotnet-calling-endpoints`. The options class always carries these knobs (auth properties vary per API — see `dotnet-authentication`): @@ -41,19 +38,16 @@ public class {Api}ClientOptions public ServerOptions Server { get; set; } = new(); public IReadOnlyList Hooks { get; set; } = []; // request/response observation — // see dotnet-configuration-resilience § Hooks - // + one nullable credentials property per auth scheme the API declares, and — for an OAuth2 - // scheme — a nullable {Scheme}TokenStrategy hook alongside it (see dotnet-authentication) + // + one nullable credentials property per auth scheme the API declares, and — for a static + // scheme — a nullable {Scheme}Provider delegate asked on every request (see dotnet-authentication) } ``` -`Logging` is a real property, not a placeholder — the SDK has a **built-in** request/response logger, and -what an unset `Logging.LoggerFactory` means depends on how the client is built. Under `Add{Api}Client` the -extension fills it from the container's `ILoggerFactory`, so logging is **already on** at your host's level. -On a client you construct yourself it falls through to a `{APICLIENTTYPENAME}_LOG` environment variable that -can switch logging — including unredacted JSON request bodies — on from outside your code. Set it -explicitly either way; **dotnet-configuration-resilience** has the full table. Tuning these knobs — `Retry` (retries, backoff, per-attempt timeout), `Logging`, and -`Server` / `Environment` (server selection and **overriding the base URL**), plus pagination — is covered in -**dotnet-configuration-resilience**. +`Logging` is a **built-in** request/response logger: under `Add{Api}Client` it is **already on**; on a client +you construct yourself a `{API}_LOG` environment variable — `{API}` being the SDK name in upper snake case — can +turn it on, unredacted JSON bodies included. Set `Logging.LoggerFactory` explicitly either way. +**dotnet-configuration-resilience** covers +`Retry`, `Logging`, `Server` / `Environment` (including **overriding the base URL**) and pagination. ## Direct instantiation @@ -64,7 +58,8 @@ using {RootNamespace}.Servers; var options = new {Api}ClientOptions { Environment = ServerEnvironment.Default(), // pick the environment your API exposes - // ...set the auth credentials property your API uses (see dotnet-authentication) + // ...set the auth credentials property your API uses, or leave it null and set its + // {API}_* environment variable instead (see dotnet-authentication) }; var httpClient = new HttpClient(); // reuse a single long-lived instance @@ -77,32 +72,19 @@ The SDK does **not** own the `HttpClient` — you provide it. Reuse one instance (or use `IHttpClientFactory`); do not create one per request. Attach custom `HttpMessageHandler`s here for logging, proxies, or custom TLS (see `dotnet-configuration-resilience`). -**Keep both the `HttpClient` and the SDK client long-lived — the client is not a stateless wrapper.** The -only thing you hand it is the HTTP pipeline; its constructor builds the rest and then owns it: - -- the **resilience pipelines** — two Polly pipelines are eagerly built from `options.Retry`; -- the **logger** — constructed here, which is also where the `{APICLIENTTYPENAME}_LOG` environment variable - is read; -- the **auth schemes**, and for an OAuth2 SDK the auth scheme *is* the access-token cache — an instance - field on the scheme object. - -That last one is the reason a per-request client is a real cost rather than a stylistic one: a fresh client -starts with an empty token cache, so **every resolution pays a token request on its first call**. Three -calls through three transient clients is three token round-trips where a shared client makes one. - -Reuse one `HttpClient` (or let `IHttpClientFactory` own it) *and* one SDK client for the app's lifetime. -Construct per request only where you genuinely need different credentials per request — and then expect the -token fetch. +**Keep the SDK client long-lived too.** Its constructor builds and owns the retry pipelines (from +`options.Retry`), the logger (reading `{API}_LOG`) and the auth schemes — for OAuth2 the scheme +holds the access-token cache, so a fresh client starts with an empty cache and **pays a token request on its +first call**. Reuse one SDK client for the app's lifetime; construct per request only where credentials +genuinely differ per request, and expect the token fetch. ## Choosing the server / base URL -Environments are modeled as a `ServerEnvironment` string-enum with one constant per environment the API -defines (e.g. `ServerEnvironment.Production`, or region constants). Select one on `options.Environment`. -Overriding a templated parameter or the base URL is nested **per server AND per environment** — -`options.Server.{ServerName}.{Environment}.BaseUrl` (with any templated params at the same level), NOT -directly on `ServerOptions`. **dotnet-configuration-resilience** documents this in full and owns -server / base-URL configuration. The exact constants and template parameters for your API come from the -contract sheet (grounded from the SDK map/source). +Select the environment with `options.Environment = ServerEnvironment.{Environment}` — one constant per +environment (e.g. `ServerEnvironment.Production`, or region constants). Base-URL and templated-parameter +overrides live at `options.Server.{ServerName}.{Environment}`, NOT directly on `ServerOptions` — see +**dotnet-configuration-resilience**. The constants and template parameters come from the contract sheet +(grounded from the SDK map/source). ## Dependency injection (ASP.NET Core / generic host) @@ -122,18 +104,13 @@ builder.Services.Add{Api}Client(options => }); ``` -⚠ **The extension registers the client as a `singleton`, and that has a consequence worth planning for.** -A singleton calls `CreateClient()` *once* and holds that `HttpClient` for the process lifetime, so -`IHttpClientFactory`'s handler rotation never applies to it and a DNS change is cached indefinitely — the -classic symptom is an app that keeps calling a decommissioned IP after a provider fails over, and only a -restart fixes it. (A transient registration avoids *this* problem — each resolution takes a fresh `HttpClient` and the -pooled pipeline stays rotated — but it buys stale-DNS safety with a fresh, empty OAuth token cache per -resolution, so it is a trade, not a fix. See the lifetime note above.) - -The actual fix is cheap: set `PooledConnectionLifetime` on the primary handler so the pool recycles -connections on a timer, and keep the SDK client long-lived. Registering yourself over a named `HttpClient` -(below) gives you the same control plus an unshared pipeline. Confirm the registration in the extension rather than trusting this paragraph if your SDK was -generated by a different version — it is one line, and the contract sheet carries it. +⚠ **The extension registers the client as a `singleton`.** It calls `CreateClient()` *once* and holds that +`HttpClient` for the process lifetime, so `IHttpClientFactory`'s handler rotation never applies to it and a +DNS change is never picked up — the app keeps calling a decommissioned IP after a provider fails over, until +a restart. A transient registration avoids stale DNS but pays a fresh, empty OAuth token cache per +resolution (see the lifetime note above). The fix: set `PooledConnectionLifetime` on the primary handler so +the pool recycles connections on a timer, and keep the SDK client long-lived. Registering yourself over a +named `HttpClient` (below) gives you the same control plus an unshared pipeline. To attach custom `DelegatingHandler`s (logging, proxies, custom TLS) under this DI registration, configure the **default, unnamed** factory client it resolves — e.g. @@ -145,10 +122,8 @@ yourself over a **named** `HttpClient` — the same shape the extension uses, mi ### Registering over a named `HttpClient` -The full shape. **`Timeout` is not optional to think about** — the default is `100s`, which matches the SDK's -own per-attempt retry timeout. On defaults a hung provider costs you ~100s on a `POST` and **~407s on a -`GET`**, because the SDK's per-attempt timeout is itself a retry trigger on the retryable verbs (see -**dotnet-configuration-resilience**). Either number is an outage, not a timeout: +The full shape. **Set `Timeout`**: the default `100s` bounds one attempt, and a hung provider costs ~100s on +a `POST` and ~407s on a `GET` (see **dotnet-configuration-resilience** § *Bounding a call*): ```csharp using {RootNamespace}; @@ -175,10 +150,8 @@ services.AddSingleton(sp => }); ``` -Both knobs above are load-bearing and they answer different failures: `PooledConnectionLifetime` keeps DNS -fresh behind a long-lived client, and `Timeout` stops a hung provider from holding a request, a pooled connection and the caller open (~100s, -and ~407s on a retryable verb — see **dotnet-configuration-resilience**). Setting -only the first is the common mistake — it looks like the resilience box is ticked. +`PooledConnectionLifetime` keeps DNS fresh behind a long-lived client; `Timeout` stops a hung provider holding +the request. Set both. Then inject it: @@ -191,30 +164,19 @@ public sealed class MyService({Api}Client client) ## Inbound webhooks — what `Core/Webhooks/` does and does not give you -Every emitted SDK ships a `Core/Webhooks/` tree: `WebhookRequest`, `WebhookEvent<…>`, -`WebhookEventParser<…>`, and a `Signing/` folder holding `SignatureVerifier`. Three facts about it, verified -on both sampled 4.0.0 SDKs, decide whether any of it is usable: - -- **`SignatureVerifier` is `internal sealed`, with no `InternalsVisibleTo`.** You cannot call it, construct - it, or subclass it from your code. It is fully implemented — HMAC, digest encodings, replay tolerance — - and on both samples it has **zero callers**. -- **`WebhookEventParser.Parse` verifies nothing.** It parses the body with `JsonDocument.Parse`, - checks the root is a JSON object, and hands off to an abstract `CreateEvent`. The name reads like a - security boundary; it is a deserializer. -- **`WebhookEventParser` and `WebhookEvent` are `public abstract`, and neither sampled SDK generates a - concrete subclass**, because neither spec declares webhook events. The public machinery has nothing to - instantiate — a base class waiting on generated code that was never emitted. - -So on an SDK with no generated events, signature verification is yours to write, against the provider's -published scheme. `WebhookRequest` remains useful on its own — `FromStream`, `FromBytes`, `TryGetHeader` -give you a body-and-headers holder to verify against — but it computes nothing for you. - -> **Not settled by either sample.** Whether a spec that *does* declare webhook events generates a concrete -> parser, and whether that generated parser calls the internal `SignatureVerifier`, is unknown here — no -> sampled SDK exercises it. An `internal` verifier is exactly what you would expect if generated code is -> its intended caller, so do not read "verification happens outside the SDK" as a property of the -> generator. It is what is true when no events were generated. Look for a `WebhookEvent` subclass in the -> emitted tree before assuming either way. +Every SDK ships `Core/Webhooks/`: `WebhookRequest` (`FromStream`, `FromBytes`, `TryGetHeader` — a +body-and-headers holder) and the `public abstract` `WebhookEventParser` and `WebhookEvent<…>`. +**`WebhookEventParser.Parse` verifies nothing** — it checks the body is a JSON object and builds the +event; it is a deserializer, not a security boundary. + +If the SDK has a `{RootNamespace}.Webhooks` namespace, it holds a concrete `{Api}WebhookParser`, registered +by `services.Add{Api}Webhooks()`. If that namespace also holds a public `{Api}WebhookSignatureVerifier`, +verify with its `bool Verify(WebhookRequest)` before you parse: it is built from `WebhookOptions` (`Secret`, +`TimeProvider`, and `ReplayTolerance` where present) and registered by +`services.Add{Api}WebhookSignatureVerifier(o => o.Secret = ...)`; its constructor throws +`InvalidOperationException` on a blank `Secret`. Without that class, verification is yours to write against +the provider's published scheme — `Core/Webhooks/Signing/SignatureVerifier` is `internal` and cannot be +called from your code. ## Next diff --git a/plugins/spotify/skills/dotnet/dotnet-configuration-resilience/SKILL.md b/plugins/spotify/skills/dotnet/dotnet-configuration-resilience/SKILL.md index 8d1c807a..e1e44431 100644 --- a/plugins/spotify/skills/dotnet/dotnet-configuration-resilience/SKILL.md +++ b/plugins/spotify/skills/dotnet/dotnet-configuration-resilience/SKILL.md @@ -1,20 +1,17 @@ --- name: dotnet-configuration-resilience -description: Client configuration and resilience for an APIMatic-generated .NET SDK in C# — retries and backoff, timeouts and cancellation, base-URL/server selection, list pagination, SSE streaming, and request/response logging. Load before you register or tune the client — the option names alone do not reveal which calls retry, what a timeout actually bounds, or what you must still set yourself. +description: Load before registering or tuning an APIMatic .NET SDK client in C# — retries and backoff, timeouts and cancellation, base-URL/server selection, list pagination, SSE streaming, request/response logging and hooks. Load it even when the option names look obvious; they don't show which calls retry or what a timeout bounds. --- # Configuration & resilience for an APIMatic .NET SDK -> **One skill, every shape.** This file covers every configuration surface the 4.0.0 generator -> emits. Which parts YOUR SDK exercises — which pagination strategy an operation gets, whether any -> operation declares an idempotency-key parameter, which server variables exist — are facts of the -> API definition, not of this skill: take them from the contract sheet or the map, and **apply -> only the guidance that matches**. +> **One skill, every shape.** This file covers every configuration surface the SDK can have. Which +> ones YOUR SDK uses — the pagination strategy of each operation, any idempotency-key parameters, the +> server variables — is in the contract sheet or the map: **apply only the guidance that matches**. Most types below live under `{RootNamespace}.Core.Configuration` and `{RootNamespace}.Servers`; the exception family (`SdkException` and its leaves — see **dotnet-error-handling**) sits under `.Core.Exceptions` and the per-call `RequestOptions` under `.Core`. Each section names its own namespace. -All of them are generic across APIMatic .NET SDKs built by this generator. ## ServerOptions configuration for each Environment @@ -61,7 +58,7 @@ client to change environment. | Setting | Default | | --- | --- | | `StatusCodesToRetry` | `408, 429, 500, 502, 503, 504` | -| `HttpMethodsToRetry` | `GET, HEAD, PUT, OPTIONS` (idempotent only — gates **every** retry trigger, see notes) | +| `HttpMethodsToRetry` | `GET, HEAD, PUT, OPTIONS` — gates every transient retry trigger, not the OAuth2 `401` re-send (Notes) | | `MaxRetries` | `3` | | `Delay` | `1s` | | `BackOffFactor` | `2` | @@ -70,23 +67,12 @@ client to change environment. | `Timeout` | `100s` (**per attempt**) — **too long for any interactive path; set it explicitly** | | `OnRetry` | `null` | -**Do the arithmetic on those defaults before you accept them.** `MaxRetries = 3` means up to 4 attempts, each -bounded at `100s`, with `1s + 2s + 4s` of backoff between them. What that costs depends on the **verb**, because -`HttpMethodsToRetry` gates *every* retry trigger — including the per-attempt timeout firing (see Notes): - -| Provider behaviour | On a retryable verb (`GET`/`HEAD`/`PUT`/`OPTIONS`) | On any other verb | -| --- | --- | --- | -| **Hangs** (no response at all) | up to **4 × 100s + 7s ≈ 407s** — the per-attempt timeout fires and the rejection **is** retried | ≤ **100s** — one attempt, then the call ends | -| **Fails retryably** (a `503`, a connection reset) | up to **≈ 407s** — each attempt can burn nearly the full timeout | ≤ **100s** — one attempt at the provider's own latency; never resent | - -So the worst case on a `GET` is ≈**7 minutes** on the defaults — almost all of it per-attempt `Timeout`, -not backoff — and up to ≈**9.7 minutes** -(`4 × 100s + 3 × 60s`) against a provider that answers every attempt with a large `Retry-After`, since that -header replaces the backoff and clamps at 60s (see Notes). Either way it is nowhere near the ≈100s the -`Timeout` value suggests. The SDK's send path is fully async, so no thread is blocked — but the request, a -pooled connection and the caller's browser are all held open for that whole window. Treat every default in -this table as a value you have chosen only once you have written it down; `Timeout` in particular has no -defensible default for a request-path call. +**Worst case on the defaults:** up to 4 attempts × `100s` + `1s + 2s + 4s` of backoff ≈ **407s** on a +retryable verb (`GET`/`HEAD`/`PUT`/`OPTIONS`) — whether the provider hangs (the per-attempt timeout is itself +retried) or fails retryably — and up to ≈ **9.7 minutes** (`4 × 100s + 3 × 60s`) if every attempt returns a +large `Retry-After`. Any other verb gets one attempt, ≤ **100s** — two when an OAuth2 `401` is re-sent +(Notes). The request, a pooled connection and your caller are held open for that whole window, so choose +every value in this table deliberately; `Timeout` has no safe default for a request-path call. Customize — always by `with` on `Default()`: every `RetryOptions` member is `required`, so a partial `new RetryOptions { MaxRetries = 5 }` does not compile: @@ -107,80 +93,55 @@ Notes: - The *n*th retry waits `Delay * BackOffFactor^(n-1) + random(0, MaxJitter)` — so the 1st retry waits `Delay` (1s), the 2nd `Delay * BackOffFactor` (2s), and so on. Set `UseExponentialBackoff = false` for a constant `Delay` between attempts. -- **`HttpMethodsToRetry` gates every trigger, not just the status one.** `ShouldHandle` reads - `method is in HttpMethodsToRetry && (transport fault || status is in StatusCodesToRetry)` — the method check - is a top-level `&&` sitting above *both* arms. So with the defaults a `POST`/`PATCH`/`DELETE` is **never** - resent by the SDK: not on a `503`, not on a connection reset, not on a timeout. This is the control that - keeps a non-idempotent write from executing twice, and it is on by default. Adding a verb to - `HttpMethodsToRetry` removes that protection for **every** operation that uses the verb, not just the one - you had in mind — read *Making a write safe under retries* below before you do. -- **Three things trigger a retry on an eligible verb**, and one of them is easy to miss: - `HttpRequestException` (connection reset, DNS failure, dropped socket); `TimeoutRejectedException` — the - SDK's **own per-attempt `Timeout` firing**; and a response whose status is in `StatusCodesToRetry`. Because - the per-attempt timeout is itself a retry trigger, a hung provider on a `GET` costs the *whole* budget - (4 × `Timeout` + backoff), not one `Timeout`. A `TaskCanceledException` — from your own - `CancellationToken`, or from `HttpClient.Timeout` — is **not** in the set and ends the call where it fires. -- **You never catch `TimeoutRejectedException` or the raw `HttpRequestException`.** Polly classifies the - raw exceptions *inside* the pipeline, so retry behaviour is exactly as described above; what leaves the - pipeline is wrapped once, by cause. An exhausted per-attempt `Timeout` reaches your `catch` as - `SdkTimeoutException` — message `"GET https://host/path received no response within 100 s."`, - `Timeout` the window that elapsed, the Polly rejection as `InnerException`. A connection reset, DNS - failure or dropped socket reaches you as `SdkConnectionException` — `"{call} could not be sent: …"` with - the `HttpRequestException` as `InnerException`. Both derive from `SdkException`, so the call's `Method` - and `RequestUri` are on the exception. Your **own** cancellation is the one thing that is never wrapped: - it surfaces as the usual `OperationCanceledException` / `TaskCanceledException`, so the *type* now tells - the SDK's timeout and your cancellation apart — no inner-exception sniffing needed. +- **`HttpMethodsToRetry` gates every transient trigger** — status, transport fault and timeout alike. With + the defaults a `POST`/`PATCH`/`DELETE` is **never** resent on any of them: not on a `503`, not on a + connection reset, not on a timeout — which keeps a non-idempotent write from executing twice. The one + exception is the OAuth2 `401` re-send in the next note, which this list does not gate. Adding a verb removes + that protection for **every** operation using it — read *Making a write safe under retries* below first. +- **An OAuth2 `401` is re-sent once, on any verb.** A call authenticated by an OAuth2 scheme (alone or in an + AND/OR group) that gets a `401` drops the cached token, fetches a new one and is re-sent once — whatever + `HttpMethodsToRetry`, `MaxRetries` or `RetryOptions.Disabled()` say. A request whose body cannot be + replayed (a binary body, a multipart form with a binary part) is not re-sent: its `401` reaches you, and + the next call fetches a fresh token. A static credential's `401` is never re-sent. +- **On an eligible verb three things trigger a retry:** an `HttpRequestException` (connection reset, DNS + failure, dropped socket), the SDK's **own per-attempt `Timeout` firing**, and a status in + `StatusCodesToRetry`. A `TaskCanceledException` — from your own `CancellationToken`, or from + `HttpClient.Timeout` — is **not** retried and ends the call where it fires. +- **What reaches your `catch`:** an exhausted per-attempt `Timeout` as `SdkTimeoutException` (`Timeout` is + the window that elapsed), a connection reset, DNS failure or dropped socket as `SdkConnectionException`; + the raw exception is the `InnerException`, never what you catch. Your own cancellation surfaces unwrapped, + as `OperationCanceledException` / `TaskCanceledException`. See **dotnet-error-handling** for the family + and its messages. - **`Retry-After` overrides the computed backoff.** If the failing response carries a `Retry-After` header (delta-seconds or an HTTP date) that value is used as the delay instead of `Delay × BackOffFactor^n + jitter`. Both paths are then clamped to a hard **60s** ceiling that is not configurable — a provider asking for a 10-minute pause gets 60s, and a large `BackOffFactor` cannot push a single delay past a minute. -- **Multipart is not blanket-excluded.** Retry eligibility is decided per request type *before* the - pipeline runs: a binary-body request with its payload **present** never retries (with the optional - payload absent it is an empty send and stays eligible); a multipart/form-data request retries - **unless it carries a binary part**; JSON, form-url-encoded and empty-body requests are eligible. - An ineligible request is **not** left unprotected — it runs on a *timeout-only* pipeline built - from the same `RetryOptions`, so it keeps the per-attempt `Timeout` and loses only the retry - strategy. -- `Timeout` is **per attempt**, not total — to cap a whole call, use a `CancellationToken` (below). It is - nullable: set `Timeout = null` to disable the per-attempt timeout entirely. +- **Some requests never retry:** one whose binary body is present, or a multipart form with a binary part. + They still get the per-attempt `Timeout`. JSON, form-url-encoded, other multipart and empty-body requests + follow the verb rule. +- `Timeout` is nullable: `null` disables the per-attempt timeout. To cap a whole call, use a + `CancellationToken` (*Bounding a call* below). - `OnRetry`'s `RetryAttempt` also carries `Reason` — `RetryReason.Status(HttpStatusCode)` or - `RetryReason.Failure(Exception)` — log it to record *why* each retry fired. - -⚠▶▶ **A per-attempt timeout does not bound a REQUEST.** If one handler makes more than one SDK call — -a loop over recipients or invoices, a fan-out, a send-then-schedule pair — the per-call timeouts **add up**, and -they add up *faster* when each failure is caught so the work can continue: every swallowed timeout -costs its full bound and the next call still runs. Two calls at 30s is a 60s request; three is 90s. -Put one deadline on the whole handler and pass its token to every call inside it: - -```csharp -using var cts = CancellationTokenSource.CreateLinkedTokenSource(ct); -cts.CancelAfter(TimeSpan.FromSeconds(20)); // the REQUEST's budget, not one call's -var deadline = cts.Token; -// pass `deadline` — not `ct` — to every SDK call in this handler -``` - -**The check, and it is arithmetic, not judgement:** `calls in this handler × per-call timeout` must -sit under the budget you are willing to make a caller wait. If it does not, the per-call timeout is -not a bound on anything the caller can perceive. Count the calls in the loop, not the calls in the -snippet — a handler that processes every record on file makes as many calls as there are -records. + `RetryReason.Failure(Exception)` — log it to record *why* each retry fired. The per-attempt `Timeout` + firing arrives as `RetryReason.Failure(TimeoutRejectedException)` and a dropped connection as + `RetryReason.Failure(HttpRequestException)`, so switch on the exception type to tell them apart. ### Making a write safe under retries -**Start from what the defaults already give you.** `HttpMethodsToRetry` gates every trigger (see Notes), so -out of the box the SDK never resends a `POST`, `PATCH` or `DELETE` — on any trigger. Two gaps remain: +**Start from what the defaults already give you:** the SDK never resends a `POST`, `PATCH` or `DELETE` on a +transient failure (see Notes). Three gaps remain: -- **`PUT` *is* in the default list.** HTTP calls `PUT` idempotent; your provider's `PUT` may still carry a - per-call side effect — an audit row, an outbound webhook, a metered charge — that a resend duplicates. -- **"The SDK did not resend it" is not "the write did not happen."** A transport failure on a `POST` leaves - the outcome *unknown*: the bytes may have reached the provider before the socket died. That is a - reconciliation problem, and no retry setting solves it. +- **An OAuth2 `401` is re-sent on every verb.** That write reaches the provider twice. A `401` usually means + the provider did nothing, but a guard or a test that counts sends sees two. +- **`PUT` *is* in the default list.** Your provider's `PUT` may still carry a per-call side effect — an audit + row, an outbound webhook, a metered charge — that a resend duplicates. +- **"The SDK did not resend it" is not "the write did not happen."** A transport failure on a write leaves + the outcome *unknown*: the bytes may have reached the provider before the socket died. No retry setting + solves that — see *A write whose outcome is unknown*. -**Retries can be turned off.** `RetryOptions.Disabled()` is `Default() with { MaxRetries = 0 }`, and the -factory skips the retry strategy outright when `MaxRetries <= 0` rather than handing `0` to Polly — so there -is no `MaxRetryAttempts >= 1` validation error and no `MaxRetries = 1` floor. `Disabled()` keeps the -per-attempt `Timeout`; only the retries go. The pipeline is built once in the client constructor, so this is a +**Retries can be turned off per client.** `RetryOptions.Disabled()` is `Default() with { MaxRetries = 0 }`; +it keeps the per-attempt `Timeout`. The pipeline is built in the client constructor, so this is a per-**client** choice, not a per-call one. **Decide which requirement you are meeting before you pick a remedy — they are not interchangeable:** @@ -189,66 +150,37 @@ per-**client** choice, not a per-call one. anything counts sends — a side effect the provider records per call, an audit trail, a test asserting exactly one upstream write — these do not satisfy it, and nothing about the code will look wrong. - *"At most one write may reach the provider"* → option 4. It is the only one that holds the count at one - **regardless of configuration**. Two others hold it at one *today*, each with its own way of quietly - stopping: the default `HttpMethodsToRetry` holds until someone widens the list, and option 3 holds until - someone re-enables retries on that client. Neither failure announces itself. + **regardless of configuration**. Two others hold it at one *today* for transient failures, each with its + own way of quietly stopping: the default `HttpMethodsToRetry` holds until someone widens the list, and + option 3 holds until someone re-enables retries on that client. Neither failure announces itself, and + neither stops the OAuth2 `401` re-send. The four, **weakest guarantee first** — so do not read the numbering as a recommendation order: 1. **Make the write idempotent at the provider** — a client-supplied unique reference or idempotency key, where the API offers one. Makes a resend *harmless* rather than rarer; the send count stays above one. - Look at **every member of the operation's `{Operation}Request` record**, not just its body model. The - generator can put a provider's idempotency key in any of three places, and only one of them is the body: - - - a **header member** — a `string?` property on the record, which the method sends as - `new HeaderParam("...", request.X)`; - - a **form field** — a member the method routes into `FormUrlEncodedRequest.Create(new Param(...))`. - Do not search for a nullable type here: the same key can be declared **`required`** on one - operation and `string?` on the next. Match on the member reaching a - `new Param("...", request.X)` in the form body, not on its nullability; - - a field on the **body model** — the type of the record's `Body` member. - - A body-model-only search finds nothing on the first two and concludes wrongly that the API offers no key. - Ask the contract sheet for the operation's full request record, not just its body shape. - - Note that **whether the provider actually rejects a duplicate value is not visible in the record or the - model**. Such a field is typically just a nullable string, equally consistent with a uniqueness-enforced - key and with a free-text label. Verify against live traffic before relying on it; if it is not enforced, - this gives you nothing. - - ⚠ **An `Idempotency-Key` header on the wire is usually not the provider's key.** The generator puts - one on **every** non-GET operation and on no GET. Its value is almost always `Guid.NewGuid()`, injected - by the generator: not a spec parameter, no doc comment, nothing the caller can reach. The exception is - an operation whose own spec declares `Idempotency-Key` as a parameter, where the generator defers to - the caller's value. - - So the header's *presence* tells you nothing — only the **source of its value** does, and that is visible - in the method body, not the signature: `new HeaderParam("Idempotency-Key", request.X)` sends the - caller's key, `new HeaderParam("Idempotency-Key", Guid.NewGuid())` is injected. Three consequences, all - of which cut against the reading you would naturally take: - - - **An injected key makes nothing safe unless your provider consumes that exact header name.** Most APIs - do not document `Idempotency-Key` as their mechanism, and on those it is inert. - - **The value is fresh per call.** `Guid.NewGuid()` is evaluated at the call site, before the resilience - pipeline runs — so it is stable across the SDK's *internal* retry attempts, and different on every - *caller-level* retry. The resend that a job re-running after a timeout produces is exactly the one it - cannot deduplicate. - - **It can sit alongside the real key, under a near-identical name.** One request can carry both the - injected `Idempotency-Key` *header* and a spec-declared `IdempotencyKey` *form field*; only the second - one means anything. Matching on the name alone picks the wrong one. - - The trap is not that an injected key is useless; it is that it is *visible*. Seeing `Idempotency-Key` go - out on the wire, or in a log, reads as evidence that idempotency is handled. Treat it as absent until you - have confirmed both that the provider consumes that header name and that a record member feeds it — and note - the default `HttpMethodsToRetry` includes `PUT`, so a `PUT` is resent by the SDK itself under a header - that probably means nothing to the provider. + Check **every member of the operation's `{Operation}Request` record**, not just its body model — ask the + contract sheet for the full record. The key can be a **header member** (a `string?` the method sends as + `new HeaderParam("...", request.X)`), a **form field** (a member passed to `new Param("...", request.X)` + in the form body — `required` on one operation and `string?` on the next, so match on the `Param`, not + on nullability), or a field of the **`Body` model**. Whether the provider actually rejects a duplicate + value is not visible in the SDK — such a field is typically just a nullable string; verify it against + live traffic before relying on it. + + ⚠ **Every non-GET call sends an `Idempotency-Key` header.** Unless the method fills it from the record + (`new HeaderParam("Idempotency-Key", request.X)`), its value is `Guid.NewGuid()`: stable across the SDK's + own retries, new on every call you make — so it cannot deduplicate a caller-level retry — and inert + unless the provider documents that header. It can sit beside a real `IdempotencyKey` form field under a + near-identical name; only the record member counts. Seeing the header on the wire or in a log is not + evidence that idempotency is handled: treat it as absent until the provider documents that header name + and a record member feeds it. 2. **Reconcile after a failure** — on a transport failure on a write, re-read provider state to establish what actually happened instead of assuming nothing did. (Same reflex as an unreadable write response — see `dotnet-error-handling`.) Detects a duplicate; does not prevent one. How: see *A write whose outcome is unknown* below. -3. **A separate client for writes**, built with `Retry = RetryOptions.Disabled()`. Removes SDK-side resends - entirely while keeping the per-attempt `Timeout`. Worth doing when you have widened `HttpMethodsToRetry` +3. **A separate client for writes**, built with `Retry = RetryOptions.Disabled()`. Removes the transient + resends while keeping the per-attempt `Timeout`; the OAuth2 `401` re-send stays (Notes). Worth doing when you have widened `HttpMethodsToRetry` for the read path and need the write path held at one send regardless. 4. **A `DelegatingHandler` that refuses a re-send it did not authorise** — the only option that holds the count at one no matter how the client is configured, because a blocked attempt never reaches the @@ -256,24 +188,19 @@ The four, **weakest guarantee first** — so do not read the numbering as a reco duplicate would be externally visible or costly to undo, and combine it with option 2 to settle the outcome of the one send you allowed. - Two details decide whether it works, and both are easy to get wrong: + Two details decide whether it works: - - **Do not keep the "already sent" marker on the `HttpRequestMessage`.** A fresh request object is built - for each attempt, so a marker set via `HttpRequestOptionsKey` is gone by the retry and the guard never - fires — measured: 4 sends, i.e. no protection at all. Keep the count in state that outlives the - request, such as an `AsyncLocal` scope the caller opens around the write; retries run inside the - caller's async context, so the scope flows into the handler on every attempt (measured: 1 send). - - **Do not throw an `HttpRequestException` to refuse**, and do not let the refusal path time out — both - are retry triggers, so the refusal itself becomes retryable. Throw a private sentinel type that derives - from `Exception`; it propagates out unwrapped, and your integration boundary translates it. + - **Keep the "already sent" count in state that outlives the request** — e.g. an `AsyncLocal` scope the + caller opens around the write; retries run inside the caller's async context, so the scope reaches the + handler on every attempt. Each attempt builds a fresh `HttpRequestMessage`, so a marker set via + `HttpRequestOptionsKey` is gone by the retry and the guard never fires. + - **Refuse by throwing a private type derived from `Exception`**, not `HttpRequestException`, and don't + let the refusal time out — both are retry triggers. The private type propagates unwrapped; your + integration boundary translates it. Count the send *before* it goes out. A request that failed on the way out may still have been received, - so "this may already have taken effect" is the only safe reading — surface it as an **unknown outcome** - to be settled by re-reading provider state (option 2), not as a definite failure. - -`HttpMethodsToRetry` **is** the primary control here — it gates every trigger, and keeping non-idempotent -verbs out of it is most of the job. The options above cover what it cannot: a `PUT` with side effects, a list -you have widened, and the unknown outcome a transport failure leaves behind. + so surface it as an **unknown outcome** settled by re-reading provider state (option 2), not as a + definite failure. **All four bound the call YOU make to the provider. None of them is a reason to change the contract your own callers see.** Taking an idempotency key from your callers can be a deliberate API design; @@ -345,23 +272,16 @@ There are three places a bound can live, and **two of the three are per-attempt* Both per-attempt timeouts stop when the response headers arrive; reading the body after that is bounded only by your `CancellationToken` (on an event stream, also by `StreamReadTimeout`, below). -**`HttpClient.Timeout` is applied per attempt here, which is not obvious.** It is enforced by a CTS created -inside each `SendAsync`, and the retry pipeline sits *above* `SendAsync` — so every retry gets a fresh full -`Timeout`. - -**Two per-attempt timeouts, and on a retryable verb only one of them ends the call.** -`options.Retry.Timeout` expiring raises `TimeoutRejectedException` *inside* the pipeline, which *is* in the retry set — on an eligible verb the -attempt is retried and the cost multiplies (that is the ≈407s row above); only once the retries run out does -the SDK convert it to the `SdkTimeoutException` you catch. `HttpClient.Timeout` expiring raises -`TaskCanceledException` inside the pipeline, which is *not* in the set — so it ends the call the first time -it fires, on any verb — and the SDK converts that too, into the **same** `SdkTimeoutException` (with -`Timeout = HttpClient.Timeout`), so a caller cannot tell from the type which knob fired; `Timeout` says -which. (On a non-retryable verb the distinction collapses: neither is retried and both end the call on -the first fire.) That asymmetry makes `HttpClient.Timeout` the cheapest bound on the wait for the response -headers: a `10s` value bounds that wait at ≈10s whatever the verb. What it does not bound is a provider that fails *retryably* just under the limit on every attempt — that still costs -≈ `4 × 10s + 7s ≈ 47s`. It is also the only bound left standing if you set `options.Retry.Timeout = null`. A -good backstop and the cheapest fix for a hang before the headers; still not a call budget. (An *infinite* `HttpClient.Timeout` -never fires, and a `TaskCanceledException` under one is not the SDK's to explain — it passes through raw.) +**`HttpClient.Timeout` also applies per attempt** — every retry gets a fresh full window. + +**On a retryable verb only one of the two per-attempt timeouts ends the call.** `options.Retry.Timeout` +firing is retried (the ≈407s case); `HttpClient.Timeout` firing is not — it ends the call the first time, on +any verb — so a `10s` value bounds the wait for the response headers at ≈10s, though a provider failing +*retryably* just under it on every attempt still costs ≈ `4 × 10s + 7s ≈ 47s`. Both surface as +`SdkTimeoutException`, whose `Timeout` says which fired. With `options.Retry.Timeout = null` it is the only +per-attempt bound left. An *infinite* `HttpClient.Timeout` never fires, and a `TaskCanceledException` under one +passes through unwrapped. A good backstop and the cheapest fix for a hang before the headers; still not a call +budget. Set all three — they catch different failures. The per-attempt bounds cap one attempt's wait for the headers; the token caps the sum, which is the only thing your caller experiences: @@ -393,11 +313,11 @@ async Task Bounded(Func> call, CancellationToke Then every operation goes through `Bounded(...)`, and the budget is one value in one place. -**The invariant to check:** your worst case — `attempts × per-attempt timeout + total backoff` — must sit -below the deadline your own caller is working to. If it does not, the caller times out first and your retries -are burning provider capacity for a response nobody is still waiting for. A `TaskCanceledException` from your -own token is **not** retried and **not** wrapped (see Notes above), so the token cuts the call cleanly and -surfaces as itself. +**The check:** `calls in the handler × (attempts × per-attempt timeout + backoff)` must sit below the +deadline your own caller is working to — count loop iterations, not lines of code. A handler that makes +several SDK calls (a loop over recipients or invoices, a fan-out, a send-then-schedule pair) adds up their +bounds, and faster when each failure is caught so the work continues; pass one `Bounded` deadline token to +every call in it. Cancelling that token is not retried, so it cuts the call cleanly. ## The clock — `TimeProvider` @@ -405,29 +325,22 @@ Every place the SDK reads time goes through **one** option, `options.TimeProvide `System.TimeProvider`, default `TimeProvider.System`): the retry backoff and the `Retry-After` arithmetic, the per-attempt `Timeout`, the SSE idle window (`StreamReadTimeout`, below), OAuth2 token expiry, webhook replay tolerance (its own `WebhookOptions.TimeProvider`) and the elapsed-milliseconds figure in the response -log line. There is no second clock inside the engine — a component that needs time is handed this one, and -never falls back to `TimeProvider.System` on its own. +log line. ```csharp options.TimeProvider = TimeProvider.System; // the default; set it only to substitute a clock ``` -Under `services.Add{Api}Client(...)` the option is **seeded from the container before your `configure` -callback runs**: a `TimeProvider` you registered — in any order relative to the SDK registration — is picked -up, and a value you assign in `configure` wins over it. The SDK **never registers** a `TimeProvider` in your -container, so it neither collides with yours nor leaves one behind. The precedence is: explicit option > -container registration > `TimeProvider.System`. The same seeding applies to -`Add{Api}WebhookSignatureVerifier` for webhooks. +Under `services.Add{Api}Client(...)`, a `TimeProvider` registered in your container — in any order relative +to the SDK registration — is used unless your `configure` callback sets one: explicit option > container +registration > `TimeProvider.System`. The SDK **never registers** a `TimeProvider` itself. The same applies to +`Add{Api}WebhookSignatureVerifier`. -The practical consequence is for tests: one fake clock on `options.TimeProvider` drives retries, idle -timeouts and token expiry together, with no real sleeps. Use a provider that **implements timers** — -`FakeTimeProvider` from `Microsoft.Extensions.TimeProvider.Testing` — because the backoff and the idle -window are timers on the provider; a `GetUtcNow`-only fake throws when the SDK asks for one. See -**dotnet-testing** § *Fake the clock*. +To fake it in tests, see **dotnet-testing** § *Fake the clock*. ## Pagination -Operations the API marks as paginated return **`Pageable<{PageResponse}, {Item}>`**, and the shape catches +Paginated operations return **`Pageable<{PageResponse}, {Item}>`**, and the shape catches people out: `Pageable` implements `IAsyncEnumerable<`**`TItem`**`>`, so a plain `await foreach` walks **individual items**, not pages. The SDK fetches each page and advances the paging state for you — one of five strategies (offset, cursor, keyset, `Link`-header, or page-number), chosen per operation. @@ -476,18 +389,6 @@ me when to stop" as the *only* stop condition and you have written an unbounded returning a next-page link, a cursor that fails to advance, or a filter the provider quietly ignores will each spin until something else kills the request. -What that failure looks like in production — the request does not return slowly, it **does not return at -all**: - -``` -status=0 upstream=55909 -CLIENT_ERROR:TaskCanceledException:The request was canceled due to the configured -HttpClient.Timeout of 75 seconds elapsing. -``` - -Tens of thousands of provider calls billed, the caller left holding a dead request, and no error the -provider can be blamed for. The bug is entirely on the consuming side. - **Every page loop needs at least one bound that does not depend on the provider's cooperation.** Pick the one that matches the use case; a page cap is the cheapest and is never wrong: @@ -516,7 +417,7 @@ If there is no such convention and the return type genuinely cannot change, thro silently. ⚠⚠ **A `LogWarning` at the cap followed by `return results;` is the defect.** Log it as well, never instead. -**No-throw variant.** Where generated, a sibling `{Operation}Result` returns +**No-throw variant.** Where it exists, a sibling `{Operation}Result` returns `Pageable, {Item}>` — the same streaming, but its **`.AsPages(ct)`** hands you an `ApiResult` per page that you inspect instead of it throwing: @@ -536,15 +437,13 @@ await foreach (var result in client.{ApiGroup}.{Operation}Result(request, cancel > Not every list endpoint is paginated. An operation with no pagination metadata is a plain list call > (returns a list or a wrapper — see **dotnet-calling-endpoints**); to page one of those, drive its own -> `page`/`perPage` query params yourself and stop when a page returns fewer than `perPage` items. -> **A hand-driven loop needs the same bound as an auto-paginated one** — "fewer than `perPage`" and -> "no next-page link" are both provider-supplied stop conditions, and neither is a bound. Carry a page -> cap alongside it (see *Never leave a page loop unbounded* above). +> `page`/`perPage` query params yourself, stop when a page returns fewer than `perPage` items, and carry +> the same page cap (see *Never leave a page loop unbounded* above). ## Streaming (Server-Sent Events) -Operations the API marks as streaming (`text/event-stream`) are generated to **return -`Task>`** — `await` the call once to open the stream, then `await foreach` the +A streaming (`text/event-stream`) operation **returns `Task>`** — `await` the +call once to open the stream, then `await foreach` the frames as the server emits them. `{Item}` is `string` for a plain-text stream, or a typed model for a JSON event stream. @@ -573,28 +472,16 @@ catch (SdkConnectionException ex) // the connection dropped mid-st } ``` -**Idle timeout.** A stalled stream is bounded by the **`StreamReadTimeout` client option** — the maximum -wait **between frames**, a `TimeSpan?` on `{Api}ClientOptions` defaulting to **60 s**; set it to `null` to -wait indefinitely. It bounds only the wait for the server between frames, never your own processing time -inside the loop. When it elapses the SDK tears the stream down and the enumeration throws -`SdkTimeoutException` with `Timeout` set to the window that elapsed — the same leaf that reports a -per-attempt timeout on an ordinary call, so one `catch (SdkTimeoutException)` covers both. The window is -measured on `options.TimeProvider` (see *The clock* above), so a fake clock drives it in tests. - -**Errors** (all under `{RootNamespace}.Core.Exceptions`, all `SdkException`s that name the call): -- **Before the stream opens** — the opening `await` throws `ApiException`, with `TError` the same - two-case shape as any operation: a typed `{Operation}Error` (Case A) or `RawError` (Case B), per what the - operation declares (see **dotnet-error-handling**). -- **While enumerating** — there is no SSE-specific exception type; the family's ordinary leaves apply: - - `SdkTimeoutException` — no frame arrived within `StreamReadTimeout`; carries `Timeout`. - - `ResponseDeserializationException` — a frame couldn't be parsed as `{Item}`; carries `TargetType` and - the underlying `JsonException` (or `FormatException` for a parsed scalar) as `InnerException`. The raw - frame text is **not** on the exception or in its message. A plain-`string` stream cannot raise it. - - `SdkConnectionException` — the connection dropped mid-stream (`"{call} could not read the response - body: …"`, the `IOException` / `HttpRequestException` as `InnerException`). -- Retries do **not** apply once the stream is open; cancel via the `CancellationToken` - (`stream.WithCancellation(ct)`) to stop early — your cancellation surfaces as `OperationCanceledException`, - never wrapped. +**Idle timeout.** `StreamReadTimeout` on `{Api}ClientOptions` (a `TimeSpan?`, default **60 s**, `null` to +wait indefinitely) bounds the wait **between frames**, never your own processing inside the loop. When it +elapses the SDK tears the stream down and the enumeration throws `SdkTimeoutException` with `Timeout` set to +the window — the same leaf as a per-attempt timeout, so one `catch (SdkTimeoutException)` covers both. + +**Errors:** the opening `await` throws `ApiException` — Case A or B, as for any operation (see +**dotnet-error-handling**). While enumerating there is no SSE-specific type; the three leaves in the sample +apply. The raw frame text is **not** on `ResponseDeserializationException` or in its message, and a +plain-`string` stream cannot raise it. Retries do **not** apply once the stream is open; cancel with +`stream.WithCancellation(ct)` to stop early. ## Logging @@ -606,7 +493,7 @@ and one of the three cases is almost certainly your production path: | how the client is built | `LoggerFactory` null means | | --- | --- | | `services.Add{Api}Client(...)` | the extension fills it from the container's `ILoggerFactory` — **logging is already on**, at your host's minimum level, and the request line goes to your normal log sinks | -| `new {Api}Client(httpClient, options)` by hand | `NullLoggerFactory` — nothing is written, *unless* `{APICLIENTTYPENAME}_LOG` is set (see below) | +| `new {Api}Client(httpClient, options)` by hand | `NullLoggerFactory` — nothing is written, *unless* `{API}_LOG` is set (see below) | | you assign it yourself | your factory is used and the environment variable is ignored outright | The first row is the one that surprises people: in any ASP.NET Core or generic-host app the SDK is logging @@ -628,9 +515,8 @@ options.Logging = new LoggingOptions }; ``` -What it emits, and at which level — every row is additionally gated by `_logger.IsEnabled(level)`, so a -factory whose minimum level is `Warning` emits no request line at all; the SDK's switches are a *second* -gate, not the only one: +What it emits, and at which level — each row is also filtered by your `ILoggerFactory`'s minimum level, so a +`Warning` minimum emits no request line at all: | Event | Level | On by default | | --- | --- | --- | @@ -659,27 +545,22 @@ not. On any endpoint that carries card data, bank details, personal data or a cr switching this on writes that data to your logs. Leave it off in production; turn it on for one endpoint at a time behind a flag you can prove is off. -⚠▶▶ **An environment variable turns all of this on without a code change.** When -`options.Logging.LoggerFactory` is *still* `null` at construction — which in practice means a client you -constructed yourself, since `Add{Api}Client` always fills it (it calls `AddHttpClient()`, which registers an -`ILoggerFactory`) — the SDK reads -`{APICLIENTTYPENAME}_LOG`, the client type name upper-cased plus `_LOG`. It accepts `info`, `debug` or -`trace`, and writes to **stderr** through a built-in console logger. `debug` additionally forces request *and* response headers on; **`trace` additionally forces -`LogRequestBody` on**, i.e. unredacted JSON bodies to stderr on a host you may not control. Assigning -`LoggerFactory` yourself disables the variable outright — which is the reason to set it explicitly in -production even when you point it at `NullLoggerFactory.Instance`. - -**Per-call override.** Every generated operation takes a `RequestOptions? requestOptions = null` argument -with two properties: `LogLevel?` — the logging override this section covers — and `Hooks`, the per-call -hook list (see *Hooks* below). Passing `new RequestOptions { LogLevel = LogLevel.Debug }` **sets** the -verbosity for that one call without touching the client's configuration — useful for tracing one failing -endpoint. Two things about it are easy to get wrong: - -- It **replaces** the per-switch defaults in *both* directions, rather than only raising them. `Trace` turns - the body and headers on even when `LogRequestBody` is `false`; a value *above* `Information` — `Warning`, - say — switches the request line and the success response line **off** for that call. -- It cannot lift a level your `ILoggerFactory` has filtered out. `_logger.IsEnabled(level)` is still ANDed in - front, so a per-call `Trace` against a factory whose minimum is `Information` logs nothing extra. +⚠ **An environment variable turns all of this on without a code change.** When +`options.Logging.LoggerFactory` is *still* `null` at construction — in practice a client you constructed +yourself, since `Add{Api}Client` always fills it — the SDK reads `{API}_LOG`, the SDK name in upper snake +case plus `_LOG`. It accepts `info`, `debug` or `trace`, and writes to **stderr** through a +built-in console logger. `debug` also forces request *and* response headers on; **`trace` also forces +`LogRequestBody` on** — unredacted JSON bodies to stderr on a host you may not control. Assigning +`LoggerFactory` yourself — even `NullLoggerFactory.Instance` — disables the variable, so set it explicitly in +production. + +**Per-call override.** `new RequestOptions { LogLevel = LogLevel.Debug }`, passed as the `requestOptions` +argument every operation takes (see **dotnet-calling-endpoints**), **sets** the verbosity for that one call +without touching the client's configuration. It replaces the per-switch defaults in *both* directions: `Trace` +turns the body and headers on even when `LogRequestBody` is `false`, and a level above `Information` — +`Warning`, say — turns the request line and the success response line **off** for that call. It cannot get +past your `ILoggerFactory`'s minimum level: a per-call `Trace` against an `Information` minimum logs nothing +extra. ### Hooks — the SDK's own request/response seam @@ -705,11 +586,10 @@ The facts that decide how you use them: rate-limit budgets, a request-id echo) — the operation's return value carries only the body. A per-call hook can close over a local, which puts the observed value in scope in the same method's `catch`; a client-wide hook needs `AsyncLocal` or a scoped service to reach it. -- **A hook is an observation seam, not a veto point.** An exception thrown from a hook is not retried - (the transport arm retries only `HttpRequestException` and the timeout rejection) — it just fails the - call, and a throwing `OnResponse` fails a call that succeeded on the wire. To refuse a re-send, use - the write-guard `DelegatingHandler` under *Make the write idempotent* — a blocked attempt must never - reach the network, which no observation hook can guarantee. +- **A hook is an observation seam, not a veto point.** An exception thrown from a hook is not retried — it + fails the call, and a throwing `OnResponse` fails a call that succeeded on the wire. To refuse a re-send, + use the write-guard `DelegatingHandler` (option 4 under *Making a write safe under retries*): a blocked + attempt never reaches the network, which no hook can guarantee. ### When you still want a `DelegatingHandler` @@ -738,51 +618,30 @@ var httpClient = new HttpClient(new LoggingHandler { InnerHandler = new HttpClie var client = new {Api}Client(httpClient, options); ``` -With DI, the SDK's `Add{Api}Client` resolves the **default (unnamed)** `IHttpClientFactory` client, so attach -the handler to that one — register it and configure the default client *before* (or alongside) the SDK -registration: - -```csharp -services.AddTransient(); -services.AddHttpClient(Options.DefaultName).AddHttpMessageHandler(); -services.Add{Api}Client(options => { /* ... */ }); // resolves CreateClient() → the default client -``` - -The handler then runs on every SDK call — but so does everything else you configure on the default client, -for **every other unnamed `CreateClient()` consumer in the app**. If that blast radius is unwelcome, skip the -extension and register the client over a **named** `HttpClient` instead -(`services.AddHttpClient("my-api").AddHttpMessageHandler()`, then construct -`new {Api}Client(factory.CreateClient("my-api"), options)`), which keeps the handler, timeout and primary -handler scoped to this SDK. See **dotnet-client-initialization**. - -The `OnRetry` callback above is also a convenient place to observe retry activity. +Under `Add{Api}Client`, attach it to the **default (unnamed)** `HttpClient` the extension resolves +(`services.AddHttpClient(Options.DefaultName).AddHttpMessageHandler()`, with the handler +registered as transient) — which also affects every other unnamed consumer in the app — or register the +client over a **named** `HttpClient`; see **dotnet-client-initialization**. ### Verify on the wire (first run of any new integration) **Run the built-in logger on the first execution of any new call and inspect the output** — the default `Information` request line is enough, so this costs one `LoggerFactory` assignment. Path/template params are -not type-checked against the route (internally the value is -`object?`; it is normalised *through* JSON — which is why an enum contributes its wire value and not its C# -member name — then substituted as the resulting scalar's plain text, URL-escaped, by a plain string -replace), and on a **successful** response the -SDK returns only the deserialized body — it never surfaces the request URL or status (see -**dotnet-error-handling**). So a wrong verb, a leftover `{placeholder}`, or a mis-serialized path segment -**compiles cleanly** and produces no in-band signal; the only symptom is a runtime `404`/`422`. +not type-checked against the route (an enum contributes its wire value, not its C# member name), and a +**successful** call returns only the deserialized body — never the request URL or status. So a wrong verb, a +leftover `{placeholder}`, or a mis-serialized path segment **compiles cleanly** and shows only as a runtime +`404`/`422`. Checklist for the first printed request: 1. the **verb** matches the operation (a `404` on a path you believe exists often means the wrong method); -2. the **path** is fully formed. The failure to watch for is silent and unobvious: a path parameter whose - value is null or empty collapses to **nothing**, leaving a doubled slash (`/orders//authorize`) — not a - leftover marker. (An unbound `{placeholder}` would survive, but the generator supplies every declared - path param, so that is only reachable through a hand-set `BaseUrl`; and it prints percent-encoded, - `%7Bid%7D`, not as `{id}`.) +2. the **path** is fully formed — a null or empty path parameter collapses to **nothing**, leaving a + doubled slash (`/orders//authorize`), not a leftover marker. Only a `{placeholder}` in a hand-set + `BaseUrl` survives, and it prints percent-encoded (`%7Bid%7D`); 3. each **path-param segment** is the value the API expects — for an enum that is the **wire value** - (frequently ALL-CAPS), not the C# member name; the generated constants carry it. Nothing normalises - casing and there is no public factory, so the only way an unexpected string reaches the URL is a value - the server itself sent and your code echoed back — check `IsKnownValue()` before reusing one as input; -4. the query params you set actually appear in the query string — remembering that a value is masked - unless its key is on the known-safe list (`cursor`, `dates`, `datetime`, `limit`, `offset`, `page`, - `since`, `size`, `strings`), so for anything else you are checking that the key is present, not what it - carries. + (frequently ALL-CAPS), not the C# member name; check `IsKnownValue()` before echoing a server-sent value + back (see **dotnet-models**); +4. the query params you set actually appear in the query string — a value is masked unless its key is on + the known-safe list (see *Logging*), so for any other key you are checking that it is present, not what + it carries. Drop the level back once verified. diff --git a/plugins/spotify/skills/dotnet/dotnet-error-handling/SKILL.md b/plugins/spotify/skills/dotnet/dotnet-error-handling/SKILL.md index b4fd301b..81e5f32c 100644 --- a/plugins/spotify/skills/dotnet/dotnet-error-handling/SKILL.md +++ b/plugins/spotify/skills/dotnet/dotnet-error-handling/SKILL.md @@ -1,6 +1,6 @@ --- name: dotnet-error-handling -description: Error and exception handling for an APIMatic-generated .NET SDK in C# — load before writing any try/catch around an SDK call, an exception-translation layer, or error middleware. Covers which exception types actually reach your catch blocks, how to read status codes and error bodies safely, and the traps that make an otherwise reasonable catch ladder silently wrong. +description: Load before writing any try/catch around a call on an APIMatic .NET SDK in C#, an exception-translation layer or error middleware — which exception types reach your catch, the SdkException family, typed error bodies versus RawError, reading status codes and error bodies, and the non-throwing ApiResult variant. --- # Error handling for an APIMatic .NET SDK @@ -8,26 +8,21 @@ description: Error and exception handling for an APIMatic-generated .NET SDK in > Throughout this skill, `{...}` is a placeholder for a name you take from your SDK (e.g. `{Operation}`, > `{ApiGroup}`, `{RootNamespace}`) — replace it with the concrete identifier from the source. > -> **One skill, every error shape.** This file covers every shape the 4.0.0 generator can emit. -> Which shapes YOUR SDK uses — which case each operation is, whether typed bodies carry a status, -> which `TryGet…` accessors exist — are facts of the API definition, not of this skill: take them -> from the operation's map row or the contract sheet, and **apply only the guidance that -> matches**. An API can be all Case B, nearly all Case A, or a mix. +> **One skill, every error shape.** This file covers every error shape the SDK can have. Which ones +> YOUR SDK uses — which case each operation is, whether typed bodies carry a status, which `TryGet…` +> accessors exist — is on the operation's map row or the contract sheet: **apply only the guidance +> that matches**. An API can be all Case B, nearly all Case A, or a mix. Endpoint methods **throw on non-success responses** by default (for a non-throwing alternative, see the **`ApiResult`** section below). The thrown type is always the generic `ApiException` — but `TError` comes in **two shapes**, depending on the operation: - **Typed model (Case A)** — a per-operation `{Operation}Error` (subclass of `ApiError`) exists under - `Errors/` for the operation; `TError` is that type and you read it with typed `TryGet*` accessors. + `Errors/` for the operation; `TError` is that type. Dispatch on it with its exhaustive `Match` (one + `on{Arm}` per declared body plus a required `otherwise`), or read one body with a `TryGet*` accessor. - **`RawError` (Case B)** — when the operation has no `{Operation}Error` type, `TError` is `RawError` *directly*. `RawError` is **not** an `ApiError` and has **no** `TryGet*` / `TryGetRawError` accessors; you - read the status and body straight off `ex.Error`. How common this is, is an API fact — some APIs are almost - entirely Case B, others almost entirely Case A; each operation's map row says which it is. - -`ApiException` is declared `public sealed class ApiException : ApiException` with **no** -`where TError : ApiError` constraint — which is exactly why `TError` can be either an `ApiError` model or a -`RawError`. + read the status and body straight off `ex.Error`. ### The `SdkException` family @@ -41,7 +36,7 @@ SdkException (abstract) Method, RequestUri — the call │ └─ ResponseDeserializationException TargetType — a body (success OR error) did not match the declared type ├─ SdkConnectionException — — no usable response: could not send, or could not read the body │ └─ SdkTimeoutException (sealed) Timeout — an attempt, the transport, or an SSE stream went silent -└─ AuthSchemeException (sealed) SchemeFailures — a credential could not be applied +└─ AuthSchemeException (sealed) SchemeFailures — a required credential is not configured, a provider returned nothing, or a credential could not be applied ``` Three rules follow from the shape, and the rest of this skill applies them: @@ -49,47 +44,31 @@ Three rules follow from the shape, and the rest of this skill applies them: - **Catch specific to general.** `ApiException` means *the server answered* (you have a status); `SdkConnectionException` means *it did not*; `SdkException` is *everything the SDK raises*. A ladder that handles only `ApiException` is incomplete — see *Connection failures* below. -- **The raw cause is always `InnerException`** — the `JsonException`, the `HttpRequestException`, the Polly - timeout rejection, the token endpoint's own failure — never the thing you catch. +- **The raw cause is always `InnerException`** — the `JsonException`, the `HttpRequestException`, the + per-attempt timeout's rejection, the token endpoint's own failure — never the thing you catch. - **Your own cancellation is never wrapped.** An `OperationCanceledException` from a token *you* cancelled passes through untouched; a `catch (SdkException)` does not see it. -The messages are a contract, asserted verbatim by the SDK's own tests, and each names the call with its query -stripped: `"GET https://host/path returned 400 (BadRequest)."`, `"{call} could not be sent: …"`, +Every message names the call with its query stripped: `"GET https://host/path returned 400 (BadRequest)."`, +`"{call} could not be sent: …"`, `"{call} could not read the response body: …"`, `"{call} received no response within 100 s."`, `"{call} returned a body that could not be deserialized into {Type}."`. A log line therefore identifies the failing call without a typed catch. -These types live in **distinct** namespaces — `Core.*` is **not** a single namespace, so don't assume -`ApiError` sits with the exceptions under `Core.Exceptions`: - -- the whole `SdkException` family → `{RootNamespace}.Core.Exceptions` -- `ApiError` **and** `RawError` → `{RootNamespace}.Core.ErrorResponse` -- the per-operation `{Operation}Error` models (e.g. `CreateWidgetError`) → `{RootNamespace}.Errors` +`Core.*` is **not** one namespace — don't assume `ApiError` sits with the exceptions: -So a typed (Case A) catch needs up to **four** namespaces, not three — how many depends on whether you -spell the `out` types out or use `out var`: - -| namespace | what you need from it | +| namespace | holds | | --- | --- | -| `{RootNamespace}.Core.Exceptions` | `ApiException` — the exception itself (and the rest of the family) | -| `{RootNamespace}.Errors` | the `{Operation}Error` you name in the `catch` | -| `{RootNamespace}.Core.ErrorResponse` | `RawError`, which the inherited `TryGetRawError` hands back | -| *depends on the body* | the **typed body** a `TryGet…` yields — see below | +| `{RootNamespace}.Core.Exceptions` | the whole `SdkException` family, `ApiException` included | +| `{RootNamespace}.Core.ErrorResponse` | `ApiError` and `RawError` (which the inherited `TryGetRawError` hands back) | +| `{RootNamespace}.Errors` | the per-operation `{Operation}Error` models (e.g. `CreateWidgetError`) | -**The fourth is not a fixed namespace.** A typed body is whatever the API definition declared, so where -its type lives follows the body's schema kind — a model in `{RootNamespace}.Models`, a union in +A typed body's type lives wherever its schema kind puts it — a model in `{RootNamespace}.Models`, a union in `.Models.OneOf` / `.Models.AnyOf`, an enum in `.Models.Enums`, a binary body in `.Core.Models` -(`ErrorByteContent`), and a map or dynamic body in no SDK namespace at all -(`IReadOnlyDictionary` needs `System.Collections.Generic` and `System.Text.Json`). A -scalar body — `TryGetString`, `TryGetLong` — needs nothing. Read the accessor's `out` type and import what -*it* names; do not assume `.Models`. - -The last two rows only bite when you write the `out` type out. `out var` needs neither, which is why the -template below imports three namespaces and not four — it uses `out var` for the typed bodies and names -`RawError` explicitly. A Case B catch needs only -`Core.Exceptions` and `Core.ErrorResponse`. This namespace layout is identical across the APIMatic .NET SDKs -checked. +(`ErrorByteContent`), a map or dynamic body in the BCL (`IReadOnlyDictionary` needs +`System.Collections.Generic` and `System.Text.Json`); a scalar body (`TryGetString`, `TryGetLong`) needs +nothing. Import what an `out` type you spell out names — `out var` needs none, which is why the template +below imports three namespaces. ## Catch the exception @@ -147,17 +126,23 @@ memory: 1. **List *every* `TryGet...` accessor the operation's `{Operation}Error` declares.** The operation's map row already lists them (with the HTTP status each maps to); take them from the contract sheet. - They are the `public bool TryGet...(out ...)` methods on the `{Operation}Error` type (grounded + They are the `public bool TryGet...([NotNullWhen(true)] out ...? value)` methods, a bare `out` for a + value-type body such as `long`, on the `{Operation}Error` type (grounded from the SDK map/source). These accessors are generated per operation — one per distinct error body the operation maps — and their names embed the body type. Expect a mix of: - **typed-body accessors** named after a model or scalar — `TryGetValidationErrors`, `TryGetProblemDetails`, `TryGetString`, `TryGetLong`, …; - - **status-specific `RawError` accessors** — e.g. `TryGetNoContent(out RawError)` — the names on your operation come from its map row; - - the inherited **`TryGetRawError(out RawError)`**, which every `{Operation}Error` exposes. -2. **Write one `if` / `else if` branch per `TryGet*` method — cover them all, and put `TryGetRawError` - *last*.** Each public `TryGet*` corresponds to a status/body the operation can return; skip one and you - silently drop that response. `TryGetRawError` must be the final branch because it is **not** a catch-all - (see below) — it only fires for statuses that have no more-specific accessor. + - **status-specific `RawError` accessors** — e.g. `TryGetNoContent([NotNullWhen(true)] out RawError? value)` — the names on your operation come from its map row; + - the inherited **`TryGetRawError([NotNullWhen(true)] out RawError? error)`**, which every `{Operation}Error` exposes. +2. **Dispatch through `ex.Error.Match(...)`, passing every arm by name.** `Match` has one `on{Arm}` + parameter per `TryGet{Arm}` accessor (same stem, same value) plus a required `otherwise` that receives + the `RawError` of a status the operation does not declare — the compiler refuses a call that leaves an + arm out, so no response is silently dropped. Pass the arms by name: they are positional, in the + ordinal order of their names, and a regenerated SDK whose operation gains or loses an error body + changes the signature (a source and binary break for a positional call site). Reach for a single + `TryGet{Arm}` only when one body is all you need, and for `TryGetRawError` only as the accessor + behind `otherwise`: it is **not** a catch-all — a status with a typed or status-specific accessor + (a `422` validation payload, `TryGetNoContent`) leaves it **false**. ```csharp using {RootNamespace}.Core.Exceptions; // ApiException @@ -171,38 +156,19 @@ try } catch (ApiException<{Operation}Error> ex) { - // ex.StatusCode / ex.Headers are always here; the body is behind the accessors below. - // ONE branch per public TryGet* declared on {Operation}Error — copy the exact names from the class - // under Errors/. The TryGet{...} names below are PLACEHOLDERS; yours are named after this operation's - // responses (a typed body may be a model OR a scalar such as TryGetString/TryGetLong). - if (ex.Error.TryGet{TypedBody1}(out var body1)) // e.g. TryGetValidationErrors — a typed body - { - // inspect body1 - } - else if (ex.Error.TryGet{TypedBody2}(out var body2)) // e.g. TryGetProblemDetails — another typed body - { - // inspect body2 - } - else if (ex.Error.TryGet{Status}(out RawError statusRaw)) // e.g. TryGetNoContent(out RawError) — status-specific - { - Console.Error.WriteLine($"HTTP {(int)statusRaw.StatusCode}"); - } - // ... KEEP GOING: one else-if for EVERY remaining TryGet* the class declares — do not stop early ... - else if (ex.Error.TryGetRawError(out RawError raw)) // ALWAYS LAST: fallback for untyped statuses only - { - Console.Error.WriteLine($"HTTP {(int)raw.StatusCode}: {raw.ReadAsString()}"); - } + // ex.StatusCode / ex.Headers are always here; the body is behind the arms below. + // ONE named arm per public TryGet* declared on {Operation}Error — copy the exact names from the class + // under Errors/ (on{Body} pairs with TryGet{Body}). The on{...} names below are PLACEHOLDERS; yours are + // named after this operation's responses (a typed body may be a model OR a scalar such as onString/onLong). + ex.Error.Match( + on{TypedBody1}: body1 => { /* inspect body1 — e.g. onValidationErrors */ }, + on{TypedBody2}: body2 => { /* inspect body2 — e.g. onProblemDetails */ }, + on{Status}: statusRaw => Console.Error.WriteLine($"HTTP {(int)statusRaw.StatusCode}"), // e.g. onNoContent + // ... one named arm for EVERY remaining TryGet* the class declares — the compiler enforces it ... + otherwise: raw => Console.Error.WriteLine($"HTTP {(int)raw.StatusCode}: {raw.ReadAsString()}")); // undeclared status } ``` -**Why `TryGetRawError` goes last — it is not a universal fallback.** It returns a raw body **only** for -statuses that have no more-specific accessor on this `{Operation}Error`; a status that has a typed accessor -(e.g. a `422` validation payload) lands in that typed slot and leaves `TryGetRawError` **false**. The -status-specific `RawError` accessors (e.g. `TryGetNoContent(out RawError)`) are likewise **not** surfaced by -`TryGetRawError`. So if you check `TryGetRawError` first — or omit any of the more-specific accessors — those -typed and status-specific bodies are silently dropped. Enumerate the class and handle every accessor -explicitly. - **Don't factor error-reading into a shared helper typed as `ApiError`.** The typed `TryGet*` accessors live on the concrete `{Operation}Error`, *not* on the `ApiError` base — which exposes only `TryGetRawError`. A helper like `string Describe(ApiError e)` can therefore reach **only** `TryGetRawError`, so for any status @@ -233,24 +199,25 @@ catch (ApiException ex) } ``` -Case B needs no `.Errors` using — `RawError` lives under `{RootNamespace}.Core.ErrorResponse`. Its public -members are `StatusCode`, `ReadAsBytes`/`ReadAsString`/`ReadAsJson`; note +Case B needs no `.Errors` using. `RawError`'s public members are `StatusCode`, +`ReadAsBytes`/`ReadAsString`/`ReadAsJson`; note `ReadAsJson()` **throws `JsonException`** when the body isn't valid JSON — and a `RawError` body may not be (a gateway or proxy can answer with HTML or plain text), so prefer `ReadAsString()` unless you know it's JSON. ## Result-style alternative — `ApiResult` (no throwing) -The generator can **optionally** emit a result-style variant of an operation — so it's not guaranteed to -exist. When enabled, it appears as a **sibling method** named `{Operation}Result` (next to the throwing -`{Operation}`), returning `Task>` and **does not throw** on a non-success -status — the error is carried in the returned value instead. (`{TError}` is the same two-case shape as -above: a typed `{Operation}Error`, or `RawError`.) `ApiResult` is a public -`readonly struct` under `{RootNamespace}.Core.Models`. If the controller has no `{Operation}Result` -overload, this variant wasn't generated — use the throwing method with `try/catch` instead. +An operation may have a **sibling method** named `{Operation}Result` (next to the throwing `{Operation}`), +returning `Task>`; it **does not throw** on a non-success status — the error +is carried in the returned value instead. (`{TError}` is the same two-case shape as above: a typed +`{Operation}Error`, or `RawError`.) `ApiResult` is a public `readonly struct` under +`{RootNamespace}.Core.Models`. If the controller has no `{Operation}Result`, use the throwing method with +`try/catch`. Unlike the throwing path, `ApiResult` exposes the HTTP **`StatusCode`** and **`Headers`** on *both* success -and failure — so this is the variant to use when you need the status code, rate-limit headers, or pagination -`Link` headers. +and failure — so this is the variant to use when you need a 2xx's status code, rate-limit headers, or +pagination `Link` headers. The other way to read them on the success path is an `SdkHook.OnResponse` hook +(see **dotnet-configuration-resilience** § Hooks); on the error path every `ApiException` already carries +`StatusCode` and `Headers`. ```csharp using {RootNamespace}.Core.Models; // ApiResult @@ -269,7 +236,7 @@ if (result.TryGetResponse(out var response)) // success else if (result.TryGetError(out var error)) // failure { // 'error' is the same TError as the throwing path: - // Case A → typed {Operation}Error (use its TryGet* accessors, then TryGetRawError) + // Case A → typed {Operation}Error (dispatch with error.Match(on{Arm}: …, otherwise: …), or read one arm with TryGet*) // Case B → RawError (read error.StatusCode / error.ReadAsString()) Console.Error.WriteLine($"HTTP {(int)result.StatusCode}"); } @@ -290,13 +257,11 @@ var (isSuccess, response, error) = result; ## Connection failures, and guarding every call -The `ApiException` catches above cover API errors (the server replied with a non-2xx status). They -do **not** cover connection failures — host unreachable, DNS failure, dropped connection, or timeout. Those -come through as **`SdkConnectionException`** (could not send, or could not read the body) and its leaf -**`SdkTimeoutException`** (an attempt, the transport, or an SSE stream went silent — `Timeout` says which -window), which a `catch (ApiException<...>)` will not match. If that catch is your only guard, a connection -failure escapes and takes down whatever was running the call. The raw `HttpRequestException` is the -`InnerException`; you never catch it directly. +The `ApiException` catches above cover API errors only. No usable response — host unreachable, DNS +failure, dropped connection, timeout — throws **`SdkConnectionException`** or its leaf **`SdkTimeoutException`** +(`Timeout` says which window), with the raw cause in `InnerException`. A `catch (ApiException<...>)` does +not match them; if it is your only guard, a connection failure escapes and takes down whatever was running +the call. **A file download is the exception:** a drop while you read the returned `BinaryContent` throws a raw `IOException` from your read, not `SdkConnectionException`. @@ -313,14 +278,11 @@ catch (ApiException<{Operation}Error> ex) // a Case A operation — typed { // Carry the body's identity fields (the provider's own error code or name, any correlation // id) — the typed body is the only thing that carries them, and it does not outlive this - // catch. Check the accessors in the SAME order as the Case A ladder above: every typed - // accessor this operation declares (names from its map row), then the RawError-yielding - // arms LAST. Carry ex.StatusCode alongside whichever branch fires. - if (ex.Error.TryGet{Body}(out {Body} e)) - throw new {ProviderException}(e.{MessageField} /* + identity fields — names from the model's map row */, ex.StatusCode, ex); - if (ex.Error.TryGetRawError(out RawError raw)) - throw new {ProviderException}($"HTTP {(int)ex.StatusCode}", ex.StatusCode, ex); - throw new {ProviderException}("unrecognised error shape", ex.StatusCode, ex); + // catch. Dispatch through Match so every declared body is handled and an undeclared status lands + // in otherwise; carry ex.StatusCode alongside whichever arm fires. + throw ex.Error.Match( + on{Body}: e => new {ProviderException}(e.{MessageField} /* + identity fields — names from the model's map row */, ex.StatusCode, ex), + otherwise: raw => new {ProviderException}($"HTTP {(int)ex.StatusCode}", ex.StatusCode, ex)); } catch (ApiException ex) // a Case B operation — no typed body, just the status { @@ -343,9 +305,9 @@ catch (SdkConnectionException ex) // could not send / could not r { throw new {ProviderException}("provider unreachable", ex); // no status — nothing usable answered } -catch (AuthSchemeException ex) // OUR credential could not be applied — see Notes +catch (AuthSchemeException ex) // OUR credential is missing, its provider returned nothing, or it could not be applied — see Notes { - throw new {ProviderException}("provider credentials rejected", ex); + throw new {ProviderException}("provider credentials missing or rejected", ex); } // Do NOT add `catch (OperationCanceledException)`: the caller's own cancellation is not a provider // failure and the SDK never wraps it — let it propagate. @@ -371,29 +333,19 @@ outcome and apply the identical catch ladder at every call site — same order, When the same kind of failure (a validation rejection, say) becomes a different result on a different operation, callers can't reason about it. One shared ladder, not per-call improvisation. -**Keep distinct failures distinct — and pick the discriminator from what the error path actually -delivers.** Your error type needs to carry something that separates "you sent something invalid" -from "the provider is down". The reflex is the HTTP status; whether you *can* carry one is an API -fact, settled from the contract sheet before the boundary is written: - -- **Every `ApiException` carries `StatusCode`** — Case A and Case B alike, and the - `ResponseDeserializationException` too — so the transport status is always available to carry - and to key the ladder on. A provider **4xx** the caller can act on surfaces as that same client - **4xx**; transport failures and unknowns surface as **5xx**. -- **Operations with a typed `{Operation}Error`** (Case A) usually have a **better** discriminator - than the status: the body's own **identity fields** — the provider's error code or name, - fine-grained issue codes, a correlation id — which say more than a status would (whether each - field is `required` or nullable is on the model's map row). A typed error class can route - several documented statuses into ONE accessor, so the accessor that fired and `ex.StatusCode` - are two different facts — carry both. Some operations add status-specific - `TryGet…(out RawError)` accessors as well. The operation's map row lists all of it. -- **Accessor names differ per operation** — they embed the body type (`TryGet{Body}`), so a - guessed name is a compile error (`CS1061`), not a runtime surprise. Take each name from the - operation's own map row every time. - -Whichever discriminator applies, collapsing every failure into one blanket status (e.g. 502 for -everything) throws away the one signal that separates "you sent something invalid" from "the -provider is down." +**Keep distinct failures distinct.** Your error type needs to carry something that separates "you sent +something invalid" from "the provider is down": + +- **Every `ApiException` carries `StatusCode`** — Case A, Case B and `ResponseDeserializationException` + alike — so a provider **4xx** the caller can act on can surface as that same **4xx**, and transport + failures and unknowns as **5xx**. +- **A Case A body usually discriminates better** — its **identity fields**: the provider's error code or + name, fine-grained issue codes, a correlation id (whether each is `required` is on the model's map row). + One accessor can cover several documented statuses, so carry both the body fields and `ex.StatusCode`. + Accessor names embed the body type, so a guessed one fails to compile (`CS1061`) — take each from the + operation's map row. + +Never collapse every failure into one blanket status (e.g. 502 for everything). One ladder, in the single place where your error type becomes a caller-facing status. This is where the discriminator you carried gets read back — a ladder with **no branch reading it** is @@ -438,27 +390,19 @@ bucket; validation, conflict and not-found are the caller's to fix. And keep the 5xx: a status or code you have not mapped is an unknown, not a caller error — the provider can add one without warning you. -**Status and headers on the *success* path** are not on the return value — for metrics on a 2xx, or -rate-limit headers, use the `{Operation}Result` sibling (above) or an `SdkHook.OnResponse` hook -(`options.Hooks` client-wide, or `requestOptions.Hooks` per call — see -**dotnet-configuration-resilience** § Hooks). On the *error* path you need neither: every -`ApiException` already carries `StatusCode` and `Headers`. Hooks run once per attempt, so under retry -"the status" they observe means the last attempt's. - -**An unreadable body is not one case but two — decide which before you map it.** An unreadable -**success** body is genuinely unknown: 5xx. An unreadable **error** body is not — the provider -rejected the request and only the *detail* was lost, so answering 5xx tells a retrying caller to -keep retrying something that can never succeed. The exception below tells you which you have. - -**A body that does not match the model is a third failure kind — catch it and sanitize.** The -server can return a body that no longer matches the declared type; the SDK wraps the -`System.Text.Json.JsonException` in **`ResponseDeserializationException`** — an `ApiException` -(so `StatusCode`, `Headers` and `ContentType` are on it) that also names the `TargetType` it was -building, with the `JsonException` as `InnerException`. It is **not** an `ApiException`, so a -ladder with only typed catches lets it through — and if it reaches a generic handler that writes -`exception.Message` the response leaks the SDK type name and the call URL. Catch it at the same -boundary and convert it with a caller-safe message, and **read `ex.StatusCode` to tell the two cases -apart**: +**A body that does not match the model is a third failure kind — catch it and sanitize.** The SDK +throws **`ResponseDeserializationException`** — an `ApiException` (so `StatusCode`, `Headers` and +`ContentType` are on it) that names the `TargetType` it was building, with the `JsonException` as +`InnerException`. It is **not** an `ApiException`, so a ladder with only typed catches lets it +through, and a generic handler that writes `exception.Message` leaks the SDK type name and the call URL. +It fires on a success body (a `OneOf` or `AnyOf` response type is the exception: its Unknown slot takes a +body no variant accepts, see `dotnet-models`), and on an error body that doesn't fit the operation's +`{Operation}Error` — +then your typed `catch` never fires, and there is no fallback to `RawError`. Catch it at the same boundary +with a caller-safe message, and **read `ex.StatusCode` to tell the two cases apart**: an unreadable +**success** body is genuinely unknown (5xx); an unreadable **error** body means the provider rejected the +request and only the *detail* was lost — keep that status, or a retrying caller keeps retrying something +that can never succeed: catch (ResponseDeserializationException ex) { @@ -467,15 +411,6 @@ apart**: throw new {ProviderException}("The provider returned a response that could not be processed.", ex.StatusCode, ex); } -**The error-path variant used to lose the status; it no longer does.** `{Operation}Error` models are -generated per operation and can disagree with the body the API really sends on that status. When they -do, the parse fails *while the error object is being constructed* and the SDK throws -`ResponseDeserializationException` **instead of** `ApiException<{Operation}Error>` — your typed -`catch` never fires. But the status, headers and content type ride on the exception, so "you were -rejected and I lost the reason" is fully expressible: map it by `ex.StatusCode` like any other -`ApiException`, not as a 5xx. The SDK deliberately does *not* degrade an unparseable error body to -`RawError`: a silent fallback would hide the contract drift that is the real defect here. - **Never map a parse failure onto a domain *absence*.** "I could not read the answer" is not "the provider said no." It is tempting on a lookup — an unreadable body and a genuine miss both leave you without a record — but they are different facts and only one of them is a *fact*. Where a lookup @@ -483,10 +418,8 @@ gates a create, that conversion turns a corrupt response into a spurious create; produces a confident wrong answer, which is worse than an error. If the operation's miss really is signalled by an empty body, match on *empty*, not on *unparseable*. -The rule generalizes: whatever converts SDK failures into your own type must carry only a -caller-safe message — never surface `ex.ToString()` or `exception.Message` from an SDK or -framework exception on the wire (the same leak the `ApiError.ToString()` bare-type-name trap -above produces). +Whatever converts SDK failures into your own type carries only a caller-safe message — never an SDK or +framework exception's `ToString()` or `Message` on the wire. **A successful reply can still hand you `null`.** An omitted optional member reads `null`, and so does a JSON `null` on a required string, list, model or enum. An absent required member, or `null` on a @@ -495,20 +428,20 @@ call, and every object you reach them through (`x.Y` before `x.Y.Z`). ## Notes -- A call can also throw `AuthSchemeException` (under `{RootNamespace}.Core.Exceptions`) — a credential - could not be *applied*, which is not an API error. It is an `SdkException` (so it names the API call you - made) but **not** an `ApiException`, so the typed catches above won't match it — give it its own arm, as - the ladder does. It carries `IReadOnlyList SchemeFailures`: with a **single** failing scheme, +- A call can also throw `AuthSchemeException` (under `{RootNamespace}.Core.Exceptions`) — a required + credential is not *configured*, or a credential provider *returned nothing*, so the call fails before + anything is sent, naming the scheme and carrying an empty `SchemeFailures`; or a credential could not be + *applied*. None of these is an API error. It is an + `SdkException` (so it names the API call you made) but **not** an `ApiException`, so the typed catches + above won't match it — give it its own arm, as the ladder does. It carries + `IReadOnlyList SchemeFailures`: with a **single** failing scheme, that failure is also the `InnerException` directly and the list's only entry; with **several** (an SDK whose API composes schemes with OR and none succeeded), `InnerException` is an `AggregateException` of them. The classic cause is an OAuth2 token endpoint refusing the client credentials: the token endpoint's own `ApiException` (pointing at the token URL, with its status) is the **cause** inside the `AuthSchemeException`, not what your `catch` sees — so log `InnerException` to learn *why* auth failed. An `AuthSchemeException` is never wrapped in another. -- Retries happen automatically before an exception is thrown, and `HttpMethodsToRetry` - (`GET/HEAD/PUT/OPTIONS` by default) gates **every** trigger — status, transport fault, and the SDK's own - per-attempt timeout alike. So an error on a `POST`/`PATCH`/`DELETE`, or on a call that sends a file, - surfaces on the first attempt, with no resend. That is not the same as "the write did not happen": a transport failure (`SdkConnectionException`) - may have been thrown after the bytes reached the provider, so the outcome is *unknown* and the caller needs - to be told that rather than "it failed". A per-attempt timeout that outlives its retries surfaces as - `SdkTimeoutException`. See **dotnet-configuration-resilience**. +- Retries run before anything is thrown; a call that sends a file is never retried, and with the defaults + neither is a `POST`/`PATCH`/`DELETE` — except that an OAuth2 `401` is re-sent once on any verb, a file + upload excepted. A transport failure on a write leaves its outcome *unknown* — tell the + caller that, not "it failed". See **dotnet-configuration-resilience**. diff --git a/plugins/spotify/skills/dotnet/dotnet-getting-started/SKILL.md b/plugins/spotify/skills/dotnet/dotnet-getting-started/SKILL.md index db32c93a..76c5cc85 100644 --- a/plugins/spotify/skills/dotnet/dotnet-getting-started/SKILL.md +++ b/plugins/spotify/skills/dotnet/dotnet-getting-started/SKILL.md @@ -1,17 +1,15 @@ --- name: "dotnet-getting-started" -description: "Spotify Web API .NET SDK identity and lookup layer (.NET/C# only) you load directly — install, root namespace, environments, auth pattern, and the SDK map (shipped inside the SDK source repo): every operation signature and error case by lookup, plus the source file declaring each model, enum and error type. Load it for every contract fact, never memory; dotnet-integrate-spotify-web-api is the workflow that uses it." +description: "Load for any Spotify Web API .NET SDK contract fact in C#, instead of memory: install, namespaces, environments, auth, and the SDK map giving every operation signature and error case and the file declaring each model, enum and error type. .NET/C# only; dotnet-integrate-spotify-web-api is the workflow that drives it." --- # Getting started with the Spotify Web API .NET SDK -> **Who this skill is for.** This is the **map layer**: load it to ground every Spotify Web API SDK fact. `dotnet-integrate-spotify-web-api` is the workflow that drives it — you collect the contracts for the work in scope into `spotify-web-api-plan.md`, implement from that sheet, and come back to the one map page a row cites for any fact the sheet is missing. Every contract fact comes from here, never from memory. +> **Map layer** for `dotnet-integrate-spotify-web-api`: the contracts in scope go into `spotify-web-api-plan.md`; come back to the map page a row cites for any fact the sheet lacks. -This is the **SDK-specific** entry point. For general patterns that apply to any APIMatic-generated .NET SDK (auth, calling endpoints, models, error handling, retries, testing), see the companion API-agnostic skills: `dotnet-client-initialization`, `dotnet-authentication`, `dotnet-calling-endpoints`, `dotnet-models`, `dotnet-error-handling`, `dotnet-configuration-resilience`, `dotnet-testing`. +Usage companions: `dotnet-client-initialization`, `dotnet-authentication`, `dotnet-calling-endpoints`, `dotnet-models`, `dotnet-error-handling`, `dotnet-configuration-resilience`, `dotnet-testing`. The SDK map is authoritative for the SDK's *surface* (signatures, model shapes, enums, which error type an operation throws); the companions are the *usage layer* — how to call each piece and the gotchas a signature cannot show. Reading the map or source does not replace a step's companion: at each step below, load the companion *and* confirm names against the map. -**The SDK map and these companion skills are complementary — load both.** The map (generated from the SDK source, which remains the ground truth) is authoritative for the SDK's *surface* (signatures, model shapes, enums, which error type an operation throws); the companion skills are the *usage layer* on top — the best-practice way to call each piece and the gotchas a signature cannot show. Reading the map or source does not remove the need to load the skill for that step, so at each step below, load the companion *and* confirm names against the map. - -> **Ground every signature, model, enum, and error type in the SDK map** (`sdk-map.md` + `map/operations/`, inside the SDK source repo — see the *SDK source* section for obtaining it). The map is **method-first**: operation signatures, error cases with their `TryGet…` accessors, pagination and server/auth wiring are on its pages by lookup — and for every type an operation names, the map names the **file that declares it**, so a shape question (fields, wire names, enum values, union accessors) is one targeted file open, never a search. When a map-sourced name fails to compile, re-read the file its row names; **never fill the gap from memory.** Do **not** decompile or reflect over the installed reference, do **not** fetch SDK files from the web ad hoc, and do **not** grep or run other expensive searches over the clone. +> **Ground every signature, model, enum, and error type in the SDK map** (`sdk-map.md` + `map/operations/`, inside the SDK source repo — see the *SDK source* section for obtaining it); **never fill a gap from memory.** ## SDK identity @@ -24,12 +22,10 @@ This is the **SDK-specific** entry point. For general patterns that apply to any | Client class | `SpotifyWebApiClient` | | Options class | `SpotifyWebApiClientOptions` | | Auth | **OAuth 2.0** authorization code — set `Oauth20`
**OAuth 2.0** client credentials — set `Oauth20ClientCredentials` | -| Environments | `ServerEnvironment.Production` *(default)* → `https://api.spotify.com/v1`
`ServerEnvironment.Environment2` → `https://accounts.spotify.com` | -| Log environment variable | `SPOTIFYWEBAPICLIENT_LOG` | +| Environments | `ServerEnvironment.Production` *(default)*
base URL per server group (2 groups): `sdk-map.md` *Servers & auth* | +| Log environment variable | `SPOTIFY_WEB_API_LOG` | | Target framework | `netstandard2.0` (C# `LangVersion 14`) | -The table above is **orientation, not a copy-paste recipe** — it gives you the names and facts (install, namespaces, the auth *pattern*, the environments), while the actual integration code comes from the companion skills. Load every one the contract sheet's REQUIRED READING names before you start implementing (`dotnet-integrate-spotify-web-api` makes that binding); the **Integration workflow** below says which governs which step. - ## Namespaces (using-directives) The SDK splits its public types across **separate child namespaces**. C# does **not** import child namespaces transitively, so `using SpotifyWebApi.Models;` alone does **not** make enums, union types, or error types visible — you get `CS0103`/`CS0246` ("name/type does not exist") on build. Add a separate `using` for each kind of type you reference: @@ -46,32 +42,31 @@ Models, enums, union types and the generated error types each sit in their own c This SDK is **not published to a package feed**, so there is no `dotnet add package` for it. Build it from its repository — , branch `main` — and reference the resulting assembly from the project that will call Spotify Web API, then write the `using` directives from the table above. -> **Build against the assembly built from that repository, and do not copy the SDK source into your repository.** A copy is a fork: the next time the SDK is regenerated the copy stays behind, and the map then describes code you are not building against. The map is read from the read-only **reference clone** the *SDK source* section below describes, which lives in the system temp directory, is obtained at the start of SDK work and is never part of the build. +> **Build against the assembly built from that repository; never copy the SDK source into your repository** — a copy is a fork the map stops describing. The map is read from the read-only **reference clone** (*SDK source* below), never part of the build. ## SDK map — look up first, open the named file second, never grep -The SDK ships a generated map **inside the SDK source repo**, at the SDK root — the map and the SDK regenerate together in one repo, so they cannot drift apart. The map is **method-first**: operation contracts are on its pages; model, enum and error **shapes are deliberately not duplicated there** — the map names the file declaring each type, and you read the shape in that file. Every path below is relative to the SDK root in the clone — obtain it first (next section): +The map sits at the SDK root **inside the SDK source repo** and always matches the source beside it. It is **method-first**: operation contracts are on its pages; for model, enum and error shapes it names the file declaring each type, and you read the shape in that file. Every path below is relative to the SDK root in the clone — obtain it first (next section): - **`sdk-map.md`** — the index and the read-once pages: SDK identity, client construction and the full options surface, the error-handling model (Case A typed / Case B raw), the **defaults table** for operations, the model/enum/error directory conventions, *Namespaces by content type*, and *Servers & auth*. - **`map/operations/`** — one page per controller, one block per operation: the exact C# signature with its request record's required members, the return type, the error case (A: typed `{Operation}Error` with its `TryGet…` accessors and their statuses / B: `RawError`), pagination and server-group bullets **only where they differ from the defaults**, and a **Type sources** table naming the file that declares every type the operation mentions. -- **Shapes live in the source, one type per file.** Every file under `src/SpotifyWebApi/Models/`, `src/SpotifyWebApi/Errors/` and `src/SpotifyWebApi/Requests/` declares exactly one public type named after the file, so a type name *is* its path: take it from the operation's Type sources table (or the kind's directory — records `src/SpotifyWebApi/Models/`, enums `src/SpotifyWebApi/Models/Enums/`, typed errors `src/SpotifyWebApi/Errors/`, request records `src/SpotifyWebApi/Requests/`, or `src/SpotifyWebApi/Requests//` for an operation on a controller; an operation with several tags is filed under the first tag it declares) and read the fields, `required` flags, enum values and, on a model, the `[JsonPropertyName]` wire names from that one file (a request record is never serialized and carries none). The compiler is the backstop: a wrong name fails to build. +- **Shapes live in the source, one type per file.** Every file under `src/SpotifyWebApi/Models/`, `src/SpotifyWebApi/Errors/` and `src/SpotifyWebApi/Requests/` declares exactly one public type named after the file, so a type name *is* its path (the directories are under *Layout* below), or take it from the operation's Type sources table. Read the fields, `required` flags, enum values and, on a model, the `[JsonPropertyName]` wire names from that one file, scoped (a request record is never serialized and carries none). The compiler is the backstop: a wrong name fails to build. -**This map is how you traverse the SDK.** Do **not** grep, glob, `find`, or otherwise scan the clone to locate an operation, model, enum, union, or error type — the map (and the name-is-path convention) is the locator. Instead: +**Never grep, glob, `find` or otherwise scan the clone to locate anything** — the map and the name-is-path rule are the locator. Instead: 1. Open `sdk-map.md` and follow its controller table to the operations pages in scope; read every contract fact (signature, error accessors, pagination) by lookup. 2. **Silence means the default.** The index's defaults table states what holds for every operation (throw-only, no pagination, the default server group, inputs as one request record); an operation's block states only what differs. A block silent on pagination has none — take the default and move on rather than opening the source to confirm it. -3. For a **shape** (model fields, enum values, union accessors, a typed error's payload), open the one declaring file the map names — that is the normal flow here, not a fallback — and read it scoped. -4. The **HTTP verb/route and the endpoint's behavioural prose** live on the operation method itself — the XML `` docs in the `Api/{Controller}.cs` file the page header names; what each input means is in the per-member docs on its request record. Read them there when wire-level detail or call-acceptance semantics matter; never reconstruct a route from memory. +3. The **HTTP verb/route and the endpoint's behavioural prose** live on the operation method itself — the XML `` docs in the `Api/{Controller}.cs` file the page header names; what each input means is in the per-member docs on its request record. Read them there when wire-level detail or call-acceptance semantics matter; never reconstruct a route from memory. Keep lookups cheap — the rules that keep a session's context small: -- Collect the contracts for **every** in-scope operation in **one** pass — signatures and error accessors from the map pages, then required fields with wire names and enum values from the declaring files those pages name — into the **contract sheet** in `spotify-web-api-plan.md`, then implement from the sheet. Do not re-open a map page or source file per field, and never re-look-up a fact the sheet already carries. +- Collect every in-scope contract in **one** pass into the **contract sheet** in `spotify-web-api-plan.md` (format in `dotnet-integrate-spotify-web-api`); never re-look-up a fact the sheet already carries. - When you do open a source file, read it **scoped**: with an offset/limit, or a search for the one symbol — never dump a whole file into the conversation. - Never open the SDK's `api-reference.md` — the map supersedes it. ## SDK source — get it first; the map lives inside it -The SDK source is where the map lives, so **getting it is the first step of SDK work this session, not a fallback**: one shallow clone at the recorded ref, into the **system temp directory** (`/spotify-web-api-sdk-src/`), reused for the whole session. It is a read-only reference, never in the project repo, and **not** a build dependency. Opening the **one declaring file** a map page names is the normal flow here — that is where model, enum and error shapes live. What stays off-limits is *locating* anything by scanning: every file you open is one the map named, opened scoped, never found by grep. +The SDK source is where the map lives, so **getting it is the first step of SDK work this session, not a fallback**: one shallow clone at the recorded ref, into the **system temp directory** (`/spotify-web-api-sdk-src/`), reused for the whole session. It is a read-only reference, never in the project repo, and **not** a build dependency. **Clone once, up front**, into a fresh timestamped folder under `/spotify-web-api-sdk-src/`, and reuse that folder for the rest of your session: @@ -89,35 +84,35 @@ git clone --filter=blob:none --branch main https://github.com/context-plugins/sp # Reuse $dir for the rest of your session (it is your clone path). ``` -The source you read is branch `main`: a branch is a moving target, not a pin — it can be regenerated after this plugin ships, and then the map you read describes code the package no longer matches. If a name from the map fails to compile, trust the compiler, re-read the source file the map's row names, and report the mismatch; never patch around it from memory. +The source you read is branch `main`: a branch is a moving target, not a pin — it can move after this plugin ships, and then the map you read describes code the package no longer matches. If a name from the map fails to compile, trust the compiler, re-read the source file the map's row names, and report the mismatch; never patch around it from memory. The clone stays in the system temp directory, and `spotify-web-api-plan.md` never carries its path — the plan must stay portable. Then confirm the SDK shape **only** from the clone — not by either of these: -- **Do not decompile or run reflection over the built assembly.** A compiled assembly drops what the source carries and the other skills rely on: the XML ``/parameter doc-comments, the exact parameter names and order, and each method's internal request-builder list. -- **Do not fetch SDK files from the web one at a time** as your way in — `…/blob/…` pages return HTML (not source) and guessed paths fail, which is exactly how ad-hoc fetching breaks. Read the local clone instead; only if you truly cannot clone (`git` is unavailable), fetch a **raw** URL derived from the source repo above — never a `…/blob/…` page. +- **Do not decompile or run reflection over the built assembly.** It drops what the source carries and the other skills rely on: the XML ``/parameter doc-comments and the exact parameter names and order. +- **Do not fetch SDK files from the web one at a time** as your way in — `…/blob/…` pages return HTML, not source. Read the local clone instead; only if you truly cannot clone (`git` is unavailable), fetch a **raw** URL derived from the source repo above — never a `…/blob/…` page. Layout — where the SDK map's file references resolve, relative to the SDK root in the clone (open these directly; do not scan for them): - `src/SpotifyWebApi/Api/` — one file per controller/group; **this is where the operation methods live** (the HTTP verb and route, and the XML `` docs carrying the endpoint's behavioural prose). The map's per-controller pages name the exact file. -- `src/SpotifyWebApi/Models/` (+ `src/SpotifyWebApi/Models/Enums/`) — body and response models, unions and enums; one public type per file, named after the file. -- `src/SpotifyWebApi/Requests/` — one request record per operation that takes input, carrying the per-member docs for each input; a controller's records sit in `src/SpotifyWebApi/Requests//` (an operation with several tags is filed under the first tag it declares). +- `src/SpotifyWebApi/Models/` (+ `src/SpotifyWebApi/Models/Enums/`) — body and response models, unions and enums. +- `src/SpotifyWebApi/Requests/` — one request record per operation that takes input, carrying the per-member docs for each input; a controller's records sit in `src/SpotifyWebApi/Requests//` (an operation on several controllers has one record, in one of their folders — its Type sources table names which). - `src/SpotifyWebApi/Errors/` — per-operation `{Operation}Error` types (only Case-A operations have one; the map's rows say which case each operation is). - `src/SpotifyWebApi/Core/` — HTTP infrastructure (the `SdkException` family, `RawError`, auth, retries, `SdkHook`). - `src/SpotifyWebApi/Servers/`, `src/SpotifyWebApi/SpotifyWebApiClient.cs`, `src/SpotifyWebApi/ServiceCollectionExtensions.cs` — environments, the client, DI. -**Leave the clone where it sits — do not delete it, copy it or edit it.** It is a read-only reference with nothing of yours in it, and keeping it is what lets every later step in this session reuse it instead of cloning again. An edit made in it never reaches the SDK, so report what needs changing instead of patching it; the OS reaps the temp directory on its own, and a future session simply makes its own timestamped clone. +**Leave the clone in place and unedited** — later steps reuse it instead of cloning again, and an edit made in it never reaches the SDK, so report what needs changing instead. The OS reaps the temp directory on its own. ## Idempotency — the real keys are on the map; the injected header is not one -The generator injects an `Idempotency-Key: Guid.NewGuid()` header on **every non-GET operation that does not already declare that header itself** — fresh on every call, invisible to you, and **not** an idempotency key in any meaningful sense: a value that changes per call deduplicates nothing, and Spotify Web API may not document reading that header at all. `dotnet-configuration-resilience` explains why a visible header like this is worse than an absent one. +**Every non-GET call sends an `Idempotency-Key` header.** Unless the operation's request record carries that header as a member, its value is a fresh `Guid.NewGuid()` on every call — it deduplicates nothing, and Spotify Web API may not read the header at all, so never cite it as a key. -Whether an operation takes a **real**, caller-supplied key is an API fact, visible on that operation's request record: look for a key-shaped member (an idempotency key, a request id) in the record file its **Type sources** table names. Its semantics — retention windows, when it is mandatory — are provider prose, in that member's XML docs and the method's `` in the `Api/` file the page names. Some APIs expose **`If-Match` optimistic concurrency** instead — a different guarantee (reject my write if the resource changed) solving a different problem (lost updates, not duplicates); those members show on the request record too. For every write with no key, the answer is reconciliation — `dotnet-configuration-resilience` — not hope. +Whether an operation takes a **real**, caller-supplied key is visible on that operation's request record: look for a key-shaped member (an idempotency key, a request id) in the record file its **Type sources** table names. Its semantics — retention windows, when it is mandatory — are in that member's XML docs and the method's `` in the `Api/` file the page names. An **`If-Match`** member on the record guards against lost updates, not duplicates. For every write with no key, the answer is reconciliation: `dotnet-configuration-resilience`. ## Sensitive data — check the request models before you log anything -Whether this API's **request** models carry fields you must never log — card or bank numbers, personal data, message content — is a shape question: each request model's declaring file (the map's Type sources table names it) lists every field with its `[JsonPropertyName]` wire name. If the scope touches such a field, three generator facts decide your logging posture (all in `dotnet-configuration-resilience`): JSON request bodies are logged **verbatim** when `LogRequestBody` is on, with no redaction; form bodies are masked only by deny-list; and leaving `options.Logging.LoggerFactory` unset arms the `SPOTIFYWEBAPICLIENT_LOG` environment variable, whose `trace` level forces body logging on with no code change and no deploy. So on any build that can carry such a field: `LogRequestBody` stays off, `LoggerFactory` is set explicitly in production, and your own diagnostics never echo a request body on those paths. +Whether this API's **request** models carry fields you must never log — card or bank numbers, personal data, message content — is a shape question: each request model's declaring file (the map's Type sources table names it) lists every field with its `[JsonPropertyName]` wire name. If the scope touches such a field, the SDK's logging decides your posture (see `dotnet-configuration-resilience`): JSON request bodies are logged **verbatim** when `LogRequestBody` is on, with no redaction; form bodies are masked only by deny-list; and leaving `options.Logging.LoggerFactory` unset arms the `SPOTIFY_WEB_API_LOG` environment variable, whose `trace` level forces body logging on with no code change and no deploy. So on any build that can carry such a field: `LogRequestBody` stays off, `LoggerFactory` is set explicitly in production, and your own diagnostics never echo a request body on those paths. Responses are often safer — many APIs return masked variants of what requests carry raw — but that too is a model-shape fact: check the response model's file before assuming. @@ -125,21 +120,21 @@ Responses are often safer — many APIs return masked variants of what requests On a success the SDK returns only the deserialized body: the HTTP status and headers of a successful call are **not on the return value**, and unless the map's error-handling model notes no-throw `{Operation}Result` siblings for this SDK, there is no non-throwing variant to get them from. On an error, what is reachable depends on the operation's error case — its map row: a Case B `RawError` carries `StatusCode`; a typed Case A body may or may not (see `dotnet-error-handling`). -**Hooks are the SDK's own seam for transport metadata.** `options.Hooks` (client-wide) and `requestOptions.Hooks` (per call, appended after the client-wide list) take `SdkHook` instances; `SdkHook.OnResponse((response, context) => …)` sees every raw `HttpResponseMessage` — status, `Retry-After`, rate-limit budget headers, a request-id echo for correlation — and `SdkHook.OnRequest` the outgoing request. A hook runs **inside the retry pipeline, once per attempt**, so "the" value is the last attempt's; a per-call hook can close over a local, which puts the observed value in scope in the same method's `catch`. `RawClient.ExecuteResult` does return an `ApiResult`, but `RawClient` is `internal sealed`, so hooks — not reflection, and not a `DelegatingHandler` you would otherwise need — are the supported way in. +The status and headers of a successful call (`Retry-After`, rate-limit budgets, a request-id echo) are reachable only through **hooks** — `SdkHook.OnResponse` on `options.Hooks`, or per call on `requestOptions.Hooks`, running once per attempt; see *Hooks* in `dotnet-configuration-resilience`. ## The `dotnet-*` skill names are not unique across plugins -Every APIMatic .NET plugin ships this same set of `dotnet-*` skill names. Copies from the **same generator version** are byte-identical, so between those plugins a collision is harmless. A copy from a **different generator version** is not — it describes a different runtime, and an older plugin's retry eligibility, request-options surface and unknown-field handling all differ from this SDK's. **Load the copy that ships with THIS plugin**: write plugin-qualified names where your harness supports them, and where it does not, confirm the copy you loaded describes the runtime this SDK actually ships — `RequestOptions` carrying both a log level and `Hooks`, and a `src/SpotifyWebApi/Core/Hooks/SdkHook.cs` in the source. The `X-APIMatic-Gen-Version` wire header does not distinguish these surfaces, so it is not the check. +Every APIMatic .NET plugin ships this same set of `dotnet-*` skill names, and a copy from another plugin may describe a different runtime. **Load the copy that ships with this plugin**: write plugin-qualified names where your harness supports them, and where it does not, confirm the copy you loaded describes the runtime this SDK ships — `RequestOptions` carrying both a log level and `Hooks`, and a `src/SpotifyWebApi/Core/Hooks/SdkHook.cs` in the source. The `X-APIMatic-Gen-Version` wire header does not distinguish these runtimes, so it is not the check. ## Integration workflow — load the companion skill at each step -You loaded every companion the sheet named before starting (per `dotnet-integrate-spotify-web-api`); before you write the code for each step, re-read the one that governs it — even if you have already read the relevant source. Each step calls out the trap the signature hides (in *parens*). A typical integration reaches them in this order: +You loaded every companion the sheet named before starting (per `dotnet-integrate-spotify-web-api`); before you write the code for each step, re-read the one that governs it — even if you have already read the relevant source. A typical integration reaches them in this order: -1. **Client & DI setup** — load **dotnet-client-initialization** before you write `new SpotifyWebApiClient(...)`, build its options, or DI-register it. (*The signature will not tell you:* the `HttpClient`/handler pipeline must be long-lived and reused via `IHttpClientFactory`, not rebuilt per request; the SDK client wrapper over it may be transient.) -2. **Authentication** — load **dotnet-authentication** before you set credentials. The scheme(s) this SDK accepts are the credentials properties on `SpotifyWebApiClientOptions` — the identity table above names them. (*The signature will not tell you:* set credentials before constructing the client or in the DI callback, and load secrets from configuration rather than hardcoding.) -3. **Calling an endpoint / building a request body** — load **dotnet-calling-endpoints** before the first `client.{ApiGroup}.{Operation}(...)` call. (*The signature will not tell you:* every input goes on the operation's request record — `required` members must be set, the rest are optional or already carry the spec's default; and whether a write takes a real idempotency key is on that record — the injected `Idempotency-Key` header is not one, see *Idempotency* above.) -4. **Models** — load **dotnet-models** the moment a request/response field is not a plain string or number. (*The signature will not tell you:* unions are built with factory methods and read via `TryGet…` (no `new`), enums are `OpenStringEnum` / `OpenIntEnum` records with a generated `Match` — not C# enums, and with no public factory — and unknown response fields are kept on any model that carries an extension-data bag — conventionally `AdditionalProperties`, but a schema that closes itself with `additionalProperties: false` has none, and one that already declares a member of that name pushes the bag to a deduplicated spelling. Check the model's own map row rather than assuming the property is there.) -5. **Error handling** — load **dotnet-error-handling** before you write any `try/catch`. (*The signature will not tell you:* an operation is either Case B (`ApiException`, no typed accessors) or Case A (a typed `{Operation}Error`) — how the API mixes them is its own fact, so confirm each operation's case in its map row; and `TryGetRawError` is not a catch-all on the typed errors. Whether no-throw `…Result` variants exist at all is stated once, in the map's defaults table; never assume one does.) -6. **Configuration & resilience** — load **dotnet-configuration-resilience** when you tune retries, timeouts, the base URL, pagination, or logging. (*The signature will not tell you:* `HttpMethodsToRetry` gates **every** retry trigger, so a `POST` is never resent by default — but a `GET` that hangs costs far more than the `Timeout` value suggests, because the per-attempt timeout is itself retried. `Timeout` is per-attempt not total, `RetryOptions.Disabled()` turns retries off, and there **is** a built-in logger on `options.Logging` — whose `LogRequestBody` does not redact JSON.) -7. **Testing** — load **dotnet-testing** before you stub the SDK. (*The signature will not tell you:* the `HttpClient` constructor argument is the test seam; match the project's existing framework and assertion style.) +1. **Client & DI setup** — load **dotnet-client-initialization** before you write `new SpotifyWebApiClient(...)`, build its options, or DI-register it. +2. **Authentication** — load **dotnet-authentication** before you set the credentials properties on `SpotifyWebApiClientOptions` — the identity table above names them. +3. **Calling an endpoint / building a request body** — load **dotnet-calling-endpoints** before the first `client.{ApiGroup}.{Operation}(...)` call; whether a write takes a real idempotency key is on its request record (*Idempotency* above). +4. **Models** — load **dotnet-models** the moment a request/response field is not a plain string or number. A model's extension-data bag for unknown fields is `AdditionalProperties`, a numbered variant of that name on a model that already has a property called that, and absent on a model that admits no extra fields — confirm it in the model's file. +5. **Error handling** — load **dotnet-error-handling** before you write any `try/catch`; confirm each operation's Case A or B in its map row. +6. **Configuration & resilience** — load **dotnet-configuration-resilience** when you tune retries, timeouts, the base URL, pagination, or logging. +7. **Testing** — load **dotnet-testing** before you stub the SDK. diff --git a/plugins/spotify/skills/dotnet/dotnet-integrate-spotify-web-api/SKILL.md b/plugins/spotify/skills/dotnet/dotnet-integrate-spotify-web-api/SKILL.md index e35d355b..7456edcd 100644 --- a/plugins/spotify/skills/dotnet/dotnet-integrate-spotify-web-api/SKILL.md +++ b/plugins/spotify/skills/dotnet/dotnet-integrate-spotify-web-api/SKILL.md @@ -1,55 +1,66 @@ --- name: "dotnet-integrate-spotify-web-api" -description: "MANDATORY FIRST STEP for Spotify Web API .NET SDK work in a C#/.NET project — load this BEFORE opening the SDK map or touching any project file; .NET/C# SDK ONLY, never load it for any other language. Applies when asked to integrate Spotify Web API in C# — Albums, Artists, Audiobooks, CategoriesApi, Chapters, Episodes, Genres, Library, MarketsApi, Player, Playlists, Search, Shows, Tracks, Users — or when a Spotify Web API .NET SDK call errors or behaves unexpectedly. It carries four binding rules stated NOWHERE else — (1) for implementation work, the plan file spotify-web-api-plan.md is written at the project repo root BEFORE any project file is created or edited; (2) dotnet-getting-started and the SDK map it carries are loaded and used for every contract fact, never memory; (3) every dotnet-* skill the contract sheet's REQUIRED READING names is loaded before implementation starts; (4) every sheet row carries one of three labels — a map page, UNVERIFIED, or YOUR CALL — not in the map. Skip it and SDK facts get written from stale memory." +description: "MANDATORY FIRST STEP for any Spotify Web API .NET SDK work in C#: integrating Spotify Web API, or a Spotify Web API .NET SDK call that errors or behaves unexpectedly. Load it before opening the SDK map or touching any project file — it sets the plan-first workflow (spotify-web-api-plan.md before any code) and the map-grounding rules. .NET/C# only; never load it for another language." --- # Spotify Web API .NET SDK — Workflow (map + skills) -You are the Spotify Web API .NET SDK specialist for this task — one agent for every SDK need: planning, answering contract questions, implementing, and fixing SDK errors. Your scope is **C#/.NET only**: if a request concerns any other language or SDK, say so and stop. Your source of truth is the **SDK map that ships inside the SDK source repo** (`sdk-map.md` plus its `map/operations/` pages; model, enum and error shapes live in the source files those pages name), obtained per `dotnet-getting-started`, plus the companion `dotnet-*` skills for usage traps. Your training data on this SDK is stale — every fact you emit must come from a map page or a map-named source file you actually read this session, in that same clone. You never guess, and you never open the SDK's `api-reference.md`. You do all of it yourself — ground, plan, implement, fix — there is no helper agent to delegate to. +You orchestrate this task: the `spotify-web-api-planner` agent writes the plan and its contract sheet; you answer contract questions, implement from the sheet and fix SDK errors yourself. Your source of truth is the **SDK map that ships inside the SDK source repo** (`sdk-map.md` plus its `map/operations/` pages; model, enum and error shapes live in the source files those pages name), obtained per `dotnet-getting-started`, plus the companion `dotnet-*` skills for usage traps. Your training data on this SDK is stale — every fact you emit must come from a map page or a map-named source file you actually read this session, in that same clone; you never guess. -**Scope guard:** the APIMatic-generated Spotify Web API **.NET SDK** (root namespace `SpotifyWebApi`) in **C#/.NET projects only**. Unrelated API, or any language other than C#/.NET — do nothing; this skill does not apply. +**Scope guard:** the APIMatic-generated Spotify Web API **.NET SDK** (root namespace `SpotifyWebApi`) in **C#/.NET projects only**. For any other API or language, say so and stop — this skill does not apply. + +## The planner agent + +`spotify-web-api-planner` ships with this plugin. It writes `spotify-web-api-plan.md` — the plan and its contract sheet — and revises it in place; it writes no project code. Start it the first of these ways your host allows: + +1. **Your subagent tool lists it.** Some hosts list a plugin's agents under the plugin's name, as `spotify:spotify-web-api-planner`; start it by whichever of the two names your subagent tool lists. +2. **It isn't listed, or you can't start a subagent.** Tell the user in one line that you are writing the plan yourself, then do so as *Step 1* describes. Don't stop to ask. + +However you start it: + +- **Start it on the same model you are running on.** If your subagent tool takes a model, pass your own model; if it has no model option, leave its default. Tell the user in one line which model you started it on. +- **Start it once per integration.** A plan revision is a follow-up message to that same agent; re-start it, carrying the clarification and the plan path, only where your host cannot message it. Never start a second one for the same integration. ## Grounding rules -- **Map for contracts; the map-named file for shapes.** Follow `dotnet-getting-started`'s *SDK map* and *SDK source* sections in full — they define how to obtain the source (the map lives inside it), that reading a model/enum/error shape means opening the one declaring file the map names (routine, scoped), and why locating anything by grep/glob/`find` over the tree is a defect rather than a shortcut. The clone stays in the system temp directory, and `spotify-web-api-plan.md` never carries its path — the plan must stay portable. -- **Never grep, glob or `find` the SDK tree to locate something** — the map is the locator, and a type name is its path. Every lookup starts at the map index and ends on the one page (or the one source file) it names. -- **Your contract sheet never leaves a contract fact open for "later."** The map pages and the files they name answer nearly everything — resolve them during planning, not mid-implementation. For the rare in-scope fact even the source cannot settle: if only live traffic could confirm it, convert it into a concrete defensive-coding directive on the sheet and label the uncertainty `UNVERIFIED`. Never leave a row marked for a later source lookup: an open row is how you end up opening source mid-implementation. +- **Map for contracts; the map-named file for shapes** — follow `dotnet-getting-started`'s *SDK map* and *SDK source* sections in full. +- **Your contract sheet never leaves a contract fact open for "later."** The map pages and the files they name answer nearly everything — resolve them during planning. A fact only live traffic could confirm becomes a concrete defensive-coding directive on the sheet, labelled `UNVERIFIED` (§7); never leave a row marked for a later source lookup. - **When you judge how far a contract can be trusted**, the trust judgment may cite ONLY evidence visible in the map or SDK source (e.g. two generated definitions that disagree, a suspicious shared model) — never training-data memory of this API, and never claims about what the live wire "usually" sends. -- **The sheet records Spotify Web API's call surface; the application's design is decided at implementation time.** Its persistence, its concurrency rules, and the request contract its own callers must satisfy are not SDK facts. Where an SDK fact forces an application decision, record the fact and its consequence on the sheet, mark the decision `YOUR CALL — not in the map`, and decide it at implementation time against the task. +- **The sheet records Spotify Web API's call surface, not the application's design** — its persistence, its concurrency rules, and the request contract its own callers must satisfy. Where an SDK fact forces an application decision, record the fact and its consequence and mark the decision `YOUR CALL — not in the map` (§7), to be decided at implementation time against the task. - **Name only what you have read.** Never name a claim, header or route of the application as though you knew it exists — unless you have read that code. Name configuration by its binding key, never by a raw environment variable, and give the default the map documents where there is one: a setting you invent a name for is a setting no deployment will supply. ## Workflow **If the user opens with a reported SDK error or unexpected Spotify Web API behaviour** (not new feature work), go straight to *Step 4 — Fixing SDK errors* below — do not run the plan-first flow for a bug report. Otherwise, for implementation work: -### Step 1 — Plan first: write `spotify-web-api-plan.md` (always, for any implementation work) +### Step 1 — Plan first: the planner writes `spotify-web-api-plan.md` (always, for any implementation work) -Your FIRST deliverable is `spotify-web-api-plan.md` at `/spotify-web-api-plan.md` — that exact path, always; never pick another location. It carries the plan and the contract sheet in the format below, and it is the only project-repo file you write before the HARD GATE further down. +Your FIRST action, once you have reached the SDK source (the one prerequisite below that comes before the start), is to start **`spotify-web-api-planner`**, as *The planner agent* says, once, with the user's full request and the name of this skill, `dotnet-integrate-spotify-web-api`. Dictate in its task the absolute project root, the absolute path of the SDK source you reached — it reads the map and the source there rather than reaching its own — and the absolute path it must write to — `/spotify-web-api-plan.md`, that exact path, always; never another location. It grounds and writes the plan and the contract sheet exactly as *How to ground* and the format below describe, and returns the file's path. Those subsections are its instructions and your reference: you read the sheet in that format, and once the code compiles you fill its `TBD` cells and settle its `YOUR CALL — not in the map` entries, as *Step 3* says. Do the rest of the read-only prerequisites below in the same message as the start, and while it works. + +**If you couldn't start the planner** (case 2 in *The planner agent*), *How to ground* and the format are your own instructions: write the file yourself at that path. It is the only project-repo file you write before the HARD GATE further down. #### How to ground (map-first, one pass) 1. Load `dotnet-getting-started`; open `sdk-map.md` (the index). 2. From the index, open the **operations pages** for every controller in scope — take signatures (the request record each operation takes, and its required members), return types, error case (A: typed `ApiException<{Operation}Error>` with its `TryGet…` accessors and payload type / B: `ApiException`), and pagination — remembering that a block silent on a defaults-table point means the default applies. Where an operation's *semantics* decide what you must pass, that prose is the method's XML `` in the `Api/` file the page names, and the per-member docs on its request record: read it there. 3. Open, scoped, the **declaring source file** for every request/response model you will reference — the operation's **Type sources** table names it — and take field names WITH their `[JsonPropertyName]` wire names, `required` flags, nullability, and the envelope shape. Enum value lists and union accessors come from their declaring files the same way. -4. Identify which companion skill governs each step in scope. For each, write the trap note as a **named hazard plus a `MUST load` pointer** — *not* as the resolved answer. Naming the hazard ("what `Timeout` actually bounds") is right; resolving it inline ("`Timeout` is per-attempt") is wrong — a resolved trap gives you no reason to load the skill, and the skill carries the parts a one-line note cannot. **Never restate a companion skill's default or semantics in a trap note — not even when you believe it correct.** Write the *consequence*, not the answer. Contract *facts* are the opposite: those you resolve fully and inline. -5. Collect everything in ONE pass — the whole point is that you never have to rediscover a contract mid-coding. +4. Map each in-scope step to the companion skill that governs it, as a trap note (format in §3 below). + +#### Prerequisites -#### Prerequisites you can run alongside +**Reach the SDK source before you start the planner** (per `dotnet-getting-started`) — the map lives inside it, so this comes before any map work, and the planner reads the copy you reached rather than reaching its own. -These need no SDK knowledge and touch no project file, so do them before or alongside the map work: +The rest need no SDK knowledge and touch no project file, so do them while the planner works — or alongside your own map work, if you are writing the plan yourself: -- reaching the SDK source (per `dotnet-getting-started` — the map lives inside it, so this comes before any map work); - the repo survey (read-only exploration of conventions and layering) — record each convention as *pattern + the ONE exemplar file path to imitate*, NOT inline code snippets: you will read the exemplar at edit time anyway, so a snippet dump gets paid for twice; - `dotnet restore` and a baseline `dotnet build` / `dotnet test` of the UNTOUCHED solution, so later failures are attributable to your changes; - locating the SDK reference and its version in the project; - credentials/environment verification (per the task's secret-handling rules); - setting up your task tracking. -Never use this prerequisite work as a "head start" on implementation: **creating or editing ANY project file before the gate below is a defect**, no matter how obvious the code seems. - #### HARD GATE -**No project-file creation or edits until `spotify-web-api-plan.md` exists at that path with every section below filled in.** Starting to code before the sheet exists defeats the plan-first design: the sheet is what keeps SDK facts out of your memory and in the map. The gate bars coding before the sheet exists; it does not bar the read-only prerequisite work above. +**No project-file creation or edits until the planner has RETURNED, `spotify-web-api-plan.md` EXISTS at the path you dictated (check it — a helper can misreport where it saved), every section below is filled in, and you have read it.** If you wrote the plan yourself, the gate is the file existing at that path with every section filled in. The read-only prerequisites above are allowed; using them as a "head start" on code is a defect, however obvious the code seems. #### The `spotify-web-api-plan.md` format (keep it tight — tables, not prose) @@ -68,28 +79,26 @@ The CONTRACT SHEET also carries a **CROSS-OPERATION INVARIANTS** table, directly **Enforced where** names the member that checks, before the write, that the caller's value is in that set. If the application never reads that set, say so there and add the read — the check is part of the work. `YOUR CALL — not in the map` is not a legal entry in any cell of this table. -3. **Trap notes** — one line per hazard, attached to the step where it bites, each ending in an inline **`MUST load `** pointer. Name the hazard and its consequence; do not resolve it. ⚠⚠ **"Do not resolve it" is the load-bearing half of this rule.** A trap note that answers its own question hands you a usable one-liner — and holding one, you do not open the skill. You implement from the sentence, and everything the skill carries beyond it never reaches the code. So: state the hazard, state what it costs, hand over the skill, and stop. No fix, no snippet, not even a partial answer. A trap note from which you could write correct code without loading the named skill is a defect. -4. **REQUIRED READING** — close the sheet with the de-duplicated list of every `dotnet-*` skill named above, one line each: skill · the step it governs. Write each name so the copy is unambiguous — every APIMatic .NET plugin ships these same skill names, and a bare name gives you no way to tell which one you loaded. State that these are to be loaded **before implementation starts**, and that the sheet deliberately does not carry their contents. This block is mandatory even when the trap notes are few — an integration always writes an error boundary, so `dotnet-error-handling` always appears here. Always include, verbatim, this hazard row: a body that does not match its declared type — a drifted or malformed **2xx** response (a missing `required` member) or a **non-2xx** body that does not match its operation's generated `{Operation}Error` shape — surfaces as `ResponseDeserializationException`, an `ApiException` that keeps the HTTP status and names the target type but is **not** an `ApiException`; a catch ladder that handles only `ApiException` lets it escape, so it must also catch `ResponseDeserializationException` (or `ApiException`). -5. **PRODUCTION READINESS** — the fixed table below, every row carrying a *decision*. Naming a skill in REQUIRED READING does not address a concern; it defers it. `N/A` is a legitimate answer where it is genuinely true, but it must carry its reason. +3. **Trap notes** — one line per hazard, attached to the step where it bites, each ending in an inline **`MUST load `** pointer. State the hazard and what it costs, never the answer — no fix, no snippet, not even a companion default you believe correct: "what `Timeout` actually bounds" is a trap note, "`Timeout` is per-attempt" is not. A trap note from which you could write correct code without loading the named skill is a defect. Contract *facts* are the opposite: resolve those fully and inline. +4. **REQUIRED READING** — close the sheet with the de-duplicated list of every `dotnet-*` skill named above, one line each: skill · the step it governs, each name plugin-qualified (every APIMatic .NET plugin ships these same names), all to be loaded **before implementation starts**. It always lists `dotnet-error-handling`, even when the trap notes are few, and always carries, verbatim, this hazard row: a body that does not match its declared type — a drifted or malformed **2xx** response (a missing `required` member) or a **non-2xx** body that does not match its operation's generated `{Operation}Error` shape — surfaces as `ResponseDeserializationException`, an `ApiException` that keeps the HTTP status and names the target type but is **not** an `ApiException`; a catch ladder that handles only `ApiException` lets it escape, so it must also catch `ResponseDeserializationException` (or `ApiException`). +5. **PRODUCTION READINESS** — the fixed table below, every row recording a *decision*, or `N/A` with its reason where that is genuinely true. A row that only names a skill — even one in REQUIRED READING — restates the concern, or sits blank is **not addressed**. 6. **Assumptions & Blockers** — anything you had to assume about the user's intent, and anything that blocks planning. An empty section is a valid outcome; an invented fact is not. If you expect the provider to reject a call the plan makes, that is a **Blocker**. -7. Every row's **source** cell cites its map page or the map-named declaring file, so a later lookup is one targeted open, not a search. A row with neither to cite is not a contract fact: write `YOUR CALL — not in the map` there instead. Three labels, one order — a fact the map settles cites that page or file; a fact only live traffic can settle is `UNVERIFIED`; a decision about the application is `YOUR CALL — not in the map`. Something that stops you planning goes in §6. +7. **Source labels** — every row's **source** cell is one of: the map page or map-named file it came from (so a later lookup is one targeted open); `UNVERIFIED` (only live traffic can settle it); `YOUR CALL — not in the map` (a decision about the application). Something that stops you planning goes in §6. | # | Concern | The decision the plan must record | | --- | --- | --- | -| 1 | **Credential fail-fast** | Where credentials are bound, and that the host refuses to start when one is missing or blank — rather than discovering it as a 401 on the first call in production. A multi-part credential needs **every** part checked, because a blank part is not a missing one. | +| 1 | **Credential fail-fast** | Where credentials are bound — code, the SDK's own environment variables, a provider or `IConfiguration` — and that the host refuses to start when one is missing or blank, rather than discovering it as an `AuthSchemeException` on the first call in production. The check follows the source: the SDK's variable itself when that supplies the credential, the provider's own source when a provider does. A multi-part credential needs **every** part checked, because a blank part is not a missing one. | | 2 | **Secret sourcing & rotation** | Where the secret comes from, and that the DI registration builds the options object **once at registration** and captures it in the singleton — so a rotated secret does not take effect until the process restarts. If rotation without a restart is required, say how. | -| 3 | **Total timeout budget** | The number the caller actually gets, not the knob. `Timeout` is **per attempt**, so a hung retryable call costs a multiple of it. State the budget and where it is enforced — a `CancellationToken` deadline is the only thing that bounds a whole call. | -| 4 | **Write-retry ownership** | Which of the scope's writes the SDK may resend and which it may not. The default `HttpMethodsToRetry` covers `GET, HEAD, PUT, OPTIONS`, so `POST`/`PATCH`/`DELETE` are never resent by the SDK — and `PUT` **is**. | -| 5 | **Idempotency & ambiguous writes** | For each write in scope: the key it uses, or that none exists. Whether an operation takes a REAL caller-supplied key — and its member name — is on that operation's request record: the record file its map row's **Type sources** table names. The generator-injected `Idempotency-Key` header (`Guid.NewGuid()`, fresh on every call) is **not** a key and must not be cited as one. Where no key exists, record the reconciliation path instead. | -| 6 | **Observability** | What is logged at which level, that **JSON request bodies are logged unredacted** when `LogRequestBody` is on, and which correlation id from the provider's error bodies reaches your own logs. | -| 7 | **Sensitive data** | Whether the scope carries data you would not want in a log — each request model's declaring file lists every field in scope. If it does: `LogRequestBody` stays off **and** `LoggerFactory` is assigned explicitly, so the SDK's log environment variable cannot switch it on from outside the code (see `dotnet-getting-started`). Form bodies are masked only by deny-list, so a key you have not listed prints in the clear. | +| 3 | **Total timeout budget** | The number the caller actually gets, not the knob — state the budget and where it is enforced. What `Timeout` bounds, and what bounds a whole call: `dotnet-configuration-resilience`. | +| 4 | **Write-retry ownership** | Which of the scope's writes the SDK may resend and which it may not — the retried verbs are under *Retries* in `dotnet-configuration-resilience`. | +| 5 | **Idempotency & ambiguous writes** | For each write in scope: its real key — a member of its request record (*Idempotency* in `dotnet-getting-started`) — or that none exists, and then its reconciliation path. The `Idempotency-Key` header every non-GET call sends is **not** a key and must not be cited as one. | +| 6 | **Observability** | What is logged at which level, and which correlation id from the provider's error bodies reaches your own logs. | +| 7 | **Sensitive data** | Whether the scope carries data you would not want in a log (*Sensitive data* in `dotnet-getting-started`). If it does: `LogRequestBody` off, `LoggerFactory` assigned explicitly, and every sensitive form-body key added to the deny-list. | | 8 | **Environment selection** | Which base URLs each deployment talks to. Enumerate the server groups and environment members from the map's *Servers & auth* section — there may be more than one group, and each operation resolves through its own. State which groups the scope touches and what each deployment sets; if the SDK declares no sandbox environment, say how test traffic is kept away from the live system. | | 9 | **Duplicate prevention under concurrency** | For each write a caller can trigger twice: its row in **DUPLICATE CLAIMS** below. If this codebase has nowhere to keep a claim that outlives the process, that is a Blocker in §6, not a row. | | 10 | **Partial results** | For each paged read that can stop at a cap: the field or return type that tells the caller the result was cut short. | | 11 | **Unknown outcomes** | For each write whose connection can fail after the provider may have acted: how the code settles the outcome instead of reporting a failure. | -A reviewer grades that table alone: each row either records a decision or records why it does not apply. A row that points at a skill, restates the concern, or sits blank is **not addressed**. Rows 5, 7, 8, 9 and 11 are the ones where "not addressed" costs something that cannot be recovered afterwards — a duplicate charge or duplicate write, sensitive data in a log, or test traffic sent to a live system. - **DUPLICATE CLAIMS** — one row per write a caller can trigger twice; `none` if the task has no such write. | Write | Where the claim is stored | What rejects the second one | Where that rejection is caught | Where in the code | @@ -125,36 +134,35 @@ Keep the file lean: no copied map pages, no full model dumps, and no clone path ### Step 2 — Required reading (do this before you write any code) -The contract sheet ends with a **REQUIRED READING** block, and its rows carry inline `MUST load ` pointers. **Load every `dotnet-*` skill the sheet names, now, before you start implementing** — not lazily at the step that needs it. The sheet deliberately does *not* carry the how-to: it names the hazard and hands you the skill that resolves it, so an unloaded pointer is a gap in what you know, not a formality. If the sheet names none, load `dotnet-error-handling` anyway — every integration writes an error boundary. - -These are API-agnostic usage skills; loading them is not the same as reading the map. Contract *facts* still come only from the sheet or a map lookup. +The contract sheet ends with a **REQUIRED READING** block, and its rows carry inline `MUST load ` pointers. **Load every `dotnet-*` skill the sheet names, now, before you start implementing** — not lazily at the step that needs it; the sheet names hazards, not their answers. If the sheet names none, load `dotnet-error-handling` anyway — every integration writes an error boundary. Before implementing, check the plan's **Assumptions & Blockers** section: -- Blocker or major assumption → surface it to the user in plain language, get their answer, then revise `spotify-web-api-plan.md` in place with targeted edits — edit the changed rows, append the new section. Rewriting the whole file to change a few rows is a defect. +- Blocker or major assumption → surface it to the user in plain language, get their answer, and send it to the SAME planner as a follow-up message (re-start it, carrying the clarification and the plan path, only where your host cannot message it). It revises `spotify-web-api-plan.md` in place and replies with the changed rows verbatim: work from that reply, not a re-read of the file. If you wrote the plan yourself, revise it in place with targeted edits — edit the changed rows, append the new section. Rewriting the whole file to change a few rows is a defect. - Minor assumptions only → proceed. Full re-planning only on genuine scope change; for a single missing fact mid-implementation, look it up in the map — never guess. ### Step 3 — Implement from the contract sheet -1. Read `spotify-web-api-plan.md` once. Treat its contracts as authoritative — do not re-derive or "double-check" them from memory. A row whose source column says `YOUR CALL — not in the map` is the one exception: that row is a planning-time judgment about YOUR application, so weigh it against the task and follow the task. -2. Implement sequentially, following the repo's own conventions and layering. You loaded the companion skills the sheet named in Step 2 — implement each step in line with the one that governs it. Take every contract *fact* (signatures, wire names, error accessors, enum values) from the contract sheet or a map lookup — never re-derive one from a companion. +1. Read `spotify-web-api-plan.md` once and treat its contracts as authoritative — never re-derive or "double-check" one from memory; re-open the map page a row cites. Only a `YOUR CALL — not in the map` row is weighed against the task, and the task wins. +2. Implement sequentially, following the repo's own conventions and layering, each step in line with the companion that governs it. Take every contract *fact* (signatures, wire names, error accessors, enum values) from the contract sheet or a map lookup — never from memory or a companion. 3. After every change: `dotnet build`; fix non-SDK errors yourself. -4. **Any compile or runtime error involving an SDK type or member** (`CS1061`, `CS0117`, `CS0234`, `CS0104`, `CS1503`, `CS7036`, … on `SpotifyWebApi.*`, or a provider error at runtime) → *Step 4* below. Do not attempt more than one self-fix of an SDK-name error before switching to that procedure — rewriting from the same knowledge that produced the error is guessing. +4. **Any compile or runtime error involving an SDK type or member** → *Step 4* below, after at most one self-fix. 5. Once the code is complete, open each member the **DUPLICATE CLAIMS** and **UNKNOWN OUTCOMES** rows name and confirm it runs when that write runs. Where the code falls short of a row, fix the code, not the row. -6. Run the project's tests (`dotnet test`); verify the integration end to end the way the task demands. +6. Then settle every `YOUR CALL — not in the map` entry in `spotify-web-api-plan.md`: overwrite the marker where it stands, in its row or in **Assumptions & Blockers**, with the decision the code made and the member that implements it, so no entry is left open. Never gather the decisions in a section of their own. Name each one in your final report. A `YOUR CALL` left in the plan is a decision nobody recorded; one the report leaves out is a decision the user never saw. +7. Run the project's tests (`dotnet test`); verify the integration end to end the way the task demands. ### Step 4 — Fixing SDK errors (map-first, in place) -A compile or runtime error involving an SDK type or member (`CS1061`, `CS0117`, `CS0234`, `CS0104`, `CS1503`, `CS7036`, … on `SpotifyWebApi.*`, or a provider error). Resolve it map-first — never patch it by guessing. Load `dotnet-getting-started` first if you have not already — the map is where every fix below comes from. +A compile or runtime error involving an SDK type or member (`CS1061`, `CS0117`, `CS0234`, `CS0104`, `CS1503`, `CS7036`, … on `SpotifyWebApi.*`, or a provider error). Resolve it map-first — load `dotnet-getting-started` first if you have not already — never by guessing. -1. **Map lookup first.** For an operation symbol, find its block on the controller's operations page; for a model, enum, error or request-record symbol, open the declaring file — its name is its path (`src/SpotifyWebApi/Models/{Type}.cs`, `src/SpotifyWebApi/Models/Enums/{Type}.cs`, `src/SpotifyWebApi/Errors/{Type}.cs`, `src/SpotifyWebApi/Requests/{Type}.cs`, or `src/SpotifyWebApi/Requests/{Controller}/{Type}.cs` for an operation on a controller — an operation with several tags is filed under the first tag it declares), or take it from the operation's Type sources table. If the code contradicts what you read (wrong field name, missed response envelope, wrong param order, wrong namespace), that is the fix. Response envelopes are the classic case: response types often wrap their payload in one field — reads go one level down. +1. **Map lookup first.** For an operation symbol, find its block on the controller's operations page; for a model, enum, error or request-record symbol, open the declaring file — its name is its path (the layout in `dotnet-getting-started`'s *SDK source* section), or take it from the operation's Type sources table. If the code contradicts what you read (wrong field name, missed response envelope, wrong param order, wrong namespace), that is the fix. Response envelopes are the classic case: response types often wrap their payload in one field — reads go one level down. 2. **Go one level deeper on a real gap.** If what you read matches the code, or ambiguity remains, open the operation's own method in the `Api/{Controller}.cs` file the page header names — its `` docs and the request it builds — and the per-member docs on its request record, in this session's SDK clone, scoped. Never scan the tree. -3. **Never re-guess.** Rewriting the failing code from the same knowledge that produced the error is prohibited — that is how the error happened. Each failing symbol gets a map/source-grounded answer before its line changes; never mutate payloads, field names, or status handling speculatively to "see if it works". +3. **Never re-guess** from the knowledge that produced the error: each failing symbol gets a map/source-grounded answer before its line changes; never mutate payloads, field names, or status handling speculatively to "see if it works". 4. **Fix in place** — edit only the project files involved in the error, grounded in the map row (or the named source file). 5. **Build to verify, and classify the outcome:** compiles clean → run `dotnet test` on the touched tests when they exist; compile error → the fix is not done, resolve it the same map-first way and rebuild; build blocked (output locked) → the solution is running, so stop it if you started it, or ask the user to rather than killing their process. -6. **Runtime / provider errors** — read the provider's error payload through the documented path: the operation's error case and `TryGet…` accessors from its map row; `dotnet-error-handling` for the Case A/B mechanics. Config-shaped failures (401, wrong host, timeouts): check auth, the server-node/base-URL configuration, and retry semantics before touching call sites. +6. **Runtime / provider errors** — read the provider's error payload through the documented path: the operation's error case and `TryGet…` accessors from its map row; `dotnet-error-handling` for the Case A/B mechanics. Config-shaped failures (`AuthSchemeException`, 401, wrong host, timeouts): check auth, the server-node/base-URL configuration, and retry semantics before touching call sites. If a fix corrects a row in `spotify-web-api-plan.md`, correct the row in the file too — the sheet stays the record of what was verified. @@ -164,10 +172,8 @@ A standalone Spotify Web API question with no code change: load `dotnet-getting- ## Anti-patterns — never do these +- **Never create or edit a project file while `spotify-web-api-planner` is running**, and never start a second one for the same integration. - **Never write a Spotify Web API/SDK fact from memory** — every signature, field name, enum value, and error type in your code must come from the contract sheet or a map lookup. And **never write a call from memory "to fix later".** -- **Do not re-derive or double-check a sheet row from memory** — re-open the one map page it cites. -- **Do not re-derive a contract fact from a `dotnet-*` companion** — they are usage guidance; facts come from the map. - **Do not grep, glob or `find` the SDK tree, and do not open its `api-reference.md`** — the map is the locator; `dotnet-getting-started` says why. - **Do not web-search Spotify Web API for an implementation detail** — the map and the SDK source it lives in are the ground truth for THIS SDK version, and `SpotifyWebApi` is what the generated source declares, not what public docs describe. -- **Do not resolve a trap note inline on the sheet** — name the hazard and the skill. diff --git a/plugins/spotify/skills/dotnet/dotnet-models/SKILL.md b/plugins/spotify/skills/dotnet/dotnet-models/SKILL.md index c426a34b..146ebd6f 100644 --- a/plugins/spotify/skills/dotnet/dotnet-models/SKILL.md +++ b/plugins/spotify/skills/dotnet/dotnet-models/SKILL.md @@ -1,6 +1,6 @@ --- name: dotnet-models -description: Working with models in an APIMatic-generated .NET SDK in C# — building request models, required members and nullability, enums, union/AnyOf accessors, and JSON wire names versus C# property names. Load before constructing request payloads or mapping SDK models onto your own domain types. +description: Load before building request payloads for an APIMatic .NET SDK in C# or mapping its models onto your own types — required members and nullability, OneOf/AnyOf unions, open enums, dates, collections, validation attributes, JSON wire names versus C# property names, and unknown fields. --- # Working with models in an APIMatic .NET SDK @@ -17,19 +17,24 @@ installed package. When a field can be one of several types, APIMatic generates a union `record` (under `{RootNamespace}.Models.OneOf` or `.Models.AnyOf`). Build these with the generated **static factory -methods** (one per variant) and read them back with **`TryGet…` methods** — a union has no -object-initializer. JSON (de)serialization is automatic. +methods** (one per variant) and read them back with **`TryGet…` methods** or branch over every variant +with **`Match`** — a union has no object-initializer, and the `Optional` backing each variant is +internal, so the factories, `TryGet…` and `Match` are the whole surface. JSON (de)serialization is +automatic. - `OneOf` — the value is exactly one variant, selected on the wire by a **discriminator property** (e.g. `type`). The generated converter reads that property and switches on it. - `AnyOf` — no discriminator; the converter **tries each variant's schema in declaration order** and takes the first that deserializes. -⚠ **A payload matching no variant throws.** Both converters end in -`throw new JsonException("JSON does not match … schemas: …")`, raised mid-deserialization of the response — -you do not get a null union or an unset variant. A provider that adds a variant your SDK predates turns -into a `JsonException` on a call that was previously fine, so a union field is a place to expect -regeneration pressure. See `dotnet-error-handling` for where that surfaces in a catch ladder. +⚠ **A payload matching no variant does not throw** — it lands in the union's **Unknown** slot as the raw +`JsonElement`: `TryGetUnknown(out var raw)` returns `true`, every `TryGet{Variant}` returns `false`, and +the value serializes back verbatim. A variant the provider adds after your SDK was generated therefore does +not break the call; your code decides what to do with it. A `OneOf` whose discriminator property is missing +or not a string still throws, and so does a known discriminator value whose body does not fit that variant +(a missing required member or a wrong-typed value); both reach your catch as +`ResponseDeserializationException` (see `dotnet-error-handling`). You cannot build an Unknown value +yourself: its factory is not public. ### Construct @@ -43,49 +48,62 @@ var u2 = {Union}.{Variant}(new {Variant} { /* ... */ }); {Union} u4 = new {Variant} { /* ... */ }; // same as {Union}.{Variant}(...) ``` -**A `OneOf`'s variants are always model or enum references** — the generator builds them from the schema's -discriminator mappings, so a `OneOf` has no primitive, list or map variant at all, and every variant it does -have gets an implicit conversion. An `AnyOf` is the open one: primitives and models get a conversion, while -list, map and untyped-object variants do not, and neither do two variants that share one CLR type (the -operators would collide). The factory is the form that always exists — reach for the implicit conversion -only where you can see one. +**A `OneOf`'s variants are always model or enum references** — it has no primitive, list or map variant, and +every variant gets an implicit conversion. On an `AnyOf`, primitive and model variants get one; list, map and +untyped-object variants do not, and neither do two variants that share one CLR type. The factory always +exists — reach for the implicit conversion only where you can see one. ### Read / unwrap ```csharp -// Each variant has a bool TryGet{Variant}(out var value). The member name comes from the -// variant's SCHEMA type, not its CLR type — a `decimal` variant reads TryGetBigDecimal: +// Each variant has a bool TryGet{Variant}([NotNullWhen(true)] out T? value), a bare out T for a +// value type. The member name comes from the variant's SCHEMA type, not its CLR type — a `decimal` +// variant reads TryGetBigDecimal: if (u1.TryGetString(out var s)) { /* use s (string) */ } else if (u1.TryGetBigDecimal(out var d)) { /* use d (decimal) */ } // OneOf: branch over the variants you expect if (resp.{Field}.TryGet{Variant}(out var v)) { /* ... */ } else if (resp.{Field}.TryGet{OtherVariant}(out var w)) { /* ... */ } + +// Match: one on{Variant} handler per variant, in the order the union declares them, then otherwise, +// which receives the raw JsonElement of a value the SDK could not place. +// The Func overload returns a value; the Action overload (same handler names) runs a side effect. +var result = resp.{Field}.Match( + on{Variant}: v => Handle(v), + on{OtherVariant}: w => HandleOther(w), + otherwise: raw => HandleUnrecognised(raw)); ``` +Every `Match` handler is required, `otherwise` included, so a variant you leave out is a compile error — +unlike a `TryGet` chain, whose last `else` the compiler never checks and which silently drops an Unknown +value. Pass the handlers **by name**: a regenerated SDK whose spec adds or reorders a variant changes the +`Match` signature, and two variants of one CLR type (`onString` / `onEmailString`) would swap silently at +a positional call site. When you read with `TryGet…` instead, end the chain with +`TryGetUnknown(out var raw)` or an `else`, so an unrecognised value is handled on purpose. + The factory and `TryGet` names are built from the **variant's schema type name, which is often not its CLR type name** — this is the single easiest thing to get wrong when writing a union branch from memory: | Variant | Factory method | Reader | | --- | --- | --- | -| a model `{Variant}` | `.{Variant}({Variant})` | `TryGet{Variant}(out {Variant})` | -| a big-decimal (CLR `decimal`) | `.BigDecimal(decimal)` | `TryGetBigDecimal(out decimal)` | -| a UUID (CLR `Guid`) | `.Guid(Guid)` | `TryGetGuid(out Guid)` | -| a date-time (CLR `DateTimeOffset`) | `.DateTime(DateTimeOffset)` | `TryGetDateTime(out DateTimeOffset)` | -| a date (**also** CLR `DateTimeOffset`) | `.Date(DateTimeOffset)` | `TryGetDate(out DateTimeOffset)` | -| an email / uri / ip (all CLR `string`) | `.EmailString(...)` / `.UriString(...)` / `.IpString(...)` | `TryGetEmailString(...)`, … | -| a list of `{Variant}` | `.ListOf{Variant}(IReadOnlyList<{Variant}>)` | `TryGetListOf{Variant}(out IReadOnlyList<{Variant}>)` | -| a map of `{Variant}` | `.MapOf{Variant}(...)` | `TryGetMapOf{Variant}(out …)` | - -So a `decimal` variant is `TryGetBigDecimal`, never `TryGetDecimal`; three variants that are all CLR -`string` get three different names; and a `DateTimeOffset` variant is `TryGetDateTime` **or** `TryGetDate` -depending on which the definition declared — two members, one CLR type, and the C# signature cannot tell -them apart. Where two variants would collide outright the generator suffixes them (`String`, `String2`). -The primitive rows apply to `AnyOf` only, since a `OneOf` has no primitive variants. **Take the exact member -name from the contract sheet** (grounded from the SDK map/source) rather than deriving it from -the C# type you see. (Unions use the per-variant factories and `TryGet…` readers shown above; -`TryGetKnownValue` belongs to enums.) The `Optional` backing a union is internal — interact only through the factories and -`TryGet…`. +| a model `{Variant}` | `.{Variant}({Variant})` | `TryGet{Variant}([NotNullWhen(true)] out {Variant}? value)` | +| a big-decimal (CLR `decimal`) | `.BigDecimal(decimal)` | `TryGetBigDecimal(out decimal value)` | +| a UUID (CLR `Guid`) | `.Guid(Guid)` | `TryGetGuid(out Guid value)` | +| a date-time (CLR `DateTimeOffset`) | `.DateTime(DateTimeOffset)` | `TryGetDateTime(out DateTimeOffset value)` | +| a date (**also** CLR `DateTimeOffset`) | `.Date(DateTimeOffset)` | `TryGetDate(out DateTimeOffset value)` | +| an email / uri / ip (all CLR `string`) | `.EmailString(...)` / `.UriString(...)` / `.IpString(...)` | `TryGetEmailString([NotNullWhen(true)] out string? value)`, … | +| a list of `{Variant}` | `.ListOf{Variant}(IReadOnlyList<{Variant}>)` | `TryGetListOf{Variant}([NotNullWhen(true)] out IReadOnlyList<{Variant}>? value)` | +| a map of `{Variant}` | `.MapOf{Variant}(...)` | `TryGetMapOf{Variant}([NotNullWhen(true)] out IReadOnlyDictionary? value)` | + +A reference-type reader is `[NotNullWhen(true)] out T?`: `out var` infers `T?`, and the compiler narrows it to +`T` inside the `if`; outside the check the value may be null. A value-type reader stays a bare `out T`. + +The primitive rows apply to `AnyOf` only. Two variants that would collide outright are suffixed (`String`, +`String2`); a variant named `Unknown`, or named like its own union, takes a `Variant` suffix +(`UnknownVariant`). Each row's `Match` handler is `on` + its factory name (`onBigDecimal`, `onEmailString`, +`onListOf{Variant}`). **Take the exact member name from the contract sheet** (grounded from the SDK +map/source) rather than deriving it from the C# type you see. ## Collections @@ -109,21 +127,16 @@ never a cast to `Dictionary`. ## Dates & numbers -- **A date/time field is not necessarily a `DateTimeOffset?` — check the property type.** The generator - emits `DateTimeOffset?` only where the API definition marks the field as a date/time. Where it does not, - the field is a plain `string?`, frequently carrying a `[RegularExpression]` attribute that *documents* an - RFC-3339 shape without enforcing it (see below). Both are common in the same SDK, and one of the sampled - SDKs has **no** `DateTimeOffset` in its models at all. Take the type from the contract sheet; a - `DateTimeOffset.Parse` written against a field that is already a `DateTimeOffset` will not compile, and a - hand-built string written into a `DateTimeOffset?` field will not either. -- **A `DateTimeOffset` model property carries no converter** — it round-trips as `System.Text.Json`'s - default, ISO-8601 with an offset (`"2024-06-17T15:30:45+00:00"`), *even where the API documents a - date-only shape*. The generator does ship four date converters (ISO-8601, RFC-1123, Unix epoch seconds, - date-only), but it attaches them to **whole-response payloads** — an operation whose response body is a - date scalar, or a list or map of them — not to properties inside a model. So if a field's documented wire shape is `YYYY-MM-DD` and - the property is a `DateTimeOffset?`, what the SDK sends is the full ISO-8601 form, and reconciling that - with the provider is your problem, not the SDK's. Do not hand-format anyway; for your own formatting use - the BCL (`DateTimeOffset.Parse`, `.ToString("O")`), never the SDK's internal converters. +- **A date/time field is not necessarily a `DateTimeOffset?` — check the property type.** It can be a + plain `string?`, often with a `[RegularExpression]` that *documents* an RFC-3339 shape without enforcing it + (see below); both occur in one SDK, and some SDKs have no `DateTimeOffset` at all. Take the type from the + contract sheet: `DateTimeOffset.Parse` against a field that is already a `DateTimeOffset` will not compile, + nor will a hand-built string written into a `DateTimeOffset?` field. +- **A `DateTimeOffset` model property round-trips as `System.Text.Json`'s default**, ISO-8601 with an offset + (`"2024-06-17T15:30:45+00:00"`), *even where the API documents a date-only shape* — a field documented as + `YYYY-MM-DD` is sent in the full form, and reconciling that with the provider is yours. Do not + hand-format it; for your own formatting use the BCL (`DateTimeOffset.Parse`, `.ToString("O")`), never the + SDK's internal converters. - Money/quantities may be `string`, `decimal`, or a string-or-number `AnyOf` union; the model's property type is the source of truth. Numeric types vary per SDK (`int`, `long`, `double`, …) — take the exact type from the contract sheet; don't assume `double`. @@ -164,13 +177,13 @@ enums. Use the static constants; they convert implicitly to their underlying val (or the implicit conversion) yields the raw wire value — but **not** `ToString()`, see the warning below — and `==` compares by value, so two instances read from the same wire value are equal. -There is **no public factory**: `{EnumType}.FromValue(...)` does not exist, and a value the spec does not -declare cannot be constructed in code. Resolve a raw value with `{EnumType}.TryGetKnownValue(value, out var +There is **no public factory**: `{EnumType}.FromValue(...)` does not exist, and an undeclared value cannot +be constructed in code. Resolve a raw value with `{EnumType}.TryGetKnownValue(value, out var known)` — exact, case-sensitive — and guard a received value with `instance.IsKnownValue()`. A server value the SDK does not declare still deserializes (enums are open on reads), round-trips unchanged with the server's own casing, and compares without constructing one: `instance.Is("raw")` or `instance == "raw"`. -Branch with the generated `Match`, not a `switch`: one `on{Member}` arm per declared value in spec order, +Branch with the generated `Match`, not a `switch`: one `on{Member}` arm per declared value in declaration order, then `otherwise`, which receives the raw wire value of anything undeclared. Pass the arms by name — the parameters are positional, and a regenerated SDK that adds or reorders a value changes the signature (a source break, and `MissingMethodException` for an assembly compiled against the old shape). @@ -212,18 +225,17 @@ See [reference.md](reference.md) for full string- and int-enum declarations and Models declare their wire properties explicitly. An object or allOf model also carries a `[JsonExtensionData]` bag — `public AdditionalProperties AdditionalProperties { get; init; } = [];` -(`{RootNamespace}.Core.Models`) — so unknown JSON fields are **kept**, not dropped: a field the provider -added after this SDK was generated survives deserialization and round-trips back out on serialize. A -schema with `additionalProperties: false` has no bag, a `OneOf`/`AnyOf` union has none of its own, and the -bag is named `AdditionalProperties2` when a spec property's C# name is already `AdditionalProperties`. -Take the bag's name and type from the contract sheet. +(`{RootNamespace}.Core.Models`) — so unknown JSON fields are **kept**: a field this SDK does not model +survives deserialization and round-trips back out on serialize. A model that admits no extra fields has no +bag and drops them, a `OneOf`/`AnyOf` union has none of its own, and the bag is named `AdditionalProperties2` +when the model already has an `AdditionalProperties` property. Take the bag's name and type from the contract +sheet. Read one with `response.AdditionalProperties.TryGetValue("field_name", out var value)` (deserializes the captured `JsonElement` to `T`), or `TryGetElement` for the raw `JsonElement`; `Set(key, value)` adds -one to a request. When the schema types its extra fields, the bag is `AdditionalProperties`, whose -`TryGetValue("field_name", out var value)` takes no type argument. -Two cautions: the keys are **wire names** (there is no C# property, so nothing maps the -casing for you), and a field appearing here rather than as a typed property is a regeneration signal — -prefer regenerating the SDK over building program logic on stringly-typed lookups. The -bag itself has no `[JsonPropertyName]` and no wire name — its contents merge -into the model's own JSON object. +one to a request. When every extra field has one type, the bag is `AdditionalProperties`, whose +`TryGetValue("field_name", out var value)` takes no type argument. Two cautions: the keys are **wire names** +(there is no C# property, so nothing maps the casing for you), and a field appearing here rather than as a +typed property is one this SDK version does not type — prefer an SDK version that does over building +program logic on stringly-typed lookups. The bag itself has no `[JsonPropertyName]` and no wire name — its +contents merge into the model's own JSON object. diff --git a/plugins/spotify/skills/dotnet/dotnet-models/reference.md b/plugins/spotify/skills/dotnet/dotnet-models/reference.md index e780a4e6..1147fca3 100644 --- a/plugins/spotify/skills/dotnet/dotnet-models/reference.md +++ b/plugins/spotify/skills/dotnet/dotnet-models/reference.md @@ -1,19 +1,5 @@ # Models reference (APIMatic .NET) -## Date/time - -**Check the property type first.** A date/time field is `DateTimeOffset?` only where the API definition -marks it as a date/time; otherwise it is a plain `string?`, often with a `[RegularExpression]` attribute -documenting (not enforcing) an RFC-3339 shape. Both appear in generated SDKs, and some SDKs contain no -`DateTimeOffset` at all. - -Where it *is* a `DateTimeOffset`, the property carries **no converter attribute** and round-trips as -`System.Text.Json`'s default — ISO-8601 with offset, `"2024-06-17T15:30:45+00:00"` — even where the API -documents a date-only shape. The four generated date converters (ISO-8601, RFC-1123, Unix epoch seconds, -date-only) are attached to whole-response payloads, not to model properties. Work with `DateTimeOffset` -directly and let the SDK serialize it; for formatting in your own code use the BCL -(`DateTimeOffset.Parse`, `.ToString("O")`, …), not the SDK's internal converters. - ## String-enums Every enum — schema enums under `Models/Enums/` and the server-environment enum under `Servers/` — is a @@ -77,22 +63,24 @@ public sealed record {EnumType} : OpenIntEnum<{EnumType}> long n = {EnumType}.On; // implicit conversion to long ``` -Member names come from the spec's `x-enum-varnames` when it declares them, otherwise `Value{n}` / -`Negative{n}` from the value itself. +A member with no declared name is `Value{n}` / `Negative{n}`, from the value itself. ## Union types — finding the exact members For a `OneOf`/`AnyOf` type, the contract sheet lists the exact members (grounded from the SDK map/source). Each variant `{V}` produces: -- a factory `static {Union} {V}({V} value)` (the parameter type usually equals the variant type name), and -- a reader `bool TryGet{V}(out {V} value)`. +- a factory `static {Union} {V}({V} value)` (the parameter type usually equals the variant type name), +- a reader `bool TryGet{V}([NotNullWhen(true)] out {V}? value)` for a reference type, `bool TryGet{V}(out {V} value)` + for a value type, and +- a handler `on{V}` in both `Match` overloads (`Func<{V}, TResult>` / `Action<{V}>`), in declaration order, + before the closing `otherwise` (`Func` / `Action`). + +Every union also has `bool TryGetUnknown(out JsonElement value)` for a value the SDK could not place. Its +factory is internal: application code can read such a value and send it back, but cannot create one. -A `OneOf`'s variants are always model/enum references (they come from the schema's discriminator -mappings), and each gets an `implicit operator {Union}({Variant})`. On an `AnyOf`, primitive and model -variants get one; list, map and untyped-object variants do not, and neither do two variants sharing one CLR -type. Unions are immutable records — there are no object-initializers and no way to mutate -one after construction. +Which variants also get an `implicit operator {Union}({Variant})` is in the SKILL. Unions are immutable +records — there are no object-initializers and no way to mutate one after construction. ## Notes @@ -102,12 +90,3 @@ one after construction. `required` property, which writes `null` when its type is nullable (`public required string? Reason`), and a non-optional property with a default (`public long Priority { get; init; } = 1L;`), whose type cannot hold null. There is no way to send an explicit `null` for an optional property; the difference matters on a PATCH. -- Unless its schema sets `additionalProperties: false`, an object or allOf model ends with a - `[JsonExtensionData]` bag, usually `public AdditionalProperties AdditionalProperties - { get; init; } = [];` — unknown response fields are captured there (keyed by **wire name**) and - round-trip on serialize. See the SKILL's *Unknown / future fields* for the read/write API and the - cautions. On the older 4.0.0 surface this property does not exist and unknown fields are dropped — - check the core-surface stamp before carrying this expectation across SDKs. -- Validation attributes (`[StringLength]`, `[RegularExpression]`, `[MaxLength]`, `[MinLength]`) are - transcribed from the API definition and are **never evaluated by the SDK** — see the SKILL for what to do - about that. diff --git a/plugins/spotify/skills/dotnet/dotnet-testing/SKILL.md b/plugins/spotify/skills/dotnet/dotnet-testing/SKILL.md index 720a21eb..b7b008f0 100644 --- a/plugins/spotify/skills/dotnet/dotnet-testing/SKILL.md +++ b/plugins/spotify/skills/dotnet/dotnet-testing/SKILL.md @@ -1,6 +1,6 @@ --- name: dotnet-testing -description: Testing code that calls an APIMatic-generated .NET SDK in C# — which seam to fake, covering error and edge paths, asserting real behaviour rather than execution, and keeping tests independent of SDK internals. Load before writing tests for the integration layer. +description: Load before writing tests for code that calls an APIMatic .NET SDK in C# — the HttpClient stub seam, error and retry paths, faking the clock, constructing SDK exceptions directly, and asserting the outgoing request. --- # Testing code that uses an APIMatic .NET SDK @@ -57,10 +57,19 @@ static {Api}Client ClientReturning(HttpStatusCode status, string json) { Content = new StringContent(json, System.Text.Encoding.UTF8, "application/json") }); - return new {Api}Client(new HttpClient(handler), new {Api}ClientOptions { /* auth not needed for stubs */ }); + return new {Api}Client(new HttpClient(handler), new {Api}ClientOptions + { + {Credential} = "test-token", // one placeholder per credential the operations under test require + }); } ``` +**Set every credential the operations under test require, even against a stub.** An unset required +credential throws `AuthSchemeException` before the stub sees a request. A value set in code also shields +the test from any `{API}_*` environment variable on the machine — `{API}` being the SDK name in upper snake +case. For an OAuth2 scheme, see *Test a client with OAuth credentials*: the placeholder makes the stub's +first request the token `POST`. + ## Test a success path ```csharp @@ -77,12 +86,9 @@ public async Task ReturnsDeserializedBody() ## Test an error path -Endpoint methods throw `ApiException` on non-2xx (see `dotnet-error-handling`). `TError` is the -operation's `{Operation}Error` model (**Case A**) for operations that have a generated `{Operation}Error` -type, or `RawError` **directly** (**Case B**) otherwise — so assert the type that matches your operation. -Whichever the case, the exception itself carries `StatusCode`, `Headers` and `ContentType` (from -`ApiException`) plus the failed call's `Method` and `RequestUri` (from the `SdkException` root), and its -`Message` is the call and the status — `"POST https://host/path returned 422 (UnprocessableEntity)."`. +Endpoint methods throw `ApiException` on non-2xx — `{Operation}Error` (**Case A**) or `RawError` +(**Case B**); see `dotnet-error-handling` — so assert the type that matches your operation. The exception +carries `StatusCode`, `Headers`, `ContentType`, `Method` and `RequestUri`. **Case A — typed `{Operation}Error`:** @@ -99,17 +105,13 @@ public async Task ThrowsOnApiError() () => client.{ApiGroup}.{Operation}(request, cancellationToken: default)); Assert.Equal(HttpStatusCode.UnprocessableEntity, ex.StatusCode); // the status is on the exception - // ex.Error is the typed ApiError. For a status the operation maps to a typed body (e.g. 422), assert the - // typed accessor — its name embeds the body type; the contract sheet lists the exact accessor name. - // TryGetRawError is FALSE for those statuses, so don't assert through it here: + // Assert the accessor for this status (name from the contract sheet); TryGetRawError is false here. Assert.True(ex.Error.TryGetSomeTypedBody(out var typed)); - // ...assert on 'typed'. TryGetRawError fires ONLY for a status that falls to the error factory's - // default arm. A status with its own RawError accessor — TryGetNoContent, say — populates that - // accessor and leaves TryGetRawError false, so assert the specific one. + // ...assert on 'typed'. } ``` -**Case B — `ApiException`** (e.g. read/list/find/archive/delete operations). Here `ex.Error` *is* +**Case B — `ApiException`.** Here `ex.Error` *is* the `RawError` — there is no `TryGet*` / `TryGetRawError`; read it directly: ```csharp @@ -123,11 +125,11 @@ Assert.Equal(HttpStatusCode.UnprocessableEntity, ex.StatusCode); // same value // You can also assert the deserialized error body: ex.Error.ReadAsString() / ex.Error.ReadAsJson(). ``` -**A body that does not match the model is a third outcome.** Stub a 2xx whose JSON does not fit the -response type — or an error status whose body does not fit the `{Operation}Error` template — and the call -throws `ResponseDeserializationException`: an `ApiException` (so `StatusCode` tells you which of the two it -was) but **not** an `ApiException`, carrying the `TargetType` it tried to build and the -`JsonException` as `InnerException`. Lock this down for any operation whose provider is known to drift: +**A body that does not match the model is a third outcome.** A 2xx whose JSON does not fit the response type, +or an error body that does not fit `{Operation}Error`, throws `ResponseDeserializationException` (see +`dotnet-error-handling`); its `StatusCode` says which. A `OneOf` or `AnyOf` response type is the exception: a +body no variant accepts lands in its Unknown slot (see `dotnet-models`), so assert `TryGetUnknown` there +instead of a throw. Lock it down for any operation whose provider is known to drift: ```csharp var client = ClientReturning(HttpStatusCode.OK, """{ "{resource}": "not-an-object" }"""); @@ -141,9 +143,8 @@ Assert.Equal(typeof({ReturnType}), ex.TargetType); ## Test the result-style (`ApiResult`) variant -If the operation exposes the optional non-throwing `{Operation}Result` sibling (see `dotnet-error-handling`), -there is nothing to catch — stub the response and assert on the returned `ApiResult` -directly. The status code and headers are available on both the success and failure outcomes. +If the operation has a `{Operation}Result` sibling (see `dotnet-error-handling`), there is nothing to catch — +assert on the returned `ApiResult`; status and headers are on both outcomes: ```csharp using {RootNamespace}.Core.Models; // ApiResult @@ -169,22 +170,21 @@ public async Task ResultVariantReportsFailureWithoutThrowing() With OAuth credentials set, the first request your stub sees is the token `POST`. `ClientReturning` answers every request alike, so give `StubHandler` a responder that returns queued responses, a token response such as `{ "access_token": "t", "token_type": "Bearer" }` first. The token is cached, so two calls make three -requests. Or keep the credentials set and give `options.{Scheme}TokenStrategy` a stub that returns -`new OAuthToken { AccessToken = "t", TokenType = "Bearer" }` (for authorization code, an -`OAuthTokenRefreshable`, with `TryRefreshToken` returning `null`), because a strategy without credentials is -never used. Either way, an authorization-code client also needs a `PromptForAuthorizationCode` that returns a -fixed code. -For a bad-credentials test, answer the token request with a 4xx and assert `AuthSchemeException`. +requests. An authorization-code client also needs a `PromptForAuthorizationCode` that returns a fixed code. +A `401` on an authenticated call makes the SDK drop the token, fetch a new one and re-send once, so a stub that +answers `401` sees a second token request and a second call before the `401` reaches the test. +For a bad-credentials test, answer the token request with a 4xx and assert `AuthSchemeException`; for a missing +credential, leave the property unset (and its `{API}_*` environment variable too) and assert +`AuthSchemeException` before any request reaches the stub. ## Fake the clock The SDK reads time through exactly one seam — `{Api}ClientOptions.TimeProvider` (default `TimeProvider.System`). Retry backoff, `Retry-After`, the per-attempt timeout, the SSE idle timeout, OAuth2 -token expiry and the logged request durations all follow it, so one fake provider drives them together and -a retry test no longer sleeps through `1s + 2s + 4s` of real backoff. Use a provider that **implements -timers** — `FakeTimeProvider` from `Microsoft.Extensions.TimeProvider.Testing` — because the retry delay -and the idle window are timers on the provider: a `GetUtcNow`-only fake throws when the SDK asks it for a -timer, which is deliberate and better than a silent real sleep. +token expiry and the logged request durations all follow it, so one fake provider drives them together with +no real sleeps. Use a provider that **implements timers** — `FakeTimeProvider` from +`Microsoft.Extensions.TimeProvider.Testing` — because the retry delay and the idle window are timers on the +provider: a `GetUtcNow`-only fake throws when the SDK asks it for a timer. ```csharp using Microsoft.Extensions.Time.Testing; // FakeTimeProvider (Microsoft.Extensions.TimeProvider.Testing) @@ -192,7 +192,11 @@ using Microsoft.Extensions.Time.Testing; // FakeTimeProvider (Microsoft.Extens var clock = new FakeTimeProvider(); var responses = new Queue([HttpStatusCode.ServiceUnavailable, HttpStatusCode.OK]); var handler = new StubHandler(_ => new HttpResponseMessage(responses.Dequeue()) { Content = new StringContent("{}") }); -var client = new {Api}Client(new HttpClient(handler), new {Api}ClientOptions { TimeProvider = clock }); +var client = new {Api}Client(new HttpClient(handler), new {Api}ClientOptions +{ + {Credential} = "test-token", // as in ClientReturning + TimeProvider = clock, +}); var call = client.{ApiGroup}.{Operation}(request, cancellationToken: default); // a GET: retryable clock.Advance(TimeSpan.FromSeconds(2)); // past the 1s backoff (+ up to 500ms jitter) @@ -202,10 +206,8 @@ Assert.Equal(2, handler.Requests.Count); ``` The awaited call does not complete until the fake clock moves past the backoff — start the call, `Advance`, -then `await`. Under DI, register the fake as the container's `TimeProvider` (before *or* after -`Add{Api}Client` — order does not matter) and the SDK seeds the option from it; an explicit -`o.TimeProvider = clock` in the configure callback wins over the container. The SDK never registers a -`TimeProvider` itself, so nothing of yours is overwritten. +then `await`. Under DI, register the fake as the container's `TimeProvider` (either order) or set +`o.TimeProvider = clock` in the configure callback (see **dotnet-configuration-resilience** § *The clock*). ## Construct an SDK exception directly @@ -250,13 +252,13 @@ Because the stub captures `LastRequest`, you can assert method, path, query, hea ```csharp var handler = new StubHandler(_ => new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent("{}") }); -var client = new {Api}Client(new HttpClient(handler), new {Api}ClientOptions()); +var client = new {Api}Client(new HttpClient(handler), new {Api}ClientOptions { {Credential} = "test-token" }); await client.{ApiGroup}.{Operation}(request, cancellationToken: default); Assert.Equal(HttpMethod.Post, handler.LastRequest!.Method); Assert.Contains("/expected/path", handler.LastRequest!.RequestUri!.AbsolutePath); -Assert.Contains("per_page=20", handler.LastRequest!.RequestUri!.Query); // query params are snake_case on the wire +Assert.Contains("per_page=20", handler.LastRequest!.RequestUri!.Query); // the wire name, not the C# property // Assert the serialized request body of a POST/PUT/PATCH: var sentJson = handler.LastBody; // NOT LastRequest.Content — see below @@ -266,31 +268,23 @@ Assert.Contains("\"expected_field\"", sentJson); ## Notes - ⚠ **Read the request body inside the handler, never off the captured request afterwards.** The SDK - disposes the request content in a `finally` that runs per attempt, *inside* the pipeline — so by the time - your awaited call returns, `handler.LastRequest.Content.ReadAsStringAsync()` throws - `ObjectDisposedException`. That is why the stub above buffers `Bodies` during `SendAsync`. Everything - else on the captured `HttpRequestMessage` — method, URI, headers — survives and can be asserted normally. + disposes the request content after each attempt, so once your awaited call returns, + `handler.LastRequest.Content.ReadAsStringAsync()` throws `ObjectDisposedException` — hence `Bodies` in the + stub above. Method, URI and headers on the captured `HttpRequestMessage` survive and can be asserted. - Mocking libraries (Moq, NSubstitute) work too — mock `HttpMessageHandler.SendAsync` (it's `protected`, so use `Protected()` with Moq). The hand-written stub above avoids that friction. -- A stubbed retryable response — the default set is exactly `408, 429, 500, 502, 503, 504`, not all `5xx` - — on a retryable method will be retried by the SDK before the call returns. `HttpMethodsToRetry` (`GET/HEAD/PUT/OPTIONS` by default) gates **every** trigger, so a - `POST` retries on nothing — not a `503`, not a thrown `HttpRequestException`, not the per-attempt timeout - — unless you add its verb to the list (see `dotnet-configuration-resilience`). To observe retries firing, - stub a `GET` that returns `503` then `200` and count invocations. -- **Status faults and transport faults are separate retry triggers** — the SDK distinguishes them itself - (`RetryAttempt.Reason` is `RetryReason.Status(...)` *or* `RetryReason.Failure(Exception)`), and a third, - the per-attempt timeout, arrives as `RetryReason.Failure(TimeoutRejectedException)`. A test that stubs a - `503` therefore proves nothing about what happens when the *connection* fails. The verb filter holds all - three at one send for a `POST` — which is exactly the property worth locking down with a test, because it - is a *configuration* guarantee and someone widening `HttpMethodsToRetry` for the read path silently - removes it. What reaches the test is the SDK's wrapper, never the raw `HttpRequestException`: a failed - send surfaces as `SdkConnectionException` (message `"POST https://host/path could not be sent: connection - reset"`, the raw exception as `InnerException`), and an exhausted per-attempt timeout as - `SdkTimeoutException` with `Timeout` set to the window that elapsed. +- **Retries run before the call returns.** A stubbed `408`/`429`/`500`/`502`/`503`/`504` (not every `5xx`) on + `GET`/`HEAD`/`PUT`/`OPTIONS` is retried — stub `503` then `200` and count requests; a `POST` is retried on + nothing but an OAuth2 `401`, which every verb re-sends once (see `dotnet-configuration-resilience`). Status and transport faults are separate triggers + (`RetryAttempt.Reason` is `RetryReason.Status(...)` or `RetryReason.Failure(...)`), so a `503` stub proves + nothing about a connection failure — and the one-send `POST` is worth a test, since widening + `HttpMethodsToRetry` silently removes it. A thrown `HttpRequestException` surfaces as + `SdkConnectionException` with the raw exception as `InnerException`, and an exhausted per-attempt timeout + as `SdkTimeoutException`: ```csharp // Transport fault: the stub throws instead of answering, then we count what the server actually received. var handler = new StubHandler(_ => throw new HttpRequestException("connection reset")); - var client = new {Api}Client(new HttpClient(handler), new {Api}ClientOptions()); + var client = new {Api}Client(new HttpClient(handler), new {Api}ClientOptions { {Credential} = "test-token" }); var ex = await Assert.ThrowsAsync( () => client.{ApiGroup}.{Operation}(request, cancellationToken: default)); @@ -298,10 +292,8 @@ Assert.Contains("\"expected_field\"", sentJson); Assert.IsType(ex.InnerException); Assert.Equal(1, handler.Requests.Count(r => r.Method == HttpMethod.Post)); // no resend ``` -- **Your own cancellation is the one thing the SDK never wraps.** A token you cancel surfaces as the usual - `OperationCanceledException` / `TaskCanceledException`, not as an `SdkException` — so a test that cancels - mid-call asserts on the framework type, and a `catch (SdkException)` in the code under test must be - expected *not* to fire. +- **Your own cancellation surfaces as `OperationCanceledException`**, never an `SdkException` — assert the + framework type, and expect a `catch (SdkException)` in the code under test *not* to fire. - For DI-based code, the SDK's `Add{Api}Client` resolves the **default (unnamed)** `IHttpClientFactory` client, so register your stub on that one, then resolve `{Api}Client` from the provider: ```csharp @@ -309,8 +301,6 @@ Assert.Contains("\"expected_field\"", sentJson); services.AddHttpClient(Options.DefaultName).ConfigurePrimaryHttpMessageHandler(() => stubHandler); var client = services.BuildServiceProvider().GetRequiredService<{Api}Client>(); ``` - A `TimeProvider` registered in the same container is picked up by the SDK automatically — see *Fake the - clock* below. - To look up an operation's signature, its request type, or a `{Operation}Error`'s accessor names, take them from the contract sheet (grounded from the SDK map/source) — not a decompiled or reflected view of the installed package, and not memory. diff --git a/plugins/spotify/skills/python/python-authentication/SKILL.md b/plugins/spotify/skills/python/python-authentication/SKILL.md index 87665c39..4b770f4e 100644 --- a/plugins/spotify/skills/python/python-authentication/SKILL.md +++ b/plugins/spotify/skills/python/python-authentication/SKILL.md @@ -1,6 +1,6 @@ --- name: python-authentication -description: Authentication for an APIMatic-generated Python SDK — supplying credentials in typed or dict form, the scheme shapes, the managed OAuth2 token lifecycle and its caching, what a failed token fetch actually raises (and why it bypasses the non-raising response mode), and loading secrets safely. Load before wiring credentials into the client, or when a call fails with 401/403. +description: Load before setting credentials on an APIMatic-generated Python SDK client, or when a call fails with 401/403 or a token fetch fails. Covers each scheme's constructor keyword in typed or dict form — Basic, bearer, API key and the three OAuth2 grants — the managed token lifecycle and caching, composite schemes, what a failed token fetch raises, and loading secrets. --- # Authenticating an APIMatic Python SDK client @@ -16,22 +16,19 @@ dict of the same keys; set the one(s) your API uses, then construct the client ( To see which schemes a specific SDK accepts, read the **credentials keywords on its client constructor** — those are the source of truth (take them from the contract sheet, grounded in the SDK map's constructor-keyword table and its *Servers & auth* section, not from recall). -`{root_package}/auth.py` is the cheap cross-check: -its `AuthSchemes` holder carries exactly one field per declared scheme, and the field names *are* the -constructor keywords. The `{root_package}/core/auth/schemes/` directory ships *every* scheme the -generator supports as shared runtime code regardless of what the API accepts, so never infer a scheme -from that directory. (An SDK whose API uses only OAuth2 client credentials, for instance, exposes a -single `{oauth2}=` keyword and its `{oauth2}_token_source=` override.) +`{root_package}/auth.py` is the cheap cross-check: its `AuthSchemes` holder carries exactly one field +per declared scheme, named as the constructor keyword. Never infer a scheme from +`{root_package}/core/auth/schemes/`: it ships every scheme kind, whatever the API accepts. (An SDK +whose API uses only OAuth2 client credentials, for instance, exposes a single `{oauth2}=` keyword and +its `{oauth2}_token_source=` override.) The credential classes below live under `{root_package}.core` and are the **same across all APIMatic -Python SDKs**; only the **keyword names** are generated per-API — each is the security scheme's id from -the spec, snake_cased (hence the `{...}` placeholders). +Python SDKs**; only the **keyword names** differ per SDK — each is the scheme's id, snake_cased (hence +the `{...}` placeholders). ## The two spellings -Every credential keyword accepts a typed model or a mapping, and they are exactly equivalent — a -`coerce` classmethod is the single place the dict form is resolved, so the two cannot produce different -requests: +Every credential keyword accepts a typed model or a mapping, and the two produce identical requests: ```python from {root_package}.core import ClientCredentials @@ -74,15 +71,14 @@ its discovery document says how a token is obtained, not how it is sent. ## API key (header, query, or cookie) The key is sent as a header, query parameter, or cookie — its placement and name are fixed by the -generated scheme. Set the configured key keyword to your key string: +SDK's scheme. Set the configured key keyword to your key string: ```python client = {Client}({api_key}="API_KEY") ``` A query-placed key is percent-encoded exactly as an endpoint's own query parameter; a cookie-placed key -is sent verbatim, because RFC 6265's `cookie-value` alphabet already admits every character a base64 -key uses and encoding it would corrupt the credential. +is sent verbatim. > **Applies only when the SDK declares an OAuth2 scheme.** The next five sections — the three grants, > the managed token lifecycle, and the token-fetch failure mode — describe machinery that exists only @@ -105,10 +101,9 @@ client = {Client}({oauth2}=ClientCredentials( pre-join it yourself, or you send one scope literally named `"a b"`. Omit it to get whatever the client's default scopes are. -When the flow declares a scope vocabulary, the generator emits a `Literal` alias for it in -`{root_package}/auth.py` (`{Flow}Scope`) and types `scopes` by that alias — so a scope the flow does not -document fails the type check at the call site instead of the request at the provider. A flow that -declares no scopes has no alias, and `scopes` is a plain `list[str] | None`. +Where `{root_package}/auth.py` declares a `{Flow}Scope` `Literal` alias, `scopes` is typed by it — so +a scope the flow does not document fails the type check at the call site instead of the request at the +provider. A flow with no alias takes a plain `list[str] | None`. ## OAuth 2.0 — authorization code (3-legged, with PKCE) @@ -168,20 +163,18 @@ is the part that matters: - **The token is fetched lazily, on the first authenticated call** — not at construction. A client built with bad credentials constructs perfectly happily; the failure surfaces at the first operation. -- The fetch is a `POST` to the token endpoint derived from the client's `base_url`, form-encoded, with - the client id and secret sent per the placement the spec declares — commonly HTTP Basic - (`client_secret_basic`, both halves percent-encoded before base64), otherwise in the form body - (`client_secret_post`). +- The fetch is a form-encoded `POST` to the token endpoint derived from the client's `base_url`, with + the client id and secret sent as HTTP Basic (`client_secret_basic`) or in the form body + (`client_secret_post`), per the scheme. - The resulting token is **cached in memory on the client's auth scheme** and reused across calls, which - is the whole reason a client must be long-lived (`python-client-initialization`). The cache is - double-checked under a lock, so a burst of concurrent first calls pays for **one** fetch. + is the whole reason a client must be long-lived (`python-client-initialization`); a burst of + concurrent first calls pays for **one** fetch. - A token with an `expires_in` is renewed ~30s before expiry (or at half its lifetime, whichever leaves more time, for tokens shorter than a minute). Without an `expires_in` there is no client-side deadline and the token is used until the server rejects it. -- **Refreshing applies only to the authorization-code grant**, whose scheme prefers a refresh over a - re-acquisition — a re-acquisition would run your prompt again. Client-credentials and password - re-acquire instead (RFC 6749 §4.4.3 says the client-credentials grant SHOULD NOT be issued a refresh - token), so the password grant re-sends the resource owner's password at every expiry. +- **Refreshing applies only to the authorization-code grant**, where a re-acquisition would run your + prompt again. Client-credentials and password re-acquire instead, so the password grant re-sends the + resource owner's password at every expiry. - **On a `401`, the cached token is invalidated** so the next call re-authenticates — but **the failing request is not retried**. This is deliberate: the caller sees one `401` and then recovery. Do not write a retry loop *just* for this; do expect that a revoked credential surfaces as exactly one @@ -197,59 +190,41 @@ anything satisfying the token-source protocol: `TokenSource` (`fetch(credentials scheme's cache, which is private. Your source **must not issue a request that itself uses this scheme** — it runs inside that scheme's lock and would deadlock. -## The failure mode that surprises everyone +## A failed token fetch raises `AuthSchemeError` -**A failed token fetch raises the SDK's ordinary API exception — but its payload is a different type -than any operation's.** For a managed-OAuth SDK, the token endpoint's error body is fixed by -RFC 6749 §5.2, so the SDK decodes it into an `OAuthProviderError` (`error`, `error_description`, -`error_uri`) — or a `RawError` if the provider's body does not conform. - -Two consequences, and both are the sort of thing that costs an afternoon: - -1. **The exception surfaces out of your *operation* call**, because that is where the lazy fetch - happens. A traceback for bad credentials points at the operation you called, and the frames - underneath name the token source. Reading only the top frame sends you looking in the wrong place - entirely. -2. **The non-raising response mode does not protect you.** The `with_raw_response` variant returns a - result object instead of raising *for the operation* — but the token fetch passes its own result - through `unwrap()` internally, so an auth failure raises even there. Any code path that touches the SDK needs to handle - this, including one written specifically to avoid exceptions. - -So a boundary that catches only the operation's error union is incomplete. Narrow on the payload type: - -```python -from {root_package}.core import ApiError, OAuthProviderError, RawError - -try: - result = client.{controller}.{operation}(body) -except ApiError as e: - if isinstance(e.error, OAuthProviderError): - # Credentials/token problem — no operation request was ever sent. - log.error("auth failed: %s (%s)", e.error.error, e.error.error_description) - raise ConfigurationError("API credentials rejected") from e - ... # the operation's own error union -``` - -Treat this as a **configuration** failure, distinct from an operation rejection: nothing was attempted, -so retrying it or reporting it as a failed operation are both wrong. `python-error-handling` has the -full catch ladder. +It names **your operation's** call, not the token endpoint, so an `except ApiError` around that call +never catches the token endpoint's `401`. What went wrong is on `__cause__`: an `ApiError` whose +`error` is a `RawError` when the endpoint refused (the RFC 6749 `error` code is in +`e.__cause__.error.json()`), or an `SdkConnectionError` when it could not be reached. It +surfaces out of your **operation call**, where the lazy fetch happens — the top frame names the +operation, the frames beneath it the token source — and it raises under `with_raw_response` too. +Treat it as a **configuration** failure: no operation request was sent, so neither retry it nor report +it as a failed operation; `python-error-handling` has the ladder. ## Combined / multiple schemes -When an operation (or the whole API) requires more than one scheme, APIMatic composes them per -operation — OpenAPI's OR-of-ANDs, arm by arm — and the generated client wires the composition for you. -You configure it by setting the relevant credentials keywords: +When an operation (or the whole API) requires more than one scheme, the client composes them per +operation for you. You configure it by setting the relevant credentials keywords: - **AND** (`AllSchemes`) — every *configured* member applies to the request. -- **OR** (`AnySchemes`) — the first *configured* member applies. Selection is on **credential presence**, - never on "applying it did not fail", so an unconfigured member listed first cannot win and send the - request unauthenticated. - -**This layer never withholds a request over a missing credential, and never raises for one.** An -unconfigured member simply drops out and the request goes out with whatever *was* configured; with -nothing configured at all it goes out unauthenticated. The server decides. Because composition is -per-operation, one client may authenticate different operations with different schemes — set every -keyword the operations your integration calls actually need. +- **OR** (`AnySchemes`) — the first *configured* member that applies wins. An unconfigured member is + never tried, so one listed first cannot win and send the request unauthenticated, and a configured + member that raises yields to the next. Only when every configured member raised does the call raise + `AuthSchemeError`, each failure in `scheme_failures`. A failure a later member recovers from is + absorbed: the call goes ahead on that member's credential. A failed token request logs its own + lines (a WARNING where it was refused, an ERROR where it got no response), and those are the signal + that a fallback credential is in use. The group adds no line of its own; wrap that scheme if you + want one naming it. + +**A missing credential never withholds a request and never raises.** Omitting a credentials keyword is +legal and silent — the client is built with a no-auth scheme — and an unconfigured composite member +simply drops out, so the request goes out with whatever *was* configured; with nothing configured at +all it goes out unauthenticated, and the server decides. Most APIs then answer `401`; an API that +serves anonymous traffic at all (public endpoints, or a reduced rate limit for keyless callers) +answers `200` and hides the omission entirely. Because composition is per-operation, one client may +authenticate different operations with different schemes — so verify every keyword the operations +your integration calls actually need is set, and on blanket `401`s check that before suspecting the +credentials themselves. ## No auth @@ -286,19 +261,8 @@ Two things that help, both already built in: ## Notes -- A given SDK only exposes the credentials keywords for the schemes its API uses; those names are - generated per-API (hence the `{...}` placeholders above). -- **Omitting a credentials keyword is legal and silent.** The client is then built with a no-auth - scheme and requests go out unauthenticated. Nothing warns you at construction. Most APIs then - answer `401`; an API that serves anonymous traffic at all (public endpoints, or a reduced rate - limit for keyless callers) answers `200` and hides the omission entirely — so verify the keyword is - actually set rather than waiting for a `401` to tell you, and if you *are* getting blanket `401`s, - check that before suspecting the credentials themselves. -- Set credentials **at construction**. The scheme is built there; assigning to a private attribute - afterwards is not supported. To rotate a credential, build a new client and close the old one. -- Rotation with a long-lived client: the token cache is per client instance, so swapping in a new - client atomically (build, then replace the reference, then close the old one) rotates without a - window where calls have no credential. -- A per-call `extra_headers` outranks the credential: header precedence is API-wide → the endpoint's - own → auth → `extra_headers`. That is the deliberate way to override an `Authorization` header — or - blank it for a call meant to go out anonymous — and also the way to break auth by accident. +- Set credentials **at construction**; assigning to a private attribute afterwards is not supported. + To rotate a credential, build a new client, replace the reference, then close the old one — the + token cache is per client instance, so there is no window where calls have no credential. +- A per-call `extra_headers` outranks the credential, so it can override or blank `Authorization` for + one call (`python-calling-endpoints`). diff --git a/plugins/spotify/skills/python/python-calling-endpoints/SKILL.md b/plugins/spotify/skills/python/python-calling-endpoints/SKILL.md index a6e72427..17495ee7 100644 --- a/plugins/spotify/skills/python/python-calling-endpoints/SKILL.md +++ b/plugins/spotify/skills/python/python-calling-endpoints/SKILL.md @@ -1,6 +1,6 @@ --- name: python-calling-endpoints -description: Calling operations on an APIMatic-generated Python SDK — finding the group that owns an operation, the positional/keyword-only split and the parameters that never appear in the signature at all, passing a body as a model or a dict, uploading a file or a raw binary body, the two response modes, consuming a streamed file response, consuming an event stream, per-call request options, and async usage. Load before writing the first call to an SDK operation, or when an operation's shape or return type is unclear. +description: Load before writing the first call to an operation on an APIMatic-generated Python SDK, or when an operation's parameters or return type are unclear. Covers finding the group that owns an operation, the positional/keyword-only split, parameters absent from the signature, bodies as models or dicts, the parsed and with_raw_response modes, return types, iterating a paginator, per-call request_options and async calls. --- # Calling endpoints on an APIMatic Python SDK @@ -36,29 +36,21 @@ parameter you must pass `None` to just to reach a later one. Omit what you do no ### Where a parameter lands — the rule -Each parameter the description declares produces **one of three** outcomes, and the third one catches -people out: - -| What the description declares | What you get | +| Declared as | What you get | |---|---| | **required**, no fixed value | a **positional** parameter, no default | | **optional** | a **keyword-only** parameter defaulting to `None` | | a **default value** | a **keyword-only** parameter defaulting to *that value* — even if the parameter is required | | a **constant** value | **no parameter at all** — the value is baked into the request and you cannot change it | -Two consequences worth stating on the contract sheet: - -- **"Required" does not mean "path".** Positional parameters are ordered **path → query → header → - body**, so a required *query* or *header* parameter is positional too, sitting between the path - parameters and the body. Take the boundary from the sheet; never infer it from the URL. -- **A parameter with a declared default is keyword-only whatever its optionality**, and the SDK sends - that default on every call you don't override. +**"Required" does not mean "path".** Positional parameters are ordered **path → query → header → +body**, so a required *query* or *header* parameter is positional too, sitting between the path +parameters and the body. Take the boundary from the sheet; never infer it from the URL. ### Non-`None` defaults silently narrow what comes back -This is the single most common wasted afternoon on a generated SDK. A parameter carrying a -spec-declared default is *always sent*, so the response you get is the one that default asked for — -not the full resource. Typical shapes: +A parameter's non-`None` default is **sent on every call** you don't override, so the response you +get is the one that default asked for — not the full resource. Typical shapes: - a representation/verbosity switch defaulting to the minimal form, so a create returns little more than an id, a status and some links; @@ -87,7 +79,7 @@ Prefer models in application code: better inference, better errors, and required at construction. The dict form suits payloads assembled from external data. See `python-models`. **Form and multipart** — there is **no single body parameter**. Each field (and each file) becomes its -own parameter, following the same three-way split rule above. Do not go looking for a `body=`; read the +own parameter, following the same rule above. Do not go looking for a `body=`; read the signature. An optional part is omitted by leaving its parameter at its default: a part passed `None` is dropped from the body rather than sent empty. @@ -102,26 +94,18 @@ position. **No payload** — no body parameter at all. -**An optional-looking body is not permission to omit it.** A body typed `... | None = None` reflects -what the *description* marked optional, not what the endpoint needs. A create whose body is optional in -the spec will type-check with no arguments and then fail at the provider. Where a call obviously needs -a payload, pass one. +**An optional-looking body is not permission to omit it.** A body typed `... | None = None` does not +mean the endpoint works without one: a create with an optional body type-checks with no arguments and +then fails at the provider. Where a call obviously needs a payload, pass one. Serialization happens while the request is built, **before** anything is sent — so a body the SDK cannot dump raises out of the call with no request made. See `python-models`. ### File and binary parameters -**One name per client, whichever position it is.** A multipart file part and a raw binary body take -the same alias, and only the client you called decides which: `FileInput` on the sync client, -`AsyncFileInput` on the async one, and `list[…]` of either for an array part. Both are imported from -`{root_package}.core`. - -Nothing validates a file, so what the alias accepts is wider than the annotation shows — `bytes`, a -`Path`, any object with a binary `read`, a chunk iterator, and an `anyio`-style handle on the async -client. Which one you pass has consequences the signature cannot show: what stays resident, what can -be re-sent, who closes your handle, whether the body goes out sized or chunked, and what the file is -called on the wire. There is **no `str` arm** at either position — wrap a path in `Path`. +A multipart file part and a raw binary body take the same alias — `FileInput` on the sync client, +`AsyncFileInput` on the async one, `list[…]` of either for an array part — imported from +`{root_package}.core`. There is **no `str` arm** at either position — wrap a path in `Path`: ```python from pathlib import Path @@ -129,10 +113,8 @@ from pathlib import Path client.{group}.{operation}(Path("invoice.pdf")) # the default: streams, sized, names itself ``` -**Load `python-file-handling`** before passing anything other than a `Path`, and before consuming a -file an operation returns. It carries the arm-by-arm decision with its costs, the three behaviours -that differ between a part and a raw body, overriding the filename or media type, and how to read a -`FileResponse` without leaking its connection. +**Load `python-file-handling`** before passing anything other than a `Path` — what each arm costs, +the part-vs-raw-body differences, and overriding the filename or media type are there. ## Making the call and reading the response @@ -146,10 +128,11 @@ raises `ApiError`: value = client.{group}.{operation}(...) ``` -**Non-raising — `with_raw_response`.** Returns a result you branch on. Use it when you need the +**Non-raising — `with_raw_response`.** Returns a result you branch on — **2xx is `Success`, +everything else is `Failure`**, both carrying `.status_code` and `.headers`. Use it when you need the **status code or response headers** (the parsed form exposes neither on success, except for a file -response, which carries its own `headers`), or when a non-2xx is -an expected outcome rather than an exception: +response, which carries its own `headers`), or when a non-2xx is an expected outcome rather than an +exception: ```python from {root_package}.core import Success, Failure @@ -162,16 +145,15 @@ match client.{group}.with_raw_response.{operation}(...): ``` Both are frozen dataclasses, so `match` needs no boilerplate and `isinstance` narrowing is equivalent. -`unwrap(result)` (from `{root_package}.core`) collapses either back to the payload — which is literally -how the parsed form is built: every parsed method is `unwrap(...)` around its raw peer. +`unwrap(result)` (from `{root_package}.core`) collapses either back to the payload, raising on a +`Failure` exactly as the parsed form does. **`with_raw_response` removes one exception path, not the need for a `try`.** Two failures still raise -in both modes: a failed token fetch (it unwraps internally), and any decode failure. See -`python-error-handling`. +in both modes: a failed token fetch and any decode failure. See `python-error-handling`. ### Return types -Five shapes, and the sheet names which one each operation has — the map block states it directly as +Six shapes, and the sheet names which one each operation has — the map block states it directly as **Returns (parsed)** and **Returns (raw)**: - **A decoded model** — the JSON case, and the common one. @@ -181,6 +163,9 @@ Five shapes, and the sheet names which one each operation has — the map block - **An event stream** — `EventStream[T]` (`AsyncEventStream[T]` on the async client), for an operation declaring a `text/event-stream` response. It arrives **unread**, holds a connection, and iterating it yields `T`; see below. +- **A paginator** — `Paginator[Page, Item]` (`AsyncPaginator[Page, Item]` on the async client), for + a paginated operation, whose map block also carries a **Paging** bullet. It sends nothing until you + iterate it, and iterating it yields `Item`s from every page; see below. - **`None`** — the operation declares no response body. **`-> None` means the call succeeded.** Do not bind it and do not test it — success is "no exception @@ -188,20 +173,12 @@ raised", exactly as for the others. Two follow-ons: if you need the resulting st separate call; and if you need the status code (`200` vs `204`), the raw peer is `ApiResult[None, ...]` and `Success(payload=None, status_code=...)` is the only place it appears. -Writing `value = client.{group}.{operation}(...)` on a `-> None` operation type-checks under a loose -annotation and then fails later with an `AttributeError` on `None`. - ### Consuming a file response -A `FileResponse` is a body that has **not been read yet** and holds its connection until it is, -which makes it the one return value with a lifecycle. Three calls consume it and all three close it — -`save_to(...)`, `read()`, or a drained `iter_bytes()` under `with` — and the async twin mostly -`a`-prefixes them. - -Getting this wrong leaks a connection rather than raising, so **load `python-file-handling`** before -writing the consuming code. It carries the lifecycle in full: which warning fires when one is -abandoned and how to make it fail a test, the single-use rule, what `save_to` does with a directory, -and why a `try` around the call alone catches nothing. +A `FileResponse` arrives **unread** and holds its connection until `save_to(...)`, `read()` or a +drained `iter_bytes()` under `with` closes it; the async twin mostly `a`-prefixes them. A mistake +leaks a connection rather than raising, so **load `python-file-handling`** before writing the +consuming code. ### Consuming an event stream @@ -209,6 +186,33 @@ An `EventStream[T]` is iterated, not read: a drained `for` releases its connecti needs `with`. **Load `python-event-streams`** before writing the loop — it carries the lifecycle, the union narrowing, and the failures that are silent. +### Iterating a paginator + +A `Paginator` is a lazy walk over the whole collection, not a page. Calling the method sends nothing; +the first request goes out when you start iterating, and each new iteration starts again from the +first page. Iterate it for items, or call `iter_pages()` for the pages: + +```python +for item in client.{group}.{operation}(...): + ... + +for page in client.{group}.{operation}(...).iter_pages(): + ... +``` + +- **The arguments set the first request only.** The SDK moves the offset, page, cursor or link forward + from each response and stops on the API's own signals — the map block's **Paging** bullet says + which. There is no next-page method; to resume from a known point, pass it as the first-page + argument. +- **Cap a walk with `break` or `itertools.islice`.** There is no page-cap argument, and either stops + the walk with no further request. A `list(...)` over an uncapped paginator fetches every page. +- **Errors raise from the loop, not the call** — so a `try` around the call alone catches nothing. + `python-error-handling` has the detail. +- **The raw peer's pages are results.** `client.{group}.with_raw_response.{operation}(...)` returns + `Paginator[ApiResult[Page, E], Item]` and never raises for an API error: iterating it for items + yields the items of every successful page and ends at a failed one, and `iter_pages()` yields one + `Success` or `Failure` per page, the `Failure` last. + ## Per-call overrides — `request_options` @@ -219,30 +223,36 @@ accepted typed or dict-shaped: client.{group}.{operation}(..., request_options={"timeout": 5.0}) ``` -The keys are exactly `timeout` (seconds, must be > 0), `extra_headers`, and the two retry overrides -`max_retries` and `status_codes_to_retry` (`python-configuration-resilience`). It is validated with +The keys are exactly `timeout` (seconds, must be > 0), `extra_headers`, the two retry overrides +`max_retries` and `status_codes_to_retry`, `log_level` and `hooks` (`python-configuration-resilience`). +The typed form is `RequestOptions` on the sync client and `AsyncRequestOptions` on the async one: the +same keys, the async `hooks` being `AsyncSdkHook` or an `AsyncSdkHooksDict` where the sync ones are +`SdkHook` or an `SdkHooksDict`, so a hook of the other client's flavour is a type error at the call +site. It is validated with `extra="forbid"`, so `{"timeuot": 5}` raises `ValidationError` rather than being ignored — and because the dict form is a closed `TypedDict`, a type checker catches it at the call site first. -`extra_headers` wins over both the API's and the endpoint's own headers, which makes it the deliberate -way to override a header the SDK sets — including blanking an auth header for a call meant to go out -anonymous. That precedence is a footgun as much as a feature: setting `authorization` here overrides -the managed token. +`extra_headers` wins over the API's, the endpoint's and the auth scheme's headers (precedence +API-wide → endpoint → auth → `extra_headers`), which makes it the deliberate way to override a header +the SDK sets — including blanking an auth header for a call meant to go out anonymous — and the way to +break auth by accident: setting `authorization` here overrides the managed token. Two mechanics: - **Header names are lowercased on the way out**, at every layer including yours, so the merge is - genuinely case-insensitive and the request reaching the transport is keyed in lowercase. Look - request headers up that way (`python-testing`). -- **`Cookie` folds instead of replacing.** Every other field takes the later layer and discards the - earlier; a cookie you add joins the jar alongside whatever the endpoint or a credential put there - (RFC 6265 permits one `Cookie` field). So a cookie-carried credential cannot be blanked with - `extra_headers` the way a header-carried one can. + case-insensitive and the request reaching the transport is keyed in lowercase. Look request headers + up that way (`python-testing`). +- **`Cookie` folds instead of replacing.** Every other field takes the later layer; a cookie you add + joins whatever the endpoint or a credential put there, so a cookie-carried credential cannot be + blanked with `extra_headers` the way a header-carried one can. ## Async -The async client's operations are identical in name and parameters — you await them. There is no -`_async` suffix and no separate method list; the client class you hold decides the flavour: +The async client's operations have the same names and parameter names — you await them, and their +`request_options` is `AsyncRequestOptionsOrDict` (above). There is no +`_async` suffix and no separate method list; the client class you hold decides the flavour. The one +exception is a paginated operation: it is a **plain call** returning `AsyncPaginator`, so you +`async for` over it with no `await` on the call. ```python value = await client.{group}.{operation}(...) @@ -269,12 +279,9 @@ results = await asyncio.gather(*(one(a) for a in args)) ## Timeouts and cancellation -There is no cancellation-token parameter. Python's own mechanisms apply: - -- **Per call** — `request_options={"timeout": ...}`, which sets the limit on each wait for this one request. -- **The whole call** — `asyncio.wait_for(...)` around it, in async code; see - `python-configuration-resilience`. -- **Sync code has no whole-call limit.** The timeout only limits each wait — set one anyway. +There is no cancellation-token parameter. `request_options={"timeout": ...}` limits each wait of one +request; `asyncio.wait_for(...)` around the call limits the whole call in async code +(`python-configuration-resilience`). Sync code has no whole-call limit — set the timeout anyway. ## Next diff --git a/plugins/spotify/skills/python/python-client-initialization/SKILL.md b/plugins/spotify/skills/python/python-client-initialization/SKILL.md index 357e6284..7bff951b 100644 --- a/plugins/spotify/skills/python/python-client-initialization/SKILL.md +++ b/plugins/spotify/skills/python/python-client-initialization/SKILL.md @@ -1,6 +1,6 @@ --- name: python-client-initialization -description: Creating and holding an APIMatic-generated Python SDK client in Python — construction, the keyword-only constructor shape, choosing the sync or async class, transport ownership and the close/aclose obligation, and where the client lives in a script, an ASGI app, or a forking worker. Load before wiring the client into an application or writing the factory that builds it. +description: Load before constructing an APIMatic-generated Python SDK client or wiring it into an application — a script, an ASGI app (FastAPI, Starlette), a WSGI app or a forking worker (Gunicorn, Celery). Covers the keyword-only constructor, choosing the sync or async class, transport ownership and the close/aclose obligation, and how long the client lives. --- # Initializing an APIMatic Python SDK client @@ -23,8 +23,10 @@ constructor: {Api}Client( *, # server selection — one of four shapes, see "Choosing the server / base URL" - timeout: float = 30.0, # seconds; the generator's default + timeout: float = 30.0, # seconds retry_options=None, # None: the default policy; 0 disables; a count, RetryOptions or dict tunes it + logging_options=None, # what the built-in HTTP logging records — see python-configuration-resilience + hooks=None, # hook objects or {"on_request": [...], ...} — see python-configuration-resilience custom_http_client=None, # your own transport {scheme}=None, # one credentials keyword per declared scheme {scheme}_token_source=None, # managed-OAuth schemes only @@ -35,25 +37,23 @@ Every parameter sits after `*` — there are **no positional arguments**, so a p immediate `TypeError`. There is no options object, no builder, and no separate configuration type to populate: everything is a constructor keyword. -Operations are exposed on the client. Most are grouped under **group accessors** (one per API resource -group) and called `client.{group}.{operation}(...)` — for example, a `widgets` group's `list_widgets` -operation is `client.widgets.list_widgets(...)`. An operation that belongs to no group sits **directly -on the client**, called `client.{operation}(...)`. Accessors are `cached_property`, so they are -attributes without parentheses and return the same object each time. The available accessors (and any -direct operations) come from the contract sheet, grounded in the SDK map's controller table -(`sdk-map.md`) — not from a runtime `dir()` or a REPL poke. See -`python-calling-endpoints`. +Operations hang off **group accessors** — `client.{group}.{operation}(...)`, or `client.{operation}(...)` +for an ungrouped one. Accessors are `cached_property` attributes, not methods: no parentheses, and the +same object each time. Take them from the contract sheet, grounded in the SDK map's controller table +(`sdk-map.md`), not from a runtime `dir()` (`python-calling-endpoints`). Both classes are also exported under the fixed aliases `Client` and `AsyncClient`. **Prefer the full names** — a bare `Client` collides in any application that talks to more than one API. -The async class is a peer, not a variant: same accessors, same operation names, same parameters. Four -names differ: +The async class is a peer, not a variant: same accessors, same operation names, same parameter names. +What differs at the client: | | Sync | Async | |---|---|---| | Transport keyword | `custom_http_client=` | `custom_async_http_client=` | | Transport protocol | `HttpClient` | `AsyncHttpClient` | +| Hooks | `SdkHook` / `SdkHooksDict` | `AsyncSdkHook` / `AsyncSdkHooksDict` | +| Per-call options | `RequestOptions` | `AsyncRequestOptions` | | Shutdown | `client.close()` | `await client.aclose()` | | Scope form | `with` | `async with` | @@ -83,18 +83,11 @@ client = {Api}Client( ) ``` -`timeout` is validated at construction: non-positive (or NaN) raises `ValueError` immediately. -Credentials passed in dict form are validated by pydantic with `extra="forbid"`, so a misspelled key -raises `ValidationError` there and then. - -Two things are **not** validated, so a clean construction does not mean a working client: - -- **`base_url` is taken unchecked.** A typo or the wrong environment surfaces as a connection error or - a `401` at the first call. -- **Credentials are never exercised.** Managed-OAuth schemes fetch the token lazily on the first API - call, so wrong credentials construct happily and fail later, pointing at whichever operation ran - first. Every credentials keyword also defaults to `None`, and omitting it configures the client for - **no auth** — requests go out unauthenticated and the server answers `401`. +Construction validates `timeout` (`ValueError`) and dict-form credentials (`ValidationError`), but a +clean construction does not mean a working client: **`base_url` is taken unchecked** — a typo or the +wrong environment surfaces as a connection error or a `401` at the first call — and **credentials are +never exercised**: a managed-OAuth token is fetched on the first call, and an omitted credentials +keyword means no auth (`python-authentication`). ### Transport ownership and the close obligation @@ -120,23 +113,10 @@ is `aclose`, and calling `close()` on an async client is an `AttributeError`. ## Choosing the server / base URL -Server selection is **not** an environment enum. What the constructor accepts depends on what the spec -declares, in one of four shapes: - -| The API declares | Constructor keywords | -|---|---| -| one server, one environment | `base_url: str \| None = None` | -| one server, several environments | `environment` (a string literal alias, with a default), then `base_url` | -| several servers, one environment | `server_config: {Server}ConfigOrDict \| None = None` | -| several servers, several environments | `environment`, then `timeout`, then `server_config` | - -Omitting the server keyword falls through to the config's own default rather than writing `None` over -it — and **that default is whatever the spec listed first, which for many providers is a sandbox.** -Nothing announces it. Confirm the default from the contract sheet — the SDK map's *Servers & auth* -section names the base URL each arm resolves to — and pass the server explicitly in -every environment, production included. Server template variables live on the config class, so how you -reach them follows the arm above. **python-configuration-resilience** owns server / base-URL -configuration in full. +The server keyword takes one of four shapes, and **omitting it silently selects the API's +first-listed environment — often a sandbox.** Pass it explicitly in every environment, production +included; **python-configuration-resilience** owns the shapes, their nesting and server template +variables. ## Where the client lives @@ -184,48 +164,48 @@ thread-safe. The async client may be built outside a running loop, but from its ## Supplying your own transport The transport is a `Protocol` — a structural interface, not a base class. The sync one requires -`send(request) -> HttpResponse` and `close()`; the async one `send` and `aclose()`. There is one -request seam whatever the operation returns, a file included, so a transport that implements those -two satisfies the Protocol under `mypy --strict`: +`send(request) -> HttpResponse` and `close()`; the async one `send` and `aclose()`: ```python client = {Api}Client(custom_http_client=MyTransport(), {scheme}=...) ``` -This is the seam for **logging, tracing, metrics and tests** — the SDK ships no logging or middleware of -its own. Wrap the SDK's own transport rather than reimplementing HTTP: +This is the seam for **tests and for replacing the send itself**. Tracing, metrics and changing a +request or response go in a hook instead, and HTTP logging is built in +(`python-configuration-resilience` covers both), so wrap the transport only for what neither can do. +Wrap the SDK's own transport rather than reimplementing HTTP: ```python -class LoggingTransport: - def __init__(self, inner): self._inner = inner +class ReplayTransport: + def __init__(self, inner, replies): self._inner, self._replies = inner, replies def send(self, request): + if (reply := self._replies.get((request.method, request.url))) is not None: + return reply(request) # your own HttpResponse; nothing is sent, which no hook can do # The head only: the body is still on the socket, and the caller closes it. - response = self._inner.send(request) - log.info("%s %s -> %s", request.method, request.url, response.status_code) - return response + return self._inner.send(request) def close(self): self._inner.close() ``` -`send` returns an `HttpResponse` — `url`, `status_code`, lowercased `headers`, +`send` returns an `HttpResponse` — `method`, `url`, `status_code`, lowercased `headers`, `iter_bytes(chunk_size)`, `read()` and `close()` — whose body has **not** been read. That is true of every response, not just a download, so a wrapper must hand each one back unread; logging its size means consuming it, which leaves the caller nothing to read. `iter_bytes(None)` must yield each chunk as the network delivered it, holding nothing back — an event stream reads it that way, and a wrapper that re-chunks to a fixed size delays every small event. -Four obligations the protocol places on anything you supply, all silent when broken: **do not mutate +Five obligations the protocol places on anything you supply, all silent when broken: **do not mutate the incoming request** (it is frozen); **honour `request.timeout`** when set, falling back to your own -when it is `None`; **lowercase the response header names**, because callers look them up that way; and -**return once the head has arrived**, leaving the body for whoever reads it. - -Two consequences. First, **the `timeout=` you passed to the client no longer reaches the wire** — that -value only builds the client's *own default* transport, so set the timeout on the one you pass or you -have silently reverted to the underlying library's default. The per-call -`request_options={"timeout": ...}` is the exception: it travels on the request object and reaches any -transport honouring the obligation above. Second, **the client still closes it** — don't close it -yourself while the client is alive, and don't share one transport between two clients. +when it is `None`; **lowercase the response header names**, because callers look them up that way; +**return once the head has arrived**, leaving the body for whoever reads it; and **raise +`SdkConnectionError`** (`SdkTimeoutError` for a timeout) from `send` and from the response's reads when +no usable response arrives, chained `from` your library's exception (`python-configuration-resilience`). + +Two consequences. First, **the client's `timeout=` does not reach the wire** — set the timeout on your +transport, or you get the underlying library's default; a per-call `request_options` timeout still +arrives on the request (`python-configuration-resilience`). Second, **the client still closes it** — +don't close it yourself while the client is alive, and don't share one transport between two clients. ## Next diff --git a/plugins/spotify/skills/python/python-configuration-resilience/SKILL.md b/plugins/spotify/skills/python/python-configuration-resilience/SKILL.md index 05c86314..9d48e42e 100644 --- a/plugins/spotify/skills/python/python-configuration-resilience/SKILL.md +++ b/plugins/spotify/skills/python/python-configuration-resilience/SKILL.md @@ -1,6 +1,6 @@ --- name: python-configuration-resilience -description: Client configuration and resilience for an APIMatic-generated Python SDK — server and base-URL selection, the retry policy (on by default, off with `max_retries=0`) and what it will and will not repeat, what a timeout actually bounds, proxies and TLS, and request/response logging through the transport seam. Load before you configure or tune the client — the keyword names alone do not reveal what is handled for you and what is not. +description: Load before configuring or tuning an APIMatic-generated Python SDK client — choosing the server or base URL, retries, idempotency keys, timeouts, proxies and TLS, turning on request/response logging, or running your own code on every request with hooks. Covers the default retry policy and what it repeats, what a timeout bounds, the built-in HTTP logging (off by default; `logging_options`, `{ROOT_PACKAGE}_LOG` and a per-call `log_level`), request and response hooks (`hooks=` on the client and per call), and what the SDK leaves to you. --- # Configuration & resilience for an APIMatic Python SDK @@ -9,34 +9,26 @@ description: Client configuration and resilience for an APIMatic-generated Pytho > `{group}`, `{root_package}`) — replace it with the concrete identifier from the source. Configuration is not an options object here. Everything is either a **constructor keyword** on the -client (`python-client-initialization`), a field on a **config model** — the server config or -`RetryOptions` — or a **per-call `request_options`**. There is no third place to look. +client (`python-client-initialization`), a field on a **config model** — the server config, +`RetryOptions` or `LoggingOptions` — or a **per-call `request_options`**. There is no third place to look. ## What this SDK does not do for you -Read this before designing around a capability you assume exists. The generator emits **none** of the -following, so each is yours to build or deliberately do without: - -| Capability | Status | What to do instead | -|---|---|---| -| **Streaming — file responses** | a `FileResponse` arrives with its body unread and holds its connection until you consume it | `save_to` / `read` / `iter_bytes` (see `python-file-handling`) | -| **Streaming — SSE** | an `EventStream` arrives with its body unread; iterating yields each event's decoded data, and `timeout` bounds the gap between events | a `for` loop, or `with` for an early exit (see `python-event-streams`) | -| **Request/response logging** | none — no hook, no event | Wrap the transport; see below | -| **Circuit breaking, rate limiting** | none | Your own, around the call | -| **A mock/offline mode** | none | Point `base_url` at a mock server, or supply a fake transport (`python-testing`) | - -**Retries are on by default.** A client built without `retry_options` retries idempotent calls up to -three times; set `max_retries` to `0` to turn that off — see *Retries* below. +| Capability | What to do instead | +|---|---| +| **Circuit breaking, rate limiting** | Your own, around the call | +| **A mock/offline mode** | Point `base_url` at a mock server, or supply a fake transport (`python-testing`) | What the SDK *does* own: the request pipeline, auth application and token caching, response decoding, -error mapping, connection pooling, one timeout, and — once you turn it on — the retry loop. +error mapping, connection pooling, one timeout, the retry loop (on by default — see *Retries* below), +HTTP logging (silent until its logger is raised — see *Logging* below), and streamed file and +event-stream responses (`python-file-handling`, `python-event-streams`). ## Server and base-URL configuration -Server selection is **not** an environment enum. What the constructor accepts depends on what the -description declares, in one of four shapes — take yours from the contract sheet, grounded in the SDK -map's *Servers & auth* section, which names the environments and servers this SDK declares and so -settles which arm it is: +Server selection is **not** an environment enum. The constructor takes one of four shapes, set by what +the API declares — take yours from the contract sheet; the SDK map's *Servers & auth* section settles +which arm it is: | The API declares | Constructor keywords | |---|---| @@ -55,18 +47,15 @@ client = {Api}Client(environment="production", server_config={"{server}": {"prod wrong nesting raises `ValidationError` rather than being ignored.** With one environment each server's field holds `base_url` directly. With several, each server's field holds **one field per environment** and the `base_url` sits inside the environment's variant — passing `{"{server}": {"base_url": ...}}` -there fails with `Extra inputs are not permitted`. Take the nesting from the SDK map's *Servers & auth* -section rather than from this shape. +there fails with `Extra inputs are not permitted`. -Either way `server_config` is a pydantic model with a dict companion, coerced through `.coerce()`, -holding **one field per server the API declares**. Template variables sit beside `base_url` at +Either way `server_config` is a pydantic model with a dict companion, holding **one field per server +the API declares**. Template variables sit beside `base_url` at whichever level carries it. -**Omitting the server keyword takes the description's own default, and that default is whatever the -spec listed first — for many providers a sandbox.** Nothing announces it. A deployment that believes it -configured production and did not gets sandbox behaviour with production credentials, which fails auth -in a way that looks like a credentials problem, not an environment one. Pass the server explicitly in -every environment, production included. +**Omitting the server keyword silently selects the API's first-listed environment — often a +sandbox.** Production credentials against it fail like a credentials problem, not an environment one. +Pass the server explicitly in every environment, production included. **Server template variables are only reachable in the `server_config` arms.** They are fields on the config class, so where the constructor takes a `server_config` you set them there. Where it takes a @@ -88,10 +77,8 @@ the token fetch too. ## Retries — on by default -A client built without `retry_options` uses the **default policy** in the table below: a `GET`, `HEAD`, -`PUT` or `OPTIONS` call that meets a `408`, `429`, `500`, `502`, `503`, `504` or a dropped connection is -retried up to three times. -Retrying is configured by one options class, `RetryOptions` (from `{root_package}.core`), passed to the +A client built without `retry_options` uses the **default policy** in the table below. Retrying is +configured by one options class, `RetryOptions` (from `{root_package}.core`), passed to the client in any of four spellings: ```python @@ -140,11 +127,14 @@ A call is repeated only when **all** of these hold: A `401` is never in the default set; it invalidates the cached credential for the next call instead (`python-authentication`). Whatever you add to `status_codes_to_retry` is retried, so leave out statuses that cannot succeed a second time. When the last attempt fails, you see what a single attempt -would give you: the `ApiError`, the raw response's `Failure`, or the HTTP library's own exception. +would give you: the `ApiError`, the raw response's `Failure`, or `SdkConnectionError` with the HTTP +library's exception on `__cause__`. -A **custom transport** must raise `TransportError` (`from {root_package}.core import TransportError`) -for a failed send to be retried; the shipped `Httpx2Client` does. Anything else it raises reaches you on -the first attempt. +A **custom transport** must raise `SdkConnectionError` (`SdkTimeoutError` for a timeout) from `send` +for a failed send to be retried, naming the call as `method=request.method, url=safe_url(request.url)` +(`from {root_package}.core import SdkConnectionError, SdkTimeoutError, safe_url`). Its response's reads +must raise the same for a body they could not deliver. The shipped `Httpx2Client` does both. +Anything else it raises reaches you, unwrapped, on the first attempt. ### Per-call overrides @@ -159,18 +149,11 @@ client.{group}.{operation}(arg, request_options={"status_codes_to_retry": frozen and each of your attempts is a new call with a new idempotency key (below). If you need behaviour the options cannot express, turn the SDK's off for that call and own it. -**Only a write that was sent may have landed.** A write that timed out *after it was sent* may have -succeeded — a reset after the bytes reached the server is indistinguishable from one before. A write -that was never sent did not happen; `python-error-handling` names the four exceptions that mean so. - -**The retry arithmetic is not a ceiling.** `(max_retries + 1) × timeout` plus the waits between them -can be exceeded, because one attempt can outlast its timeout; see *Bounding a call*. - ### Making a write safe when you retry **Every operation other than a `GET` sends an `Idempotency-Key` header** — a UUID minted once per call, -unless the description declares its own header of that name, in which case that one is a keyword you -set. Within the SDK's retry loop every attempt carries the *same* key, which is what makes adding `POST` +unless the operation has its own `Idempotency-Key` header parameter, which is then a keyword you set. +Within the SDK's retry loop every attempt carries the *same* key, which is what makes adding `POST` to `http_methods_to_retry` safe **where the provider deduplicates on it**. A retry you write yourself is a new call and mints a new key — the provider sees two submissions. @@ -227,8 +210,7 @@ await asyncio.wait_for(async_client.{group}.{operation}(arg), budget) # the wh ``` - The value is **seconds, as a float**; the per-call option overrides the client's. -- It must be **> 0**. The constructor raises `ValueError` otherwise — and rejects NaN too, since the - guard is written `not timeout > 0`. +- It must be **> 0** (NaN is rejected too); the constructor raises `ValueError` otherwise. - The default is **30 seconds** per wait. - Under the default transport, one float sets connect, read, write and pool timeouts alike. To separate them (a short connect, a longer read), build your own transport with an @@ -240,7 +222,7 @@ keeps arriving slowly is never cut off, and each attempt — up to `max_retries longer than the number you set. This timeout firing is a transport failure and retries on the curve like any other; a `408` is the server's request timeout and sits in the default status set. -**If you supply `custom_http_client`, the client's `timeout=` no longer reaches the wire.** That value +**If you supply `custom_http_client`, the client's `timeout=` does not reach the wire.** That value only builds the SDK's *own* default transport. Set the timeout on the transport you pass, and honour `request.timeout` inside it (`python-client-initialization`). @@ -271,52 +253,70 @@ client = {Api}Client(custom_http_client=transport, {scheme}=...) - **`verify=False` disables certificate verification.** It is not a debugging convenience for anything carrying credentials; fix the trust store instead. -## Logging — wrap the transport +## Logging — off by default, through the standard logger -There is no logging hook and no event to subscribe to. The transport protocol is the seam: implement -it, delegate to the real one, and log around the call. +The SDK writes every HTTP exchange through Python's standard `logging` module under the +`{root_package}` logger and configures nothing itself: no handler, no level, never the root. Turn it +on as for any library, or from the environment for a run you cannot edit — `{ROOT_PACKAGE}_LOG` is the +package name upper-cased with `_LOG` appended: ```python -import logging, time -from {root_package}.core import Httpx2Client +import logging -log = logging.getLogger(__name__) +logging.basicConfig() # your handler; the root stays at WARNING +logging.getLogger("{root_package}").setLevel(logging.INFO) # INFO: the lines; DEBUG: the dumps too +``` -class LoggingTransport: - def __init__(self, inner): self._inner = inner +```bash +{ROOT_PACKAGE}_LOG=info python app.py # the request and response lines +{ROOT_PACKAGE}_LOG=debug python app.py # plus request headers, request body and response headers +``` - def send(self, request): - started = time.monotonic() - # The head only -- do not read the body here; the caller owns it. - response = self._inner.send(request) - log.info( - "%s %s -> %s (%.0f ms)", - request.method, request.url, response.status_code, - (time.monotonic() - started) * 1000, - ) - return response +| Level | What is written | +|---|---| +| `INFO` | `HTTP GET https://api.example.com/items?page=2` as each attempt is sent, and `HTTP GET … -> 200 (12 ms)` when its head arrives | +| `WARNING` | the response line for any status outside 2xx, and `HTTP GET … retrying in 1.0 s (attempt 1/3): 503 Service Unavailable` before each retry | +| `ERROR` | `HTTP GET … failed after 6210 ms: ConnectError` when a call ends in an exception, with the exception attached | +| `DEBUG` | the request headers, the request body and the response headers — each only when its flag below is on | - def close(self): self._inner.close() +The dumps are opt-in through `logging_options`, a dict or a `LoggingOptions` from `{root_package}.core`: +```python client = {Api}Client( - custom_http_client=LoggingTransport(Httpx2Client(timeout=10.0)), {scheme}=... + logging_options={"log_request_headers": True, "log_response_headers": True, "log_request_body": True}, + {scheme}=..., ) ``` -The async version is the same shape with `async def send` and `async def aclose`. Both members are -required, and they are the only two: one request seam serves every operation, a download included, -so there is no second method to forget. - -**The elapsed time above bounds the head, not the call.** `send` returns once the response head has -arrived, so a body still on the wire is not in that measurement — for a download it is barely in it -at all. Timing the whole exchange means timing where the body is consumed, which is the caller's -code, not this wrapper. - -**Log the method, URL and status — not headers or bodies.** The auth header carries a live credential -and bodies carry whatever the API moves; neither belongs in your logs or your traces. If you must -capture a body to debug, gate it behind a flag that is off by default and redact before writing. - -This same wrapper is where OpenTelemetry spans, metrics and request-id propagation belong. +| Option | Default | Effect | +|---|---|---| +| `log_request_headers` | `False` | the sent headers at DEBUG, masked | +| `log_response_headers` | `False` | the received headers at DEBUG, masked | +| `log_request_body` | `False` | the request body at DEBUG: its text when in memory, a description when streamed | +| `body_size_limit` | `32768` | bytes of a logged body kept before it is cut | +| `redaction_placeholder` | `"REDACTED"` | what a hidden value prints as | +| `unmask_headers` / `mask_headers` | none | header names to show, or hide, against the built-in safe list | +| `mask_keys` | 11 credential names | query and form keys whose values are always hidden; naming a set replaces the default | + +**What is never printed.** A header value is shown only when its name is on a built-in list of +standard headers that carry no credential, so `Authorization`, `Cookie` and API-key headers print +`REDACTED`. A query value is shown only for nine paging names (`cursor`, `limit`, `offset`, `page`, +`since`, `size` and three more), and a URL's user and password are dropped. A form field under +`mask_keys` is hidden. A JSON body is printed as sent, so turn `log_request_body` on only where its +content may be logged. A response body is never logged. + +**One call, quieter.** `request_options={"log_level": logging.WARNING}` is a floor: records below it +are not written for that call. It never turns on a record the client's options leave off. + +**`{ROOT_PACKAGE}_LOG` sets the level and, where no handler listens, adds a stderr one;** `debug` +also turns the three flags on. An application that configured logging keeps its own handlers and +format. The SDK never touches the `httpx2` or `httpcore2` loggers; if your root logger is at INFO, +raise those two to WARNING yourself, or httpx2 prints its own unmasked line per attempt. + +**Tracing, metrics and anything the records do not carry** go in a hook (*Hooks* below). The +transport seam stays for what a hook cannot do, replacing the send itself: wrap the SDK's own transport +and delegate (`python-client-initialization` shows the shape). The wrapper sees the head only — do not +read the body there — and the auth header is live, so never log it yourself. ### Verify on the wire (first run of any new call) @@ -324,22 +324,74 @@ On success the SDK returns the decoded body and nothing else — never the URL o parameter, a header you thought you set, or a query parameter that silently did not serialize produces **no in-band signal**; the only symptom is a `404`/`422` that looks like a provider problem. -Run the logging transport the first time you execute any new call, and check: +Run the first call under `{ROOT_PACKAGE}_LOG=debug`, and check in the request line and header dump: 1. the **method** matches the operation; 2. the **path** has no unsubstituted `{placeholder}`; 3. path segments carry **wire values** — an enum's string, not a Python member name; -4. the **query parameters** you set actually appear. +4. the **query parameter names** you set appear (a value outside the paging names prints `REDACTED`). + +Then drop the variable. + +## Hooks — your code on every attempt + +A hook is caller code the SDK runs on **every attempt** of every request, inside the retry loop. +`before_request(request, context)` runs after authentication and before the request line is logged, +and returns the request to send. `after_response(response, context)` runs after the response line and +the 401 check and before the retry decision, and returns the response the call acts on. + +```python +from dataclasses import replace + +from {root_package}.core import HookContext, HttpRequest, SdkHook + + +# new_traceparent() stands for your own tracer. +class Tracing(SdkHook): + def before_request(self, request: HttpRequest, context: HookContext) -> HttpRequest: + return replace(request, headers={**request.headers, "traceparent": new_traceparent()}) + + +def stamp(request: HttpRequest, context: HookContext) -> HttpRequest: + return replace(request, headers={**request.headers, "x-tenant": "acme"}) + + +client = {Api}Client(hooks=[Tracing()]) # every call +client.{group}.{operation}(arg, request_options={"hooks": {"on_request": [stamp]}}) # this call, after the client's +``` -Then gate the wrapper behind a debug flag. +- **Subclass `SdkHook` and override either method, or pass plain functions keyed by event**, + `{"on_request": [...], "on_response": [...]}` (an `SdkHooksDict`). One place takes one spelling, + never a mix; a hook that keeps state between the request and its response is a class. Any other key + is a type error and is ignored at run time. A request is frozen: return it, or a + `dataclasses.replace` of it. +- **A call's hooks are appended to the client's, never substituted**, so a call site cannot switch off + what the client installed. +- **The client keeps the hooks you pass, uncopied**, so a list changed after construction is read by + the next call. +- **The async client takes `AsyncSdkHook`**, whose two methods are `async def` and receive an + `AsyncHookContext` and an `AsyncHttpResponse`; its dict (`AsyncSdkHooksDict`) takes `async def` + functions under the same two keys, and a call's hooks go in `AsyncRequestOptions`. A hook of the + wrong flavour is a type error; nothing is checked at run time. +- **A hook runs once per attempt**, so it must be safe to run more than once, and `before_request` may + run with no `after_response` to follow when the send fails. +- **A hook that raises ends the call** with that exception, unwrapped. To have the attempt retried as a + failed send, raise `SdkConnectionError(message, method=context.method, url=safe_url(context.url))` + (both from `{root_package}.core`) **from `before_request`**; it is then retried under the same method + and retry-count rules as a transport failure. Raised from `after_response`, it ends the call like any + other exception. +- **On a token request an OAuth scheme makes, only the client's hooks run**, not the call's, and one + that raises reaches you as `AuthSchemeError` with its exception in `scheme_failures` + (`python-error-handling`); in an OR requirement the next configured scheme is tried first. +- **A hook that reads the response body must return a response that still carries it**, and one that + returns a different response must close the original or keep it inside. +- **Hooks see the credential in clear**, on API calls and on the token requests an OAuth scheme makes. + Never log `request.headers` from one. ## Connection pooling -The client holds one pooled transport. Reuse the client and close it on shutdown; a client per call -pays a fresh TCP and TLS handshake every time, and under managed auth a fresh token fetch as well. -Under forking servers (Gunicorn, uWSGI, Celery prefork), construct it **after** the fork — a pool -inherited across `fork()` is shared by processes that each believe they own it, which surfaces as -intermittent, unexplainable connection errors. See `python-client-initialization`. +The client holds one pooled transport. Reuse one client and close it on shutdown; under forking +servers construct it **after** the fork (`python-client-initialization`). ## Next diff --git a/plugins/spotify/skills/python/python-error-handling/SKILL.md b/plugins/spotify/skills/python/python-error-handling/SKILL.md index 02bf6bbe..b1cc97be 100644 --- a/plugins/spotify/skills/python/python-error-handling/SKILL.md +++ b/plugins/spotify/skills/python/python-error-handling/SKILL.md @@ -1,6 +1,6 @@ --- name: python-error-handling -description: Error and exception handling for an APIMatic-generated Python SDK — load before writing any try/except around an SDK call, an exception-translation layer, or error middleware. Covers the single ApiError type and its per-operation error union, narrowing with isinstance or match, the failures that are NOT ApiError and reach your boundary unmatched, and the traps that make an otherwise reasonable except ladder silently wrong. +description: Load before writing any try/except around an APIMatic-generated Python SDK call, an exception-translation layer or error middleware. Covers the SdkError family — ApiError and its per-operation error union, ResponseDecodeError, SdkConnectionError / SdkTimeoutError and AuthSchemeError — narrowing with isinstance or match, and with_raw_response. --- # Error handling for an APIMatic Python SDK @@ -10,41 +10,49 @@ description: Error and exception handling for an APIMatic-generated Python SDK > source. Operations **raise on non-2xx responses** by default (for a non-raising alternative, see the -**`with_raw_response`** section below). The raised type is always `ApiError` — there is exactly one -exception class in these SDKs, and the variation lives entirely in the payload it carries. +**`with_raw_response`** section below). Everything the SDK raises for a call derives from one root, +`SdkError`, so one `except SdkError` covers any number of calls: + +| Exception | Raised when | Attributes beyond `method`, `url` | +|---|---|---| +| `ApiError[E]` | an error status (parsed mode only) | `error`, `status_code`, `headers` | +| `ResponseDecodeError` | a body, 2xx or documented error, its declared type rejects | `status_code`, `headers` | +| `SdkConnectionError` | no usable response: the send failed after the retries, or the body read failed | — | +| `SdkTimeoutError` (a `SdkConnectionError`) | the connection failure that was a timeout | `timeout` | +| `AuthSchemeError` | a credential that could not be applied | `scheme_failures` | + +Every member names the call (`e.method`, and `e.url`, the path rendered with no query) and keeps what +caused it, as the library or pydantic raised it, on `e.__cause__`. `ApiError` and `ResponseDecodeError` +are **siblings**: `except ApiError` never catches a 2xx that broke its contract, and +`except (ApiError, ResponseDecodeError)` spells "the server answered". ```python -from {root_package}.core import ApiError, RawError +from {root_package}.core import ApiError, RawError, SdkError ``` `ApiError` is generic in its payload (`ApiError[E]`), but you catch it **unparametrized**. A runtime `except` clause cannot discriminate a type parameter, so `except ApiError` catches every operation's -failure and you narrow on `e.error` afterwards. This is the opposite of a generator that encodes the -error type into the exception class: here the compiler-equivalent check happens at the `isinstance`, -not at the `except`. +failure and you narrow on `e.error` afterwards. ## Catch the exception -`ApiError` carries three things: +`ApiError` carries three things beyond the call: | Attribute | Type | Notes | |---|---|---| | `e.error` | the operation's error union | The decoded body. **This is the information.** | -| `e.status_code` | `int` | The status that failed. | +| `e.status_code` | `int` | The status that failed — set whichever arm of the union you got. | | `e.headers` | `Mapping[str, str]` | The response head, keys lowercased. | -**`str(e)` and `repr(e)` deliberately omit the body.** They render as `HTTP 422: {TypedError}` — the -status and the payload's *type name* only, so response bodies stay out of logs and tracebacks by -default. That is a sound default and a trap: a handler that logs `str(e)` and nothing else records -that something failed and discards every diagnostic. Read `.error` explicitly and log the fields you -choose. - -The status is **always** on `e.status_code`, whichever arm of the union you got — you never have to -choose between a typed body and knowing the status. +**`str(e)` and `repr(e)` deliberately omit the body**, so response bodies stay out of logs and +tracebacks: `str(e)` is the call and the status, `GET https://host/path returned 404 (Not Found)`, and +`repr(e)` the status and the payload's *type name*. A +handler that logs `str(e)` and nothing else discards every diagnostic; read `.error` and log the +fields you choose. ### Which error union does an operation carry? -Every operation's union is generated into its own module, `{root_package}/errors/{operation}_error.py`, +Every operation's union is declared in its own module, `{root_package}/errors/{operation}_error.py`, as a type alias: ```python @@ -56,16 +64,14 @@ Four places give you that alias, in order of preference: 1. **The contract sheet** — it lists the union per operation. 2. **The operation's map block** (`map/operations/{group}.md`) — its **Error** line names the alias and its case, and its **Error arms** bullet lists each arm *with the HTTP statuses it maps from*. - This is where the sheet's row should have come from. 3. **The operation's docstring**, whose `Raises:` section ends with the union verbatim: `` `error` is `{TypedError} | RawError`. `` 4. **The error module itself**, whose `map` is a `match` on `status_code` naming the schema each status decodes to. -**`RawError` is always the last arm.** The generator emits it unconditionally as the catch-all, so -every operation can hand you a `RawError` for any status it does not document — there is no operation -whose failure is guaranteed typed. An operation that documents *no* error schema has no error module -at all and always yields `RawError`. +**`RawError` is always the last arm**: any status the operation does not document yields `RawError`, +so no operation's failure is guaranteed typed. An operation that documents *no* error schema has no +error module at all and always yields `RawError`. ### Narrowing the union @@ -73,16 +79,13 @@ at all and always yields `RawError`. > per-operation error unions, or an operation whose alias is `RawError` alone (Case B), has nothing to > narrow — `e.error` is always `RawError` there. Skip to *Result-style alternative* for those. -**The typed arm is not one type across the API, and assuming it is is the mistake that costs the -afternoon.** A description that declares a different error schema per tag gets a different model per -tag, so a check written against one operation's arm silently fails on another's — those failures fall -through to the `RawError` branch and lose every field they actually carried. Take the arm from the -contract sheet per operation — the map's **Error arms** bullet is per-operation for exactly this -reason — never reuse one from a sibling call. +**The typed arm differs per operation.** A check written against one operation's arm silently falls +through to the `RawError` branch on another's and loses every field it carried, so take each +operation's arms from its own sheet row or the map's per-operation **Error arms** bullet — never from +a sibling call. An operation can also declare **more than one** typed arm — one per documented status or status -*range* (`4XX`, `5XX` are legal), so a union may read `{TypedError1} | {TypedError2} | RawError`. -Handle each arm you declared. +*range* (`4XX`, `5XX`), so a union may read `{TypedError1} | {TypedError2} | RawError`. Handle each. Narrow with `match` or `isinstance` — a type checker understands both — on a class arm only; a `oneOf` alias is not a class either, so match its variants. After narrowing the class arms, what remains is @@ -120,8 +123,9 @@ undocumented case — so prefer `text()` for logging unless you know better. ## Result-style alternative — `with_raw_response` (no raising) -Every operation has a raw peer reached through `with_raw_response`, which returns the outcome instead -of raising: +Every operation's raw peer, reached through `with_raw_response`, returns the outcome instead of +raising — **2xx is `Success`, everything else is `Failure`**, both carrying `.status_code` and +`.headers` (`python-calling-endpoints` has the mechanics): ```python from {root_package}.core import Success, Failure @@ -133,54 +137,41 @@ match client.{Group}.with_raw_response.{Operation}(...): ... # 'err' is the same union as the raising path ``` -`Success` and `Failure` are frozen dataclasses, so pattern matching needs nothing added; both carry -`.status_code` and `.headers` as fields of their own. On the **success** path this mode is the only -way to read either — except for a file response, which carries its own `headers` on the parsed path. -On the failure path `ApiError` already carries both, so the choice there is about whether you want an -exception, not about what you can see. `unwrap(result)` (from `{root_package}.core`) collapses either -back to the raising behaviour — in fact every parsed method is literally `unwrap(...)` around its raw peer. - -The split is mechanical: **2xx is `Success`, everything else is `Failure`.** No nuance, no per-status -judgement. Use this variant when you need the status code or headers on the *success* path, or when a -non-2xx is an expected outcome rather than an exception. - -**This mode is not exception-free.** See the next section: a decode failure raises in both modes, and -so does a failed token fetch. Mapping a `Failure` to your own error uses the same function as the -raising path — see *Guarding every call site*. +On the failure path `ApiError` already carries the status and headers, so choosing this mode there is +about whether you want an exception — use it when a non-2xx is an expected outcome. **It is not +exception-free**: the rest of the family — a decode, connection or authentication failure — raises in +both modes (next section). Map a +`Failure` through the same function as the raising path — see *Guarding every call site*. ## The failures that are not `ApiError` -Each of these reaches your boundary without matching `except ApiError`. - -### Decode failures — and they bypass *both* response modes +Each of these reaches your boundary without matching `except ApiError`, and each is an `SdkError`. -If a body does not deserialize, decoding raises `pydantic.ValidationError` (a subclass of -`ValueError`), or a plain `ValueError` when the body is not JSON at all. The pipeline states the rule -outright: *a deserialization failure is not an API error, so it propagates in both response modes -rather than becoming a failure.* `with_raw_response` does **not** convert it into a `Failure`. +### Decode failures — `ResponseDecodeError`, in *both* response modes -It arrives from two directions that mean opposite things: +If a body does not deserialize, the call raises `ResponseDecodeError` — pydantic's `ValidationError`, +or the parser's `ValueError` for a body that is not JSON at all, is its `__cause__` — in both response +modes: `with_raw_response` does **not** convert it into a `Failure`. Its `status_code` tells apart two +cases that mean opposite things: - **A 2xx whose body drifted** → the call may well have *succeeded* server-side and you cannot read - the result. The outcome is **unknown**. For a write, re-read state rather than retrying blindly. + the result. The outcome is **unknown** (a 5xx at your boundary). For a write, re-read state rather + than retrying blindly. - **A non-2xx whose body does not match the declared error schema** → the request was **rejected**; - only the detail was lost. Retrying is pointless, since it can never succeed. - -Mapping both to a 5xx is wrong half the time. At minimum, do not report a deterministic rejection as -an outage. + only the detail was lost. Retrying can never succeed, so do not report it as an outage — a 5xx tells + a retrying caller to keep retrying. -**On the success path this fires far less often than you would expect, and the gap it leaves is -worse.** Models are generated with required members only where the description marks them required — -which is frequently nowhere — and every other member defaults to `UNSET`. A response missing a field -therefore validates cleanly: +**On the success path a missing member does not raise.** Only a model's bare-annotated members are +required — on a response model often none — and every other member defaults to `UNSET`, so a response +missing a field validates cleanly: ```python value = client.{Group}.{Operation}(...) # 200 with a truncated or empty body value.{member} # UNSET — not an exception, not None ``` -A `ValidationError` on a 2xx means a *type* mismatch or a non-JSON body, not an absent field. So the -guard belongs somewhere else than you would place it by habit: +A `ResponseDecodeError` on a 2xx means a *type* mismatch or a non-JSON body, not an absent field. Guard the +members you depend on, immediately after every call that matters: ```python value = client.{Group}.{Operation}(...) @@ -188,24 +179,15 @@ if value.{member} is UNSET: raise ProviderError(502, "{Operation} returned no {member}", outcome_unknown=True) ``` -**Assert on the members you depend on, immediately after every call that matters.** For a write, an -absent identifier has the same "outcome unknown" character as a decode failure — the call may have -taken effect and you cannot name what it created. Nothing in the SDK does this for you. - -### Transport failures — the HTTP library's exceptions, unwrapped - -The SDK does **not** wrap its transport's exceptions where you catch them. The protocol says -implementations *may raise their underlying library's exceptions*; the shipped transport reports a -failed send to the retry loop, and when the last attempt fails the pipeline raises the library's own -exception. So connection refused, DNS failure, TLS error, dropped socket and timeout all reach you as -`httpx2` exceptions. +For a write, an absent identifier is "outcome unknown" like a decode failure — the call may have taken +effect and you cannot name what it created. Nothing in the SDK does this for you. -⚠ **`httpx2.HTTPError` is the base class of every one of them, timeouts included.** A lone -`except httpx2.HTTPError` arm therefore catches connection-refused and read-timeout together and gives -them one outcome — and those are opposite facts. +### Connection failures — `SdkConnectionError`, the library's exception on `__cause__` -**Which transport failures reached the server, and which did not.** This is a property of the -exception class, not a judgement call: +Connection refused, DNS failure, TLS error, dropped socket and timeouts reach you — after the last +attempt — as `SdkConnectionError`, with the `httpx2` exception on `__cause__`; a timeout is its leaf +`SdkTimeoutError`, whose `timeout` is the window that elapsed. Whether the request reached the server +is a property of the **cause's** class: | exception | did the request reach the server? | outcome | | --- | --- | --- | @@ -217,100 +199,104 @@ exception class, not a judgement call: | `httpx2.WriteTimeout` | **maybe** — sending was interrupted mid-body | **unknown** | | `httpx2.RemoteProtocolError` | **maybe** — the peer closed after the request went out | **unknown** | -`ConnectTimeout`, `PoolTimeout` and `ReadTimeout` are all `httpx2.TimeoutException` and they fall on -**opposite sides of this table**, so splitting on `TimeoutException` does not split on the thing that -matters. Split on whether the request was ever sent: +`ConnectTimeout`, `PoolTimeout` and `ReadTimeout` all arrive as `SdkTimeoutError` yet fall on +**opposite sides of this table**, so `except SdkTimeoutError` does not split them — test `__cause__`: ```python import httpx2 +from {root_package}.core import SdkConnectionError -except (httpx2.ConnectError, httpx2.ConnectTimeout, httpx2.PoolTimeout, httpx2.ProxyError) as e: - # Nothing reached the provider. Fail the operation outright; there is nothing to reconcile. - ... -except httpx2.RequestError as e: - # It may have landed. Record the outcome as UNKNOWN and reconcile before any retry. - ... -``` +NEVER_SENT = (httpx2.ConnectError, httpx2.ConnectTimeout, httpx2.PoolTimeout, httpx2.ProxyError) -Catch `httpx2.RequestError`, not `httpx2.HTTPError`, in that second arm. `HTTPError` is also the base of -`HTTPStatusError` — what `raise_for_status()` raises — and that one means a **complete response -arrived**, so sweeping it into the unknown-outcome arm mislabels the one case that is fully known. - -⚠ **`PoolTimeout` is the one to get right.** It is the characteristic failure of a saturated sync -client, which is the setup this skill recommends — so it arrives *in bulk*, exactly when the system is -already under strain. Marking it unknown floods reconciliation with work at the worst moment, for -requests that were never sent. - -**Only the second arm has an unknown outcome.** Marking a refused connection "unknown" is not the -cautious default: it schedules reconciliation for an event that provably did not happen, and it -trains the caller to distrust a failure that is in fact definitive. +except SdkConnectionError as e: + if isinstance(e.__cause__, NEVER_SENT): + ... # Nothing reached the provider. Fail the operation outright; there is nothing to reconcile. + else: + ... # It may have landed. Record the outcome as UNKNOWN and reconcile before any retry. +``` -Note the coupling: your error boundary imports the transport's exception types because the SDK's -transport does. If you supply a custom transport (`python-client-initialization`), it is *your* -transport's exceptions that arrive and this clause needs revisiting. +A `__cause__` of `None` (a custom transport that chained nothing) falls to the unknown arm, the safe +one. `PoolTimeout`, the saturated-pool failure that arrives in bulk under load, was never sent; +marking it unknown floods reconciliation with requests that never left. A custom transport +(`python-client-initialization`) raises this family too, with *its* library's classes on `__cause__`, +so `NEVER_SENT` needs those. ### A streamed download moves the failure out of the call -An operation that returns a file is one place where the call returning successfully does not mean -the transfer succeeded. The pipeline yields as soon as the response *head* arrives; the body is still -on the socket. So a connection dropped mid-transfer raises out of `read()`, `iter_bytes()` or -`save_to(...)` — not out of the call — and a `try` wrapped around the call alone catches nothing: +A file response returns as soon as the *head* arrives, so its status and headers are final, but a +connection dropped mid-transfer raises out of `read()`, `iter_bytes()` or `save_to(...)` — not out of +the call — and a `try` wrapped around the call alone catches nothing (`python-file-handling` has the +lifecycle, async included): ```python f = client.{group}.{operation}(...) # returns on the head; nothing is downloaded yet try: - f.save_to("out.bin") # the transport failure surfaces here -except httpx2.RequestError: + f.save_to("out.bin") # the connection failure surfaces here +except SdkConnectionError: ... ``` -Three consequences. The status code and headers are trustworthy before the body is — a `Failure` on a -streamed call is a real outcome, not a guess. A partial write is possible, which is why `save_to` -stages through `.part` and renames only on success, so a failed download never appears under the -final name. And `request_options={"timeout": ...}` bounds **each read**, not the call as a whole, so a -stalled transfer raises rather than hanging. The same holds on the async client, with the failure -raising out of the awaited consumer. `python-calling-endpoints` has the lifecycle itself. - ### An event stream raises from the loop An operation that returns an event stream succeeds as soon as the head arrives, like a download. What -follows raises from the **loop**: a frame the event type rejects raises pydantic's `ValidationError` -after the stream has closed, an oversized event or bad UTF-8 raises `ValueError`, and a dropped or -stalled connection raises `httpx2.RequestError` — there is no SSE exception class. +follows raises from the **loop**: a frame the event type rejects, an oversized event or bad UTF-8 +raises `ResponseDecodeError` after the stream has closed, and a dropped or stalled connection raises +`SdkConnectionError` — there is no SSE-specific class. `python-event-streams` has the full table. -### Authentication failures wear the same exception +### A paginator raises from the loop + +A paginated operation sends nothing at the call — it returns a `Paginator` — so its failures arrive +while iterating. Parsed item iteration raises `ApiError` at the failed page, after every item before +it: **wrap the `for`, not the call**. + +```python +try: + for item in client.{group}.{operation}(...): + ... +except ApiError as e: + ... +``` + +Raw mode never raises for an API error. Iterating the raw paginator for items yields the items of +every successful page and ends at the failed one; `iter_pages()` yields each page's `ApiResult`, and +a `Failure` is the last one it yields, so the walk ends there with the error body and no exception. +`ResponseDecodeError` and `SdkConnectionError` still raise from either loop, and a link walk raises +`ValueError` on a next link to a different origin. + +### Authentication failures — `AuthSchemeError` -A failed token fetch raises `ApiError` — but its payload is `OAuthProviderError | RawError`, **not** -the operation's union. Two consequences: +A credential that could not be applied raises `AuthSchemeError`, naming **your** call, not the token +endpoint's, so an `except ApiError` around the call never catches a token endpoint's `401`. The +scheme's own failure is `__cause__`, and every failure is in `scheme_failures`: + +| `e.__cause__` | What happened | +|---|---| +| `ApiError` (its `error` a `RawError`) | the token endpoint refused; the RFC 6749 `error` code is in `e.__cause__.error.json()` | +| `SdkConnectionError` | the token endpoint could not be reached | +| `ResponseDecodeError` | the token endpoint answered with a body it should not have | +| `AnySchemesError` | every configured member of an OR requirement raised | +| anything else | your own scheme or token source raised it, or a client hook did on the token request (`python-configuration-resilience`) | + +Two consequences: - It surfaces out of the **operation call**, because the token is fetched lazily on first use. The traceback points at whichever operation ran first, not at the client you configured. - It raises in `with_raw_response` mode too, because the fetch happens while the request is being built, before anything is sent. -Check it **first** in the ladder — nothing was ever sent, so it is a configuration fault, not a -rejection: - -```python -from {root_package}.core import OAuthProviderError - -except ApiError as e: - if isinstance(e.error, OAuthProviderError): - raise ProviderError(502, "provider refused our credentials") from e - ... -``` +Nothing was ever sent, so it is a configuration fault, not a rejection. The `except AuthSchemeError` +arm below maps it that way. -**A missing credential raises nothing at all.** The SDK never refuses to send a request because a -credential is absent — an unconfigured scheme contributes nothing and the request goes out -unauthenticated, so the server decides. With composite (AND/OR) security this holds too: a partial -set is applied as-is rather than withheld. There is no local "auth could not be satisfied" exception -to catch; you get a `401` from the provider instead. See `python-authentication`. +**A missing credential raises nothing**: the request goes out without it and the provider answers, +typically `401` (`python-authentication`). ### Your own mistakes -`ValidationError` from constructing a model with a missing or wrong-typed member, and `TypeError` from -passing a positional argument to a keyword-only signature, are programming errors. Let them fail +`ValidationError` from constructing a model with a missing or wrong-typed member, `TypeError` from +passing a positional argument to a keyword-only signature, and the `ValueError` for a value the SDK +refuses before sending (a path value its type rejects) are programming errors. None is an +`SdkError`. Let them fail loudly in development; do not let a production ladder swallow them. ## Guarding every call site @@ -321,8 +307,8 @@ job, a health check). A connection failure during a read fails just as hard as o call left unguarded next to one that is guarded is the one that breaks. **Convert failures to your own type in one place**, so the rest of the code has a single failure type -rather than four unrelated ones. The type is yours — the SDK's only exception class is `ApiError`; -transport and decode failures arrive as library exceptions, below. If your codebase already has an +rather than several. The type is yours: the SDK's family says *what happened*, and yours carries *what +your boundary answers*. If your codebase already has an error type, give it these two fields instead of adding another: ```python @@ -338,14 +324,15 @@ arms whichever way you called (below): ```python import httpx2 -from pydantic import ValidationError -from {root_package}.core import ApiError, OAuthProviderError +from {root_package}.core import ApiError, AuthSchemeError, ResponseDecodeError, SdkConnectionError from {root_package}.models import {TypedError} +NEVER_SENT = (httpx2.ConnectError, httpx2.ConnectTimeout, httpx2.PoolTimeout, httpx2.ProxyError) + def provider_error(status, error) -> ProviderError: match (status, error): # OUR credentials or OUR quota: the caller did nothing wrong and cannot fix it. - case (401 | 403, _) | (_, OAuthProviderError()): + case (401 | 403, _): return ProviderError(502, "provider refused our credentials") case (429, _): return ProviderError(503, "rate-limited") @@ -366,14 +353,18 @@ try: except ApiError as e: raise provider_error(e.status_code, e.error) from e -except ValidationError as e: - raise ProviderError(502, "unreadable response", outcome_unknown=True) from e # do NOT assume failure +except AuthSchemeError as e: + raise ProviderError(502, "provider refused our credentials") from e # never sent: configuration -except (httpx2.ConnectError, httpx2.ConnectTimeout, httpx2.PoolTimeout, httpx2.ProxyError) as e: - raise ProviderError(502, "Never sent.", outcome_unknown=False) from e # KNOWN: nothing happened +except ResponseDecodeError as e: + if 200 <= e.status_code < 300: + raise ProviderError(502, "unreadable response", outcome_unknown=True) from e # do NOT assume failure + raise provider_error(e.status_code, None) from e # rejected; detail lost -except httpx2.RequestError as e: - raise ProviderError(504, "No response.", outcome_unknown=True) from e # UNKNOWN: may have landed +except SdkConnectionError as e: + if isinstance(e.__cause__, NEVER_SENT): + raise ProviderError(502, "Never sent.", outcome_unknown=False) from e # KNOWN: nothing happened + raise ProviderError(504, "No response.", outcome_unknown=True) from e # UNKNOWN: may have landed ``` **Your own time limit needs its own arm.** In async code, an `asyncio.wait_for` around the call raises @@ -381,8 +372,8 @@ except httpx2.RequestError as e: `ProviderError(504, "No response.", outcome_unknown=True)`. **The raw variant maps through the same function.** A `Failure` is a value, not an exception, so there -is nothing to chain `from`; and a refused token fetch still raises `ApiError` here (it happens before -the request is sent), so the `except ApiError` above stays around the raw call too: +is nothing to chain `from`; and a refused token fetch still raises `AuthSchemeError` here (it happens +before the request is sent), so the `except` arms above stay around the raw call too: ```python match client.{Group}.with_raw_response.{Operation}(...): @@ -392,10 +383,6 @@ match client.{Group}.with_raw_response.{Operation}(...): raise provider_error(status, err) ``` -Note the last two arms, and their order: the narrow tuple must come **first**, because -`httpx2.RequestError` is its base class and would otherwise swallow it. The two are different facts, -and a single `except httpx2.HTTPError` merges them. - ⚠ **Two arms raising the same class with the same values is not a split.** The distinction has to reach something that acts on it, or it is a comment. Note that both arms above raise the **same class** on purpose — what differs is the **values they pass**, so there is no way to write either @@ -412,26 +399,9 @@ except ProviderError as e: return error_response(e.status_code, safe_message) # 502 never sent · 504 outcome unknown ``` -**Then write the test that tells the two apart.** This is what decides whether the split is real. The -check is not "are there two arms" but **"does one assertion pass for both inputs?"** — if it does, the -distinction is not real, however well the production branch reads: +Test that the two inputs yield different `(status_code, outcome_unknown)` (`python-testing`). -```python -def test_unsent_is_not_the_same_failure_as_unknown(): - unsent = failure_from(httpx2.ConnectError("refused")) # never left the process - unknown = failure_from(httpx2.ReadTimeout("no reply")) # may have landed - - assert (unsent.status_code, unsent.outcome_unknown) == (502, False) - assert (unknown.status_code, unknown.outcome_unknown) == (504, True) - assert unsent.status_code != unknown.status_code # the caller can tell them apart - assert reconciled() == [unknown.reference] # and only one reconciles -``` - -Two tests asserting the *same* exception for a refused connection and a read timeout is this defect -wearing a passing suite. - -Always `raise ... from e`. Losing `__cause__` costs you the traceback that names which of the four -paths you were on. +Always `raise ... from e`. Losing `__cause__` costs you the traceback that names which path you were on. ## Presenting failures at your boundary @@ -445,34 +415,21 @@ unknown error has no meaningful client status and belongs at 5xx. Collapsing eve blanket status discards the only signal separating "you sent something invalid" from "the provider is down". -**Not every provider failure is the caller's fault.** A `401`/`403` means *your* credentials are wrong, -and a `429` means *your* quota is spent — passing either straight through tells the caller they are -unauthenticated or throttled when they are neither. Those belong at 5xx (the `match` above), and so -does the default arm. - -**An unreadable body is two cases, not one — decide which before you map it.** An unreadable -*success* body is genuinely unknown: 5xx. An unreadable *error* body is not — the provider rejected -the request and only the detail was lost, so answering 5xx tells a retrying caller to keep retrying -something that can never succeed. - **Never map a parse failure onto a domain absence.** "I could not read the answer" is not "the provider said no". On a lookup both leave you without a record, but only one is a fact — and where a lookup gates a create, conflating them turns a corrupt response into a spurious create. If a miss is signalled by an empty body, match on *empty*, not on *unparseable*. -**Never surface `str(e)` or a traceback to your caller.** For an SDK exception the string is only -`HTTP 422: {TypedError}`, so it is useless as well as leaky; a `ValidationError` embeds pydantic type -and field-path detail. Log the detail, return a message you wrote. +**Never surface `str(e)` or a traceback to your caller** — an `SdkError`'s message names the provider's +URL, and its `__cause__` (a pydantic `ValidationError`, an `httpx2` error) embeds field-path and host +detail. Log the detail, return a message you wrote. ## Notes -- **Retries are on by default.** A retryable status or transport failure surfaces only after the last - attempt, and the exception you catch is the same one a single attempt would raise. With `max_retries` - set to `0` nothing is resent. See `python-configuration-resilience`. -- **A `401` invalidates the cached credential but does not retry the request.** Your code sees one - `401` (your boundary answers it as `502`), and the *next* call obtains - a fresh token. Do not read a single 401 as a permanent credential failure. -- `ApiError` implements `__reduce__`, so it pickles — it survives crossing a process boundary (a - Celery result, a multiprocessing queue) with its payload intact. -- `e.headers` has **lowercased keys**, guaranteed by the transport contract — look up - `"x-request-id"`, never `"X-Request-Id"`. +- **Retries are on by default**; what you catch is the last attempt's failure, the same one a single + attempt would raise (`python-configuration-resilience`). +- **A `401` drops the cached token without retrying the call** (`python-authentication`): your code + sees one `401` — your boundary answers `502` — and the next call fetches a fresh token. +- Every `SdkError` pickles, so it survives crossing a process boundary (a Celery result, a + multiprocessing queue) with its payload intact; `copy` and `deepcopy` work too. +- Your own cancellation (`KeyboardInterrupt`, `asyncio.CancelledError`) is never wrapped. diff --git a/plugins/spotify/skills/python/python-event-streams/SKILL.md b/plugins/spotify/skills/python/python-event-streams/SKILL.md index 90ce063f..9ff44026 100644 --- a/plugins/spotify/skills/python/python-event-streams/SKILL.md +++ b/plugins/spotify/skills/python/python-event-streams/SKILL.md @@ -1,6 +1,6 @@ --- name: python-event-streams -description: Consuming a server-sent-events (text/event-stream) operation on an APIMatic-generated Python SDK — what EventStream[T] / AsyncEventStream[T] yields, how the loop must end so the connection is released, narrowing a union of event types, what raises and when (there is no SSE exception class), the silent failures, and bounding the wait. Load before writing the loop over an operation that returns an event stream, in addition to `python-calling-endpoints`. +description: Load before writing the loop over an APIMatic-generated Python SDK operation that returns a server-sent-events (text/event-stream) stream, together with `python-calling-endpoints`. Covers what EventStream[T] / AsyncEventStream[T] yields, ending the loop so the connection is released, narrowing event unions, what raises from the loop, and bounding the wait. --- # Event streams on an APIMatic Python SDK @@ -74,17 +74,16 @@ does **not** — it leaves `T | UnsetType`. | What failed | Parsed call | `with_raw_response` | |---|---|---| | a non-2xx status (the head) | raises `ApiError` at the call | returns `Failure` — no raise | -| a frame the event type rejects | raises pydantic's `ValidationError` from the loop, **after** the stream closed | same | -| an event over 1 MiB, or bad UTF-8 | raises `ValueError` / `UnicodeDecodeError` from the loop | same | -| the wire stalls | raises `httpx2.ReadTimeout` from the loop | same | -| the connection drops mid-stream | raises an `httpx2.RequestError` subclass from the loop, such as `RemoteProtocolError` or `ReadError` | same | +| a frame the event type rejects | raises `ResponseDecodeError` from the loop, **after** the stream closed; pydantic's `ValidationError` on `__cause__` | same | +| an event over 1 MiB, or bad UTF-8 | raises `ResponseDecodeError` from the loop; the `ValueError` / `UnicodeDecodeError` on `__cause__` | same | +| the wire stalls | raises `SdkTimeoutError` from the loop; `httpx2.ReadTimeout` on `__cause__` | same | +| the connection drops mid-stream | raises `SdkConnectionError` from the loop; an `httpx2` error such as `RemoteProtocolError` or `ReadError` on `__cause__` | same | | **the connection closes a body with no `Content-Length` that is not chunked** | **nothing — the loop ends early** | same | | **the body is not an event stream** | **nothing — the loop ends with zero events** | same | -**There is no SSE exception class.** Everything the loop raises for a bad body is already a -`ValueError`, so one `except ValueError` covers the family. A stalled or dropped connection is not a -bad body: it raises `httpx2.RequestError` (`ReadTimeout` included), so catch that too. Put both -boundaries around the **loop**, not only the call — the call returns as soon as the head arrives. +**There is no SSE-specific exception class.** A bad body is `ResponseDecodeError` and a stalled or +dropped connection `SdkConnectionError`, both `SdkError`, so one `except SdkError` covers the loop. Put +the boundary around the **loop**, not only the call — the call returns as soon as the head arrives. The last row is a known gap: the SDK does not check `Content-Type`, so a 200 carrying a proxy's HTML page or a buffered JSON body parses as a stream of zero events and ends quietly. If a stream yields diff --git a/plugins/spotify/skills/python/python-file-handling/SKILL.md b/plugins/spotify/skills/python/python-file-handling/SKILL.md index df25a80e..eb832423 100644 --- a/plugins/spotify/skills/python/python-file-handling/SKILL.md +++ b/plugins/spotify/skills/python/python-file-handling/SKILL.md @@ -1,6 +1,6 @@ --- name: python-file-handling -description: Sending and receiving files with an APIMatic-generated Python SDK — which arm of the upload alias to hand an endpoint and what each one costs in memory, re-sendability and ownership, the three behaviours that differ between a multipart part and a raw body, when a body goes out chunked rather than sized, overriding a filename or media type, and consuming a streamed file response without leaking its connection. Load before passing a file to an operation or consuming one it returns, in addition to `python-calling-endpoints`. +description: Load before passing a file to an APIMatic-generated Python SDK operation or consuming a file it returns, together with `python-calling-endpoints`. Covers which upload arm to pass and its memory, re-send and ownership costs, multipart part vs raw body, chunked vs sized bodies, filename and media-type overrides, and consuming a file response without leaking its connection. --- # File handling on an APIMatic Python SDK @@ -17,8 +17,9 @@ AsyncFileInput = AsyncBinaryContent | NamedFile[AsyncBinaryContent] # asyn ``` So you make exactly one choice: **where the bytes come from**. The destination is fixed by the -endpoint, and the flavour by the client. All of these are imported from `{root_package}.core`, and -`list[FileInput]` is an array part. +endpoint, and the flavour by the client. These aliases and their content unions, `NamedFile`, the two +reader protocols and the two response classes are all imported from `{root_package}.core` — they are +not re-exported from the package root — and `list[FileInput]` is an array part. Nothing validates what you pass, so a wrong arm is a type error at build time and a wrong *value* is a failure at send time. What each arm accepts is wider than the annotation suggests. @@ -67,10 +68,8 @@ These are the only places the position still matters, and none of them is visibl windows rather than one whole `bytes` from an `AsyncIterable` — your pieces are forwarded as you yield them, so a single large `bytes` is resident before the SDK ever sees it. - So **do not reach for an async handle over a file you could have named.** `anyio.open_file(p)` in - a part costs two reads and a write where `Path(p)` costs one read. The async arms earn their keep - when there is no path — bytes arriving from another connection, a queue, a subprocess — and cost a - round trip through the filesystem when there is one. + So prefer `Path(p)` to `anyio.open_file(p)` in a part — one read instead of two reads and a write; + the async arms are for bytes with no path behind them (another connection, a queue, a subprocess). On the **async client**, reading a *sync* arm inside a multipart body occupies the event loop while it reads, so `bytes` and the async arms are the spellings that never block it there. A raw body has @@ -109,8 +108,8 @@ client.{group}.{operation}(NamedFile(b"...", filename="invoice.pdf", media_type= Set `filename` and it wins over a `Path`'s own name and a handle's `.name` alike, so wrapping a named source renames it rather than being ignored. -**Every file currently goes out as `application/octet-stream`** whatever the spec declares, so -`NamedFile(content, media_type=...)` is the only way to send anything else. If the server validates a +**Every file goes out as `application/octet-stream`** unless you pass +`NamedFile(content, media_type=...)` — the only way to send anything else. If the server validates a part's `Content-Type`, say the type yourself. ## There is no `str` arm @@ -161,30 +160,24 @@ Both iterators take a `chunk_size`, defaulting to 64 KiB. f.aread()`, `async for chunk in f.aiter_bytes()`, `await f.aclose()`, and `async with` as the spelling to reach for. **`save_to` is the exception**: it keeps its name and is awaited — `await f.save_to("out.bin")` — so there is no `asave_to`. Calling it without `await` creates a coroutine - and drops it: nothing is written and the connection stays held. An abandoned response defers its - warning to loop shutdown, where it is far less useful — and that warning is silenced by default - too. + and drops it: nothing is written and the connection stays held. An abandoned async response defers + its warning to loop shutdown, and that `ResourceWarning` is hidden by Python's default warning + filters — so the leak is silent unless you enable it. - **`save_to` accepts a directory**, naming the file from the server's `Content-Disposition` — reduced to a safe basename first, because that header is attacker-controlled — and raising `ValueError` when - the server sent no filename, or sent one that reduces to nothing safe to create: empty, `.` or - `..`, a reserved device name (`CON`, `NUL`, `COM1`…), or longer than 255 characters. It writes - `.part` and moves it into place atomically, so an interrupted download never appears under + the server sent no filename or none that is safe to create: empty, `.` or `..`, a reserved device + name (`CON`, `NUL`, `COM1`…), or longer than 255 characters. It writes `.part` and moves it + into place atomically, so an interrupted download never appears under the final name. If the destination cannot be opened at all — a missing parent directory, or permissions — the response is still consumable. - **The head has already arrived**, so `headers`, `media_type`, `content_length` and `filename` are readable before you read a byte. `filename` is the server's suggestion and may be `None`. - **`request_options={"timeout": ...}` bounds each read of the body**, not the call as a whole, so a - stalled download raises rather than hanging. -- **A transport failure mid-download raises out of the *read*, not out of the call.** The call already + stalled download raises `SdkTimeoutError` rather than hanging. +- **A connection failure mid-download raises `SdkConnectionError` out of the *read*, not out of the call.** The call already returned successfully — only the head had arrived — so a `try` wrapped around the call alone catches nothing. Put the boundary around the consuming code (`python-error-handling`). With `with_raw_response`, the payload is the same unread `FileResponse`. The raw peer buys you the status code and headers, not the bytes — a result carries no body of its own, because here the body *is* the payload. - -## Where these types live - -Import all of them from `{root_package}.core`: the two aliases and their content unions, `NamedFile`, -the two reader protocols, and the two response classes. They are not re-exported from -`{root_package}/__init__.py`, so the package root is not where to look for them. diff --git a/plugins/spotify/skills/python/python-getting-started/SKILL.md b/plugins/spotify/skills/python/python-getting-started/SKILL.md index 55fbe788..f50ccd2d 100644 --- a/plugins/spotify/skills/python/python-getting-started/SKILL.md +++ b/plugins/spotify/skills/python/python-getting-started/SKILL.md @@ -1,20 +1,16 @@ --- name: "python-getting-started" -description: "Spotify Web API Python SDK identity and lookup layer (Python only) — install, import root, base URL/environments, the auth pattern, the SDK map that ships at the SDK root (`sdk-map.md` + `map/operations/`) and how to traverse it, and the module table naming the one file owning each fact the map leaves to the source. Load this before answering any Spotify Web API Python SDK contract question or writing any SDK code." +description: "Load before answering any Spotify Web API Python SDK question or writing Python code against the SDK (Python only). The SDK's lookup layer: install, imports, environments and base URL, auth, the SDK map (`sdk-map.md` + `map/operations/`) and how to read it, and the module that owns each fact the map leaves to the source." --- # Getting started with the Spotify Web API Python SDK -> **Who this skill is for.** This is the **lookup layer** for anyone writing Spotify Web API Python SDK code — it is yours to follow directly and fully. Ground every contract fact here (in the SDK map, and in the source modules it names) rather than in recall, and carry those facts onto a contract sheet before you implement. Load `python-integrate-spotify-web-api` for the workflow that wraps this skill. +> **Lookup layer** for Spotify Web API Python SDK code: ground every contract fact here, in the SDK map and in the source modules they name — never in recall — and carry those facts onto a contract sheet before you implement. `python-integrate-spotify-web-api` holds the workflow around it. -This is the **SDK-specific** entry point. For general patterns that apply to any APIMatic-generated Python SDK (client construction, auth, calling endpoints, models, error handling, resilience, testing), see the companion API-agnostic skills: `python-client-initialization`, `python-authentication`, `python-calling-endpoints`, `python-models`, `python-error-handling`, `python-configuration-resilience` and `python-testing`. - -**This page and those companion skills are complementary — load both.** This page is authoritative for the SDK's *identity and surface* (what to install, what to import, the controllers, which module owns which fact); the companion skills are the *usage layer* on top — the best-practice way to call each piece and the gotchas a signature cannot show. Reading a module in the installed package does not remove the need to load the skill for that step, so at each step below, load the companion *and* confirm names against the installed package. +This page owns the SDK's *identity and surface* (install, imports, controllers, which module owns which fact). The API-agnostic companion skills own *usage* — `python-client-initialization`, `python-authentication`, `python-calling-endpoints`, `python-models`, `python-error-handling`, `python-configuration-resilience` and `python-testing`; load each at its step (see **Integration workflow**) and confirm names against the installed package. ## SDK identity -Verified against `spotify_web_api/` and `pyproject.toml` of the generated package at version `2024.3.3`. **Re-verify after a version bump** — this page is a snapshot, not a live read. - | Fact | Value | | --- | --- | | API | Spotify Web API | @@ -22,21 +18,18 @@ Verified against `spotify_web_api/` and `pyproject.toml` of the generated packag | Import root (what you import) | `spotify_web_api` — not the string you install | | Source repository | https://github.com/context-plugins/spotify-python-sdk | | Source branch | `main` | -| Version | `2024.3.3` | +| Version | `2024.3.3` — re-verify this page after a version bump | | Sync client class | `SpotifyWebApiClient` (alias `Client`) | | Async client class | `AsyncSpotifyWebApiClient` (alias `AsyncClient`) | -| Client construction | **keyword-only**: `environment` · `base_url` · `timeout` (default `30.0`) · `retry_options` · `oauth_2_0` · `oauth_2_0_token_source` · `oauth_2_0_client_credentials` · `oauth_2_0_client_credentials_token_source`, and the transport override — `custom_http_client` on the sync client, `custom_async_http_client` on the async one (the names differ; see step 1) | +| Client construction | **keyword-only**: `server_config` · `timeout` (default `30.0`) · `retry_options` · `logging_options` · `hooks` · `oauth_2_0` · `oauth_2_0_token_source` · `oauth_2_0_client_credentials` · `oauth_2_0_client_credentials_token_source`, and the transport override — `custom_http_client` on the sync client, `custom_async_http_client` on the async one (the names differ) | | Auth | **OAuth 2.0** authorization code — set `oauth_2_0` · **OAuth 2.0** client credentials — set `oauth_2_0_client_credentials` | -| Environments | 2 environments selected by `environment` (default `"production"`), overridable with `base_url` | -| Base-URL config | `ServerConfig` (`spotify_web_api/server/server_config.py`), frozen, `extra="forbid"` | +| Environments | one environment; 2 named servers configured through `server_config` | +| Base-URL config | `ServerConfig` (`spotify_web_api/server/server_config.py`) | | Python floor | **`>=3.10`** (classifiers list `3.10–3.14`) | | Runtime dependencies | `httpx2 (>=2.13.1,<3.0.0)` · `certifi (>=2024.7.4)` · `pydantic[email] (>=2.11.0,<3.0.0)` · `typing-extensions (>=4.13.0,<5.0.0)` | -| Typing | ships `py.typed`; the package is checked under `mypy --strict` with `warn_unreachable`. Callers get full inference — **a type error against this SDK is a real contract violation, not noise** | -| Line length / lint | `ruff`, 120 cols (only relevant when editing the SDK itself) | +| Typing | ships `py.typed` — **a type error against this SDK is a real contract violation, not noise** | | Surface | 138 operations across 15 controllers · 129 models · 4 unions · 18 enums · 89 per-operation error unions | -The table above is **orientation, not a copy-paste recipe** — it gives you the names and facts (install, import roots, the auth *pattern*, the base-URL knob), while the actual integration code comes from the companion skills. Load each one as you reach its step (see **Integration workflow** below) and confirm its types against the installed package. - ## Install — from source Into the same environment your project runs in, install the distribution from its repository, — it is not published to a package index: @@ -48,58 +41,56 @@ python -c "import spotify_web_api, pathlib; print(pathlib.Path(spotify_web_api._ **Run the second line too.** A `pip install` that reports success is not proof the SDK is importable where your project runs. If the probe raises `ModuleNotFoundError`, the install went into a different interpreter: re-run it through the one your project uses (`python -m pip install …`) and probe again. If it prints a path whose contents are not this SDK, what you installed is not this distribution. -The distribution carries its own `pyproject.toml`, so `pip` builds and installs it like any released package, copied into site-packages. Do not vendor its source into your project, add its directory to `sys.path`, or install it editable (`-e`) from a throwaway clone — an editable install points at that directory, so deleting the clone breaks every import. - -Once the second line prints this SDK's directory, write the imports from the table above: the distribution name you install and the package name you import are not the same string. Requires Python 3.10 or newer. +Install it as a package, into site-packages. Do not vendor its source into your project, add its directory to `sys.path`, or install it editable (`-e`) from a throwaway clone — an editable install points at that directory, so deleting the clone breaks every import. ## Imports — the package splits its surface across four modules Python does not re-export child modules transitively, so `from spotify_web_api import models` alone does **not** make enums, error unions, or runtime types reachable. Import each kind of type from the module that owns it. -`spotify_web_api/__init__.py` exports exactly 6 names beside the `spotify_web_api.models` subpackage it re-exports: +`spotify_web_api/__init__.py` exports exactly 7 names beside the `spotify_web_api.models` subpackage it re-exports: ```python from spotify_web_api import ( AsyncClient, AsyncSpotifyWebApiClient, Client, - Environment, ServerConfig, + ServerConfigDict, + ServerConfigOrDict, SpotifyWebApiClient, ) ``` -Everything else comes from its own subpackage, and the split matters because each kind of type a caller reaches for lives in a different module: +Everything else comes from its own subpackage: | What you need | Where it lives | | --- | --- | | Domain models, their `…Dict` companions | `spotify_web_api.models` | | Enums (and their open `…OrStr`/`…OrInt` aliases) | `spotify_web_api.models.enums` | -| `ApiError` · `RawError` · `ApiResult` · `RequestOptions` · `AuthorizationCodeCredentials` · `ClientCredentials` · `HttpClient` · `SdkBaseModel` · `UNSET` · `Optional` | `spotify_web_api.core` | +| `SdkError` · `ApiError` · `RawError` · `ApiResult` · `RequestOptions` · `AuthorizationCodeCredentials` · `ClientCredentials` · `HttpClient` · `SdkBaseModel` · `UNSET` · `Optional` | `spotify_web_api.core` | | Per-operation error *unions* | `spotify_web_api.errors` (`AddToQueueErrorBody`, …) | -`spotify_web_api.core` re-exports its whole public surface (a curated `__all__`), so import from `…core` rather than from the private modules beneath it (`…core.results`, `…core.exceptions`, `…core.auth.schemes`). +`spotify_web_api.core` re-exports its whole public surface, so import from `…core` rather than from the private modules beneath it (`…core.results`, `…core.exceptions`, `…core.auth.schemes`). -## Environments +## Servers — one config object, several servers -The constructor takes an `environment` keyword — a **string literal alias**, not an enum — followed by `base_url`. The declared environments and the base URL each resolves to: +This SDK has 2 named servers and a single environment, so the constructor takes `server_config: ServerConfigOrDict | None = None` rather than a bare `base_url`. Each server is a field on that config: -| `environment=` | Base URL | Hosting | -| --- | --- | --- | -| `"production"` *(default)* | `https://api.spotify.com/v1` | — | -| `"environment2"` | `https://accounts.spotify.com` | — | +| Server field | Base URL | +| --- | --- | +| `default` | `https://api.spotify.com/v1` | +| `auth_server` | `https://accounts.spotify.com` | Consequences to state on every contract sheet that touches configuration: -- Omitting `environment` gives you **`"production"`**, silently — it is whatever the description listed first, not necessarily production. -- `base_url` overrides the environment's URL entirely when both are passed. -- The token endpoint is derived from the same base URL (`/api/token`), so it always follows the environment — you never configure it separately. +- Omitting `server_config` falls through to the config's own defaults rather than writing `None` over them. +- The token endpoint (`/api/token`) resolves against the `auth_server` server rather than a client-wide base URL, so `server_config` is what moves token traffic. - `ServerConfig` is a frozen pydantic model with `extra="forbid"`: a misspelled keyword raises `ValidationError` at construction rather than being ignored. - `timeout` is validated too — the base client raises `ValueError` for any non-positive value. ## Auth pattern (two schemes) -OAuth 2.0 authorization code, exposed as the client's `oauth_2_0=` keyword taking `AuthorizationCodeCredentials` **or a plain dict**. The client fetches and caches the bearer token itself, lazily, from `/api/token`. +OAuth 2.0 authorization code, exposed as the client's `oauth_2_0=` keyword taking `AuthorizationCodeCredentials` **or a plain dict**. The client fetches and caches the bearer token itself, lazily, from `/api/token` on the `auth_server` server. ```python from spotify_web_api import Client @@ -112,7 +103,7 @@ client = Client(oauth_2_0=AuthorizationCodeCredentials(client_id="…", client_s client = Client(oauth_2_0={"client_id": "…", "client_secret": "…", "redirect_uri": "…", "prompt_for_authorization_code": prompt}) # equivalent ``` -OAuth 2.0 client credentials, exposed as the client's `oauth_2_0_client_credentials=` keyword taking `ClientCredentials` **or a plain dict**. The client fetches and caches the bearer token itself, lazily, from `/api/token`. +OAuth 2.0 client credentials, exposed as the client's `oauth_2_0_client_credentials=` keyword taking `ClientCredentials` **or a plain dict**. The client fetches and caches the bearer token itself, lazily, from `/api/token` on the `auth_server` server. ```python from spotify_web_api import Client @@ -122,42 +113,18 @@ client = Client(oauth_2_0_client_credentials=ClientCredentials(client_id="…", client = Client(oauth_2_0_client_credentials={"client_id": "…", "client_secret": "…"}) # equivalent ``` -**Every credentials keyword is optional at the type level and that is a trap worth flagging on every sheet.** Omit it and the client is built with `no_auth`: every request goes out unauthenticated. Nothing fails at construction. Most APIs then answer `401`; an API that serves anonymous traffic at all answers `200` and hides the omission entirely — verify the keyword is set rather than waiting for a `401` to tell you. - -See `python-authentication` for the full picture, including what a *failed token fetch* raises — it is not what a caller expects, and it is the single most common surprise in this SDK. +**Every credentials keyword is optional** — omit it and requests go out unauthenticated, with nothing failing at construction; `python-authentication` covers how to catch that, and what a *failed token fetch* raises. ## Controllers -Controllers and their operation counts (`client.`): - -| Attribute | Class | Ops | Area | -| --- | --- | --- | --- | -| `client.albums` | `Albums` / `AsyncAlbums` | 9 | `check_users_saved_albums` · `get_an_album` · `get_an_albums_tracks` · `get_an_artists_albums` · `get_multiple_albums` · `get_new_releases` · … | -| `client.artists` | `Artists` / `AsyncArtists` | 10 | `check_current_user_follows` · `follow_artists_users` · `get_an_artist` · `get_an_artists_albums` · `get_an_artists_related_artists` · `get_an_artists_top_tracks` · … | -| `client.audiobooks` | `Audiobooks` / `AsyncAudiobooks` | 7 | `check_users_saved_audiobooks` · `get_an_audiobook` · `get_audiobook_chapters` · `get_multiple_audiobooks` · `get_users_saved_audiobooks` · `remove_audiobooks_user` · … | -| `client.categories_api` | `CategoriesApi` / `AsyncCategoriesApi` | 3 | `get_a_categories_playlists` · `get_a_category` · `get_categories` | -| `client.chapters` | `Chapters` / `AsyncChapters` | 3 | `get_a_chapter` · `get_audiobook_chapters` · `get_several_chapters` | -| `client.episodes` | `Episodes` / `AsyncEpisodes` | 7 | `check_users_saved_episodes` · `get_a_shows_episodes` · `get_an_episode` · `get_multiple_episodes` · `get_users_saved_episodes` · `remove_episodes_user` · … | -| `client.genres` | `Genres` / `AsyncGenres` | 1 | `get_recommendation_genres` | -| `client.library` | `Library` / `AsyncLibrary` | 29 | `change_playlist_details` · `check_current_user_follows` · `check_users_saved_albums` · `check_users_saved_audiobooks` · `check_users_saved_episodes` · `check_users_saved_shows` · … | -| `client.markets_api` | `MarketsApi` / `AsyncMarketsApi` | 1 | `get_available_markets` | -| `client.player` | `Player` / `AsyncPlayer` | 15 | `add_to_queue` · `get_a_users_available_devices` · `get_information_about_the_users_current_playback` · `get_queue` · `get_recently_played` · `get_the_users_currently_playing_track` · … | -| `client.playlists` | `Playlists` / `AsyncPlaylists` | 16 | `add_tracks_to_playlist` · `change_playlist_details` · `check_if_user_follows_playlist` · `create_playlist` · `follow_playlist` · `get_a_categories_playlists` · … | -| `client.search` | `Search` / `AsyncSearch` | 1 | `search` | -| `client.shows` | `Shows` / `AsyncShows` | 7 | `check_users_saved_shows` · `get_a_show` · `get_a_shows_episodes` · `get_multiple_shows` · `get_users_saved_shows` · `remove_shows_user` · … | -| `client.tracks` | `Tracks` / `AsyncTracks` | 17 | `add_tracks_to_playlist` · `check_users_saved_tracks` · `get_an_albums_tracks` · `get_an_artists_top_tracks` · `get_audio_analysis` · `get_audio_features` · … | -| `client.users` | `Users` / `AsyncUsers` | 12 | `check_current_user_follows` · `check_if_user_follows_playlist` · `follow_artists_users` · `follow_playlist` · `get_current_users_profile` · `get_followed` · … | - -Every controller has an `Async…` peer whose operations are identical in name and parameters and differ solely by being awaited. Do not emit a separate row for an async operation; state the rule once on the sheet. - -The SDK map's controller table carries the same counts and links to a page per controller (`map/operations/.md`) — go there for the operations themselves. +15 controllers, reached as `client.`. Every controller has an `Async…` peer whose operations have the same names and parameter names and are awaited, their `request_options` being `AsyncRequestOptionsOrDict` — state that once on the sheet rather than a row per async operation. `sdk-map.md`'s **Operations — by controller** table lists each controller's attribute, classes and operation count, and links its page (`map/operations/.md`), one block per operation. ## SDK map — look up first, open the module second The SDK ships a generated map at its **root** — the directory holding `pyproject.toml`, the `spotify_web_api/` source directory, and these two entries: -- **`sdk-map.md`** — the index: client construction with the full constructor-keyword table, the error-handling model (`ApiError` / `ApiResult` / `RawError`, Case A vs Case B), where models, enums and error aliases live, servers and auth, and the link table into the operations pages. -- **`map/operations/.md`** — one page per controller, one `###` block per operation: the HTTP verb and route, the sync parsed signature, each parameter's role and wire name, both return types, the error alias with the status each arm maps from, and a **Type sources** table naming the module that declares every *generated* type the operation mentions. +- **`sdk-map.md`** — the index: constructor keywords, the error model (`ApiError` / `ApiResult` / `RawError`, Case A vs Case B), where models, enums and error aliases live, servers and auth, and links to the operations pages. +- **`map/operations/.md`** — one `###` block per operation: verb and route, signature, parameter roles and wire names, both return types, error arms with the status each maps from, and a **Type sources** table naming the module of every *generated* type it mentions. **Installing the distribution does not give you the map.** `pyproject.toml` ships the `spotify_web_api/` package only, so `sdk-map.md` and `map/operations/` are absent from the installed package — they live in the SDK's own source tree, at the root of its repository, , in lockstep with the code the map describes — clone it to a temporary directory, outside the project repo: @@ -169,23 +136,15 @@ Confirm the map comes from the release you installed before you read anything ou Every `Source` path on the map is relative to that SDK root, so `spotify_web_api/models/album_base.py` opens as written from there — and the same path resolves inside the installed package, which is where you read a module's body once the map has named it. -**The map is the locator; the source modules are the shapes.** Read the map first — signatures, routes, parameter roles, return types, error unions, and which module declares a type are all answered there without opening a single `.py` file. Then open the one module the map names for what it deliberately does not carry: a model's members, an enum's values, a field's wire alias. The map says so itself — *"Shapes live only in the source … Never grep for a type."* +**The map is the locator; the source modules are the shapes.** Read the map first — an operation's signature, route, parameter roles and return types, the client's constructor keywords, the `timeout` default, the members of `ApiError` / `Success` / `Failure` / `RawError`, each operation's error union with the status each arm maps from, base-URL and auth wiring, and which module declares a type are all answered there; don't open a module for them. Open the one module the map names only for what it leaves out: a model's members, an enum's values, a field's wire alias. The map says so itself — *"Shapes live only in the source … Never grep for a type."* -**The map carries shapes; what an operation *means* lives elsewhere.** When *what* to pass depends on meaning — which values a field accepts beyond its type, a rule that couples two fields, what a defaulted parameter actually selects — the map will not settle it. Open the operation's docstring in `spotify_web_api/apis/.py` (or `client.py` where operations sit on the client) and `api-reference.md` at the SDK root for that operation *before* writing the sheet row, and record what you found there. A value you already "know" for a field the map types as a plain `str` is a lookup, not a recall — the memory ban applies to it. +**Meaning is not on the map.** When what to pass depends on semantics — values a field accepts beyond its type, a rule that couples two fields, what a defaulted parameter selects — read the operation's docstring in `spotify_web_api/apis/.py` (or `client.py` where operations sit on the client) and its entry in `api-reference.md` at the SDK root before writing the sheet row, and record what you found — even for a value you think you know. `sdk-map.md` carries the invariants every operation block assumes, so load it before any `map/operations/` page; the pages are written to be read beside it. ## Contract facts — the map first, then the module -**Six of these are map lookups — don't open the module for them:** an operation's signature, parameters and return type; the client's constructor keywords; the `timeout` default; the members of `ApiError` / `Success` / `Failure` / `RawError`; an operation's error union and the status each arm maps from; base-URL and auth wiring. The table below covers everything else, and the full body behind a map row. - -Read the one module that owns the fact **inside the installed package**. Locate it first: - -```bash -python -c "import spotify_web_api, pathlib; print(pathlib.Path(spotify_web_api.__file__).parent)" -``` - -Failing that, it is under the project's environment (`.venv/Lib/site-packages/spotify_web_api` on Windows, `.venv/lib/python3.*/site-packages/spotify_web_api` elsewhere). **If the package is not installed, install it first** — see *Install* above; until then mark the fact `UNVERIFIED` and say what would settle it rather than answering from memory. Paths below are relative to that package root: +For everything the map leaves out, and the full body behind a map row, read the one module that owns the fact **inside the installed package** — locate it with the probe from *Install*. Failing that, it is under the project's environment (`.venv/Lib/site-packages/spotify_web_api` on Windows, `.venv/lib/python3.*/site-packages/spotify_web_api` elsewhere). **If the package is not installed, install it first** — see *Install* above; until then mark the fact `UNVERIFIED` and say what would settle it rather than answering from memory. Paths below are relative to that package root: | Question | Module | | --- | --- | @@ -193,9 +152,11 @@ Failing that, it is under the project's environment (`.venv/Lib/site-packages/sp | Client construction, keywords, controller wiring | `client.py`, `async_client.py`, `base_client.py` | | Timeout default and validation | `base_client.py` (`DEFAULT_TIMEOUT = 30.0`) | | The request/response pipeline, 401 handling, 2xx-vs-error split | `core/raw_client.py` | -| Exception shape (`ApiError.error`, `.status_code`, `.headers`) | `core/exceptions.py` | +| Exception family (`SdkError` and its members; `ApiError.error`, `.status_code`, `.headers`) | `core/exceptions.py` | | `Success`/`Failure`/`RawError` | `core/results.py` | | Per-call overrides | `core/request_options.py` | +| Request and response hooks | `core/hooks.py` | +| Logging options, levels and masking | `core/logging.py` | | `UNSET`, `Optional`, `OptionalNullable` | `core/optionality.py` | | Model base config, `to_dict`/`to_json` | `core/models.py` | | A model's members, required vs `UNSET`, wire aliases | `models/.py` | @@ -210,42 +171,37 @@ Failing that, it is under the project's environment (`.venv/Lib/site-packages/sp **Read scoped.** These modules carry long design docstrings; `grep -n` for the symbol and read the surrounding lines rather than whole files. Never quote a docstring's design rationale onto a contract sheet — the sheet carries facts an implementer must obey, not the reasoning behind them. -Keep lookups cheap — the rules that keep a session's context small: +Keep lookups cheap: -- Collect the contracts for **every** in-scope operation in **one** pass — signature, required members with wire aliases, the error union, enum values — into a short **contract sheet** in your plan or working notes, then implement from the sheet. Don't re-open a module per member, and never re-look-up a fact the sheet already carries. -- Recurse into a model's members only where the task actually sets them — a full transitive expansion is hundreds of rows and nobody needs it. -- Trust the interpreter over this page: if a name here ever fails to type-check or import, re-read the module the table above names and report the drift; never patch around it from memory. +- Collect the contracts for **every** in-scope operation in **one** pass — signature, required members with wire aliases, the error union, enum values — onto the contract sheet, then implement from it; never re-open a module for a fact the sheet carries. +- Expand a model's members only where the task sets them. +- If a name here fails to type-check or import, re-read the module the table names and report the drift; never patch around it from memory. ## Integration workflow — load the companion skill at each step -Before you write the code for each step, load the named companion skill — even if you have already read the relevant module. Each step calls out the trap the signature hides (in *parens*). A typical integration reaches them in this order: +Before you write the code for each step, load the named companion skill — even if you have already read the relevant module; it owns the traps the signature hides. A typical integration reaches them in this order: -1. **Client construction & lifetime** — load **python-client-initialization** before you write `Client(...)` or `AsyncClient(...)`. (*The signature won't tell you:* the constructor is keyword-only, so nothing can be passed positionally; the client owns an `httpx2` connection pool and you **must** `close()` (sync) or `await aclose()` (async) or use it as a context manager; it must be long-lived and module- or app-scoped, never rebuilt per request; the sync and async clients do not mix; and the transport-override keyword differs by client — `custom_http_client` vs `custom_async_http_client`.) -2. **Authentication** — load **python-authentication** before you set credentials. The two schemes are `oauth_2_0=` and `oauth_2_0_client_credentials=`. (*The signature won't tell you:* every credentials keyword is *optional* — omit it and every request goes out unauthenticated, with no failure at construction and not necessarily a `401` to tell you; the token is fetched lazily and cached by the client; and a **failed token fetch** raises something other than what a caller expects and **bypasses the non-raising response mode** entirely. Load secrets from the environment or a secret store, never hardcode.) -3. **Calling an endpoint** — load **python-calling-endpoints** before the first `client..(...)` call. (*The signature won't tell you:* every operation splits positional path params (and sometimes the body) from a keyword-only tail after `*`; every keyword-only parameter has a **real** default, so there is no "must pass `None` explicitly" hazard; **43 operations return `None`**, so `with_raw_response` is the only way to observe their status code; and the two response modes — raising vs `ApiResult` — behave differently on failure.) -4. **Models** — load **python-models** the moment a request/response member is not a plain string or number. (*The signature won't tell you:* `Optional[T]` here is `T | UnsetType`, **not** `typing.Optional` — `None` is not a legal value for it; models are frozen pydantic instances with `…Dict` TypedDict companions; enums are **open** (`…OrStr`/`…OrInt`), so an unknown wire value passes through as a plain `str`/`int` rather than raising; wire aliases differ from Python member names; unknown response fields are **preserved**, not dropped; and serialize via `to_dict`/`to_json`.) -5. **Error handling** — load **python-error-handling** before you write any `try/except`. (*The signature won't tell you:* there is a single `ApiError` type whose `.error` is a **per-operation union**, and a decode failure raises `ValidationError`/`ValueError`, not `ApiError`, and bypasses both response modes; `httpx2` transport exceptions reach your boundary unwrapped.) -6. **Configuration & resilience** — load **python-configuration-resilience** when you set the base URL, timeouts, retries, proxies, TLS, or logging. (*The signature won't tell you:* **retrying is on by default** — `retry_options` takes a count, a `RetryOptions` or its dict, `max_retries` set to `0` turns it off, and one call overrides it through `request_options`; a `401` is never retried; `timeout` defaults to `30.0` and is a single float that maps onto `httpx2`'s timeout semantics, limiting each wait rather than the whole call; and there is no logging hook — you wrap the transport seam.) -7. **Testing** — load **python-testing** before you stub the SDK. (*The signature won't tell you:* the seam is the **transport protocol** (`HttpClient`/`AsyncHttpClient` in `core/transport.py`) passed as `custom_http_client` — not the client class; a fake transport implements `send` and `close`, the two the protocol declares, and `send` answers with the head alone; assert on the request the SDK actually built, and cover all four failure kinds, decode failures included.) +1. **Client construction & lifetime** — load **python-client-initialization** before you write `Client(...)` or `AsyncClient(...)`. +2. **Authentication** — load **python-authentication** before you set credentials. +3. **Calling an endpoint** — load **python-calling-endpoints** before the first `client..(...)` call. +4. **Models** — load **python-models** the moment a request/response member is not a plain string or number. +5. **Error handling** — load **python-error-handling** before you write any `try/except`. +6. **Configuration & resilience** — load **python-configuration-resilience** when you set the base URL, timeouts, retries, proxies, TLS, or logging. +7. **Testing** — load **python-testing** before you stub the SDK. ## What a contract sheet must carry for this SDK Beyond the usual signatures and model members, a Python sheet is incomplete without these, because each one is a decision the implementer cannot make correctly from the signature alone: -1. **Sync or async** — which client class, and the reminder that the two do not mix. Plus the `close()`/`aclose()` obligation and where the client is held. -2. **The keyword-only boundary** for each operation: what is positional (path params, sometimes the body) and what sits after `*`. Every keyword-only parameter has a real default, so there is no "must pass `None` explicitly" hazard — say so, so nobody writes defensive `None`s. -3. **The 43 operations that return `None`** — `albums.remove_albums_user` · `albums.save_albums_user` · `artists.follow_artists_users` · `artists.unfollow_artists_users` · `audiobooks.remove_audiobooks_user` · `audiobooks.save_audiobooks_user` · `episodes.remove_episodes_user` · `episodes.save_episodes_user` · `library.change_playlist_details` · `library.follow_artists_users` · `library.remove_albums_user` · `library.remove_audiobooks_user` · `library.remove_episodes_user` · `library.remove_shows_user` · `library.remove_tracks_user` · `library.save_albums_user` · `library.save_audiobooks_user` · `library.save_episodes_user` · `library.save_shows_user` · `library.save_tracks_user` · `library.unfollow_artists_users` · `player.add_to_queue` · `player.pause_a_users_playback` · `player.seek_to_position_in_currently_playing_track` · `player.set_repeat_mode_on_users_playback` · `player.set_volume_for_users_playback` · `player.skip_users_playback_to_next_track` · `player.skip_users_playback_to_previous_track` · `player.start_a_users_playback` · `player.toggle_shuffle_for_users_playback` · `player.transfer_a_users_playback` · `playlists.change_playlist_details` · `playlists.follow_playlist` · `playlists.unfollow_playlist` · `playlists.upload_custom_playlist_cover` · `shows.remove_shows_user` · `shows.save_shows_user` · `tracks.remove_tracks_user` · `tracks.save_tracks_user` · `users.follow_artists_users` · `users.follow_playlist` · `users.unfollow_artists_users` · `users.unfollow_playlist`. Their raw peers are `ApiResult[None, …]`, so `with_raw_response` is the only way to observe the status code. -4. **Required vs `UNSET`** for every model member the task sets, and the fact that `Optional[T]` here is `T | UnsetType` — **not** `typing.Optional`, so `None` is not a legal value for it. -5. **The `ApiError.error` union** for each operation in scope — there are **five** typed error bodies in this SDK, so the union is never uniform. Every union is ` | RawError`: - 1. `Forbidden1` — 138 operations (`albums.check_users_saved_albums` · `albums.get_an_album` · `albums.get_an_albums_tracks` · `albums.get_an_artists_albums` · `albums.get_multiple_albums` · `albums.get_new_releases` · `albums.get_users_saved_albums` · `albums.remove_albums_user` · `albums.save_albums_user` · `artists.check_current_user_follows` · `artists.follow_artists_users` · `artists.get_an_artist` · `artists.get_an_artists_albums` · `artists.get_an_artists_related_artists` · `artists.get_an_artists_top_tracks` · `artists.get_followed` · `artists.get_multiple_artists` · `artists.get_users_top_artists` · `artists.unfollow_artists_users` · `audiobooks.check_users_saved_audiobooks` · `audiobooks.get_an_audiobook` · `audiobooks.get_audiobook_chapters` · `audiobooks.get_multiple_audiobooks` · `audiobooks.get_users_saved_audiobooks` · `audiobooks.remove_audiobooks_user` · `audiobooks.save_audiobooks_user` · `categories_api.get_a_categories_playlists` · `categories_api.get_a_category` · `categories_api.get_categories` · `chapters.get_a_chapter` · `chapters.get_audiobook_chapters` · `chapters.get_several_chapters` · `episodes.check_users_saved_episodes` · `episodes.get_a_shows_episodes` · `episodes.get_an_episode` · `episodes.get_multiple_episodes` · `episodes.get_users_saved_episodes` · `episodes.remove_episodes_user` · `episodes.save_episodes_user` · `genres.get_recommendation_genres` · `library.change_playlist_details` · `library.check_current_user_follows` · `library.check_users_saved_albums` · `library.check_users_saved_audiobooks` · `library.check_users_saved_episodes` · `library.check_users_saved_shows` · `library.check_users_saved_tracks` · `library.create_playlist` · `library.follow_artists_users` · `library.get_a_list_of_current_users_playlists` · `library.get_followed` · `library.get_users_saved_albums` · `library.get_users_saved_audiobooks` · `library.get_users_saved_episodes` · `library.get_users_saved_shows` · `library.get_users_saved_tracks` · `library.get_users_top_artists` · `library.get_users_top_tracks` · `library.remove_albums_user` · `library.remove_audiobooks_user` · `library.remove_episodes_user` · `library.remove_shows_user` · `library.remove_tracks_user` · `library.save_albums_user` · `library.save_audiobooks_user` · `library.save_episodes_user` · `library.save_shows_user` · `library.save_tracks_user` · `library.unfollow_artists_users` · `markets_api.get_available_markets` · `player.add_to_queue` · `player.get_a_users_available_devices` · `player.get_information_about_the_users_current_playback` · `player.get_queue` · `player.get_recently_played` · `player.get_the_users_currently_playing_track` · `player.pause_a_users_playback` · `player.seek_to_position_in_currently_playing_track` · `player.set_repeat_mode_on_users_playback` · `player.set_volume_for_users_playback` · `player.skip_users_playback_to_next_track` · `player.skip_users_playback_to_previous_track` · `player.start_a_users_playback` · `player.toggle_shuffle_for_users_playback` · `player.transfer_a_users_playback` · `playlists.add_tracks_to_playlist` · `playlists.change_playlist_details` · `playlists.check_if_user_follows_playlist` · `playlists.create_playlist` · `playlists.follow_playlist` · `playlists.get_a_categories_playlists` · `playlists.get_a_list_of_current_users_playlists` · `playlists.get_featured_playlists` · `playlists.get_list_users_playlists` · `playlists.get_playlist` · `playlists.get_playlist_cover` · `playlists.get_playlists_tracks` · `playlists.remove_tracks_playlist` · `playlists.reorder_or_replace_playlists_tracks` · `playlists.unfollow_playlist` · `playlists.upload_custom_playlist_cover` · `search.search` · `shows.check_users_saved_shows` · `shows.get_a_show` · `shows.get_a_shows_episodes` · `shows.get_multiple_shows` · `shows.get_users_saved_shows` · `shows.remove_shows_user` · `shows.save_shows_user` · `tracks.add_tracks_to_playlist` · `tracks.check_users_saved_tracks` · `tracks.get_an_albums_tracks` · `tracks.get_an_artists_top_tracks` · `tracks.get_audio_analysis` · `tracks.get_audio_features` · `tracks.get_playlists_tracks` · `tracks.get_recommendations` · `tracks.get_several_audio_features` · `tracks.get_several_tracks` · `tracks.get_track` · `tracks.get_users_saved_tracks` · `tracks.get_users_top_tracks` · `tracks.remove_tracks_playlist` · `tracks.remove_tracks_user` · `tracks.reorder_or_replace_playlists_tracks` · `tracks.save_tracks_user` · `users.check_current_user_follows` · `users.check_if_user_follows_playlist` · `users.follow_artists_users` · `users.follow_playlist` · `users.get_current_users_profile` · `users.get_followed` · `users.get_list_users_playlists` · `users.get_users_profile` · `users.get_users_top_artists` · `users.get_users_top_tracks` · `users.unfollow_artists_users` · `users.unfollow_playlist`); distinguishing members `error` - 2. `TooManyRequests1` — 138 operations (`albums.check_users_saved_albums` · `albums.get_an_album` · `albums.get_an_albums_tracks` · `albums.get_an_artists_albums` · `albums.get_multiple_albums` · `albums.get_new_releases` · `albums.get_users_saved_albums` · `albums.remove_albums_user` · `albums.save_albums_user` · `artists.check_current_user_follows` · `artists.follow_artists_users` · `artists.get_an_artist` · `artists.get_an_artists_albums` · `artists.get_an_artists_related_artists` · `artists.get_an_artists_top_tracks` · `artists.get_followed` · `artists.get_multiple_artists` · `artists.get_users_top_artists` · `artists.unfollow_artists_users` · `audiobooks.check_users_saved_audiobooks` · `audiobooks.get_an_audiobook` · `audiobooks.get_audiobook_chapters` · `audiobooks.get_multiple_audiobooks` · `audiobooks.get_users_saved_audiobooks` · `audiobooks.remove_audiobooks_user` · `audiobooks.save_audiobooks_user` · `categories_api.get_a_categories_playlists` · `categories_api.get_a_category` · `categories_api.get_categories` · `chapters.get_a_chapter` · `chapters.get_audiobook_chapters` · `chapters.get_several_chapters` · `episodes.check_users_saved_episodes` · `episodes.get_a_shows_episodes` · `episodes.get_an_episode` · `episodes.get_multiple_episodes` · `episodes.get_users_saved_episodes` · `episodes.remove_episodes_user` · `episodes.save_episodes_user` · `genres.get_recommendation_genres` · `library.change_playlist_details` · `library.check_current_user_follows` · `library.check_users_saved_albums` · `library.check_users_saved_audiobooks` · `library.check_users_saved_episodes` · `library.check_users_saved_shows` · `library.check_users_saved_tracks` · `library.create_playlist` · `library.follow_artists_users` · `library.get_a_list_of_current_users_playlists` · `library.get_followed` · `library.get_users_saved_albums` · `library.get_users_saved_audiobooks` · `library.get_users_saved_episodes` · `library.get_users_saved_shows` · `library.get_users_saved_tracks` · `library.get_users_top_artists` · `library.get_users_top_tracks` · `library.remove_albums_user` · `library.remove_audiobooks_user` · `library.remove_episodes_user` · `library.remove_shows_user` · `library.remove_tracks_user` · `library.save_albums_user` · `library.save_audiobooks_user` · `library.save_episodes_user` · `library.save_shows_user` · `library.save_tracks_user` · `library.unfollow_artists_users` · `markets_api.get_available_markets` · `player.add_to_queue` · `player.get_a_users_available_devices` · `player.get_information_about_the_users_current_playback` · `player.get_queue` · `player.get_recently_played` · `player.get_the_users_currently_playing_track` · `player.pause_a_users_playback` · `player.seek_to_position_in_currently_playing_track` · `player.set_repeat_mode_on_users_playback` · `player.set_volume_for_users_playback` · `player.skip_users_playback_to_next_track` · `player.skip_users_playback_to_previous_track` · `player.start_a_users_playback` · `player.toggle_shuffle_for_users_playback` · `player.transfer_a_users_playback` · `playlists.add_tracks_to_playlist` · `playlists.change_playlist_details` · `playlists.check_if_user_follows_playlist` · `playlists.create_playlist` · `playlists.follow_playlist` · `playlists.get_a_categories_playlists` · `playlists.get_a_list_of_current_users_playlists` · `playlists.get_featured_playlists` · `playlists.get_list_users_playlists` · `playlists.get_playlist` · `playlists.get_playlist_cover` · `playlists.get_playlists_tracks` · `playlists.remove_tracks_playlist` · `playlists.reorder_or_replace_playlists_tracks` · `playlists.unfollow_playlist` · `playlists.upload_custom_playlist_cover` · `search.search` · `shows.check_users_saved_shows` · `shows.get_a_show` · `shows.get_a_shows_episodes` · `shows.get_multiple_shows` · `shows.get_users_saved_shows` · `shows.remove_shows_user` · `shows.save_shows_user` · `tracks.add_tracks_to_playlist` · `tracks.check_users_saved_tracks` · `tracks.get_an_albums_tracks` · `tracks.get_an_artists_top_tracks` · `tracks.get_audio_analysis` · `tracks.get_audio_features` · `tracks.get_playlists_tracks` · `tracks.get_recommendations` · `tracks.get_several_audio_features` · `tracks.get_several_tracks` · `tracks.get_track` · `tracks.get_users_saved_tracks` · `tracks.get_users_top_tracks` · `tracks.remove_tracks_playlist` · `tracks.remove_tracks_user` · `tracks.reorder_or_replace_playlists_tracks` · `tracks.save_tracks_user` · `users.check_current_user_follows` · `users.check_if_user_follows_playlist` · `users.follow_artists_users` · `users.follow_playlist` · `users.get_current_users_profile` · `users.get_followed` · `users.get_list_users_playlists` · `users.get_users_profile` · `users.get_users_top_artists` · `users.get_users_top_tracks` · `users.unfollow_artists_users` · `users.unfollow_playlist`); distinguishing members `error` - 3. `Unauthorized1` — 138 operations (`albums.check_users_saved_albums` · `albums.get_an_album` · `albums.get_an_albums_tracks` · `albums.get_an_artists_albums` · `albums.get_multiple_albums` · `albums.get_new_releases` · `albums.get_users_saved_albums` · `albums.remove_albums_user` · `albums.save_albums_user` · `artists.check_current_user_follows` · `artists.follow_artists_users` · `artists.get_an_artist` · `artists.get_an_artists_albums` · `artists.get_an_artists_related_artists` · `artists.get_an_artists_top_tracks` · `artists.get_followed` · `artists.get_multiple_artists` · `artists.get_users_top_artists` · `artists.unfollow_artists_users` · `audiobooks.check_users_saved_audiobooks` · `audiobooks.get_an_audiobook` · `audiobooks.get_audiobook_chapters` · `audiobooks.get_multiple_audiobooks` · `audiobooks.get_users_saved_audiobooks` · `audiobooks.remove_audiobooks_user` · `audiobooks.save_audiobooks_user` · `categories_api.get_a_categories_playlists` · `categories_api.get_a_category` · `categories_api.get_categories` · `chapters.get_a_chapter` · `chapters.get_audiobook_chapters` · `chapters.get_several_chapters` · `episodes.check_users_saved_episodes` · `episodes.get_a_shows_episodes` · `episodes.get_an_episode` · `episodes.get_multiple_episodes` · `episodes.get_users_saved_episodes` · `episodes.remove_episodes_user` · `episodes.save_episodes_user` · `genres.get_recommendation_genres` · `library.change_playlist_details` · `library.check_current_user_follows` · `library.check_users_saved_albums` · `library.check_users_saved_audiobooks` · `library.check_users_saved_episodes` · `library.check_users_saved_shows` · `library.check_users_saved_tracks` · `library.create_playlist` · `library.follow_artists_users` · `library.get_a_list_of_current_users_playlists` · `library.get_followed` · `library.get_users_saved_albums` · `library.get_users_saved_audiobooks` · `library.get_users_saved_episodes` · `library.get_users_saved_shows` · `library.get_users_saved_tracks` · `library.get_users_top_artists` · `library.get_users_top_tracks` · `library.remove_albums_user` · `library.remove_audiobooks_user` · `library.remove_episodes_user` · `library.remove_shows_user` · `library.remove_tracks_user` · `library.save_albums_user` · `library.save_audiobooks_user` · `library.save_episodes_user` · `library.save_shows_user` · `library.save_tracks_user` · `library.unfollow_artists_users` · `markets_api.get_available_markets` · `player.add_to_queue` · `player.get_a_users_available_devices` · `player.get_information_about_the_users_current_playback` · `player.get_queue` · `player.get_recently_played` · `player.get_the_users_currently_playing_track` · `player.pause_a_users_playback` · `player.seek_to_position_in_currently_playing_track` · `player.set_repeat_mode_on_users_playback` · `player.set_volume_for_users_playback` · `player.skip_users_playback_to_next_track` · `player.skip_users_playback_to_previous_track` · `player.start_a_users_playback` · `player.toggle_shuffle_for_users_playback` · `player.transfer_a_users_playback` · `playlists.add_tracks_to_playlist` · `playlists.change_playlist_details` · `playlists.check_if_user_follows_playlist` · `playlists.create_playlist` · `playlists.follow_playlist` · `playlists.get_a_categories_playlists` · `playlists.get_a_list_of_current_users_playlists` · `playlists.get_featured_playlists` · `playlists.get_list_users_playlists` · `playlists.get_playlist` · `playlists.get_playlist_cover` · `playlists.get_playlists_tracks` · `playlists.remove_tracks_playlist` · `playlists.reorder_or_replace_playlists_tracks` · `playlists.unfollow_playlist` · `playlists.upload_custom_playlist_cover` · `search.search` · `shows.check_users_saved_shows` · `shows.get_a_show` · `shows.get_a_shows_episodes` · `shows.get_multiple_shows` · `shows.get_users_saved_shows` · `shows.remove_shows_user` · `shows.save_shows_user` · `tracks.add_tracks_to_playlist` · `tracks.check_users_saved_tracks` · `tracks.get_an_albums_tracks` · `tracks.get_an_artists_top_tracks` · `tracks.get_audio_analysis` · `tracks.get_audio_features` · `tracks.get_playlists_tracks` · `tracks.get_recommendations` · `tracks.get_several_audio_features` · `tracks.get_several_tracks` · `tracks.get_track` · `tracks.get_users_saved_tracks` · `tracks.get_users_top_tracks` · `tracks.remove_tracks_playlist` · `tracks.remove_tracks_user` · `tracks.reorder_or_replace_playlists_tracks` · `tracks.save_tracks_user` · `users.check_current_user_follows` · `users.check_if_user_follows_playlist` · `users.follow_artists_users` · `users.follow_playlist` · `users.get_current_users_profile` · `users.get_followed` · `users.get_list_users_playlists` · `users.get_users_profile` · `users.get_users_top_artists` · `users.get_users_top_tracks` · `users.unfollow_artists_users` · `users.unfollow_playlist`); distinguishing members `error` - 4. `BadRequest1` — 1 operation (`audiobooks.get_an_audiobook`); distinguishing members `error` - 5. `NotFound1` — 1 operation (`audiobooks.get_an_audiobook`); distinguishing members `error` - 6. So `isinstance(e.error, Forbidden1)` matches only 138 of 138 operations. -6. **That a decode failure raises `ValidationError`/`ValueError`, not `ApiError`, in both response modes** — `core/raw_client.py` states this in `execute`'s own docstring. **And that the 2xx path declares at least one required member on 56 return types, so a truncated body fails to decode there and passes silently everywhere else.** Any sheet row for a call whose result is used must name the members the implementer has to assert on. -7. **That retrying is on by default** — `retry_options` on the client tunes it, `max_retries` set to `0` turns it off, and `request_options` overrides it per call — so the sheet says whether this integration keeps, tunes or disables it, and for which methods, since a write is repeated only when the policy names its method. -8. **What limits a whole call.** `timeout` limits each wait, not the call, so a reply whose pieces each arrive within it is never cut off. In async code, state the budget and the one place `asyncio.wait_for` enforces it for every call, and what the boundary returns for its `asyncio.TimeoutError`; in sync code, say there is none. -9. **Which environment the `environment` keyword selects**, because omitting it is silently `"production"` of the 2 declared. -10. A **REQUIRED READING** block naming the `python-*` companions that govern the steps, with `MUST load` pointers. +1. **Sync or async** — the client class, where it is held, and its `close()`/`aclose()`. +2. **The keyword-only boundary** for each operation: what is positional (each required parameter without a fixed value, path → query → header → body) and what sits after `*`. Every keyword-only parameter has a real default, so write no defensive `None`s. +3. **The 43 operations that return `None`** — the map's **Returns (parsed)** bullet says which. Their raw peers are `ApiResult[None, …]`, so `with_raw_response` is the only way to observe the status code. +4. **Required vs `UNSET`** for every model member the task sets. +5. **The `ApiError.error` union** for each operation in scope, copied from the **Error arms** bullet of its block in `map/operations/` — this SDK has **5 typed error bodies** across 138 operations, so never assume an arm is shared. Every union ends in `RawError`; an operation with no typed arm is `RawError` alone. +6. **That a decode failure raises `ResponseDecodeError`, not `ApiError`, in both response modes. And that the 2xx path declares at least one required member on 56 return types, so a truncated body fails to decode there and passes silently everywhere else.** Any sheet row for a call whose result is used must name the members the implementer has to assert on. +7. **Retries are on by default** — the sheet says whether this integration keeps, tunes (`retry_options`) or disables them (`max_retries` set to `0`), and for which methods; a write is retried only when the policy names its method. +8. **Whether logging is on, and how loud** — the sheet says whether this integration raises the `spotify_web_api` logger, which `logging_options` dumps it turns on — a JSON body is logged as sent — and any per-call `log_level`. +9. **What limits a whole call.** `timeout` limits only each wait (`python-configuration-resilience`). In async code, state the budget and the one place `asyncio.wait_for` enforces it for every call, and what the boundary returns for its `asyncio.TimeoutError`; in sync code, say there is none. +10. **Which server each call resolves against**, set through `server_config`. +11. A **REQUIRED READING** block naming the `python-*` companions that govern the steps, with `MUST load` pointers. diff --git a/plugins/spotify/skills/python/python-integrate-spotify-web-api/SKILL.md b/plugins/spotify/skills/python/python-integrate-spotify-web-api/SKILL.md index 44fd6b4c..d6a4f871 100644 --- a/plugins/spotify/skills/python/python-integrate-spotify-web-api/SKILL.md +++ b/plugins/spotify/skills/python/python-integrate-spotify-web-api/SKILL.md @@ -1,21 +1,32 @@ --- name: "python-integrate-spotify-web-api" -description: "MANDATORY FIRST STEP for Spotify Web API Python SDK work in a Python project — load this BEFORE you write any code; Python SDK ONLY, never load it for any other language. Applies when asked to integrate Spotify Web API in Python — get the current user's followed artists, add one or more items to a user's playlist, add the current user as a follower of a playlist, get a playlist owned by a spotify user, remove one or more items from a user's playlist — or when a Spotify Web API Python SDK call errors or behaves unexpectedly. Knowing the SDK exists is NOT a substitute for loading this, because it carries five binding gates stated NOWHERE else and not inferable from the package — (1) load python-getting-started, confirm the package is actually installed and read the SDK map that ships with it before any lookup, (2) the exact plan-file path and the no-project-file-edits window until a contract sheet with no open lookups exists there and you have read it, (3) the mandatory load of every python-* companion skill the sheet names, (4) sync-vs-async decided once from the host application before the first call, and (5) the memory ban, where every signature, wire alias, error union and enum member comes from a lookup and never from recall or runtime introspection." +description: "MANDATORY FIRST STEP for Spotify Web API Python SDK work in a Python project (never another language): load before writing code to integrate Spotify Web API in Python — get the current user's followed artists, add one or more items to a user's playlist, add the current user as a follower of a playlist — or when a Spotify Web API Python SDK call errors or behaves unexpectedly. Holds the plan-first workflow: the plan file, the contract sheet and its no-edits gate, and which python-* companion skills to load." --- # Spotify Web API Python SDK — Integration workflow (lookup layer + contract sheet) -You do the SDK lookups yourself: `python-getting-started` is your **lookup layer** — load it and ground every contract fact in it (and in the source modules its table names) before writing code. The `python-*` companion skills are a different thing: they are API-agnostic *usage* guidance, they are yours to load, and Step 1c below makes loading them mandatory. +`python-getting-started` is your **lookup layer**; the `python-*` companions are API-agnostic *usage* skills that Step 1c makes mandatory. ## Your lookup layer -- **`python-getting-started`** is the entry point for every SDK need. It carries the SDK's identity (distribution name vs import root, version, Python floor, install-from-source), what the root package exports and the four modules the surface splits across, environments and the base-URL knob, the auth pattern, the controllers, and a **module table** naming the one file that owns each kind of fact. Load it first, always. -- **The SDK map is your lookup surface, and you open it yourself.** The SDK ships `sdk-map.md` and `map/operations/` at its root. There is no helper agent on the Python side — the map is yours to read, not something to delegate. `python-getting-started` tells you how to traverse it: read `sdk-map.md` once, then the one controller page your operations live on. -- **The installed package is the ground truth; the module table is only the locator.** Confirm the package is importable before you rely on a lookup — `python -c "import spotify_web_api, pathlib; print(pathlib.Path(spotify_web_api.__file__).parent)"`. **If it is not installed, install it first** — `python-getting-started` carries the command; until then mark the fact `UNVERIFIED`, say what would settle it, and do not fill the hole from memory. (The distribution is not on any package index — it installs from its repository; `python-getting-started` carries the command.) -- **Read scoped.** Those modules carry long design docstrings. `grep -n` for the symbol and read the surrounding lines rather than whole files, and never copy a docstring's design rationale onto a contract sheet — the sheet carries facts an implementer must obey, not the reasoning behind them. -- **Write a contract sheet with no open lookups** before you implement: exact signatures, the keyword-only boundary, wire aliases, required-vs-`UNSET` members, the `ApiError.error` union per operation, and enum members for the operations in scope. `python-getting-started` ends with a checklist of the rows a Python sheet is incomplete without — treat that list as the checklist for your own sheet, and collect every in-scope operation in ONE pass rather than re-opening a module per member. +- **`python-getting-started`** is the entry point for every SDK need: the SDK's identity (distribution name vs import root, version, Python floor, install-from-source), the root package's exports and the modules the surface splits across, environments and the base-URL knob, the auth pattern, the controllers, and a **module table** naming the one file that owns each kind of fact. Load it first, always. +- **The SDK map** (`sdk-map.md` and `map/operations/`, at the SDK root) is yours to open and read: `sdk-map.md` once, then the one controller page your operations live on. +- **The installed package is the ground truth; the module table is only the locator.** Confirm the package imports, with the probe in `python-getting-started`, before you rely on a lookup; **if it is not installed, install it first**. Until then mark the fact `UNVERIFIED`, say what would settle it, and do not fill the hole from memory. (The distribution is not on any package index — it installs from its repository; `python-getting-started` carries the command.) +- **Write a contract sheet with no open lookups** before you implement — every in-scope operation in one pass, against the checklist that ends `python-getting-started`. -**Scope guard:** the APIMatic-generated Spotify Web API **Python SDK** (import root `spotify_web_api`, distribution `spotify-web-api`) in **Python projects only**. Unrelated API, or any language other than Python — do nothing; this skill does not apply. +**Scope:** the Spotify Web API **Python SDK** (import root `spotify_web_api`, distribution `spotify-web-api`) in **Python projects only**. + +## The planner agent + +`spotify-web-api-planner` ships with this plugin. It writes `spotify-web-api-plan.md` — the plan and its contract sheet — and revises it in place; it writes no project code. Start it the first of these ways your host allows: + +1. **Your subagent tool lists it.** Some hosts list a plugin's agents under the plugin's name, as `spotify:spotify-web-api-planner`; start it by whichever of the two names your subagent tool lists. +2. **It isn't listed, or you can't start a subagent.** Tell the user in one line that you are writing the plan yourself, then do so as *Step 1* describes. Don't stop to ask. + +However you start it: + +- **Start it on the same model you are running on.** If your subagent tool takes a model, pass your own model; if it has no model option, leave its default. Tell the user in one line which model you started it on. +- **Start it once per integration.** A plan revision is a follow-up message to that same agent; re-start it, carrying the clarification and the plan path, only where your host cannot message it. Never start a second one for the same integration. ## Workflow @@ -23,23 +34,29 @@ You do the SDK lookups yourself: `python-getting-started` is your **lookup layer ### Step 1 — Plan first (always, for any implementation work) -Your FIRST action is to load `python-getting-started` and work through the user's full request (all features in scope — one plan covers the whole implementation). Then write the plan and its contract sheet to `/spotify-web-api-plan.md` — that absolute path, not a location you pick later. +Your FIRST action, once the SDK is installed and you have reached its source (both are prerequisites below; installing follows the toolchain check and the baseline, and the gate allows it), is to start **`spotify-web-api-planner`**, as *The planner agent* says, once, with the user's full request — all features in scope; one plan covers the whole implementation — and the name of this skill, `python-integrate-spotify-web-api`. Dictate in its task the absolute project root, the absolute path of the SDK source you reached — it reads the map there rather than reaching its own — and the absolute path it must write to — `/spotify-web-api-plan.md`, that absolute path, not a location you pick later. It loads `python-getting-started`, writes the plan and its contract sheet as this step and *Step 1c* describe, and returns the file's path. -**Do the read-only prerequisites in the same pass — they need no SDK knowledge and touch no project file:** +**If you couldn't start the planner** (case 2 in *The planner agent*), load `python-getting-started`, work through the request yourself, and write the file at that path. + +**Do these two read-only prerequisites before you install the SDK — the install changes the tree they read:** -- the repo survey (read-only exploration of conventions, layering, and **whether the project is sync or `async`**) — capture each convention as *pattern + the ONE exemplar file path to imitate*, NOT inline code snippets: you will read the exemplar at edit time anyway, so a snippet dump gets paid for twice; - **establish the toolchain before you need it**: which environment manager the repo uses (`uv`, `poetry`, `pip` + venv, `pdm`), whether `spotify-web-api` is already a dependency and at what version, and the exact commands that run the project's tests and type checker. Getting this wrong later costs a broken install mid-implementation — and an uninstalled package costs you the lookup layer itself; -- a baseline run of the project's checks (`pytest`, `mypy`, `ruff` — whatever it has) on the UNTOUCHED tree, so later failures are attributable to your changes; -- credentials/environment verification (per the task's secret-handling rules) — including which host `environment` will select, since omitting it is silent; -- **a read-only smoke of each in-scope operation against the real credential**, run from your scratchpad, not the project, once the map has given you the signatures and before you finalise the sheet. A plan-, region- or entitlement-gated endpoint answers `403` here — the map presents every operation uniformly and cannot know which ones your key may call — and learning that now reorders the plan rather than the build. Skip only operations whose side effects you cannot reverse; -- setting up your task tracking. +- a baseline run of the project's checks (`pytest`, `mypy`, `ruff` — whatever it has) on the UNTOUCHED tree, so later failures are attributable to your changes. + +**Then make sure the SDK is installed and reach its source, before you start the planner** (both per `python-getting-started`) — the installed package does not carry the map, which lives in the SDK's source tree, and the planner reads the copy you reached rather than reaching its own. -Never use the planning phase to get a "head start" on implementation: **creating or editing ANY project file before the gate below is a defect**, no matter how obvious the code seems. +**Do the rest while the planner works — they need no SDK knowledge and touch no project file:** -**HARD GATE — no project-file creation or edits until:** `spotify-web-api-plan.md` EXISTS at the repo root, its contract sheet has **no open lookups**, and you have read it. The gate bars coding "meanwhile"; it does not bar the read-only prerequisite work above. Starting to code before the sheet exists defeats the entire plan-first design. +- the repo survey (read-only exploration of conventions, layering, and **whether the project is sync or `async`**) — capture each convention as *pattern + the ONE exemplar file path to imitate*, NOT inline code snippets: you will read the exemplar at edit time anyway, so a snippet dump gets paid for twice; +- credentials/environment verification (per the task's secret-handling rules) — including which host `server_config` will select, since omitting it is silent; +- setting up your task tracking. + +**HARD GATE — no project-file creation or edits until** the planner has returned, `spotify-web-api-plan.md` exists at the repo root (check it — a helper can misreport where it saved), its contract sheet has **no open lookups**, and you have read it. If you wrote the plan yourself, the gate is the same without the return. The read-only prerequisites above are not gated. **What the gate does not cover:** creating or activating a virtual environment, installing `spotify-web-api` and the toolchain into it, and the files those writes produce (`.venv/`, a lockfile the installer updates) are **prerequisites, not project-file edits**. On a greenfield repo they are the only way to reach the lookup layer at all, and they are the only writes permitted before the gate. Nothing you author by hand may change. +**One read-only prerequisite waits for the signatures: a smoke of each in-scope operation against the real credential**, run from your scratchpad, not the project, once the planner has returned and you have read the sheet, with the signatures it records, and before your first project edit — or, if you are writing the plan yourself, once the map has given you the signatures and before you finalise the sheet. A plan-, region- or entitlement-gated endpoint answers `403` here — the map presents every operation uniformly and cannot know which ones your key may call — and learning that now reorders the plan rather than the build. Send each `403` to the SAME planner as a revision, as *Step 1c* sends a blocker, and implement from its reply; if you wrote the plan yourself, revise the sheet in place. Skip only operations whose side effects you cannot reverse. + **DUPLICATE CLAIMS** — one row per write a caller can trigger twice; `none` if the task has no such write (`python-configuration-resilience`, *The same operation arriving twice*). | Write | Where the claim is stored | What rejects the second one | Where that rejection is caught | Where in the code | @@ -47,7 +64,7 @@ Never use the planning phase to get a "head start" on implementation: **creating Every row follows one order: **claim → SDK call → record the result**. The claim is a write of its own, made before the SDK call, so a second caller is stopped before it reaches the provider; release it when the provider refuses the call. -⚠⚠ **Where the claim is stored**: a store this application owns — the one the codebase already keeps its records in — never the provider. A provider idempotency key goes beside the claim, never in place of it; the SDK's own `Idempotency-Key` header is not one — it is new on every call. If this codebase has nowhere to keep a claim that outlives the process, that is a Blocker in the plan's **Assumptions & Blockers**, not a row. +⚠⚠ **Where the claim is stored**: a store this application owns — the one the codebase already keeps its records in — never the provider. A provider idempotency key goes beside the claim, never in place of it; the SDK's own `Idempotency-Key` header is not one. If this codebase has nowhere to keep a claim that outlives the process, that is a Blocker in the plan's **Assumptions & Blockers**, not a row. ⚠⚠ **What rejects the second one**: the store refusing the second caller's claim, the way this codebase already refuses a duplicate. A conflict on the save *after* the SDK call is too late — both callers have already reached the provider. A read before the write — a status check, a lookup by key — is not a refusal either: it lets both callers through. Pick a refusal the store you run against enforces. @@ -57,15 +74,13 @@ Write `TBD` in **Where in the code** while you plan — every row; it names code ### Step 1c — Required reading (do this before you write any code) -End the contract sheet with a **REQUIRED READING** block whose rows carry inline `MUST load ` pointers. **Load every `python-*` skill the sheet names, now, before you start implementing** — not lazily at the step that needs it. The sheet deliberately does *not* carry the how-to: it names the hazard and hands you the skill that resolves it, so an unloaded pointer is a gap in what you know, not a formality. +End the contract sheet with a **REQUIRED READING** block whose rows carry inline `MUST load ` pointers. **Load every `python-*` skill the sheet names, now, before you start implementing** — not lazily at the step that needs it, and even if you have already read the module. The sheet deliberately does *not* carry the how-to: it names the hazard and hands you the skill that resolves it, so an unloaded pointer is a gap in what you know, not a formality. **A fixed floor applies regardless of what the sheet says** — the sheet can add to it, never remove from it: `python-error-handling` always (every integration writes an error boundary); `python-client-initialization` before the client is constructed; `python-testing` before the first test file you create or edit, *including* a throwaway verification script that fakes the transport. A sheet row that excuses one of these ("out of scope", "no test suite requested") is not a substitute for loading it. -These are API-agnostic usage skills; loading them is not a substitute for the lookup layer, and reading a module in the installed package does not remove the need to load the skill for that step. Contract *facts* still come only from your sheet or a fresh lookup. - Before implementing, check the plan's **Assumptions & Blockers** section: -- Blocker or major assumption → surface it to the user in plain language, get their answer, and revise `spotify-web-api-plan.md` in place. +- Blocker or major assumption → surface it to the user in plain language, get their answer, and send it to the SAME planner as a follow-up message (re-start it, carrying the clarification and the plan path, only where your host cannot message it). It revises `spotify-web-api-plan.md` in place and replies with the changed rows verbatim: work from that reply, not a re-read of the file. If you wrote the plan yourself, revise it in place. - Minor assumptions only → proceed. Full re-planning only on genuine scope change; for a single missing fact mid-implementation, do the lookup, never guess. @@ -73,13 +88,13 @@ Full re-planning only on genuine scope change; for a single missing fact mid-imp ### Step 2 — Implement from the contract sheet 1. Read `spotify-web-api-plan.md` once. Treat its contracts as authoritative — do not re-derive or "double-check" them from memory. When a lookup revises a row, update the file so the sheet and the code never disagree. -2. **Decide sync vs async once, from the host application, before the first call** — and take the decision from the repo survey, not from preference. This SDK ships two complete client classes (`Client` / `AsyncClient`) and there is no bridge between them: a sync client in an `async def` blocks the event loop, and an async client in sync code is a coroutine nobody awaits. Getting this wrong is not a local fix later; it is every call site. The choice also changes the transport-override keyword (`custom_http_client` vs `custom_async_http_client`) and the teardown obligation (`close()` vs `await aclose()`). -3. **Pick the response mode per call, deliberately.** Each operation exists twice: the plain call raises `ApiError` on failure, and its `with_raw_response` peer returns `ApiResult` instead. For the operations that return `None`, the raw peer is the only way to observe the status code — so a call whose outcome you must inspect needs the mode chosen at write time, not retrofitted. -4. Implement sequentially, following the repo's own conventions and layering. You loaded the companion skills the sheet named in Step 1c — implement each step in line with the one that governs it. Take every contract *fact* (signatures, wire aliases, error unions, enum members) from the contract sheet or a fresh lookup — never re-derive one from a companion. -5. After every change: run the project's **type checker** (`mypy`/`pyright`) as well as its tests. The package ships `py.typed` and is generated under `mypy --strict`, so a type error against it is a real contract violation, not noise — it is the closest thing Python gives you to the compile step. **Treat a clean type check as the gate you do not skip.** If the project has no type checker configured, install `mypy` into the environment and run `mypy --strict` on the files you touched — the SDK is generated under that setting, so it checks cleanly against it. If you genuinely cannot install one, say so in your final report rather than silently substituting a smoke run. Fix non-SDK errors yourself. -6. **Any error involving an SDK type or member** — an `AttributeError`/`TypeError` on a `spotify_web_api.*` object, a `pydantic.ValidationError` you cannot place, a mypy error naming an SDK type, an unexpected `ApiError` — → go back to `python-getting-started`'s module table and read the one module that owns the fact. Do not attempt more than one self-fix of an SDK-name error before doing that lookup: rewriting from the same knowledge that produced the error is guessing. Remember that a **decode failure raises `ValidationError`/`ValueError`, not `ApiError`, and bypasses both response modes**, and that `httpx2` transport exceptions arrive unwrapped — so an exception that does not look like an API error may still be one of the SDK's failure kinds. +2. **Decide sync vs async once, from the repo survey, before the first call** — `Client` or `AsyncClient`. The two have no bridge, and the choice fixes the transport-override keyword and the teardown (`python-client-initialization`). +3. **Pick the response mode per call, at write time:** the plain call raises `ApiError`; its `with_raw_response` peer returns `ApiResult`, the only way to see the status of an operation that returns `None`. +4. Implement sequentially, in the repo's own conventions and layering, in line with the companion that governs each step. Take every contract *fact* (signatures, wire aliases, error unions, enum members) from the sheet or a fresh lookup — never from a companion. +5. After every change: run the project's **type checker** (`mypy`/`pyright`) as well as its tests. The package ships `py.typed`, so a type error against it is a real contract violation, not noise — it is the closest thing Python gives you to the compile step. **Treat a clean type check as the gate you do not skip.** If the project has no type checker configured, install `mypy` into the environment and run `mypy --strict` on the files you touched — the SDK checks cleanly under it. If you genuinely cannot install one, say so in your final report rather than silently substituting a smoke run. Fix non-SDK errors yourself. +6. **Any error involving an SDK type or member** — an `AttributeError`/`TypeError` on a `spotify_web_api.*` object, a `pydantic.ValidationError` you cannot place, a mypy error naming an SDK type, an unexpected `ApiError` — → go back to `python-getting-started`'s module table and read the one module that owns the fact. Do not attempt more than one self-fix of an SDK-name error before doing that lookup. A decode, connection or authentication failure is an `SdkError` too, though not an `ApiError` (`python-error-handling`). 7. Once the code is complete, open each function the **DUPLICATE CLAIMS** rows name and confirm it runs when that write runs. Where the code falls short of a row, fix the code, not the row. -8. Run the project's tests; verify the integration end to end the way the task demands. Retrying is **on by default**, so decide whether the task keeps it, tunes it through `retry_options`, or turns it off with `max_retries` set to `0`, rather than wrapping the call in a retry of your own — and say which you did. +8. Run the project's tests; verify the integration end to end the way the task demands. Keep, tune (`retry_options`) or disable (`max_retries` set to `0`) the default retries rather than wrapping the call in a retry of your own, and say which you did. Logging is **off by default**: run a new call once under `SPOTIFY_WEB_API_LOG=info` to see what went on the wire. ### Step 3 — Answering pure questions @@ -87,11 +102,9 @@ A standalone Spotify Web API question with no code change: look it up in `python ## Anti-patterns — never do these -- **Always load `python-getting-started` first.** It is your lookup layer, not optional background. (The `python-*` companions are the complement: load the ones the sheet names, per Step 1c.) Don't re-derive a contract *fact* from a companion — exact signatures, wire aliases, error unions and enum members come from the sheet or a fresh lookup. +- **Never create or edit a project file while `spotify-web-api-planner` is running**, and never start a second one for the same integration. - **Never write a Spotify Web API/SDK fact from memory** — every signature, field name, enum member, and error union in your code must come from the contract sheet or a lookup. And **never write a call from memory "to fix later".** - **Don't web-search Spotify Web API topics to find an implementation detail** — the installed package's own source is the ground truth, and the module table tells you where to look. Public Spotify Web API docs describe the REST API, not this SDK's generated surface, and the two disagree on names. - **Never introspect the SDK at runtime to discover its shape.** `dir()`, `model_fields`, `inspect.signature`, or a REPL poke is the Python-flavoured version of decompiling the package: it answers what exists, never what is *supported*, and it silently invites private attributes into your code. Read the source module instead. -- **Don't grep the package to *locate* a type** — the SDK map is the locator (and says so: *"Never grep for a type"*); grep only *inside* the module its **Type sources** table names, for the symbol. A sweep for a *shape* is a different thing, and is fine: "every member typed `Optional[Any]`", "every discriminator field" are cross-cutting questions nothing indexes, and one targeted `grep -rn` over `models/` is the right tool for them — record what it found on the sheet. -- **Don't vendor, `sys.path`-hack, or editable-install the SDK from a throwaway clone** to make a lookup possible. Install the distribution properly into the project's environment (see `python-getting-started`); an editable install pointed at a clone breaks every import the moment the clone is deleted. -- **Don't create or edit project files before the HARD GATE** in Step 1 — plan and contract sheet first, code second. +- **Don't grep the package to *locate* a type** — the map's **Type sources** table is the locator; grep only inside the module it names. A cross-cutting *shape* sweep ("every member typed `Optional[Any]`", "every discriminator field") is fine as one `grep -rn` over `models/`, recorded on the sheet. diff --git a/plugins/spotify/skills/python/python-models/SKILL.md b/plugins/spotify/skills/python/python-models/SKILL.md index cbf33c8f..b4daa979 100644 --- a/plugins/spotify/skills/python/python-models/SKILL.md +++ b/plugins/spotify/skills/python/python-models/SKILL.md @@ -1,6 +1,6 @@ --- name: python-models -description: Working with models in an APIMatic-generated Python SDK — pydantic models and their TypedDict companions, required members vs the UNSET sentinel, why Optional here is not typing.Optional, open enums, union aliases and discriminators, collections, wire aliases, frozen instances, unknown-field preservation, and serializing with to_dict/to_json. Load before constructing request payloads or mapping SDK models onto your own types. +description: Load before building request payloads for an APIMatic-generated Python SDK or mapping its response models onto your own types. Covers pydantic models and their TypedDict companions, required members vs UNSET (Optional here is not typing.Optional), open enums, union aliases and discriminators, wire aliases, unknown-field preservation, and to_dict/to_json. --- # Working with models in an APIMatic Python SDK @@ -18,9 +18,8 @@ REPL poke at the installed package. ## The base every model shares -Domain models subclass a generated base (`{root_package}.core.SdkBaseModel`) with a deliberate -configuration. It is **static generator code, identical in every APIMatic Python SDK**, and four of its -choices change how you write code: +Domain models subclass `{root_package}.core.SdkBaseModel`, configured identically in every APIMatic +Python SDK; four of its settings change how you write code: | Config | What it means for you | |---|---| @@ -48,8 +47,8 @@ class {RequestType}(SdkBaseModel): - **`Optional[T] = UNSET` is optional.** Leave it out entirely and the key is omitted from the JSON. **`Optional` here means `T | UnsetType` — present or absent, with no `None` arm.** It is *not* -`typing.Optional[T]` (`T | None`), and the difference is the arm that matters: a field the spec does -not declare nullable must not be able to reach the wire as `null`. So: +`typing.Optional[T]` (`T | None`), and the difference is the arm that matters: a field that is not +nullable cannot reach the wire as `null`. So: ```python {RequestType}({required_field}="...", {required_list}=[...], {optional_field}=None) # ✗ type error, and rejected @@ -59,9 +58,8 @@ not declare nullable must not be able to reach the wire as `null`. So: Never "clear" an optional field by passing `None`. Omit it, or pass `UNSET` explicitly if you are building the kwargs dynamically. -A field annotated **`OptionalNullable[T]`** (`T | None | UnsetType`) is the three-state case: omitted, -explicitly `null`, or a value. The generator emits it for exactly the properties the spec declared both -optional *and* nullable. There, `None` *is* meaningful — it sends `null`, which for a PATCH-style API +A field annotated **`OptionalNullable[T]`** (`T | None | UnsetType`) — a member both optional *and* +nullable — is the three-state case: omitted, explicitly `null`, or a value. There, `None` *is* meaningful — it sends `null`, which for a PATCH-style API is how you erase a value rather than leave it unchanged. Read the annotation before deciding what `None` means. @@ -99,10 +97,8 @@ rather than a runtime surprise. Three caveats: - the companion is a typing construct only — it performs no runtime validation until the SDK validates the whole body; - it cannot express `UNSET`, so a dict simply omits what it does not set; -- **the closed check only helps if a type checker actually runs.** At runtime the model base is - `extra="allow"`, so a misspelled key that no checker saw is *accepted* and sent as an extra field - rather than rejected (see *Unknown fields are preserved* below). The dict spelling is only as safe - as your `mypy`/`pyright` gate. +- **the closed check only helps if a type checker actually runs.** At runtime a misspelled key is + accepted and sent as an extra field (see *Unknown fields are preserved* below). ## Enums are open @@ -137,10 +133,9 @@ match response.{enum_field}: # handle the open arm explicitly An `if/elif` chain over members with no final `else` silently does nothing for an unknown value. -**Stringifying differs by enum kind.** The generator gives every enum `__str__ = str.__str__`. On a -`(str, Enum)` that is what you want — `str(member)` and f-string interpolation give the **wire value** -(`"{wire_value}"`), not `"{Enum}.{MEMBER}"`, so logging and comparison against raw strings both behave. -On an `(int, Enum)` that same assignment makes `str(member)` raise +**Stringifying differs by enum kind.** On a `(str, Enum)`, `str(member)` and f-string interpolation +give the **wire value** (`"{wire_value}"`), not `"{Enum}.{MEMBER}"`, so logging and comparison against +raw strings both behave. On an `(int, Enum)`, `str(member)` raises `TypeError: descriptor '__str__' requires a 'str' object` — so never interpolate an int-enum member into a log line or an f-string. Use `member.value` (or `int(member)`) instead. @@ -194,8 +189,8 @@ Four things the alias does not show: ## Collections -List properties are `list[T]`; maps are `dict[str, V]` — **the key type is always `str`**, whatever -the spec said. Inside a companion, a model element is typed as that model's companion +List properties are `list[T]`; maps are `dict[str, V]` — **the key type is always `str`**. +Inside a companion, a model element is typed as that model's companion (`list[{Model}Dict]`). ```python @@ -210,10 +205,9 @@ are different wire messages — do not use `[]` to mean "leave this alone". ## Wire aliases -The generator emits a pydantic alias for a field **exactly when the Python name no longer matches the -wire name** — snake-casing a `camelCase` property, sanitizing a name that is not a valid identifier, -escaping a Python keyword (trailing underscore, `type_` for `type`), or de-duplicating a collision. -Where the wire name is already a valid snake_case identifier, no alias is emitted at all. +A field carries a pydantic alias **exactly when its Python name differs from the wire name** — +snake-casing a `camelCase` property, sanitizing a name that is not a valid identifier, escaping a Python +keyword (trailing underscore, `type_` for `type`), or de-duplicating a collision. ```python {field}: Optional[str] = Field(default=UNSET, alias="{wireField}") @@ -224,17 +218,15 @@ input, and output uses the alias. When a sheet lists a member as `{field} (wire `{field}` in code and expect `{wireField}` in a captured request body — do not "fix" a test that asserts the alias. -**The `…Dict` companion is keyed by the PYTHON name, not the alias.** A `TypedDict` cannot declare a -keyword or a non-identifier as a key through class syntax, and the base config's `validate_by_name` is -what makes the Python spelling work: +**The `…Dict` companion is keyed by the PYTHON name, not the alias:** ```python client.{controller}.{operation}(body={"{field}": "..."}) # ✓ the companion's key client.{controller}.{operation}(body={"{wireField}": "..."}) # validates, but type-checks as nothing ``` -The serialized body carries `"{wireField}"` either way. The second form *does* validate at runtime via -`validate_by_alias` — so both happen to work, and only one is checked. Write the Python name. +The serialized body carries `"{wireField}"` either way; both validate at runtime, but only the first +type-checks. Write the Python name. ## Serializing @@ -270,13 +262,11 @@ pydantic_core._pydantic_core.PydanticSerializationError: Unable to serialize unknown type: ``` -`UnsetType` carries its own serializer, but `Any` absorbs the union arm before that serializer is -reached, so the sentinel arrives at pydantic's generic any-serializer, which has never heard of it. Every other `Optional[T]` is fine, and so is a *container* of `Any` (`Optional[list[Any]]`, `Optional[dict[str, Any]]`) — this is specific to a bare `Any` at the top of the annotation. -You get `Any` wherever the spec left a property unconstrained: a free-form object, an anonymous -object, or no schema at all. **Check the contract sheet for which members are typed `Any`** — it is +A member is typed `Any` wherever it is unconstrained: a free-form object, an anonymous object, or +no schema at all. **Check the contract sheet for which members are typed `Any`** — it is usually a small, fixed list, and a JSON-Patch-style `value` member is the classic case, because the ops that take no value are exactly the ones that would leave it unset. @@ -287,17 +277,11 @@ client.{controller}.{operation}(body={Model}({field}=None)) # request body -> {"{field}": null} ``` -It type-checks (`Any` admits `None`) and it serializes. Note the cost: the request now carries -`"{field}": null` where it should have carried nothing. Two consequences worth stating on any sheet -that touches such an operation: - -- an explicit `null` is not the same wire message as an omitted key, so a strict server-side validator - could reject it — confirm against sandbox before shipping; -- this is the one place where `None` on an `Optional[...]` field is correct. Everywhere else it is a - type error (see above). Do not generalise it. - -The dict spelling is no escape — it validates into the same model, sentinel included. If a future SDK -version widens these annotations, drop the explicit `None`. +It type-checks (`Any` admits `None`) and it serializes, at the cost of sending `"{field}": null` +instead of nothing — an explicit `null` is not the same wire message as an omitted key, so a strict +server-side validator could reject it; confirm against sandbox before shipping. This is the one place +where `None` on an `Optional[...]` field is correct; everywhere else it is a type error (see above). +The dict spelling is no escape — it validates into the same model, sentinel included. **The trap fires on the read path too.** A *response* model whose `Any`-typed member the server omitted decodes fine — and then fails `to_dict()` / `to_json()` with the same error, because that @@ -321,8 +305,8 @@ Never pass a raw member straight through to something that will encode it. ## Unknown fields are preserved -Unlike SDKs that drop unmodelled JSON, `extra="allow"` keeps them — at every nesting level, readable -via `model_extra`, and **re-emitted under the key they arrived with**: +`extra="allow"` keeps unknown fields — at every nesting level, readable via `model_extra`, and +**re-emitted under the key they arrived with**: ```python extra = response.model_extra or {} @@ -331,14 +315,14 @@ new_field = extra.get("{some_new_field}") This makes it safe to read an object, change one member and send it back without silently discarding server-side state you never modelled. The symmetry also means an unknown key *you* supply is sent -rather than rejected — convenient for a field newer than the SDK, and a silent no-op when you simply -misspell a real one. A misspelled optional member does not error; it becomes an extra. If a value you -set is not taking effect, check it against the sheet's member list before suspecting the API. +rather than rejected — convenient for a field newer than the SDK, and a silent no-op when you +misspell a real one. If a value you set is not taking effect, check it against the sheet's member list +before suspecting the API. ## Dates and numbers -The generator maps spec types to Python as follows — take the exact type of any given member from the -contract sheet rather than assuming: +Spec types map to Python as follows — take the exact type of any given member from the contract sheet +rather than assuming: | Spec type | Python type | |---|---| @@ -358,8 +342,8 @@ Three consequences: `datetime`/`date` and read one back; do not format strings by hand. Every one of those names is an `Annotated` alias over the stdlib type, declared in `{root_package}/core/converters/date_time.py`: `Date` → `datetime.date`; `RFC3339DateTime`, `RFC1123DateTime` and `UnixSecondsDateTime` → - `datetime.datetime`. The alias only governs the wire format. They are runtime types, so the map's - **Type sources** tables do not list them — this is where they live; do not go searching. + `datetime.datetime`. The alias only governs the wire format. The map's **Type sources** tables do + not list these runtime types. - **There is no `Decimal` arm.** A fractional number becomes `float`, so a spec that models money as a number gives you binary floating point. Most payment APIs instead model money as a **`str`** scaled to the currency (`"10.00"`) — where yours does, build it with `Decimal` and format explicitly, never @@ -387,11 +371,9 @@ Three consequences: amount(Decimal("1.2344"), "KWD") # "1.234" -- not "1.23" ``` -- **`binary`/`file` is never `bytes`.** A file position takes `FileInput` (`AsyncFileInput` on the - async client) and an operation that returns one hands back `FileResponse` (`AsyncFileResponse`). - Both pairs live in `{root_package}.core` rather than `{root_package}.models`, so nothing on this - page applies to them — see **python-file-handling**. Nothing base64-encodes or decodes for you - either: where an endpoint asks for base64, hand it content that already is. +- **`binary`/`file` is never `bytes` at a file position**: it takes `FileInput` and returns + `FileResponse` (`AsyncFileInput` / `AsyncFileResponse` on the async client), from + `{root_package}.core` — see **python-file-handling**. Currency codes are typically plain `str` with no enum — pass `"USD"`. diff --git a/plugins/spotify/skills/python/python-models/reference.md b/plugins/spotify/skills/python/python-models/reference.md index 8524cc0a..2dc7a18f 100644 --- a/plugins/spotify/skills/python/python-models/reference.md +++ b/plugins/spotify/skills/python/python-models/reference.md @@ -16,13 +16,6 @@ from {root_package}.core import UNSET, UnsetType - It is only ever a **default**. Never construct `UnsetType()` yourself; pass `UNSET` if you need to spell "omitted" explicitly while building kwargs. -The two annotations that admit it, one per spelling a spec can declare: - -```python -Optional = T | UnsetType # optional — omitted or a value -OptionalNullable = T | None | UnsetType # optional+nullable — omitted, null, or a value -``` - Building a payload conditionally, without a `None` ever reaching a non-nullable field: ```python @@ -50,18 +43,13 @@ from {root_package}.models.enums import {Enum} {Enum}("{wire_value}") # wire value -> member; ValueError if unknown {Enum}.{MEMBER}.value # -> "{wire_value}" -str({Enum}.{MEMBER}) # -> "{wire_value}" (str enums only — see below) +str({Enum}.{MEMBER}) # -> "{wire_value}" (str enums only; an int enum raises TypeError) list({Enum}) # every member ``` -Coercing an unknown value with `{Enum}(...)` raises `ValueError` — that is the *closed* lookup. -The **open** alias used on model fields (`{Enum}OrStr` / `{Enum}OrInt`) does not raise; it passes the -unknown value through as the underlying scalar. Do not reimplement that coercion at your boundary; -read the field and handle the scalar arm. - -`__str__ = str.__str__` is emitted on **every** enum, which is right for a `(str, Enum)` and wrong for -an `(int, Enum)`: on an int enum, `str(member)` and f-string interpolation raise -`TypeError: descriptor '__str__' requires a 'str' object`. Use `.value` for int enums. +`{Enum}(...)` is the *closed* lookup. The open alias on model fields passes an unknown value through +as the scalar (`SKILL.md` *Enums are open*) — read the field and handle that arm rather than +reimplementing the coercion at your boundary. Tolerating an unknown value when you must map to your own enum: @@ -75,35 +63,14 @@ def to_domain(value: {Enum} | str) -> MyEnum: ## Union aliases — finding the exact arms -A union is a **type alias**, not a class, so there is nothing to construct and nothing to unwrap. The -contract sheet lists the arms; each arm is used directly. The SDK map names the **module** declaring -the alias, not its arms — read them off the alias there. - ```python from {root_package}.models import {Union} # also {root_package}.models.unions.{module} ``` -- **Plain (`anyOf`)** — `{Union}: TypeAlias = {Variant1} | {Variant2}`, with a companion - `{Union}Dict: TypeAlias = {Variant1}Dict | {Variant2}Dict`. Named after its arms when the spec gave - it no name (`{Variant1}Or{Variant2}`). -- **Discriminated (`oneOf` with a discriminator, or an `allOf` base with subtypes)** — - `{Union}: TypeAlias = Annotated[Annotated[{Variant1}, Tag("{value1}")] | …, WireDiscriminator("{tag}")]`. - The tag is the union's: build the variant and the union writes it. Some variants also declare the - tag as a field of their own, in which case it is yours to set. Where the companion alias names a - wrapper (`{Union}{Variant1}Dict`), that is the dict spelling to use — the variant's own dict shape - plus the tag key. -- **One surviving arm** — no alias module is emitted at all; the field is typed with that arm directly - (`{Variant} | None` where a dropped arm was nullable). An alias the sheet does not list does not - exist. -- Read a union back with `isinstance` / `match`; there are no `TryGet…`-style readers. - -Two runtime notes that the annotation does not show: - -```python -{RequestType}({union_field}={"{tag}": "{value}", ...}) # ✓ dict form must carry the tag -{RequestType}({union_field}={...}) # ✗ ValidationError: union_tag_not_found -model.to_dict(exclude_unset=True) # ✗ drops the defaulted tag; no longer validates back -``` +The SDK map names the **module** declaring a union, not its arms — read them off the alias there. An +unnamed `anyOf` alias is named after its arms (`{Variant1}Or{Variant2}`). A discriminated alias exists +for a `oneOf` with a discriminator **and** for an `allOf` base with subtypes. Construction and reading +rules are in `SKILL.md` *Union types*. ## Reading nested optional structures @@ -138,14 +105,6 @@ Unknown keys are also reachable by attribute access **unless** the name collides ## Type-checking notes -The SDK ships `py.typed`, so `mypy`/`pyright` check your calls against it fully. - -- `Optional[T]` from the SDK and `typing.Optional[T]` are **different types**. If you import both into - one module you will confuse yourself and your reader; the SDK's generated modules never import - `typing.Optional` — unions are spelled with PEP 604 `|` — and yours should not shadow the name. -- Passing `None` to an `Optional[T]` field is a type error the checker reports. Believe it — at - runtime it is also a `ValidationError`. (`OptionalNullable[T]` is the annotation that does admit - `None`.) -- A `{Model}Dict` literal is checked structurally, so an unknown key is an error there too. That check - is what makes the dict spelling safe to use at all — it is the *only* thing that catches a - misspelling, since the model base is `extra="allow"` at runtime. +The SDK ships `py.typed`, so `mypy`/`pyright` check your calls against it fully. The SDK's modules +never import `typing.Optional` (unions are spelled with PEP 604 `|`); don't import it into a module +that also uses the SDK's `Optional`, a different type. diff --git a/plugins/spotify/skills/python/python-testing/SKILL.md b/plugins/spotify/skills/python/python-testing/SKILL.md index 883b947a..789ccfc6 100644 --- a/plugins/spotify/skills/python/python-testing/SKILL.md +++ b/plugins/spotify/skills/python/python-testing/SKILL.md @@ -1,6 +1,6 @@ --- name: python-testing -description: Testing code that calls an APIMatic-generated Python SDK — which seam to fake (the transport protocol), asserting on the request the SDK actually built, covering the error and decode-failure paths, and keeping tests independent of SDK internals. Load before writing tests for the integration layer. +description: Load before writing unit or integration tests (pytest or unittest) for code that calls an APIMatic-generated Python SDK. Covers faking the transport protocol, asserting on the request the SDK built, and covering the error, decode, transport and token-fetch failure paths. --- # Testing code that uses an APIMatic Python SDK @@ -24,14 +24,13 @@ Substitute your own `{Api}Client` and operation names as well. The transport is a `Protocol`, so a fake needs no base class, no registration and no `Mock` — just its two methods, `send` and `close`. `send` answers with the response **head**; the body stays on -the stub until something reads it, which is what lets one stub serve a JSON call and a download -alike: +the stub until something reads it: ```python import json from collections.abc import Iterator, Mapping from dataclasses import dataclass, field -from {root_package}.core import HttpRequest, HttpResponse +from {root_package}.core import HttpMethod, HttpRequest, HttpResponse @dataclass class StubResponse: @@ -40,6 +39,7 @@ class StubResponse: status_code: int = 200 headers: Mapping[str, str] = field(default_factory=dict) chunks: list[bytes] = field(default_factory=list) + method: HttpMethod = "GET" # what a streamed payload names in its errors, with url url: str = "https://api.test/resource" closed: bool = False @@ -82,9 +82,7 @@ def json_response(status: int, body: object) -> StubResponse: ) ``` -A download is queued exactly like anything else: one seam means one kind of stubbed response, and -nothing about the stub says which operation it answers. Assert on `StubResponse.closed` to prove the -caller consumed the body and released the connection. +Assert on `StubResponse.closed` to prove the caller consumed the body and released the connection. `chunks` defaults to empty, so an empty `204` is just `StubResponse(status_code=204)` — which is what an operation declaring no response body expects (`python-calling-endpoints`). @@ -94,8 +92,7 @@ Wire it in and you have a real client with no network: ```python def client_returning(*responses: StubResponse) -> tuple[{Api}Client, StubTransport]: transport = StubTransport(*responses) - # retry_options=0: retries are on by default, so without it a stubbed 429 or 503 on a GET would be - # sent four times, with real waits between them. + # retry_options=0 turns off the default retries (see Notes): one stubbed response, one send. client = {Api}Client(custom_http_client=transport, retry_options=0, {scheme}=...) return client, transport ``` @@ -106,10 +103,10 @@ contract sheet lists. Its value is that scheme's type: a plain `str` for a beare the credentials model or dict for basic auth or an OAuth grant (`python-authentication`). **Do not patch the client's private attributes** (`_raw_client`, `_auth`, …) and do not -`Mock(spec={Api}Client)`. Both couple your tests to internals the generator is free to change, and a +`Mock(spec={Api}Client)`. Both couple your tests to internals that change without notice, and a mocked client cannot catch the mistakes that actually happen — a wrong path parameter, a body that does not serialize, a header you forgot. Faking the transport exercises the real request-building -pipeline; that is the whole point. +pipeline. ### The token request comes first @@ -129,8 +126,8 @@ assert len(transport.requests) == 2 req = transport.last_request # index from the end, not [0] ``` -Or bypass acquisition entirely with a stub token source — the generator's supported injection point -(`python-authentication`) — so the stub transport only ever sees your operation: +Or bypass acquisition entirely with a stub token source (`python-authentication`), so the stub +transport only ever sees your operation: ```python from {root_package}.core import OAuthTokenRefreshable @@ -157,7 +154,8 @@ client = {Api}Client( The token is **cached on the scheme**, so only the first call fetches one: a test making two calls against one client sees three requests, not four. Forgetting the token request is the most common way a first test fails confusingly — the operation's decoder is handed the token body, and you get a -`ValidationError` about your payload rather than anything mentioning auth. The tests below queue only +`ResponseDecodeError` (a `ValidationError` about your payload on `__cause__`) rather than anything +mentioning auth. The tests below queue only the operation's response; for OAuth where the SDK fetches the token itself, put `token_response()` first (except in the bad-credentials test). @@ -217,17 +215,14 @@ def test_unmapped_status_is_raw(): # Body on demand: .text() always, .json() only if you know it is JSON (it raises ValueError). ``` -**Take the union from the contract sheet per operation.** The typed arm is not one type across the -API, so an error test copied from a sibling operation can pass for the wrong reason — it lands in the -`RawError` branch and asserts nothing about the typed body you meant to check. And never assert on -`str(e)` or `repr(e)`: they render as status plus payload *type name* by design, and are not a stable -contract. +**Take each operation's union from its own sheet row** — an error test copied from a sibling +operation can land in the `RawError` branch and pass for the wrong reason, asserting nothing about the +typed body you meant to check. ## Test the result-style (`with_raw_response`) variant -If your code uses the non-raising peer (`python-calling-endpoints`), there is nothing to catch — stub -the response and assert on the returned `ApiResult` directly. The split is mechanical: **2xx is -`Success`, everything else is `Failure`**, and both carry `.status_code` and `.headers`. +If your code uses the non-raising peer, there is nothing to catch — stub the response and assert on +the returned `Success` / `Failure` (`python-calling-endpoints`): ```python from {root_package}.core import Failure, Success @@ -243,9 +238,7 @@ def test_raw_response_reports_failure_without_raising(): assert "/{expected/path}" in transport.last_request.url # the operation, not the token ``` -This is also the mode to test in when your code depends on a header on the *success* path -(`Success(payload=..., status_code=..., headers=...)`), because the parsed form exposes neither — -except for a file response, which carries its own `headers` on the parsed path. +Test in this mode when your code reads a header on the *success* path. ## Assert the outgoing request @@ -253,66 +246,60 @@ except for a file response, which carries its own `headers` on the parsed path. actually change: ```python +import json from {root_package}.core import JsonBody req = transport.last_request assert req.method == "POST" assert req.url.endswith("/{expected/path}") assert "{query_param}=..." in req.url # query is part of the URL string -assert isinstance(req.body, JsonBody) and isinstance(req.body.value, dict) # narrow before indexing -assert req.body.value["{wire_field}"] == "..." # JsonBody carries the dumped payload +assert isinstance(req.body, JsonBody) # narrow before reading +assert json.loads(req.body.content)["{wire_field}"] == "..." # JsonBody carries the wire bytes assert req.headers["authorization"] == "Bearer t" # lowercase key — see below assert req.headers["{header}"] == "..." # a real default reached the wire ``` -**`HttpRequest.headers` keys are lowercased, not just the response's.** Every layer — the API's, the -endpoint's, the auth scheme's and your own `extra_headers` — is normalized before the merge, which is -exactly what makes the merge case-insensitive. So `req.headers["Authorization"]` is a `KeyError` and -`req.headers["authorization"]` is the assertion you want. This is the single most common way a first -request assertion fails confusingly. (The defensive `"authorization" in {k.lower() for k in -req.headers}` also works, but there is no case to defend against — assert the lowercase key.) +**`HttpRequest.headers` keys are lowercased**, at every layer — the API's, the endpoint's, the auth +scheme's and your own `extra_headers` — so assert `req.headers["authorization"]`; +`req.headers["Authorization"]` is a `KeyError`. **The body is already serialized by the time a transport sees it.** `req.body` is one of `JsonBody` -(`.value`, the dumped JSON-safe object), `FormBody` (`.fields`), `MultipartBody` (`.parts`, an -ordered sequence of `MultipartText` and `MultipartFile` — **not** a `.fields`/`.files` pair, and a -file part's `content` is the unread descriptor you passed, never bytes), `BinaryBody` -(`.content`, `.media_type`) or `TextBody` (`.text`, `.media_type`, `.charset`) — no transport ever -serializes anything — so assert on the dumped value -directly rather than re-parsing bytes. Note it uses **wire aliases**, because that is what -serialization produces: if a model's Python name differs from its JSON name, the request body has the -JSON name. Do not "fix" that in the test. - -**A list-valued query or form parameter has a per-parameter wire format.** The `Param` the generator -emitted for it in `apis/{controller}.py` carries a `SerializationFormat` — `indexed` -(`name[0]=a&name[1]=b`, URL-encoded as `name%5B0%5D=a`), `unindexed` (`name[]=a&name[]=b`), `plain` -(`name=a&name=b`), or `csv` / `tsv` / `psv` (`name=a,b`). Read it before asserting on `req.url`; -`"name=a" in req.url` is the assertion that fails against an indexed parameter. Path and header -arrays are not configurable — both fold to one comma-separated value. +(`.content`, the compact UTF-8 JSON bytes, and `.media_type`), `FormBody` (`.content`, the +url-encoded bytes), `MultipartBody` (`.parts`, an ordered sequence of `MultipartText` and +`MultipartFile` — **not** a `.fields`/`.files` pair; a text part's `.content` is its UTF-8 bytes, and a +file part's `.content` is the unread descriptor you passed, never bytes), `BinaryBody` +(`.content`, `.media_type`) or `TextBody` (`.content`, `.media_type`, `.charset`). Parse the JSON bytes +with `json.loads` and assert on the result — there is no dumped object to read — and expect **wire +aliases**: a member whose Python name differs from its JSON name is under the JSON name +(`python-models`). + +**A list-valued query or form parameter has a per-parameter wire format** — the `SerializationFormat` +on its `Param` in `apis/{controller}.py`: `indexed` (`name[0]=a&name[1]=b`, URL-encoded as +`name%5B0%5D=a`), `unindexed` (`name[]=a&name[]=b`), `plain` (`name=a&name=b`), or `csv` / `tsv` / +`psv` (`name=a,b`). Read it before asserting on `req.url`; `"name=a" in req.url` is the assertion that +fails against an indexed parameter. Path and header arrays always fold to one comma-separated value. Worth asserting once, somewhere, because they are silent when wrong: -- **The value actually reached the wire.** Models *preserve* unknown fields rather than rejecting them - (`python-models`), so a misspelled optional member becomes a preserved extra field instead of an - error. The only thing that catches it is an assertion on the serialized body. +- **The value actually reached the wire.** A misspelled optional member becomes a preserved extra + field, not an error (`python-models`); only an assertion on the serialized body catches it. - **Idempotency keys**, on operations that accept one: the same logical operation retried sends the *same* value, and two different operations send different ones (`python-configuration-resilience`). -- **Timeout plumbing.** `req.timeout` reflects a per-call `request_options={"timeout": ...}` and - **only** that. The client's own `timeout=` never rides the request — it configures the SDK's default - transport — so `req.timeout is None` on an ordinary call is correct, not a bug. A test that asserts - the client-level timeout on a captured request is asserting something that was never there; and once - you supply a stub transport, the client's `timeout=` reaches nothing at all. +- **Timeout plumbing.** `req.timeout` carries a per-call `request_options={"timeout": ...}` and + **only** that, so it is `None` on an ordinary call. The client's own `timeout=` never rides the + request — it configures the SDK's default transport, and with a stub transport it reaches nothing. - **Bodies that cannot serialize.** A value the SDK cannot dump raises *before* anything is sent, so the failure never reaches your stub and `transport.requests` stays empty. Worth one test where it applies (`python-models`). ## Cover the failures that are not `ApiError` -Three failure kinds never match `except ApiError`, and code that handles only the raised-`ApiError` -path is the norm (`python-error-handling`). Each is cheap to simulate. +Three failure kinds never match `except ApiError` (`python-error-handling`); each is cheap to +simulate. -**A decode failure — and it bypasses *both* response modes.** A body that does not deserialize raises -`pydantic.ValidationError` (or a plain `ValueError` for a non-JSON body). `with_raw_response` does -**not** turn it into a `Failure`: +**A decode failure** raises `ResponseDecodeError` (pydantic's `ValidationError`, or a plain `ValueError` +for a non-JSON body, on `__cause__`) in both response modes — `with_raw_response` does **not** turn it +into a `Failure`: ```python def test_unreadable_success_body_is_not_reported_as_failure(): @@ -324,9 +311,8 @@ def test_unreadable_success_body_is_not_reported_as_failure(): assert "/{expected/path}" in transport.last_request.url # the operation, not the token ``` -**A truncated 2xx that decodes cleanly.** Members are required only where the description marks them -required — often nowhere — so a response missing a member validates fine and reads back `UNSET`. Only -your own guard catches it, so test the guard: +**A truncated 2xx that decodes cleanly.** A response missing an optional member validates fine and +reads back `UNSET` (`python-error-handling`). Only your own guard catches it, so test the guard: ```python def test_truncated_success_body_is_not_reported_as_success(): @@ -337,28 +323,35 @@ def test_truncated_success_body_is_not_reported_as_success(): assert "/{expected/path}" in transport.last_request.url # the operation, not the token ``` -**A transport failure**, which arrives as the HTTP library's own exception, unwrapped — have the stub -answer any token response you queue, then raise on the operation's request: +**A connection failure**, which arrives as `SdkConnectionError` with the HTTP library's exception on +`__cause__`. A transport owes that shape, so the stub raises it too: answer any token response you +queue, then raise on the operation's request: ```python +import httpx2 +from {root_package}.core import SdkConnectionError, SdkTimeoutError, safe_url + class RaisingTransport(StubTransport): - """Answers the queued responses, then raises `error` on the next send.""" + """Answers the queued responses, then raises the family's exception for `cause` on the next send.""" - def __init__(self, error: Exception, *responses: StubResponse) -> None: + def __init__(self, cause: httpx2.TransportError, *responses: StubResponse) -> None: super().__init__(*responses) - self._error = error + self._cause = cause def send(self, request: HttpRequest) -> HttpResponse: if self._responses: # a queued token response, if any return super().send(request) self.requests.append(request) - raise self._error + method, url = request.method, safe_url(request.url) + if isinstance(self._cause, httpx2.TimeoutException): + raise SdkTimeoutError(f"{method} {url} timed out", method=method, url=url, timeout=5.0) from self._cause + raise SdkConnectionError(f"{method} {url} could not be sent: {self._cause}", method=method, url=url) from self._cause -def client_raising(error: Exception, *responses: StubResponse) -> tuple[{Api}Client, RaisingTransport]: +def client_raising(cause: httpx2.TransportError, *responses: StubResponse) -> tuple[{Api}Client, RaisingTransport]: # Pass token_response() only for OAuth where the SDK fetches the token itself (no # {scheme}_token_source); never for bearer, API key or basic auth. - transport = RaisingTransport(error, *responses) + transport = RaisingTransport(cause, *responses) return {Api}Client(custom_http_client=transport, retry_options=0, {scheme}=...), transport @@ -378,16 +371,13 @@ def test_read_timeout_is_an_unknown_outcome(): assert "/{expected/path}" in transport.last_request.url # the operation, not the token ``` -**Two transport failures, both inputs — never one.** A refused connection was never sent, so its -outcome is known: nothing happened. A read timeout may have landed, so its outcome is not. Test both -and expect **different** values — as the two tests above, or as the single two-input test -`python-error-handling` shows. A test that builds only one of them, or two that one assertion -satisfies, cannot tell the cases apart — and then neither can your code. When the SDK fetches a token, -let the token request through first: a failure *there* means your operation was never sent at all, -whatever the exception is called. +Test both inputs and expect **different** values: a test of only one, or two that one assertion +satisfies, cannot tell a never-sent failure from one that may have landed. When the SDK fetches a +token, let the token request through first — a failure *there* means your operation was never sent at +all. -And the one people forget: **bad credentials**. A failed token fetch raises `ApiError` too, but its -payload is `OAuthProviderError | RawError` — *not* the operation's union — and it surfaces out of the +And the one people forget: **bad credentials**. A failed token fetch raises `AuthSchemeError`, with +the token endpoint's `ApiError` on `__cause__` (never the operation's), and it surfaces out of the operation call. Return an RFC 6749 error body from the **token** request and assert your configuration error, not a rejection error: @@ -407,13 +397,14 @@ the response with `aiter_bytes`, `aread` and `aclose`, so queue an `AsyncStubRes ```python from collections.abc import AsyncIterator -from {root_package}.core import AsyncHttpResponse, HttpRequest +from {root_package}.core import AsyncHttpResponse, HttpMethod, HttpRequest @dataclass class AsyncStubResponse: status_code: int = 200 headers: Mapping[str, str] = field(default_factory=dict) chunks: list[bytes] = field(default_factory=list) + method: HttpMethod = "GET" # what a streamed payload names in its errors, with url url: str = "https://api.test/resource" closed: bool = False @@ -473,11 +464,8 @@ a `# type: ignore`. derives its payload from the model's own definition cannot detect a wrong payload. - **Build fixtures with models, then serialize** — `{request_fixture}().to_dict()` — rather than hand-writing wire JSON, so a member rename fails the fixture instead of passing a stale test. -- **Test your own boundary's output, not the SDK's.** The valuable assertions are that a 4xx the - caller caused becomes your 4xx, a 4xx that is **yours** — `401`, `403`, `429` — becomes your `502` - or `503`, and a transport failure becomes `502` if it was never sent and `504` if it may have landed - (`python-error-handling`). That the SDK raises `ApiError` on a 422 is the SDK's own tested - behaviour, not yours. +- **Test your own boundary's output** — the `provider_error` mapping in `python-error-handling` — not + that the SDK raises `ApiError` on a 422, which is the SDK's own tested behaviour. ## Integration tests against a live environment @@ -506,20 +494,18 @@ never gate CI on a third party's uptime unless you mean to. `retry_options=0` so one stubbed response is seen exactly once. In a test *about* retrying, set a policy with `initial_delay` and `max_jitter` small, queue one response per attempt and count `transport.requests`. For the loop to retry a - *transport* failure the fake must raise `TransportError` from `{root_package}.core` — a - bare `httpx2.ConnectError` bypasses the loop and reaches the test on the first attempt + *connection* failure the fake must raise `SdkConnectionError` from `{root_package}.core`, as + `RaisingTransport` does — a bare `httpx2.ConnectError` bypasses the loop and reaches the test, + unwrapped, on the first attempt (`python-configuration-resilience`). -- **A `401` invalidates the cached token but does not retry the request.** A test that stubs a `401` - therefore sees one failed operation — and the *next* call in the same test re-fetches a token, so - queue another `token_response()` for it. +- A stubbed `401` fails one operation and the *next* call re-fetches a token + (`python-authentication`), so queue another `token_response()` for it. - Mocking libraries (`unittest.mock`, `pytest-mock`) work too — the protocol is structural, so a `Mock()` with `send` and `close` configured satisfies it. The hand-written stub above gives you typed captured requests and ordered responses for free. -- **Stubbing a download** needs nothing extra: the SDK wraps the same `StubResponse` in the - `FileResponse` your assertions see, so the stub decides what the caller reads and when the - connection is released. Give it `chunks` if the test drives `iter_bytes`. What the caller may then - do with it — and the `ResourceWarning` an abandoned one emits, which a category default filters - unless you enable it here — is `python-file-handling`. +- **A download** is the same `StubResponse`, wrapped in the `FileResponse` your code sees; give it + `chunks` if the test drives `iter_bytes`. Making an abandoned download's `ResourceWarning` fail a + test is in `python-file-handling`. - **Use the client as a context manager or close it** in tests as in production; a stub's `close()` is a no-op, but the habit keeps the test and the real wiring the same shape (`python-client-initialization`). diff --git a/plugins/spotify/skills/typescript/typescript-authentication/SKILL.md b/plugins/spotify/skills/typescript/typescript-authentication/SKILL.md index ae49a764..c676f732 100644 --- a/plugins/spotify/skills/typescript/typescript-authentication/SKILL.md +++ b/plugins/spotify/skills/typescript/typescript-authentication/SKILL.md @@ -1,12 +1,12 @@ --- name: typescript-authentication -description: Authentication for an APIMatic-generated TypeScript SDK — supplying credentials on the client options object, the credential shape each scheme kind takes, OAuth 2 token caching and refresh, and replacing the token source. Load before wiring credentials into the client, or when a call comes back 401/403. +description: Load before setting credentials on an APIMatic-generated TypeScript SDK client, or when a call returns 401/403 — API keys, bearer and basic auth, the OAuth 2 client-credentials, password and authorization-code grants, token caching and refresh, and supplying your own token source. --- # Authenticating an APIMatic TypeScript SDK client -How you authenticate depends on the security scheme(s) the API declares. APIMatic surfaces each scheme -as an **optional credential member on `ClientOptions`**; set the one(s) your API uses, then construct +How you authenticate depends on the security scheme(s) the API declares. Each scheme is an +**optional credential member on `ClientOptions`**; set the one(s) your API uses, then construct the client (see `typescript-client-initialization`). There is no separate credentials builder, no per-request auth override, and no way to change a credential after construction. @@ -24,19 +24,17 @@ scheme factory as shared runtime code regardless of what the API accepts, so rel rather than that folder. Where a member's name does not tell you its kind, `src/auth-schemes.ts` shows which core factory each member is wired to. -The credential types below live under `src/core/auth/` and are exported from the package root; they -are the **same across all APIMatic TypeScript SDKs**. Only the **option member names** are generated -per-API (hence the `{scheme}` placeholders). The generator distinguishes **eight** scheme kinds — that -list is closed, so if the spec declared something outside it, read `src/auth-schemes.ts` to see what -was actually emitted rather than assuming a ninth shape. The eight collapse to **three** credential +The credential types below live under `src/core/auth/`, are exported from the package root and are +the **same across all APIMatic TypeScript SDKs**; only the **option member names** are per API (hence +the `{scheme}` placeholders). There are exactly **eight** scheme kinds, taking **three** credential shapes: | Scheme kind | `ClientOptions.{scheme}` type | Sent as | | --- | --- | --- | | HTTP bearer | `TokenProvider` | `Authorization: Bearer {token}` | -| API key in header | `TokenProvider` | the spec's header name | -| API key in query | `TokenProvider` | the spec's query parameter | -| API key in cookie | `TokenProvider` | a `Cookie` pair under the spec's name | +| API key in header | `TokenProvider` | the API's header name | +| API key in query | `TokenProvider` | the API's query parameter | +| API key in cookie | `TokenProvider` | a `Cookie` pair under the API's name | | HTTP basic | `BasicAuthCredentials` | `Authorization: Basic base64(user:pass)` | | OAuth 2 client credentials | `OAuth2ClientCredentials` | `Authorization: Bearer {fetched token}` | | OAuth 2 password | `OAuth2PasswordCredentials` | `Authorization: Bearer {fetched token}` | @@ -72,7 +70,7 @@ Sends `Authorization: Bearer ACCESS_TOKEN`. ## API key (header, query, or cookie) The key is sent as a header, query parameter, or cookie — its placement and name are fixed by the -generated scheme, not by anything you pass. Set the configured key member to your key string: +SDK, not by anything you pass. Set the configured key member to your key string: ```ts const client = new {Api}Client({ {scheme}: process.env.API_KEY! }); @@ -124,9 +122,9 @@ The SDK fetches and caches the token itself, acquiring a fresh one when it expir invalidates the cached token and re-acquires on the next call. `scope` is a **single space-delimited string**, not a list — you join it yourself, per RFC 6749 §3.3. -An empty string is treated as absent and no `scope` field is sent. The generator emits **no scope -enum or literal union** even where the spec declares a scope vocabulary, so a scope the flow does not -document type-checks fine and fails at the provider instead. +An empty string is treated as absent and no `scope` field is sent. It is typed plain `string` — **no +scope enum or literal union** — so a scope the provider does not offer type-checks and fails at the +provider. ## OAuth 2.0 — authorization code (3-legged, with PKCE) @@ -158,8 +156,8 @@ The URL handed to your callback carries `response_type=code`, `client_id`, `redi never see or manage it. - **`promptForAuthorizationCode` is called lazily**, on the first request needing the scheme — the - same point at which the other grants fetch their token. In a server app that is almost never what - you want mid-request; see *Supplying your own token source* below. + same point at which the other grants fetch their token. For a server app, see *Supplying your own + token source* below. - **PKCE is on by default.** Omitting `pkce` means `PkceMethod.S256`; `pkce: null` disables it. The verifier and challenge are generated with `crypto.getRandomValues` / `crypto.subtle`, so the runtime needs Web Crypto (Node 20+ and browsers have it). @@ -185,19 +183,18 @@ on the authorization request and never generated or checked here — the SDK nev producing and verifying it are yours alone. Your redirect handler must compare it against what you generated before returning the code, or the CSRF token is decorative. -⚠ **`clientSecret` is optional in the type, and only one of the two ways it can be missing throws.** +⚠ **`clientSecret` is optional in the type, and leaving it out throws only when PKCE is off.** | PKCE | `clientSecret` missing ⇒ | | --- | --- | | disabled (`pkce: null`) | `AuthError("A client secret is required when PKCE is disabled…")` — **before** the prompt runs | -| enabled, token request is header-placed | no error: the SDK sends `Authorization: Basic base64(clientId:)` and the provider rejects it — **after** the user has completed the full browser round-trip | -| enabled, token request is body-placed | fine — this is the public-client case | +| enabled | fine — this is the public-client case: the code exchange and every refresh send `client_id` as a form field and no `Authorization` header | -The placement is fixed by the spec, not by you, and is visible as the `placement` argument in -`src/auth-schemes.ts` (`"header"` sends `Authorization: Basic base64(clientId:clientSecret)` on the -token request; `"body"` sends `client_id` / `client_secret` as form fields). Check which one your -generated `src/auth-schemes.ts` passes before treating the secret as optional — the header case's -failure is the expensive one, because it costs an interactive login before the exchange fails. +An empty string counts as missing. The placement is not yours to choose: it is the `placement` +argument in `src/auth-schemes.ts` — `"header"` sends `Authorization: Basic +base64(clientId:clientSecret)` on the token request, `"body"` sends `client_id` / `client_secret` +as form fields. Without a secret, both placements send `client_id` alone, so a public client works +whichever one your spec chose. ## OAuth 2.0 — resource owner password @@ -215,7 +212,8 @@ const client = new {Api}Client({ ## Token caching & refresh (all OAuth 2 grants) -- Tokens are cached **in memory, per client instance**, and reused until **30 s** before expiry. +- Tokens are cached **in memory, per client instance**, and reused until **30 s** before expiry, or + for **half their lifetime** when that is longer. - Acquisition is **lazy** — on the first request that requires the scheme, not at construction. A client built with bad credentials constructs perfectly happily; the failure surfaces at the first operation. One in-flight acquisition is **shared**: concurrent requests that arrive during a fetch @@ -223,48 +221,39 @@ const client = new {Api}Client({ - The fetch is a form-encoded `POST` to the token endpoint, sent with **no auth scheme of its own**, and it runs on its own `retry.timeout` and the call's abort signal — so token-fetch time does not come out of the operation's attempt. -- **A failure while obtaining the token is not retried by the call.** It ends the call. -- **The token request is itself a `POST` under the same policy.** With the default - `httpMethodsToRetry`, an error status from the token endpoint — a `503` included — is not retried: - it is an `AuthError` and ends the call. Name `POST` in the gate and the token request retries a - retryable status like any other `POST`; the `AuthError` ends the call once those retries are spent. +- **A failure while obtaining the token ends the call.** The token request is itself a `POST` under the + client's retry policy, so with the default `httpMethodsToRetry` even a `503` from the token endpoint + is an immediate `AuthError`; name `POST` in the gate and the token request retries a retryable status + first. - **The cache lives in the client object.** Build the client once (see `typescript-client-initialization`) or every call re-runs the grant. -- **Only the authorization-code grant refreshes.** It is the one grant wired to - `oauth2RefreshableScheme` / `OAuth2RefreshableTokenStrategy`. Client-credentials and - resource-owner-password re-run the whole grant when the token expires — and a `refresh_token` in a - password-grant response is **discarded**, because the non-refreshable `OAuthToken` has no field for - it. Do not infer refresh behaviour from what the provider returns. -- When the authorization-code grant does refresh, a refresh response that omits `refresh_token` - carries the previous one forward. A refresh that fails does not throw — it returns `null` internally - and falls back to a full re-grant. +- **Only the authorization-code grant refreshes.** Client-credentials and resource-owner-password + re-run the whole grant when the token expires, and a `refresh_token` in a password-grant response is + **discarded** — do not infer refresh behaviour from what the provider returns. A refresh response + that omits `refresh_token` keeps the previous one, and a failed refresh does not throw: it falls back + to a full re-grant. - On `401`, the cached token is invalidated and re-acquired on the **next** call — `401` is not in the - default `statusCodesToRetry`, so the failing request is **not** re-sent. Handle the 401 as an ordinary `ApiError` (see `typescript-error-handling`); - the recovery is automatic on the following attempt, not on this one. + default `statusCodesToRetry`, so the failing request is **not** re-sent; handle it as an ordinary + `ApiError` (see `typescript-error-handling`). Add `401` to `statusCodesToRetry` to have the failing + call re-sent with a fresh token — every attempt resolves its credential again. A static key is + re-sent unchanged, so that only helps a scheme that fetches its credential. +- **Invalidation is a hint, not a barrier.** It clears the cache without cancelling a token fetch + already in flight, so that fetch can complete and re-populate it; "invalidate, then read" does not + guarantee a fresh token. ⚠ **A `401` on the authorization-code grant is an interactive re-authorization, not a silent refresh.** Invalidation clears the whole cached token, refresh token included, so "re-acquired" means the *full* grant runs again and `promptForAuthorizationCode` fires. Expiry takes the refresh path; a `401` does not. Plan for that in a non-interactive host. -⚠ **The 30-second buffer is flat, with no floor.** A token whose `expires_in` is **30 or less** is -already past its adjusted deadline the moment it is cached, so every request re-runs the grant and the -cache never serves anyone. There is no half-of-lifetime fallback for short tokens. If your provider -issues sub-minute tokens, supply your own token strategy rather than paying a token round-trip per -call. - -⚠ **If the token response omits `expires_in`, the token never expires as far as the SDK is -concerned** — and a non-positive `expires_in` is treated the same way. `expires_in` is RECOMMENDED but -not required by RFC 6749, and the SDK's expiry check short-circuits to "not expired" when it is -absent, so the first token is cached for the life of the client and the only thing that ever replaces -it is a `401`. That is usually fine and occasionally not: a token revoked server-side keeps being sent -until a request fails with it. If your provider omits `expires_in` and you need proactive rotation, -supply your own token strategy (below) rather than trying to bound the cache. - -- **Invalidation is a hint, not a barrier.** It clears the cache without cancelling an acquisition - already in flight, so that fetch can complete and re-populate it. That is deliberate — the newer - token post-dates the invalidation — but it means "invalidate then immediately read" is not a - guarantee of a fresh token. +**A short-lived token is renewed halfway through its lifetime.** The 30-second buffer applies to a +token issued for a minute or more; below that, the token is reused for half its `expires_in` — a 20 s +token for 10 s. So no token is stale the moment it is cached, and a sub-minute token costs one token +round-trip per half-lifetime rather than one per call. + +⚠ **A token response without a positive `expires_in` never expires in the cache** — the first token +is kept for the life of the client and only a `401` replaces it, so a token revoked server-side is +sent until a request fails with it. For proactive rotation, supply your own token strategy (below). ### Supplying your own token source @@ -311,42 +300,10 @@ turns into a redirect attempt inside a request. ## The failure mode that surprises everyone -**A failed token fetch surfaces out of your *operation* call, and `.asApiResult()` does not protect -you from it.** - -Auth is resolved inside the same dispatch the operation runs through, so both consequences follow from -one fact — the token fetch happens *during* your operation: - -1. **The traceback points at the operation you called**, not at anything named "auth". A token - endpoint that answers `400 invalid_client` becomes an `AuthError` thrown from - `client.{resource}.{operation}(...)`, with the underlying `ApiError` on `.cause` — and its own - `method` and `uri` name that operation, not the token endpoint. Reading only the top frame sends you - looking in the wrong place entirely. -2. **The non-throwing form still rejects.** `.asApiResult()` converts the *operation's* error response - into an `{ ok: false }` result instead of throwing — but auth is resolved before any response - exists, so an `AuthError` propagates straight out of the `await`. Code written specifically to - avoid exceptions still needs a `try`/`catch` around an authenticated call. - -So a boundary that only inspects `result.ok` is incomplete: - -```ts -import { AuthError } from "{package-name}"; - -try { - const result = await client.{resource}.{operation}(request).asApiResult(); - if (!result.ok) { /* the operation's own error union */ } -} catch (err) { - if (err instanceof AuthError) { - // Credentials/token problem — the operation request was never sent. - throw new Error("API credentials rejected", { cause: err }); - } - throw err; -} -``` - -Treat it as an **auth** failure, distinct from an operation rejection: nothing was attempted, -so retrying it or reporting it as a failed operation are both wrong. `typescript-error-handling` has -the full catch ladder. +A token endpoint that answers `400 invalid_client` rejects the *operation* call with `AuthError` — its +`method`/`uri` name the operation, the token endpoint's `ApiError` is on `.cause`, nothing was sent, +and `.asApiResult()` does not convert it. Catch it around every authenticated call; the ladder is in +**typescript-error-handling**. ## Combined / multiple schemes @@ -361,10 +318,6 @@ by `allAuth(...)` / `anyAuth(...)`; you configure it by setting the relevant cre not on which looks more specific. A `TokenProvider` **function** always counts as "has credentials", even if it returns an empty string — so a function provider always wins the OR. -**This layer never withholds a request over a missing credential, and never throws for one.** An -unconfigured member simply drops out and the request goes out with whatever *was* configured; with -nothing configured at all it goes out unauthenticated. The server decides. - Because composition is **per operation**, one client may authenticate different operations with different schemes — so set every member the operations your integration actually calls need, not just the ones the API's front page advertises. The per-operation requirement is the **Auth** bullet on the @@ -373,10 +326,8 @@ out: `` `{scheme}` ``, `all of …`, or `any of … — the first one configured ## No auth -An operation the spec marked public is wired to `noneAuth` and sends **no credential even when every -option member is filled**. Its **Auth** bullet reads `none — public; no credential is sent`. Nothing -you pass at construction adds a credential to such an operation — if it needs one, that is a spec -problem, not a configuration one. +An operation whose **Auth** bullet reads `none — public; no credential is sent` sends **no credential +even when every option member is filled**, and nothing you pass at construction adds one. ## ⚠ Missing credentials must stop the app from starting @@ -394,31 +345,10 @@ An API that serves anonymous traffic at all — public endpoints, or a reduced r callers — makes this worse by answering `200` and hiding the omission entirely. So verify the member is actually set rather than waiting for a `401` to tell you. -**A required credential that is not configured is a deployment fault, not a request fault.** If the -app boots with a blank secret, an operator sees a provider outage, retry logic hammers a call that can -never succeed, and the actual cause — an unset environment variable — is two layers away from the -symptom. There is no `.env` support and no `fromEnvironment()` helper in the SDK, so **validate at the -call site and refuse to boot**: - -```ts -function buildClient(): {Api}Client { - const key = process.env.API_KEY; - if (!key) { - throw new Error( - "API_KEY is not configured. Set it via environment variable or your secret store " + - "before starting the app.", - ); - } - - return new {Api}Client({ - serverEnvironment: ServerEnvironment.Production, - {scheme}: key, - }); -} -``` - -Run that check **before** the app is ready to serve — at module load or in your startup path, not -lazily on first use, which is a request, which is exactly the late failure you are trying to avoid. +**A required credential that is not configured is a deployment fault, not a request fault.** There is +no `.env` support and no `fromEnvironment()` helper in the SDK, so **validate every required +credential in your startup path and refuse to boot** — not lazily on first use, which is a request. +The factory in **typescript-client-initialization** shows the shape. Three rules for the message it fails with: @@ -435,38 +365,26 @@ absent, so a blank env var is the same fault as an unset one. ## Notes -- A given SDK only exposes the credential members for the schemes its API declares; those names are - generated per-API (hence the `{scheme}` placeholders above). Fill every member the operations you - call need. - **Credentials are fixed at construction.** `ClientOptions` is `readonly` and the auth schemes are built in the constructor, so to rotate a credential you use a `TokenProvider` **function**, replace the strategy, or build a new client. There is no mutable accessor. - **Rotating a long-lived client:** the token cache is per client instance, so swap atomically — build the new client, then replace the shared reference. In-flight calls finish on the old one and there is no window where calls have no credential. Do not mutate the old client. -- **Auth wins every header, query and cookie collision.** Auth params are merged **last**, after the - client's defaults and the endpoint's own, so a scheme's `Authorization` header overwrites anything - set earlier under that name. There is no per-request header override to undo it — a `fetch` wrapper - is the only place you can strip or replace an auth header (see +- **Auth wins every header, query and cookie collision** — a scheme's `Authorization` header + overwrites anything else under that name, and only a `fetch` wrapper can strip or replace it (see `typescript-configuration-resilience`). - **Nothing hides secrets in a log you write.** Credentials are plain objects with no redacting `toString`, so `console.log(options)` or a serialized `ClientOptions` prints them in full. The SDK's - own logging, off by default, masks the `Authorization` header, a query value off its safe list and - the OAuth form keys (`client_secret`, `password`, `refresh_token`, …) — but a JSON request body it - logs verbatim once `logRequestBody` is on (see **typescript-configuration-resilience**). -- On the OAuth 2 token request, header placement sends `base64(clientId:clientSecret)` **without - percent-encoding either half** first. A client id or secret containing a character RFC 6749 §2.3.1 - would have you encode is sent raw, so a provider that follows the RFC strictly may reject it — use - body placement or a custom strategy if your secret is not in the unreserved set. -- **`AuthError` means a credential could not be obtained** — the token request failed, every - configured branch of an alternatives requirement failed, PKCE was disabled without a secret, or your - `promptForAuthorizationCode` rejected. Being *refused* a credential by the API is an `ApiError` with - status 401/403 instead, so one `catch` arm cannot absorb the other. A token endpoint that answers with - an error status surfaces as `AuthError` with that `ApiError` on `.cause`; an alternatives requirement - whose every branch failed carries an `AggregateError` there, holding each branch's failure. -- Credentials never appear in a thrown error's message. -- **A token endpoint may live on a different server group than the operations.** Overriding - `serverOptions.default.{environment}.baseUrl` therefore does not move the token request — override - that group too if you need both redirected at a mock. See `typescript-configuration-resilience`. -- Keep secrets out of source — read `process.env` or your secret manager at the call site. Set - credentials **before** constructing the client; there is no way to add them afterwards. + own logging masks a credential in a header, the query or an OAuth form body, but not in a JSON request + body (**typescript-configuration-resilience**). +- On the OAuth 2 token request, header placement with a secret sends + `base64(clientId:clientSecret)` **without percent-encoding either half** first. A client id or + secret containing a character RFC 6749 §2.3.1 would have you encode is sent raw, so a provider that + follows the RFC strictly may reject it — use body placement or a custom strategy if your secret is + not in the unreserved set. +- `AuthError` (a credential could not be *obtained*) versus a 401/403 `ApiError` (refused by the API): + **typescript-error-handling**. +- A token endpoint may live on its own server group, so redirecting the operations' group at a mock + does not move it (**typescript-configuration-resilience**). +- Keep secrets out of source — read `process.env` or your secret manager at the call site. diff --git a/plugins/spotify/skills/typescript/typescript-calling-endpoints/SKILL.md b/plugins/spotify/skills/typescript/typescript-calling-endpoints/SKILL.md index 74e5dd04..df47f393 100644 --- a/plugins/spotify/skills/typescript/typescript-calling-endpoints/SKILL.md +++ b/plugins/spotify/skills/typescript/typescript-calling-endpoints/SKILL.md @@ -1,16 +1,16 @@ --- name: typescript-calling-endpoints -description: Calling operations on an APIMatic-generated TypeScript SDK — finding the resource that owns an operation, building the one flat channel-blind request object, required vs optional vs defaulted fields and the values that never appear on the request at all, passing a body, the ApiPromise return and the two ways to read it, bounded concurrency, and cancellation. Load before writing the first call to an SDK operation, or when an operation's shape or return type is unclear. +description: Load before writing the first call to an APIMatic-generated TypeScript SDK operation, or when an operation's request shape or return type is unclear — the one flat request object, required, optional, defaulted and SDK-fixed fields, request bodies and file uploads, binary responses, reading an `ApiPromise` or `.asApiResult()`, the `Pageable` walk a paged operation returns, and per-call retry and cancellation. --- # Calling endpoints on an APIMatic TypeScript SDK -Operations are **methods returning `ApiPromise`** on the client. Most are **grouped under a resource -getter** and called `client.{resource}.{operation}(...)`; an operation the spec left untagged sits -**directly on the client**, called `client.{operation}(...)`. The resource getter, the exact operation -name and its signature come from the generated SDK map (grounded in `src/client.ts` and -`src/resources/`) — operation names follow no fixed verb/resource pattern, so take the real name from -the map, never from memory. +Operations are **methods returning `ApiPromise`** on the client — or `Pageable`, for an operation the +API pages (see [A paged operation](#a-paged-operation)). Most are **grouped under a resource +getter** and called `client.{resource}.{operation}(...)`; an operation with no resource group sits +**directly on the client**, called `client.{operation}(...)`, and an SDK may have no resource level at +all. Take the getter, the exact operation name and its signature from the SDK map, never from memory — +operation names follow no fixed verb/resource pattern. > Throughout this skill, `{...}` is a placeholder for a name you take from your SDK (e.g. `{Api}Client`, > `{package-name}`, `{resource}`, `{Resource}`, `{Operation}`, `{Enum}`) — replace it with the concrete @@ -30,8 +30,7 @@ the map, never from memory. the docs do not carry. Both the docs and `src/` ship inside `node_modules/{package-name}/`, so read them there rather than the -compiled `dist/`. **Do not assume a `client.{resource}` level exists** — when the spec declares no tags, -or exactly one tag covering every operation, no resource classes are emitted at all. +compiled `dist/`. Resource classes are exported from the package root, but only for their merged namespaces and for `instanceof`. Never construct one: its constructor takes engine internals that are not exported. @@ -44,26 +43,23 @@ Every operation has the same shape, with no positional overload and no sync vari {operation}(request: {Resource}.{Operation}Request, options?: RequestOptions): ApiPromise ``` -- **There is exactly one request parameter**, and it is **not optional** — even when every field on it - is. An all-optional request still needs `{}` passed explicitly. -- **`options` is on every generated operation**, always last, always optional. It is - `RequestOptions` = `{ signal?: AbortSignal; retry?: RequestRetryOptions }` and nothing else — see +- **There is exactly one request parameter.** It is required when any field on it is. When every field + is optional it defaults to `{}`, so the call may leave it out — `{operation}()` sends what + `{operation}({})` sends. +- **`options?: RequestOptions` is on every operation**, always last — see [Cancellation and per-call retry](#cancellation-and-per-call-retry). -- **An operation may declare no request parameter at all.** When every value the request carries is - fixed by the spec, the generator emits no parameter and exports no request type, and `options` moves - into first position. Check the **Signature** bullet before passing `{}` — it will not type-check - against an operation whose only parameter is `RequestOptions`. +- **An operation whose every value is fixed takes no request parameter** and has no request type; + `options` is then its only parameter. Check the **Signature** bullet before passing `{}` — it will + not type-check against such an operation. ```ts await client.{resource}.{operation}(); // no request await client.{resource}.{operation}({ signal }); // options only ``` -- **The map is the source of truth for the signature.** Whether a field is required, optional or - defaulted — and whether the operation takes a body at all — varies per operation. -- **Return type** varies by operation — see - [Making the call and reading the response](#making-the-call-and-reading-the-response). -- A non-2xx response **rejects** the promise unless you opt out with `.asApiResult()` — see - **typescript-error-handling**. +- Requiredness, defaults, whether there is a body, and the return type all vary per operation — read + each from its map entry. +- A paged operation returns `Pageable` in place of `ApiPromise`, and its **Returns** + bullet names the paging strategy and what ends the walk. ## The request object is flat and channel-blind @@ -90,27 +86,18 @@ the field list either, so the table is the only place to learn what went on the ### Where a field lands — the rule -Each value the spec declares produces **one of four** outcomes, and the last one catches people out: - -| What the spec declares | What you get | +| In the map | What you get | |---|---| -| **required**, no fixed value | `f: T` — a required member of the request object | -| **optional** | `f?: T` — omit it and nothing is sent for it | -| a **default value** | `f?: T` — omit it and the SDK **still sends the default** | -| a **constant** value | **no field at all** — the value is baked into the request and you cannot change it | - -Three consequences worth taking off the map before you write the call: - -- **A constant appears in no signature and in no Fields table.** Its only listing is the operation's - **SDK-sent** bullet, which spells each fixed pair as it goes on the wire. If you are hunting for a - field to set a `Content-Type`, an API version or a fixed `grant_type` with, that is why you cannot - find one — and there is no override for it short of wrapping `fetch`. -- **"Required" says nothing about the channel.** A required field may travel in the query, a header or - the form body just as easily as the path; requiredness and channel are independent columns. Never - infer one from the route. -- **Field names are the generated `camelCase` identifiers, not the wire names.** A header field - `traceId` is transmitted as `X-Trace-Id`, and the `Wire` column is where that mapping lives — it is - written only where the two differ, so a `—` means they match. +| `Req` yes | `f: T` — a required member of the request object | +| `Req` no, no `Default` | `f?: T` — omit it and nothing is sent for it | +| a `Default` | `f?: T` — omit it and the SDK **still sends the default** | +| listed only under **SDK-sent** | **no field at all** — a fixed value (a `Content-Type`, an API version, a `grant_type`) spelled as it goes on the wire; no override short of wrapping `fetch` | + +- **Requiredness and channel are independent.** A required field may travel in the query, a header or + the form body just as easily as the path; never infer one from the route. +- **Field names are `camelCase` identifiers, not the wire names.** A header field `traceId` is + transmitted as `X-Trace-Id`; the `Wire` column gives the wire name where the two differ, and `—` + means they match. The request type is declared in the resource's merged namespace, so it is `{Resource}.{Operation}Request` — importable from the package root if you want to name it: @@ -123,17 +110,11 @@ const request: {Resource}.{Operation}Request = { /* ... */ }; ## Building request models -**A JSON, text or binary operation has a `body` field.** Where the API declares an -`application/x-www-form-urlencoded` or `multipart/form-data` request, the generator emits the parts as -**individual flat request fields** alongside the path and query ones and assembles the form itself — -there is no nested body object to construct and no `body` field to pass. The operation's **Request -body** bullet says which you are looking at; the signature settles it. - -The runtime carries six request-body shapes: **empty, JSON, form-urlencoded, text, multipart and -binary**. An **XML** body has no carrier, so the operation is still emitted but **degrades to no body -field at all** — there is nothing to supply the payload through, and the request goes out with no -body. Its **Request body** bullet reads `none` in that case. If you need such an endpoint, call it -with `fetch` directly; the SDK cannot send it. +**A JSON, text or binary operation has a `body` field; a form-urlencoded or multipart operation has +none** — its parts are **individual flat request fields** beside the path and query ones, and the SDK +assembles the form. The operation's **Request body** bullet says which. An **XML**-body operation has +no body field and sends no body (its **Request body** reads `none`); call that endpoint with `fetch` +directly. **A file field takes bytes, not a path.** Every binary `body` field and every multipart file field is typed `FileInput`, which is a `Blob`, a `Uint8Array`, an `ArrayBuffer`, a `ReadableStream` of bytes, @@ -156,64 +137,38 @@ the read, so an unread stream holds the connection until you read it, cancel it `signal`. A server-chosen file name is untrusted input: sanitise it before writing to disk. -For the JSON case, the `body` field's type is a generated model — a plain object literal, no builders. -Required members must be set; optional ones are omitted from the JSON when left `undefined`, except one -with a spec default (`s.defaulted(...)` in the model's schema), which the SDK fills in and sends. Take the -type's name and the file that declares it from the **Type sources** table: - -```ts -const result = await client.{resource}.{operation}({ - body: { - requiredProp: value, // required members must be provided - optionalProp: value, // optional; unset means omitted, unless it has a spec default - }, -}); -``` - -A body's **shape varies**: some are flat scalars, others nest an inner model. The **Fields** table and -the model file named beside it carry the real members. +For the JSON case, the `body` field's type is a generated model written as a plain object literal +(**typescript-models**); take its name and the file that declares it from the **Type sources** table. -**An optional-looking body is not permission to omit it.** A `body?: T` reflects what the *spec* marked -optional, not what the endpoint needs. A create whose body is optional in the spec type-checks with -`{}` passed and then fails at the provider. Where a call obviously needs a payload, pass one. +**An optional-looking body is not permission to omit it.** A `body?: T` is optional only in the type: +a create passed `{}` type-checks and then fails at the provider. Where a call obviously needs a +payload, pass one. ### Defaults are sent, not omitted -A field the spec gave a default is filled **by the SDK** when you omit it, and it goes on the wire. -Omitting such a field is therefore not "let the server decide" — the server sees the value. Which -fields have defaults is the `Default` column of the **Fields** table. +An omitted field with a `Default` is filled **by the SDK** and sent, so the server sees the default, +and the response is the one that default asked for — a verbosity switch defaulting to the minimal form +(a create resolving to little more than an id and a status), or a field selector defaulting to one +section. Read the `Default` column **before** concluding the API dropped data — it was never +requested. -**And a default can silently narrow what comes back.** A defaulted field is *always sent*, so the -response you get is the one that default asked for, not the full resource. The two shapes that cost -people an afternoon: +### Every value is shape-checked before anything is sent -- a representation or verbosity switch defaulting to the minimal form, so a create resolves to little - more than an id, a status and some links; -- a field selector defaulting to one section, so whole branches of the response are simply absent. - -Read the `Default` column **before** concluding the API dropped data — it was never requested. - -### Every value is validated before anything is sent - -Each field is schema-encoded on the way out. A wrong type or a malformed format (a bad date string, +Each field is schema-encoded on the way out: a wrong type or a malformed format (a bad date string, say) rejects with an `EncodeError` — its `cause` the `SchemaError` naming the field — and **nothing is -sent**: no request reaches the network. That is an error in -your code, not an API failure; see **typescript-error-handling**. - -## Enums - -Enum fields take a member of the generated `const` object. The type alias is **open** — it carries a -`| (string & {})` (or `| (number & {})`) tail — so a raw string also type-checks: +sent** (**typescript-error-handling**). -```ts -import { {Enum} } from "{package-name}"; +A value constraint the spec declares — `minLength`, `pattern`, `minimum`, `uniqueItems`, a checked +`format` such as `email` — is **not** applied by the operation, so a value that breaks one is sent as +built and refused, if at all, by the service. Whether `{model}Schema.validate(body)` checks it first, +and whether an operation exports a `{Group}.{operation}RequestSchema` to `validate` the request object +against, is stated in **typescript-models** (*Checking a value before you send it*). Either `validate` +returns `{ success: true }` or `{ success: false, message }` with every failing field named. -await client.{resource}.{operation}({ status: {Enum}.Active }); // preferred — a rename is caught -await client.{resource}.{operation}({ status: "active" }); // also compiles -``` +## Enums -Prefer the member: the string form silently survives a spec change that renames the value. See -**typescript-models** for read-back semantics and for guarding an unknown value off the wire. +Enum fields take a member of the generated `const` object — `{ status: {Enum}.Active }`. A raw string +also compiles (the type is open), but only the member catches a rename. See **typescript-models**. ## Union types, collections, and dates @@ -228,10 +183,9 @@ Some fields are not plain scalars: `oneOf`/`anyOf`/polymorphic unions declared u const value = await client.{resource}.{operation}({ /* ... */ }); ``` -> **Wrap the call in error handling — a non-2xx response *rejects*, it is not signalled by the return -> value.** The bare `await` above shows only the happy path. Before writing a real call, **load -> `typescript-error-handling`** for the `try`/`catch` shape and which error type to narrow on per -> operation — or use the non-throwing `.asApiResult()` form below. +> **A non-2xx response *rejects*.** Before writing a real call, **load `typescript-error-handling`** for +> the `try`/`catch` shape and which error type to narrow on per operation — or use the non-throwing +> `.asApiResult()` form below. Operations return `ApiPromise`, a `Promise` subclass. Two ways to consume it: @@ -256,25 +210,18 @@ type ApiResult = payload: PayloadOf }; ``` -Five things to know: - -- **`.asApiResult()` must be called on the value the operation returned.** `ApiPromise` overrides +- **Call `.asApiResult()` on the value the operation returned.** `ApiPromise` overrides `Symbol.species`, so `.then()`, `.catch()` and `.finally()` hand back a plain `Promise` and the - method is gone. `op(...).then(x => x).asApiResult()` does not compile. -- **`.asApiResult()` still rejects for every other failure** — a body that would not decode, a value that - would not encode, a connection error, a timeout, a credential that could not be obtained, or a caller - abort. It converts only the *HTTP error status* branch into a value, so it still needs a - `try`/`catch` around it. -- **On failure, `outcome` carries the error's own members, not the error object** — `status`, - `headers`, `message`, `method`, `uri` and `payload` — so `outcome.payload.kind` narrows exactly as - `err.payload.kind` would. The `ApiError` instance is not reachable through this path. -- **Nothing suppresses an unhandled rejection.** A call you never await that fails is reported by the - runtime — `unhandledRejection` on Node, which by default ends the process. `.asApiResult()` marks the - promise handled as its first act, so call it on the returned value in the same turn, and never start - a call you do not consume. -- **Both paths read one underlying outcome**, so awaiting an `ApiPromise` *and* calling - `.asApiResult()` on it issues no second request. The request goes out when the operation is called, - not when you await it — which also means a call you build and hold has already been sent. + method is gone — `op(...).then(x => x).asApiResult()` does not compile. +- **It converts only the HTTP error status.** Every other failure still rejects, so keep the + `try`/`catch`; on failure `outcome` carries the error's members, not the error object + (**typescript-error-handling**). +- **The request goes out when the operation is called**, not when you await it; awaiting and + `.asApiResult()` read the same outcome and never send twice, so a call you build and hold has already + been sent. +- **Nothing suppresses an unhandled rejection.** A call you never consume that fails is an + `unhandledRejection` — on Node, by default, the process ends. `.asApiResult()` marks the promise + handled as its first act, so call it on the returned value in the same turn. ### Status and headers @@ -284,73 +231,77 @@ deliberately unreachable. ### The success type -`T` is whatever the operation's success body decodes to. The **Returns** bullet names it, and the cases -you will meet are: +The operation's own **Returns** bullet names `T`, which can differ between sibling operations: -- **A model type** — a JSON body decoded through the generated schema. The **Type sources** table names - the file under `src/models/` where you read its shape; the map does not duplicate it. -- **A primitive** — a `text/plain` body decoded by the plain-text scalar decoder, not by a model. -- **`undefined`** — the operation's success response has no body. That is a real value, not a mistake: - the decoder asserts the body is empty, and a non-empty one rejects with `DecodeError`. +- **A model type** — a JSON body decoded through its schema. The **Type sources** table names the file + under `src/models/` where you read its shape. +- **A primitive** — a `text/plain` body. +- **`undefined`** — no body; a non-empty one rejects with `DecodeError`. Resolving *is* the success + signal: do not test the value, re-read the resulting state with a separate call if you need it, and + use `.asApiResult()` to tell a `200` from a `204`. +- **`EventStream`** — a `text/event-stream` body. The call resolves at the response headers with + nothing read, and `for await` over the stream yields each event's decoded `data` as a `T`; the + stream holds its connection until the loop ends or you `close()` it. Load + **typescript-event-streams** before you write the loop. -**On an `undefined` operation, resolving *is* the success signal.** Do not bind the value and do not -test it — success is "did not reject", exactly as for the others. Two follow-ons: if you need the -resulting state, re-read it with a separate call; and if you need to tell a `200` from a `204`, -`.asApiResult()` is the only place the status appears. +### A paged operation -Endpoints in the same family can differ, so let each operation's own **Returns** bullet decide how you -read it. +An operation the API pages returns **`Pageable`** instead of `ApiPromise`. The +**Signature** bullet shows it, and the **Returns** bullet names the strategy and what ends the walk. +Nothing is sent when you call it: the walk is lazy, the first page goes out when a loop starts, and +each new loop starts again from the first page. -## Cancellation and per-call retry +```ts +// Items, across every page — the SDK fetches the next page as the previous one runs out: +for await (const item of client.{resource}.{operation}({ /* ... */ })) { + process(item); +} -`RequestOptions` is the entire per-call surface: +// Pages, when you need the page's own members (a total, a cursor, a link): +for await (const page of client.{resource}.{operation}({ /* ... */ }).pages()) { + process(page.{items}); +} -```ts -type RequestOptions = { - signal?: AbortSignal; - retry?: RequestRetryOptions; // Pick -}; +// The result form — an error status as a value instead of a throw: +for await (const result of client.{resource}.{operation}({ /* ... */ }).asApiResult().pages()) { + if (!result.ok) break; // the failed page is the last one the walk yields +} ``` -`retry` overrides three fields of the client's retry policy for this call alone, field by field — a -field you leave out keeps the client's value: +The request's paging fields (`page`, `offset` or `cursor`, and `limit`) **seed the first page** with +their declared defaults applied; the SDK advances the page, offset or cursor from there. `options` +applies to every page the walk sends. Either loop throws `E` at the first error status, and every +other failure exactly as an awaited call would reject — a `{Api}Error` member, or a caller abort's +own `reason`. An item loop over `.asApiResult()` **ends silently** at an error status, so use +`.pages()` on the result form when the distinction matters. **Every walk needs a bound of your +own** — a page cap, an item cap or a deadline; **typescript-configuration-resilience** carries the +strategies, their stop rules and the bounded shape. + +## Cancellation and per-call retry + +`RequestOptions` = `{ signal?: AbortSignal; retry?: RequestRetryOptions; logging?: RequestLoggingOptions }` +is the entire per-call surface. `retry` overrides `maxRetries`, `timeout` and `statusCodesToRetry` for +this call, field by field — a field you leave out keeps the client's value — and `logging` takes only a +`level`. Headers, base URL, auth and the other retry and logging fields are client-level only +(**typescript-client-initialization**, **typescript-configuration-resilience**). ```ts await client.{resource}.{operation}({ /* ... */ }, { retry: { maxRetries: 0 } }); // one attempt await client.{resource}.{operation}({ /* ... */ }, { retry: { timeout: 5_000 } }); // 5 s per attempt -``` - -There is **no** per-call header, base URL or auth override, and the type admits no other retry field -(though the runtime honours one it is handed) — those belong on -`ClientOptions` at construction (**typescript-client-initialization**), and the retry policy's other -fields on `ClientOptions.retry` (**typescript-configuration-resilience**). -```ts const controller = new AbortController(); setTimeout(() => controller.abort(new Error("too slow")), 5_000); - await client.{resource}.{operation}({ /* ... */ }, { signal: controller.signal }); ``` -An already-aborted signal rejects immediately. See **typescript-configuration-resilience** for -deadlines across a whole call and for combining signals. - -Three mechanics that decide how you catch the result: - -- **Your signal and each attempt's `retry.timeout` race the same internal controller**, so an - attempt ends on whichever fires first. `retry.timeout` bounds **one attempt**, in milliseconds, even - when set per call — an idempotent call that keeps failing gets up to four of them, plus backoff — so - a signal plus your own timer is how you bound the whole call. An abort also cuts a backoff wait short, - and is never retried. -- **An abort rejects with the signal's own `reason`, unwrapped, and a timeout with `TimeoutError`** - once no retry is left. - Whatever you passed to `controller.abort(reason)` — or the `DOMException` a bare `abort()` supplies — - is what the call rejects with, so it is **not** an `{Api}Error`; the timeout is the SDK's own and - stays in the family. -- **Neither is an `ApiError`.** A `catch` that narrows on `ApiError` — or on an operation's declared - error class — will **not** match an abort, a timeout or a connection failure. See - **typescript-error-handling** for a ladder over the whole family, and for rethrowing what is outside - it. +- `retry.timeout` bounds **one attempt**, in milliseconds, even when set per call — an idempotent call + gets up to four attempts plus backoff — so only your `signal` bounds the whole call + (**typescript-configuration-resilience** for deadlines and combining signals). An abort — an + already-aborted signal included — ends the call at once, cuts a backoff wait short and is never + retried. +- An abort rejects with the signal's own `reason`, unwrapped, and an exhausted timeout with + `TimeoutError`. Neither is an `ApiError`, and the abort is not an `{Api}Error` at all — see + **typescript-error-handling** for a ladder over the whole family. ## Concurrency @@ -386,8 +337,11 @@ const all = await mapLimit(ids, 10, (id) => client.{resource}.{operation}({ id } Note that `Promise.all` rejects on the first failure and leaves the rest of the batch running unobserved; `Promise.allSettled` is usually what you want when partial success is acceptable. -Nothing is paginated and nothing is async-iterable, so there is no `for await` form. If an operation -returns a page, advance its page or cursor field yourself in a loop — see +A paged operation returns a `Pageable`: `for await` it and the SDK fetches the pages one at a time — +see [A paged operation](#a-paged-operation). The only other `for await` form is over an +`EventStream`, which only an operation whose **Returns** bullet reads `EventStream` hands back +(**typescript-event-streams**). A list operation whose **Signature** returns `ApiPromise` is a single +call; to page one of those, advance its page or cursor field yourself in a loop — see **typescript-configuration-resilience**. ## Worked example — a list/GET call @@ -425,7 +379,8 @@ if (!outcome.ok) { > This operation's success body is a model that nests its list under a member, so you read that member > and then iterate. Another operation may return the array directly, or a primitive, or `undefined`. -> Check its **Returns** bullet. +> Check its **Returns** bullet — and when its **Signature** returns `Pageable`, it is walked with +> `for await` rather than awaited (see [A paged operation](#a-paged-operation)). ## Next diff --git a/plugins/spotify/skills/typescript/typescript-client-initialization/SKILL.md b/plugins/spotify/skills/typescript/typescript-client-initialization/SKILL.md index 8f8dcacf..8e23d37f 100644 --- a/plugins/spotify/skills/typescript/typescript-client-initialization/SKILL.md +++ b/plugins/spotify/skills/typescript/typescript-client-initialization/SKILL.md @@ -1,6 +1,6 @@ --- name: typescript-client-initialization -description: Creating and reusing an APIMatic-generated TypeScript SDK client — construction, the ClientOptions shape, fetch ownership and client lifetime, and wiring the client into an application's startup. Load before wiring the client into an app or writing the factory that builds it. +description: Load before writing the code that builds an APIMatic-generated TypeScript SDK client — `ClientOptions`, environments and base URLs, client lifetime and the token cache, wiring the client into app startup or dependency injection, ESM and CommonJS, and inbound webhooks. --- # Initializing an APIMatic TypeScript SDK client @@ -18,8 +18,8 @@ from the SDK you are using: - `{resource}` / `{operation}` — a resource getter on the client and an operation on it. - `{scheme}` — a credential member on the options object, one per auth scheme the API declares. -Everything under `src/core/` is vendored static code that is **byte-identical in every generated -TypeScript SDK**, so the engine behaviours below hold without checking yours. What varies per SDK is +Everything under `src/core/` is **the same in every APIMatic TypeScript SDK**, so the engine behaviours +described in these skills hold without checking yours. What varies per SDK is `src/client.ts`, `src/client-options.ts`, `src/servers.ts`, `src/auth-schemes.ts`, `src/resources/` and `src/models/`. @@ -42,8 +42,8 @@ Two facts about where those files live: `dist`, `src`, `README.md`, `api-reference.md`, `sdk-map.md` and `map`, so the readable TypeScript source and the lookup index are both inside `node_modules/{package-name}/`. Read them there rather than the compiled `dist/`. -- **`dist/` must exist before the package can be referenced.** The SDK builds with `tshy`; a freshly - generated SDK consumed by path needs its `build` script run once. A `Cannot find module` on a +- **`dist/` must exist before the package can be referenced.** The SDK builds with `tshy`; an SDK + consumed by path needs its `build` script run once. A `Cannot find module` on a path-installed SDK is usually this, not a bad import. ## Shape of the client @@ -59,69 +59,52 @@ Nothing on it is required and neither is the argument, so `new {Api}Client()` co object is the whole configuration surface, and reading the environment into it is yours to do at the call site. -Operations are exposed on the client. Most are grouped under **resource getters** (one per API -resource group) and called `client.{resource}.{operation}(...)` — for example, a `widgets` resource's -`listWidgets` operation is `client.widgets.listWidgets(...)`. But when the spec declares **no tags**, -or exactly **one tag covering every operation**, no resource classes are emitted at all and every -operation sits **directly on the client**, called `client.{operation}(...)`. The available resource -getters (and any direct operations) come from the contract sheet (grounded in `src/client.ts` and -`src/resources/`) — not from the API's own documentation, and not from the compiled `dist/`. See -**typescript-calling-endpoints**. +Operations hang off resource getters, `client.{resource}.{operation}(...)`, or sit directly on the +client when the SDK has no resource level — take them from the contract sheet, not the API's own +documentation (**typescript-calling-endpoints**). -The options type always carries these five knobs (credential members vary per API — see +The options type always carries these six knobs (credential members vary per API — see **typescript-authentication**): ```ts export type ClientOptions = { - readonly serverEnvironment?: ServerEnvironment; // selects the base URL - readonly serverOptions?: ServerOptions; // per-server, per-environment baseUrl override - readonly retry?: RetryOptions | undefined; // retry policy + per-attempt timeout (MILLISECONDS). - // Retries ON by default - readonly logging?: LoggingOptions | undefined; // request/response logging — OFF by default - readonly fetch?: FetchLike | undefined; // the ONE transport extension point — - // see typescript-configuration-resilience + readonly serverEnvironment?: ServerEnvironment; // selects the base URL + readonly serverOptions?: ServerOptions; // per-server, per-environment baseUrl override + readonly retry?: RetryOptions | undefined; // retry policy + per-attempt timeout (MILLISECONDS). + // Retries ON by default + readonly logging?: LoggingOptions | undefined; // request/response logging — OFF by default + readonly eventStream?: EventStreamOptions | undefined; // event-stream idle timeout (MILLISECONDS) — + // read only by an EventStream operation + readonly fetch?: FetchLike | undefined; // the ONE transport extension point — + // see typescript-configuration-resilience // + one OPTIONAL credential member per auth scheme the API declares, and — for an OAuth2 scheme — // a {scheme}Strategy member alongside it (see typescript-authentication) }; ``` -Those five names are minted by the generator and cannot move; a credential spelled like one of them is -the member that takes a suffix instead. **Every member is `readonly`**, and the client captures your -options once, at construction — a different configuration means a new client. Each default is -applied where the value is read: a server variable takes the `@default` on its member in -`src/client-options.ts`, `fetch` takes its in `src/core/client-options.ts`, every `retry` field -takes its in `src/core/retry.ts`, and every `logging` field its in `src/core/logging.ts`. Read them -there rather than trusting the numbers on this page. -Note in particular that the default `serverEnvironment` is the **first** environment the spec -declares, which is not necessarily the production one. - -**Retries are on by default.** With `retry` left out, a `GET`, `HEAD`, `PUT` or `OPTIONS` call that -gets a `408`, `429`, `500`, `502`, `503` or `504`, or loses its connection, or times out, is re-sent -up to **3** more times with exponential backoff and jitter, honouring `Retry-After`. A `POST`, -`PATCH` or `DELETE` is sent once unless you name its method in `httpMethodsToRetry`. Every one of -those numbers is a `RetryOptions` field you can change, and `retry: { maxRetries: 0 }` turns retrying -off. So **a failed idempotent call surfaces only after its retries are spent** — seconds later than the -first failure, not at it. **typescript-configuration-resilience** owns the policy: the field table, -what is and is not retried, and per-call overrides. - -**`fetch` is not a niche escape hatch — it is the only transport seam there is.** The SDK carries -**no hooks, middleware or interceptors**, **no pagination** and **no streaming**. Each of those is -something you build by wrapping `fetch` — including a header you want on every request. -**typescript-configuration-resilience** carries the wrappers. **Logging is built in and off by -default**: `logging` turns it on, and so does the `{APICLIENTTYPENAME}_LOG` environment variable (the -client class name in upper snake case, plus `_LOG`) when code sets neither a `logger` nor a `level` — so a -deployment can start writing request lines with no code change. `retry.onRetry` is the one built-in -callback, and it sees only retries. A replacement `fetch` is called with one `Request` and no `init`, -and **must forward that `Request`, or its `signal`,** to whatever performs the request; drop the signal -and both cancellation and every attempt's timeout go inert. - -`retry.timeout` has its own trap: it is in **milliseconds**, it bounds **one attempt** — up to -its response headers — not the whole call, and a value the platform cannot honour is **not** "no timeout" — it is -resolved once when the client is built, and a negative, fractional, `NaN`, `Infinity` or out-of-range -value silently falls back to the default (`60_000`) rather than failing. A usable value reaches the -timer verbatim, so `timeout: 0` aborts every attempt instead of lifting the deadline. A single call -may override `maxRetries`, `timeout` and `statusCodesToRetry`, and its log level, through -`RequestOptions` = `{ signal, retry, logging }`; nothing else is per call. +Those six names are fixed in every SDK; a credential named like one of them carries a suffix +instead. **Every member is `readonly`**, and the client captures your options once, at construction — +a different configuration means a new client. Each default is applied where the value is read: a +server variable takes the `@default` on its member in `src/client-options.ts`, `fetch` takes its in +`src/core/client-options.ts`, every `retry` field takes its in `src/core/retry.ts`, every +`logging` field its in `src/core/logging.ts`, and `eventStream.idleTimeout` its in +`src/core/event-stream.ts`. Read them there rather than trusting the numbers on this +page. The default `serverEnvironment` is the **first** `ServerEnvironment` member, which is not +necessarily the production one. + +**Retries are on by default**: an idempotent call (`GET`, `HEAD`, `PUT`, `OPTIONS`) that fails +retryably is re-sent up to 3 more times with backoff, so its failure surfaces seconds late, and +`retry.timeout` (milliseconds) bounds each attempt, not the call; `retry: { maxRetries: 0 }` turns +retrying off. **typescript-configuration-resilience** owns the policy. + +**`fetch` is the only transport extension point.** The SDK has no hooks or middleware, and streams +only a `text/event-stream` response, through an operation that resolves to an `EventStream` +(**typescript-event-streams**) — build anything else by wrapping `fetch` +(**typescript-configuration-resilience**). A replacement must +forward the `Request` it is handed, or its `signal`, or cancellation and timeouts go inert. **Logging is +built in and off by default**, and the `{APICLIENTTYPENAME}_LOG` environment variable (the client class +name in upper snake case, plus `_LOG`) can turn it on with no code change +(**typescript-configuration-resilience**). ## Direct instantiation @@ -148,9 +131,9 @@ accepted and fails later, one layer from its cause: | Passed at construction | When it actually fails | | --- | --- | -| a `retry` field out of range — a negative or fractional `timeout`, a `maxJitter` above `1`, a lower-cased `"get"` in `httpMethodsToRetry` | never — that field silently falls back to its default. `timeout: 0` is the exception: it is kept, and aborts every attempt. There is no `ValueError` equivalent here | +| a `retry` field out of range — a negative or fractional `timeout`, a `maxJitter` above `1`, a lower-cased `"get"` in `httpMethodsToRetry` | never — that field silently falls back to its default. `timeout: 0` is the exception: it is kept, and aborts every attempt | | a `baseUrl` override | first call — as a connection error, or as a `401` against the wrong host | -| wrong credentials | first call — and under OAuth2, first *token* request, so the error names the token endpoint rather than the operation you wrote | +| wrong credentials | first call — under OAuth2 as an `AuthError` from that operation, with the token endpoint's `ApiError` on `.cause` (**typescript-error-handling**) | | a misspelled or extra credential field | never at run time. Credentials are plain objects checked only by TypeScript; nothing re-validates them at construction | | **an omitted** credential | first call, as a `401`. An unset credential configures the client for **no auth** — the operation sends no credential rather than erroring. See **typescript-authentication** | @@ -159,74 +142,36 @@ before constructing. ### Client and fetch lifetime -The SDK does **not** own a connection pool — `fetch` does. On Node the global `fetch` shares one -process-wide dispatcher, so the reason to keep one client is not the socket pool; it is everything the -constructor resolved and cached. - -**Keep the SDK client long-lived — it is not a stateless wrapper.** The only thing you hand it is -configuration; its constructor resolves the rest and then owns it: - -- the **transport** — a `RawClient` built over the resolved `fetch` implementation. If no `fetch` is - reachable, **the constructor throws `ConfigurationError`**, not the first call; -- the **server groups** — `buildServers(options)` runs here and resolves every group **once**: the - environment and each override are read and decoded as the client is built, and every call afterwards - only attaches its own sub-path. So assigning `serverEnvironment` or mutating an override on the - object you passed in does nothing, and a bad value throws from the constructor rather than from a - call. Configure the server before you construct, and construct a new client to change environment. - See **typescript-configuration-resilience**, *What is captured when*; -- the **auth schemes** — validated at construction (a basic-auth username containing `:` throws - `ConfigurationError` from the constructor), and for an OAuth2 SDK the auth scheme *is* the access-token - cache, closed over by the scheme object. - -That last one is the reason a per-request client is a real cost rather than a stylistic one: a fresh -client starts with an empty token cache, so **every construction pays a token request on its first -call**. Three calls through three throwaway clients is three token round-trips where a shared client -makes one — and the shared one also collapses concurrent callers onto a single in-flight token -acquisition, which the throwaway ones cannot. - -Resource getters are memoized per client (`client.{resource}` builds once, behind `??=`, and is -cached), so they are part of the same bargain. Never construct a resource class yourself: they are -exported only for their merged namespaces and for `instanceof`, and their constructors take engine -internals that are not exported. +**Keep the SDK client long-lived.** `fetch` owns the connection pool, but the constructor resolves and +then owns the rest: the `fetch` implementation, every server group (mutating the options object +afterwards does nothing; construct a new client to change environment — +**typescript-configuration-resilience**, *What is captured when*), the memoized resource getters, and +the auth schemes — for an OAuth2 SDK the scheme *is* the access-token cache. A fresh client starts with +an empty token cache, so **every construction pays a token request on its first call**, and +throwaway clients cannot share one in-flight token acquisition the way a shared client does. Construct per request only where you genuinely need different credentials per request — and then expect the token fetch. For rotating a secret without rebuilding, a credential member accepts a **function** instead of a string; see **typescript-authentication**. -**There is nothing to close.** `src/core/` declares no `close()`, no `dispose()`, and no -`Symbol.dispose` / `Symbol.asyncDispose`, so the client holds no releasable resource and needs no -shutdown hook — the connection pool belongs to the runtime's `fetch`, not to you. The flip side is -that there is no drain either: to stop in-flight requests at shutdown you abort them yourself through -each call's `signal`. +**There is nothing to close** — no `close()`, `dispose()` or `Symbol.dispose`, and no shutdown hook to +register. There is no drain either: to stop in-flight requests at shutdown, abort each call's +`signal`. -**The `fetch` implementation is resolved once, in the constructor** (`config.fetch ?? globalThis.fetch`, -then stored). Two consequences that fail silently: - -- **Monkey-patching `globalThis.fetch` after a client exists has no effect on that client.** A test - that swaps the global and reuses a module-level client is still calling the original. Pass the fake - through `ClientOptions.fetch` and build the client after — see **typescript-testing**. -- **A replacement must satisfy `typeof fetch`** — it is called as `fetch(request)`, one `Request` and - no `init`, with `this` set to `undefined`, so a transport method that depends on its receiver must be - bound before you pass it. It must forward that `Request`, or its `signal`, and resolve to a - `Response` the decoder can read `status`, `headers` and a body from. - **typescript-configuration-resilience** owns the wrappers. +**The `fetch` implementation is resolved once, in the constructor** — yours, else `globalThis.fetch`; +with neither, the constructor throws `ConfigurationError`. Patching `globalThis.fetch` after a client +exists does not reach it, so pass a fake through `ClientOptions.fetch` and build the client after it +(**typescript-testing**). A replacement is called as `fetch(request)` — one `Request`, no `init` — with +`this` set to `undefined`, so bind a method before passing it; **typescript-configuration-resilience** +owns the rest of its contract. ## Choosing the server / base URL -**The shape does not vary with the spec.** However many servers or environments the API declares — one -of each, or several of both — you always get a `ServerEnvironment` object and a `serverOptions` bag -keyed by server group; a single-server, single-environment API simply gets a one-member enum and a -one-group bag. There is no arm where the constructor takes a bare `baseUrl` instead. - -Environments are modeled as a `ServerEnvironment` const object plus a matching type alias, with one -member per environment the API defines (e.g. `ServerEnvironment.Production`, or region members). -Unlike model enums it is **closed** — no `| (string & {})` tail — so only declared members type-check. -Select one on `serverEnvironment`. - -Overriding the base URL is nested **per server group AND per environment** — -`serverOptions.{group}.{environment}.baseUrl`, NOT directly on `serverOptions`. Any **templated -server variables** sit at that same level, beside `baseUrl`, one key per variable the URL template -names: +Select an environment with `serverEnvironment: ServerEnvironment.{Environment}` — a **closed** const +object (no `| (string & {})` tail), one member per environment the API defines, even when there is only +one. There is no bare `baseUrl` option: an override is nested **per server group AND per environment** +— `serverOptions.{group}.{environment}.baseUrl` — with any template variables beside `baseUrl`, and it +merges key-wise over that environment's defaults: ```ts const client = new {Api}Client({ @@ -237,16 +182,10 @@ const client = new {Api}Client({ }); ``` -An override is merged key-wise over that environment's defaults, so setting `baseUrl` alone leaves the -template variables in place, and naming one group leaves the other groups alone. **That last part is a -trap when an OAuth token endpoint lives on its own group**: redirecting the `default` group at a mock -does not move the token request, which still reaches the real host. Override every group the run -touches. - -The group keys, the environment members, and the URL each resolves to are all in -`DEFAULT_SERVER_OPTIONS` in `src/servers.ts`, and tabulated under **Servers & auth** in the contract -sheet — **read them there**, because a member's name does not reliably tell you its host. -**typescript-configuration-resilience** owns server and base-URL configuration in full. +The group keys, the environment members, and the URL each resolves to are in `DEFAULT_SERVER_OPTIONS` +in `src/servers.ts` and under **Servers & auth** in the contract sheet — **read them there**, because a +member's name does not reliably tell you its host. **typescript-configuration-resilience** owns server +and base-URL configuration, including an OAuth token endpoint on its own server group. ## Wiring into an application @@ -265,14 +204,11 @@ export const client = new {Api}Client({ }); ``` -⚠ **A module-level client is constructed at import time, and that has a consequence worth planning -for.** It reads `process.env` when the module is first imported — which, with ESM hoisting, can be -*before* your config loader, `dotenv`, or secret fetch has run. The credential then resolves to -`undefined`, and because **an unset credential is not an SDK error** (the operation simply sends no -credential), you do not get a startup failure. You get a `401` from the API on the first call, at -runtime, in whichever code path happens to run first — which reads like an expired token rather than -a load-order bug. Two ways out: load config before anything imports this module, or build the client -in a factory called from your startup path (below). +⚠ **A module-level client reads `process.env` at import time**, which under ESM hoisting can precede +your config loader, `dotenv` or secret fetch. The credential is then `undefined`, which the SDK treats +as no auth: no startup error, just a `401` on the first call, reading like an expired token. Load +config before anything imports this module, or build the client in a factory called from your startup +path (below). ### Building it in a factory @@ -284,27 +220,16 @@ import { {Api}Client, ServerEnvironment } from "{package-name}"; export function build{Api}Client(): {Api}Client { const token = process.env.API_TOKEN; - - // SET THIS. An unset credential is NOT an SDK error — it sends no credential and 401s later. - if (!token) throw new Error("API_TOKEN is not set"); + if (!token) throw new Error("API_TOKEN is not set"); // fail at startup, not as a 401 later return new {Api}Client({ serverEnvironment: ServerEnvironment.{Environment}, - - // SET THIS. Default 60_000 ms. Bounds ONE attempt, and an idempotent call gets up to - // 4 of them. See typescript-configuration-resilience > Retries. - retry: { timeout: 10_000 }, - + retry: { timeout: 10_000 }, // per attempt; default 60_000 ms {scheme}: token, }); } ``` -Both flagged lines are load-bearing and they answer different failures: the credential check turns a -silent `401` into a startup failure, and `retry.timeout` stops a hung provider from holding the caller -open for the full default minute on every attempt — up to four of them on an idempotent call. Setting -only the timeout is the common mistake — it looks like the configuration box is ticked. - Then register the result once, however your framework shares singletons, and inject it: ```ts @@ -335,9 +260,6 @@ what makes the service testable — a test passes a client built over a fake `fe | CLI / script | one at the top, or one per run | the process is short-lived; the cache never pays back | | Browser / edge runtime | wherever your bundle initialises | the package ships `dist/esm` and `dist/commonjs` only — no bundle, no UMD, no CDN artifact — so it goes through a bundler. Deno, Bun, Workers and Vercel Edge need only the globals the map lists, but none is a tested target | -There is no fork-safety hazard to design around the way a pooled-socket SDK has: the client owns no -pool. The cost of building one per worker is the token cache, not a corrupt connection. - ## ESM and CommonJS The package ships both dialects from a single entry, so `require` works with full types. In a @@ -350,11 +272,8 @@ import sdk = require("{package-name}"); const client = new sdk.{Api}Client({ serverEnvironment: sdk.ServerEnvironment.{Environment} }); ``` -⚠ **A process that loads both dialects gets two independent copies of every class**, including every -error class, and `instanceof` across that boundary is `false`. It is a real hazard in a mixed -codebase, and it fails silently — a `catch` arm simply never matches. Pick one dialect per process -where you can; where you cannot, narrow on `err.kind` or `err.payload.kind` instead of `instanceof`. -See **typescript-error-handling**. +⚠ **A process that loads both dialects gets two copies of every class**, so `instanceof` is `false` +across them — pick one dialect per process, or narrow on `err.kind` (**typescript-error-handling**). Two consumer compiler settings change what you type at the construction site. Under `exactOptionalPropertyTypes`, **omit or spread** an absent option rather than assigning `undefined` to @@ -364,26 +283,16 @@ are imported normally. ## Inbound webhooks — what the emitted package does and does not give you -**There is no webhook surface at all** — no webhook tree, no event parser, no signature verifier, on -any generated TypeScript SDK. Nothing under `src/core/` computes any part of an inbound webhook for -you, and no member of `ClientOptions` turns one on. +**There is no webhook surface at all** — no event parser, no signature verifier, and no member of +`ClientOptions` that turns one on. So verifying an inbound webhook is entirely yours to write, against the provider's published scheme: capture the raw body before any JSON parsing, compute the signature yourself, and compare in constant time. The SDK's model types stay useful for *deserializing* an event body once you have verified it — but do not read "the SDK parses this" as "the SDK verified this". See **typescript-models**. -Testing is a different matter and needs no shipped helpers — inject a fake `fetch`; see -**typescript-testing**. - -> **Not settled by the generator's current version.** The transport carries default header, query and -> path-parameter channels that the generated client currently wires as empty arrays — a source comment -> says nothing in the spec reaches them *yet*. If a later version starts populating them, a -> client-wide header option could appear on `ClientOptions`, so read `src/client-options.ts` rather -> than assuming the option list above is complete for your SDK. - ## Next - Configure authentication → **typescript-authentication** - Make your first call → **typescript-calling-endpoints** -- Tune timeouts, retries, logging, base URL → **typescript-configuration-resilience** +- Tune timeouts, retries, logging, base URL, paging → **typescript-configuration-resilience** diff --git a/plugins/spotify/skills/typescript/typescript-configuration-resilience/SKILL.md b/plugins/spotify/skills/typescript/typescript-configuration-resilience/SKILL.md index 480ee8e7..ca7e3480 100644 --- a/plugins/spotify/skills/typescript/typescript-configuration-resilience/SKILL.md +++ b/plugins/spotify/skills/typescript/typescript-configuration-resilience/SKILL.md @@ -1,31 +1,20 @@ --- name: typescript-configuration-resilience -description: Client configuration and resilience for an APIMatic-generated TypeScript SDK — the five ClientOptions fields, server/base-URL selection and template variables, the retry policy (on by default — what it retries, what it never does, per-call overrides) and the per-attempt timeout, cancellation, the built-in logging (off by default — levels, redaction, the environment variable), proxies, TLS and connection pooling, and what the SDK does not do for you (pagination, streaming) built on the one `fetch` seam. Load before you construct or tune the client — the field list alone does not reveal that idempotent calls are retried by default and writes are not, that the timeout bounds one attempt rather than the call, that an environment variable turns logging on with no code change, that the default environment is whichever the spec listed first, that `fetch` is handed one `Request` it must forward, that Node's fetch ignores HTTP_PROXY, or that a hand-written page loop is unbounded by default. +description: Load before constructing or tuning an APIMatic-generated TypeScript SDK client — picking a server environment or overriding a base URL, changing the on-by-default retries or `retry.timeout`, adding cancellation or a deadline, turning the built-in logging on or off, making a write safe to retry, paging through results, or wrapping `fetch` for header injection, proxies, TLS or connection pooling. --- # Configuration & resilience for an APIMatic TypeScript SDK -> **One skill, every shape.** This file covers every configuration surface the TypeScript generator -> emits. Which parts YOUR SDK exercises — how many server groups and environments it declares, which -> template variables those carry, whether an operation takes a page or cursor field, whether the API -> offers an idempotency key — are facts of the API definition, not of this skill: take them from -> `sdk-map.md` and `map/operations/{resource}.md` at the package root, and **apply only the guidance -> that matches**. - -> `{...}` is a placeholder for a name you take from your SDK — `{Api}Client` (the one public client -> class, declared in `src/client.ts`), `{resource}`/`{Resource}`, `{operation}`/`{Operation}`, -> `{group}`, `{environment}`, `{variable}`, `{items}`, `{nextCursor}`. Replace each with the concrete -> identifier from the source; none of them is a name the generator emits literally. -> -> `{APICLIENTTYPENAME}_LOG` is the logging environment variable: the client class name in upper snake -> case, plus `_LOG`, so `AcmeClient` reads `ACME_CLIENT_LOG`. The getting-started skill's identity table -> names yours. +> Which server groups, environments, template variables, page/cursor fields and idempotency-key +> fields YOUR SDK has comes from `sdk-map.md` and `map/operations/{resource}.md` at the package root — +> **apply only the guidance that matches**. `{...}` marks a name to take from your SDK; `{Api}Client` +> is the one public client class, in `src/client.ts`. `{APICLIENTTYPENAME}_LOG` is the logging +> environment variable: the client class name in upper snake case, plus `_LOG`, so `AcmeClient` reads +> `ACME_CLIENT_LOG`. The getting-started skill's identity table names yours. Everything configurable is a field on `ClientOptions` (`src/client-options.ts`), passed to the one constructor. There is no `Configuration` class, no builder, and no per-request override beyond `{ signal, retry, logging }`. Server groups, environments and their URL templates live in `src/servers.ts`. -Everything under `src/core/` is vendored static code that is **byte-identical in every generated -TypeScript SDK**, so the engine behaviours below hold without checking your SDK. ## The whole configuration surface @@ -35,6 +24,7 @@ TypeScript SDK**, so the engine behaviours below hold without checking your SDK. | `serverOptions` | `ServerOptions` | `{}` | per-group, per-environment `baseUrl` and template-variable overrides | | `retry` | `RetryOptions` | retries **on** — see *Retries* | the retry policy, and `retry.timeout` (**ms**, `60_000`) bounding each attempt | | `logging` | `LoggingOptions` | **off** — see *Logging* | the built-in request/response logger, its levels and its redaction | +| `eventStream` | `EventStreamOptions` | `idleTimeout` `60_000` (**ms**) | how long an event stream may stay silent; read only by an operation that resolves to an `EventStream` — see **typescript-event-streams** | | `fetch` | `FetchLike` (`typeof fetch`) | global `fetch` | **the one transport extension point** | | `{scheme}` / `{scheme}Strategy` | per scheme | unset | credentials — see **typescript-authentication** | @@ -43,13 +33,10 @@ default environment are per-SDK. ## Not on this SDK -Absent **by design**, not undocumented. This list ships with `src/core/` and is versioned with it: - | You might reach for | Reality | | --- | --- | | hooks, middleware, interceptors, `onRequest`/`onResponse` | none. `fetch` is the one transport extension point; `retry.onRetry` is the one callback, and it sees only retries | -| pagination, `for await`, auto-paging helpers | no operation is paginated and nothing is async-iterable | -| SSE, `text/event-stream` | no event streams. Every decoder reads the body to completion, bar a binary success, which hands its stream over unread | +| SSE request bodies, WebSockets | none. `text/event-stream` is a response media type only — an operation whose success is one resolves to an `EventStream` you iterate with `for await` (**typescript-event-streams**). Every other decoder reads the body to completion, bar a binary success, which hands its stream over unread | | multipart responses, XML bodies | none. Body kinds are empty, JSON, form-urlencoded, text, multipart and binary | | per-request `headers`, `baseUrl`, idempotency key | none. `RequestOptions` is `{ signal, retry, logging }`; `retry` takes only `maxRetries`, `timeout` and `statusCodesToRetry`, and `logging` only `level` | | a circuit breaker, a rate limiter | none. The retry loop honours `Retry-After`, but nothing limits how many calls you start | @@ -60,9 +47,9 @@ those patterns and the traps in them. **What the SDK does own**, so that you do not rebuild it: URL and server resolution, request encoding and schema validation on the way out, auth application and OAuth token caching, response -decoding, the two-family error mapping, the `Idempotency-Key` on every non-GET call, the retry -loop with its per-attempt timeout, and request/response logging with redaction. Connection pooling -belongs to `fetch`, not to the client. +decoding, the two-family error mapping, the `Idempotency-Key` on every non-GET call, fetching and +advancing the pages of a paged operation, the retry loop with its per-attempt timeout, and +request/response logging with redaction. ## The `fetch` seam @@ -71,23 +58,20 @@ type FetchLike = typeof fetch; ``` The SDK calls it with **one argument, the attempt's `Request`, and no `init`**. The method, the -headers (the credential included), the body and the signal are all on that `Request`. One rule, and it -is the one that breaks things when missed: **forward that `Request`, or at least its `signal`**, to -whatever performs the request. Drop the signal and both each attempt's `retry.timeout` and per-call -cancellation go inert — the call neither aborts nor times out, because the transport enforces both -through that signal. A wrapper written against `(input, init)` still type-checks, but `init` is always -`undefined`: whatever it reads from `init` is nothing, and whatever it passes as `init` **replaces** -what the `Request` carries, so `fetch(input, { headers })` drops every header the SDK set. On an abort -a replacement may reject with whatever it likes: the SDK reads the reason off the signal it built the -`Request` with, so a deadline is still a `TimeoutError` the retry loop retries, and a caller abort -still rejects with the caller's own `reason`. +headers (the credential included), the body and the signal are all on that `Request`. **Forward that +`Request`, or at least its `signal`**, to whatever performs the request: drop the signal and both each +attempt's `retry.timeout` and per-call cancellation go inert — the call neither aborts nor times out. A +wrapper written against `(input, init)` still type-checks, but `init` is always `undefined`: whatever it +reads from `init` is nothing, and whatever it passes as `init` **replaces** what the `Request` carries, +so `fetch(input, { headers })` drops every header the SDK set. On an abort a replacement may reject with +whatever it likes: a deadline is still a `TimeoutError` the retry loop retries, and a caller abort still +rejects with the caller's own `reason`. Four facts that decide how you write a wrapper: -- **It sees every request the client makes, including the OAuth token request.** The auth schemes are - built over the same transport as the operations (`buildAuthSchemes(options, servers, rawClient)` in - the constructor), so a wrapper that logs requests logs the token POST — `client_secret` and all. The - built-in logger (*Logging*) masks it; a hand-rolled one does not. Filter by URL where that matters. +- **It sees every request the client makes, including the OAuth token request** — a wrapper that logs + requests logs the token POST, `client_secret` and all, where the built-in logger (*Logging*) masks it. + Filter by URL where that matters. - **It sits under the retry loop, so it sees every attempt.** A call retried three times is four requests through your wrapper, each a fresh `Request` with its own signal, and a wrapper that logs writes four lines. To see one line per logical call, log around the SDK call instead; to see why an @@ -115,8 +99,8 @@ export type ServerOptions = { ``` Each environment's entry exposes what the SDK substitutes into that group's URL: the **`baseUrl` -template** (always present and settable) plus any **template variables** the spec declares for that -server — a region, a subdomain, a port, an API version. Names and counts vary per API and per +template** (always present and settable) plus any **template variables** that server's URL declares +— a region, a subdomain, a port, an API version. Names and counts vary per API and per environment; a group with no variables exposes `baseUrl` alone. Read the real group keys, environment keys, URL templates and variable defaults from `DEFAULT_SERVER_OPTIONS` in `src/servers.ts`, or from the **Base URLs and overrides** table in `sdk-map.md`. @@ -136,7 +120,7 @@ const client = new {Api}Client({ }); ``` -Four things about how this resolves: +How this resolves: - **Overrides merge with the declared defaults per group-and-environment pair, key by key** (`{ ...DEFAULT_SERVER_OPTIONS.{group}.{environment}, ...yours }`). Setting `{variable}` alone keeps @@ -148,25 +132,17 @@ Four things about how this resolves: request time. A placeholder in a `baseUrl` you supply is only substituted if a declared variable of that exact name exists — otherwise it survives into the URL verbatim, and nothing rejects it the way an unfilled path parameter is rejected. -- **An environment value the SDK does not know throws `ConfigurationError` from the constructor** — - every server group is resolved once, as the client is built, so no operation method throws - synchronously. ### ⚠▶▶ Always pass `serverEnvironment` explicitly -`serverEnvironment` has a default, so `new {Api}Client()` compiles and reaches a real host. **That -default is whatever environment the spec listed first** — the first member `ServerEnvironment` -declares in `src/servers.ts`, and the one whose arm every resolver in that file labels `case -undefined:` alongside its own. For many providers the spec lists sandbox first. Nothing announces it. - -A deployment that believes it configured production and did not gets sandbox behaviour with -production credentials, which fails auth in a way that reads like a credentials problem rather than an -environment one. **Pass it in every environment, production included**, so the host a call reaches is -visible where the client is built. +`serverEnvironment` has a default, so `new {Api}Client()` compiles and reaches a real host: the +**first** member of `ServerEnvironment` in `src/servers.ts` — often sandbox. Production credentials +then fail against it as if they were wrong. **Pass it in every environment, production included.** -`ServerEnvironment` is a **closed** union — no `| (string & {})` tail — so a literal typos out at -compile time. A value arriving from configuration does not. Map it explicitly and **fail on an unknown -value** rather than falling through to the default: +`ServerEnvironment` is a **closed** union — no `| (string & {})` tail — so a mistyped literal fails to +compile; a value read from configuration does not. An unknown string throws `ConfigurationError` from +the constructor, but `undefined` silently selects the default — so map configuration values explicitly +and **fail on a miss**: ```ts const ENVIRONMENTS: Record = { @@ -178,20 +154,11 @@ const serverEnvironment = ENVIRONMENTS[process.env.API_ENV ?? ""]; if (!serverEnvironment) throw new Error(`unknown API_ENV: ${process.env.API_ENV}`); ``` -Without the guard, a typo in a deployment variable becomes `undefined`, and an `undefined` -environment is read as *none selected*: every resolver's default arm answers to `case undefined:` -alongside its own label, so the client runs quietly against the default environment instead of the -one you asked for. Nothing throws, and nothing is logged. An unknown *string* is the loud case — the -constructor rejects it with `ConfigurationError` (above) — so it is the value your own -configuration turns into `undefined` that fails silently, which is what the guard is for. - ### What is captured when -`serverEnvironment` and `serverOptions` are both read **once**, as the client is built. The constructor -calls `buildServers(options)`, which resolves every server group — the environment, its `baseUrl` and -each variable, decoded through its schema — into a value that every call afterwards only attaches its -own sub-path to. So mutating the `serverOptions` object you passed in, replacing a whole group -(`serverOptions.{group} = …`), or assigning `serverEnvironment` afterwards has no effect on the client. +`serverEnvironment` and `serverOptions` are resolved **once**, in the constructor — so a bad value +throws there, never from a call, and mutating the `serverOptions` object you passed in, replacing a +whole group (`serverOptions.{group} = …`) or assigning `serverEnvironment` afterwards has no effect. **Configure the server before you construct, and construct a new client to change environment.** ### Redirecting at a mock @@ -212,12 +179,11 @@ For a proxy, see *Proxy or custom agent* below. backing off roughly 1 s, 2 s and 4 s, and honouring `Retry-After`. - A `POST`, `PATCH` or `DELETE` is sent **once**, whatever went wrong. The method gate covers every failure, faults included. -- **A `401` is not in the default status set.** The transport invalidates whatever that operation's - auth scheme had cached, so the *next* call re-acquires; the failing call rejects. You see one `401`, - then recovery. +- **A `401` is not in the default status set**: the failing call rejects, and the *next* call + re-acquires a fetched credential (**typescript-authentication**). -The loop lives in `src/core/retry.ts`, and `src/core/raw-client.ts` runs every call through it. -Configure it with any subset of `RetryOptions` — a field you leave out keeps its default: +Its defaults live in `src/core/retry.ts`. Configure it with any subset of `RetryOptions` — a field you +leave out keeps its default: ```ts new {Api}Client({ retry: { maxRetries: 0 } }); // off: every call is sent exactly once @@ -242,66 +208,39 @@ new {Api}Client({ | `maxJitter` | `0.25` | A **fraction**, `0` to `1`, and additive: a wait lands between its delay and `delay × (1 + maxJitter)`. `0` makes every wait exact | | `onRetry` | none | `(attempt: RetryAttempt) => void`, called before each retry's wait | -`0`, `false` and `[]` are values, never misses. Anything else a field cannot honour — a negative or -fractional `timeout`, a `maxJitter` of `50`, a list carrying a lower-cased `"get"` — **silently falls -back to that field's default**, and the client still constructs. `timeout: 0` is kept: it is a -zero-length deadline that fails every attempt, not "no timeout". +`0`, `false` and `[]` are values, never misses. Anything else a field cannot honour — a negative, +fractional, `NaN`, `Infinity` or above-`2_147_483_647` `timeout`, a `maxJitter` of `50`, a list +carrying a lower-cased `"get"` — **silently falls back to that field's default** (on a call, to the +client's value), and the client still constructs. `timeout: 0` is kept: it is a zero-length deadline +that fails every attempt, not "no timeout" — an unbounded attempt is not expressible. The wait before retry *n* (counting from 0) is `min(Retry-After ?? delay × backoffFactor ** n, 60_000) × (1 + random × maxJitter)`, rounded up. The 60-second ceiling is the engine's, not an option, and jitter sits on top of it, so the longest single wait is 75 s at the defaults. -What the loop does and does not do — read these before you rely on it: +What the loop does: -- **The method gate covers every failure.** A status in the set, a dropped connection, a timeout: each - is retried only for a method in `httpMethodsToRetry`. `PUT` is in the default gate — see *Making a - write safe*. - **`Retry-After` is honoured** in both its delta-seconds and HTTP-date forms, capped at 60 s, with - jitter added on top — never subtracted, so the SDK never wakes before the time the server named. A - malformed value falls back to the curve. -- **A caller abort is never retried.** Aborting your `signal` cuts a backoff wait short and rejects - with the signal's own `reason`. -- **A streaming request body is never retried**, whatever the method, because a stream cannot be - replayed. -- **A failure while obtaining a credential is not retried.** It ends the call — once the token - request's own retries are spent, since it is a `POST` under this same policy and retries only when - `httpMethodsToRetry` names `POST`. -- **A rejection from your `fetch` that is not an SDK error counts as a dropped connection.** It - becomes a `ConnectionError` and is retried — including a refusal your own wrapper throws on purpose - (see *The `fetch` seam*). The exception is one that arrives after the attempt's timeout or your - signal fired: the SDK reads the reason off the signal it built, so a caller abort rejects as itself - and is not retried, and a timeout becomes a `TimeoutError` and is retried like any other. What the - replacement rejected with does not change either. -- **A retried-away response is released** — its body's cancel started, not awaited, before the wait, - so a cancel that stalls never holds up the retry — and only its headers reach `onRetry`. When the last attempt fails, the call rejects with **that** attempt's failure: an - `ApiError` (or the operation's subclass) for a status, a `ConnectionError` or `TimeoutError` for a - fault — the same shapes as with retrying off (**typescript-error-handling**). `.asApiResult()` sees - the last response. - -**Do the arithmetic before you accept the defaults.** `retry.timeout` bounds each attempt, not the call, -so an idempotent call's worst case is `(maxRetries + 1) × timeout` plus the waits — four minutes at the -defaults. Nothing in the SDK imposes a wall-clock ceiling on the call; *Bounding a call* below is how -you impose one. + jitter added on top, so the SDK never wakes before the time the server named. A malformed value + falls back to the curve. +- **Never retried:** a caller abort (which also cuts a backoff wait short), a streaming request body + whatever the method, and a failure to obtain a credential — the token request is itself a `POST` + under this policy (**typescript-authentication**). +- **A rejection from your `fetch` that is not an SDK error counts as a dropped connection** — see + *The `fetch` seam*. +- **The call rejects with the last attempt's failure** — an `ApiError` (or the operation's subclass) + for a status, a `ConnectionError` or `TimeoutError` for a fault — the same shapes as with retrying + off (**typescript-error-handling**). Only a retried-away response's headers reach `onRetry`, and + `.asApiResult()` sees the last response. ### Per-call overrides -Three fields can be overridden on one call through `RequestOptions.retry`, typed `RequestRetryOptions`. -Each is merged field by field over the client's policy, so a field you omit keeps the client's value: - -```ts -await client.{resource}.{operation}(request, { retry: { maxRetries: 0 } }); // this call: one attempt -await client.{resource}.{operation}(request, { retry: { timeout: 5_000 } }); // this call: 5 s per attempt -await client.{resource}.{operation}(request, { retry: { statusCodesToRetry: [503] } }); // this call: a narrower set -``` - -The type admits only these three. How many attempts *this* call gets, how long each may take, and which -statuses are worth a second try vary by call site; the backoff curve, the method gate and `onRetry` are -how the client paces itself against one server, so they are set on the client alone. A per-call -`httpMethodsToRetry` would be a second route to retrying a write. The restriction is the type's -alone: an object carrying another `RetryOptions` field — from JavaScript, or through a constant typed -as the wider record — still has it honoured, so do not rely on the type to keep a write out of the -gate for one call. +`RequestOptions.retry` (`RequestRetryOptions`) takes only `maxRetries`, `timeout` and +`statusCodesToRetry`, each merged over the client's value for that one call (syntax: +**typescript-calling-endpoints**). Backoff, the method gate and `onRetry` are client-only — but only by +type: an object carrying another `RetryOptions` field (from JavaScript, or a constant typed as the +wider record) still has it honoured, so do not rely on the type to keep a write out of the gate. ### Observing retries @@ -337,11 +276,8 @@ Rules to hold to: job that re-runs on failure — on top of the SDK's without turning the SDK's off for that path. Attempts multiply (four inside four is sixteen round-trips, and up to sixteen times the timeout), and every attempt of a caller-level layer is a new SDK call that mints a **new** `Idempotency-Key`. -- **Never retry an `EncodeError`, a `DecodeError`, an `AuthError` or a 4xx other than `408`/`429`.** On - an `EncodeError` nothing was sent at all — the fix is in your code. A `DecodeError` means the - response was malformed, which a resend rarely cures. An `AuthError` means a credential could not be - *obtained*, which is configuration, not weather. The loop retries none of them, and neither should - you. See **typescript-error-handling**. +- **Never retry an `EncodeError`, a `DecodeError`, an `AuthError` or a 4xx other than `408`/`429`** — + the loop retries none of them, and what each means is in **typescript-error-handling**. When a decision genuinely needs something the policy cannot express — a retry that depends on the decoded error payload, or on which operation it is — turn the SDK's loop off for that call and own @@ -369,15 +305,13 @@ function isTransient(err: unknown): boolean { await withRetry(() => client.{resource}.{operation}(request, { retry: { maxRetries: 0 } })); ``` -`{Api}Error` is the whole error family, narrowed on its closed `kind`. The runtime declares it as `CoreError`, and the -package exports it **only** under the SDK-branded alias — read the real name off the -`CoreError as …Error` line in `src/index.ts`. See **typescript-error-handling**. +`{Api}Error` is the whole error family, narrowed on its closed `kind`; its real name is in +**typescript-error-handling**. ### Making a write safe under retries -**Start from what you have.** With the default gate a `POST`, `PATCH` or `DELETE` is sent once. The -exposure arrives when you widen `httpMethodsToRetry` or add a retry layer of your own, and with two -things no setting fixes: +A write is exposed to a resend only when you widen `httpMethodsToRetry` or add a retry layer of your +own — and through two things no setting fixes: - **`PUT` is in the default gate — idempotent by HTTP's definition, not necessarily by your provider's.** A `PUT` can still carry a per-call side effect — an audit row, an outbound webhook, a @@ -445,17 +379,15 @@ read the numbering as a recommendation order: Three details decide whether it works: - - **A `fetch` wrapper sees every attempt of the SDK's loop by construction**, because the loop sits - above `fetch`. But its refusal reaches the loop as a `ConnectionError`, which **is retried** for a - method in the gate — each retry is refused again, and the call rejects only after the backoff, - with your error on `.cause`. Pair the guard with option 3 on the guarded write, so the refusal is - immediate, and recognise it with `err.cause instanceof YourRefusal`. + - **A `fetch` wrapper sees every attempt of the SDK's loop**, and its refusal is retried as a + `ConnectionError` (*The `fetch` seam*). Pair the guard with option 3 on the guarded write, so the + refusal is immediate, and recognise it with `err.cause instanceof YourRefusal`. - **Keep the "already sent" marker in state that outlives one attempt** — an `AsyncLocalStorage` scope the caller opens around the write, or a closure created per unit of work. A marker hung off `init` is per-attempt bookkeeping only, and a caller-level retry (a job re-running after a timeout) creates a fresh one either way. - - **Key it on method and URL.** The guard also sees the OAuth token request, and a token - acquisition must not be counted as the write. + - **Key it on method and URL**, so the OAuth token request it also sees is not counted as the + write. Count the send **before** it goes out. A request that failed on the way out may still have been received, so "this may already have taken effect" is the only safe reading — surface it as an @@ -483,42 +415,18 @@ permanent refusal. Clear it once the outcome is settled, and expire it when it n ### `retry.timeout` -In **milliseconds**, bounding **one attempt** — enforced with an `AbortController` inside the -transport, surfacing as a `TimeoutError` (`err.kind === "timeout"`) once no retry is left. Each attempt -gets its own deadline. What the field list does not tell you: - -- **It stops at the response headers.** The timer starts once the credential is in hand, so obtaining - a credential and reading the body are bounded only by your `signal`. A built-in OAuth token request - runs on its own timer. -- **A value the platform cannot honour is not "no timeout".** Negative, fractional, `NaN`, `Infinity` - and anything above `2_147_483_647` ms — the largest value a timer can hold — all fall back to the - SDK's default (on a call, to the client's value), silently, and the client still constructs. A usable - value is installed **verbatim**, `0` included, so `timeout: 0` is a zero-length deadline that fails - every attempt rather than lifting it. An unbounded attempt is not expressible. -- **One call can take its own.** `{ retry: { timeout: 5_000 } }` on the call replaces the client's - value for that call — still per attempt. For a budget on the whole call, use a signal. -- **A `fetch` replacement that does not forward the `Request`'s `signal` makes it inert.** Pass the - `Request` on, or copy it with `new Request(request)`, which keeps the signal. +In **milliseconds**, bounding **one attempt**, each with its own deadline; the last attempt's expiry +rejects as a `TimeoutError` (`err.kind === "timeout"`). It starts once the credential is in hand and +stops at the response headers, so obtaining a credential and reading the body are bounded only by your +`signal` (a built-in OAuth token request runs on its own timer). A per-call value replaces the +client's for that call, still per attempt. A value a timer cannot hold silently falls back to the +default, and `0` fails every attempt (*Retries*). ### Cancellation and real deadlines -`RequestOptions` is `{ signal?: AbortSignal; retry?: RequestRetryOptions; logging?: RequestLoggingOptions }`, -and `signal` is the whole per-call cancellation surface. - -```ts -const controller = new AbortController(); -const t = setTimeout(() => controller.abort(new Error("deadline exceeded")), 2_000); -try { - await client.{resource}.{operation}({ /* ... */ }, { signal: controller.signal }); -} finally { - clearTimeout(t); -} -``` - -A caller abort rejects with whatever you passed to `abort()` — the signal's own `reason`, unwrapped and -outside the `{Api}Error` family — so pass something diagnostic, and rethrow it from a family `catch`. -An already-aborted signal rejects immediately, and an abort during a backoff wait ends the wait and the -call; an abort is never retried. +Per-call cancellation is `RequestOptions.signal` (**typescript-calling-endpoints**). An abort rejects +with the signal's own `reason`, outside the `{Api}Error` family (**typescript-error-handling**) — so +pass something diagnostic, and rethrow it from a family `catch`. For a **deadline across a whole call or unit of work** — one call and its retries, or several calls — `AbortSignal.timeout` and `AbortSignal.any` compose (both on Node 20+): @@ -533,15 +441,10 @@ async function withDeadline(work: (signal: AbortSignal) => Promise, ms: nu That is how you give one operation a ceiling that `retry.timeout` cannot: the deadline covers every attempt and every wait, and the earlier of the two wins. -⚠▶▶ **A per-attempt timeout does not bound a request.** If one handler makes more than one SDK call — -a loop over records, a fan-out, a create-then-confirm pair — the per-call timeouts **add up**, and they -add up *faster* when each failure is caught so the work can continue: every swallowed timeout costs its -full bound and the next call still runs — and an idempotent call spends up to `maxRetries + 1` of -them before it fails. **The check is arithmetic, not judgement:** `calls in this handler × -(maxRetries + 1) × timeout`, plus the waits, must sit under the budget you are willing to make a caller -wait. Count the calls in -the loop, not the calls in the snippet — a handler that processes every record on file makes as many -calls as there are records. +⚠ **Several calls in one handler add up** — a loop over records, a fan-out, a create-then-confirm +pair — and a swallowed timeout still costs its full bound before the next call runs: `calls × +(maxRetries + 1) × timeout`, plus the waits, must fit the budget you make a caller wait. Count the +calls in the loop, not in the snippet, and bound the handler with one signal. **Give the total bound one home, not one per call site.** A controller written out at each call is the layer that gets skipped, so any operation added later silently has no ceiling. Put it at the one @@ -569,111 +472,136 @@ too. > (Chrome 98, Firefox 97, Safari 15.4). The SDK's own module-load floor is lower, so between the two > the engine still aborts the request but **produces no typed error at all**. -## Pagination — drive it yourself +## Pagination -Nothing is paginated and nothing is async-iterable. When an operation returns a page, advance its page -or cursor field in a loop and stop on the API's own end signal: +An operation the API pages returns **`Pageable<{PageResponse}, {Item}, E>`** in place of `ApiPromise`, +and its **Returns** bullet on the map names the strategy and the condition that ends its walk. The +walk is **lazy**: calling the operation sends nothing, the first page goes out when a loop starts, and +each new loop starts again from the first page. `Pageable` implements `AsyncIterable<`**`{Item}`**`>`, so a plain `for await` walks +**individual items** across every page; `.pages()` walks the decoded pages instead. The SDK fetches each +page and advances the paging state for you — one of four strategies (offset, page-number, cursor or +`Link`), chosen per operation. ```ts -// Offset/page style: -const PER_PAGE = 100; -for (let page = 1; ; page++) { - const result = await client.{resource}.{operation}({ page, perPage: PER_PAGE }); - for (const item of result.{items}) process(item); - if (result.{items}.length < PER_PAGE) break; // short page — usually the last +// The paging fields on the request (page/limit, offset/limit, or cursor) seed the FIRST page, +// with their declared defaults applied; the SDK advances the page, offset or cursor and stops when +// the API signals the end. +for await (const item of client.{resource}.{operation}({ /* limit: 100, ... */ }, { signal })) { + process(item); +} + +// Pages, not items — also where any total, cursor or link metadata on the page response lives: +for await (const page of client.{resource}.{operation}({ /* ... */ }).pages()) { + for (const item of page.{items}) process(item); } +``` + +Every page is its own request: `options` — the `signal`, the per-call `retry` and `logging` — applies to each one, +and each one goes through the retry policy on its own. Where the walk stops is the strategy's rule: + +| Strategy | Advances by | Stops when | +| --- | --- | --- | +| offset | the item count of each page | the next offset reaches the total, a page is empty, `hasMore` is `false`, or — when the page carries neither a total nor `hasMore` — a page is shorter than the limit | +| page-number | one page | the page number reaches the total pages, `hasMore` is `false`, or — when the page carries no `hasMore` — a page is empty, or is shorter than the limit with no total | +| cursor | the next cursor the response carries | the response carries no next cursor, the cursor did not change, or `hasMore` is `false` | +| `Link` | the next link the response carries, resolved against the page's own URL | the response carries no next link, or the link did not change | -// Cursor style: -let cursor: string | undefined; -do { - const result = await client.{resource}.{operation}({ ...(cursor ? { cursor } : {}) }); - for (const item of result.{items}) process(item); - cursor = result.{nextCursor}; -} while (cursor); +Two consequences of the `Link` strategy worth knowing: after the first page the request's own query +is dropped, because the link the API sent carries it; and a link is followed only to the **same origin** +as the API — another origin, or a link that is not a URL, raises `PaginationError` between pages rather +than sending a credential elsewhere (see **typescript-error-handling**). + +**A failed page throws mid-walk** — `E` for an error status, and every other failure exactly as an +awaited call would reject with it: a `{Api}Error` member, or a caller abort's own `reason`. The pages already delivered stay delivered. For the +form that turns an error status into a value, call `.asApiResult()` **on the walk**: + +```ts +for await (const result of client.{resource}.{operation}({ /* ... */ }).asApiResult().pages()) { + if (result.ok) { + // result.value is the page; result.status and result.headers are its own + } else { + // result.status, result.message, result.payload — and this is the LAST element the walk yields + } +} ``` -Read the actual page/cursor field names off the operation's **Fields** table and its response model — -they are spec-specific, and the SDK sends a defaulted `page`/`perPage` whether or not you set it. Prefer -the API's explicit end signal (a null next-cursor, a `hasMore` flag) over inferring from a short page -where one exists. +Its item loop (`for await (const item of walk.asApiResult())`) ends silently at an error status and +contributes no items for it, so an item loop that ends cannot tell the last page from a failed one — +use `.pages()` when the distinction matters. Everything else still throws from either form, as it +would from an awaited call. -### ⚠⚠ Never leave a page loop unbounded +### ⚠⚠ Never leave a page walk unbounded -**Both loops above are wrong as written**, and the reason is the same one that makes hand-driven paging -riskier than the auto-paging this SDK does not have: *the only stop condition is the provider's -cooperation*. A provider that keeps returning a next cursor, a cursor that fails to advance, a filter -the provider quietly ignores, or a `perPage` it silently caps below what you asked for will each spin -forever. The failure does not look like a slow request. It looks like a request that **never returns**, -with tens of thousands of provider calls billed behind it and no error the provider can be blamed for. +**"The SDK stops when the API signals the end" describes the happy path, not a guarantee.** The walk +ends only when the provider stops handing out a next page. A provider that keeps returning a next +link, or a filter it quietly ignores, will spin until something else kills the request. The cursor +and `Link` strategies stop on a cursor or link that did not change; nothing stops one that keeps +changing. The failure does not look like a slow request. It looks like a request that **never +returns**, with tens of thousands of provider calls billed behind it and no error the provider can be +blamed for. -**Every page loop needs at least one bound that does not depend on the provider.** Pick what matches +**A `limit` the provider silently caps below what you asked for fails the other way.** When a page +carries neither a total nor `hasMore`, an offset or page-number walk takes a page shorter than the +limit as the last one, so it stops after the first page and drops the rest without an error. Ask for +no more than the provider's documented maximum page size. + +**Every page walk needs at least one bound that does not depend on the provider.** Pick what matches the use case; a page cap is the cheapest and is never wrong: | Bound | Use when | Shape | | --- | --- | --- | -| **page cap** | always — the backstop | `if (++pages >= MAX_PAGES) break;` | +| **page cap** | always — the backstop | `if (++pages >= MAX_PAGES) break;` in a `.pages()` loop | | **item cap** | the caller wants "the first N" | `if (out.length >= max) break;` | -| **deadline** | the loop sits behind a request timeout | one `AbortSignal.timeout` passed to every call | -| **no-progress guard** | cursor or offset paging | stop if the cursor did not change between pages | +| **deadline** | the walk sits behind a request timeout | one `AbortSignal.timeout` passed as `options.signal` — it bounds the whole walk, not one page | ```ts const MAX_PAGES = 100; const signal = AbortSignal.timeout(30_000); // bounds the whole walk, not one page -let cursor: string | undefined; -let seen: string | undefined; - -for (let pages = 0; pages < MAX_PAGES; pages++) { - const result = await client.{resource}.{operation}({ ...(cursor ? { cursor } : {}) }, { signal }); - for (const item of result.{items}) process(item); +let pages = 0; - cursor = result.{nextCursor}; - if (!cursor) return; // the provider's end signal — the happy path - if (cursor === seen) throw new Error("cursor did not advance"); - seen = cursor; +for await (const page of client.{resource}.{operation}({ /* ... */ }, { signal }).pages()) { + for (const item of page.{items}) process(item); + if (++pages >= MAX_PAGES) break; // then surface the truncation — see below } -throw new Error(`stopped after ${MAX_PAGES} pages`); // truncating silently is its own defect ``` Prefer to **narrow the query before you page it** — a provider-side date range, status filter, or a -`perPage` matching what the caller needs turns "walk everything" into a handful of pages. And **a bound +`limit` matching what the caller needs turns "walk everything" into a handful of pages. And **a bound that silently truncates is a different defect from one that hangs**: when you hit the cap, surface it or log it; never return a partial set that reads like a complete one. -Wrapping a bounded loop in an async generator gives you the `for await` the SDK does not: - -```ts -async function* all{Items}(signal?: AbortSignal): AsyncGenerator<{Item}> { - let cursor: string | undefined; - for (let pages = 0; pages < MAX_PAGES; pages++) { - const result = await client.{resource}.{operation}({ ...(cursor ? { cursor } : {}) }, { signal }); - yield* result.{items}; - cursor = result.{nextCursor}; - if (!cursor) return; - } - throw new Error(`stopped after ${MAX_PAGES} pages`); -} -``` - -A failed page rejects mid-enumeration like any other call — see **typescript-error-handling**. - -## Event streams — not carried - -There is no SSE support. When the spec declares a `text/event-stream` success response, the generator -**still emits the operation** but gives it the **empty-body decoder**, because the vendored runtime -has no carrier for it. A **binary** success is different and is carried: it resolves to a -`BinaryContent` whose `stream` you read once or release — see **typescript-calling-endpoints**. - -The consequence of the empty decoder is specific and worth knowing before you debug it: it asserts -the body is empty, so such an operation **fails at the call** with `DecodeError` ("Expected an empty -response body") the moment the server sends anything — rather than quietly resolving something the -spec never described. The operation's **Returns** bullet reads `undefined` for these. - -Outbound, only an XML request body has no carrier, so such an operation is emitted with no body field -at all. Multipart and binary bodies are both sent. See **typescript-calling-endpoints**. - -**If you need one of these endpoints, call it with `fetch` directly** — build the URL from the same -base URL, and copy the credential header the SDK would have sent. The SDK cannot carry it, and no -option makes it. +> An operation whose **Signature** returns `ApiPromise` is a plain list call, however list-like its +> response. To page one of those, advance its own page or cursor field in a loop and stop on the API's +> end signal — read the field names off its **Fields** table and its response model — and carry the same +> bound: "fewer than `limit`" and "no next cursor" are both provider-supplied stop conditions, and +> neither is a bound. +> +> ```ts +> let cursor: string | undefined; +> let seen: string | undefined; +> for (let pages = 0; pages < MAX_PAGES; pages++) { +> const result = await client.{resource}.{operation}({ ...(cursor ? { cursor } : {}) }, { signal }); +> for (const item of result.{items}) process(item); +> cursor = result.{nextCursor}; +> if (!cursor) return; // the provider's end signal — the happy path +> if (cursor === seen) throw new Error("cursor did not advance"); +> seen = cursor; +> } +> throw new Error(`stopped after ${MAX_PAGES} pages`); +> ``` + +## Event streams and XML bodies + +An operation with a `text/event-stream` success response **is** carried: its **Returns** bullet reads +`EventStream`, the call resolves at the response headers, and you iterate the stream with +`for await` — load **typescript-event-streams** before you write the loop. Its one setting is +`eventStream.idleTimeout` on the client, which bounds the silence between events; `retry.timeout` +stops at the headers and never reaches the loop. + +Outbound, an operation with an XML request body has no body field. Call it with `fetch` directly — +the same base URL, and the credential header the SDK would have sent; no option makes the SDK carry +it. A **binary** success, and multipart and binary request bodies, **are** carried — see +**typescript-calling-endpoints**. ## Logging @@ -751,14 +679,14 @@ header — `authorization`, `cookie` and every api-key header are not on that li logged as it is. `redactedKeys` and `loggableContentTypes` **replace** their default rather than add to it, so spread `defaultLoggingOptions` to extend one, as above. -⚠▶▶ **`logRequestBody: true` does not redact a JSON body**, and only half-redacts a form body. A JSON -body is logged **verbatim** — truncated at `bodySizeLimit` bytes (32 KB), and only when its media type -is in `loggableContentTypes` (`application/json`, `application/x-www-form-urlencoded`). A form body gets -key masking, but by **deny-list**, not by the allow-list the URL uses: only keys in `redactedKeys` are -masked, so `card_number` in a form body prints in the clear although the same key in a query string -would not. Any other media type is not logged unless you add it to `loggableContentTypes`. On any -endpoint that carries card data, bank details, personal data or a credential in the body, switching -this on writes that data to your logs. Leave it off in production; turn it on for one endpoint at a time +⚠▶▶ **`logRequestBody: true` does not redact a JSON body**, and only half-redacts a form body. A body +is logged only when its media type is in `loggableContentTypes` (`application/json`, +`application/x-www-form-urlencoded`; add others there), truncated at `bodySizeLimit` bytes (32 KB). A +JSON body is logged **verbatim**. A form body gets key masking, but by **deny-list**, not by the +allow-list the URL uses: only keys in `redactedKeys` are masked, so `card_number` in a form body prints +in the clear although the same key in a query string would not. On any endpoint that carries card data, +bank details, personal data or a credential in the body, switching this on writes that data to your +logs. Leave it off in production; turn it on for one endpoint at a time behind a flag you can prove is off. ⚠▶▶ **An environment variable turns logging on without a code change.** When code sets neither a @@ -800,11 +728,9 @@ logging on at `info` for the first execution of any new call — `{APICLIENTTYPE 1. The **verb** matches the operation's **Wire** bullet in `map/operations/{resource}.md`. 2. The **base URL** is fully expanded — no leftover `{region}`-style server variable, which means a `baseUrl` you supplied carries a placeholder no declared variable fills. -3. The **path** is fully formed. Two different failures live here: a path field set to `null` collapses - to **nothing**, leaving a doubled slash (`/orders//confirm`); a path field left `undefined` is - rejected by its schema before anything is sent, as an `EncodeError` whose `uri` still shows the - unfilled marker. The first is silent, so it is the one to look - for. +3. The **path** is fully formed: a path field set to `null` collapses to **nothing**, silently, + leaving a doubled slash (`/orders//confirm`). (One left `undefined` rejects with `EncodeError` + before anything is sent.) 4. Each **path segment** holds the value you meant — for an enum that is the **wire value**, not the member name. 5. The **query parameters** you set are present, spelled as their `Wire` names. A `null` or `undefined` @@ -830,28 +756,22 @@ const client = new {Api}Client({ Set the header on a copy of the `Request` — the SDK has already put the content type and the credential on it, and the copy keeps them, the body and the signal. Passing `{ headers }` as `init` -instead **replaces** every header the SDK set, the credential included. This is also the only -client-wide header mechanism: the -transport carries default header, query and path-parameter channels, but the generated client currently -wires all three as empty arrays. If a later generator version starts populating them, a header option -could appear on `ClientOptions` — read `src/client-options.ts` rather than assuming the field list is -frozen. +instead **replaces** every header the SDK set, the credential included. This is the only client-wide +header mechanism: `ClientOptions` has no header option. ### Rate limiting -There is no built-in limiter. The default policy retries a `429` on an idempotent call and honours -its `Retry-After` (capped at 60 s), which absorbs an occasional limit; it does nothing to stop you -starting more calls than the provider allows. Put a concurrency/rate limiter around your calls for -that. Client-side limiting is the more predictable of the two under load — retrying into a rate limit +There is no built-in limiter. The default `429` retry absorbs an occasional limit but does nothing to +stop you starting more calls than the provider allows. Put a concurrency/rate limiter around your +calls for that. Client-side limiting is the more predictable of the two under load — retrying into a rate limit converts a fast failure into a slow one, and a fan-out of retrying calls keeps the pressure on. ### Circuit breaking Count consecutive `ConnectionError`s, `TimeoutError`s and 5xx `ApiError`s, open the circuit for a -cool-off window, and fail fast while it is open. **Put the breaker around the SDK call, not in `fetch`.** -A plain `Error` thrown from a `fetch` wrapper reaches the loop as a `ConnectionError`, which is retried -with backoff — the opposite of failing fast. Around the call, the breaker sees one outcome per call, -after the retries, and its refusal never enters the loop. +cool-off window, and fail fast while it is open. **Put the breaker around the SDK call, not in `fetch`**, +where its refusal would be retried as a `ConnectionError` (*The `fetch` seam*). Around the call, the +breaker sees one outcome per call, after the retries, and its refusal never enters the loop. ## Proxies and TLS (Node) @@ -914,8 +834,7 @@ nothing extra. Two consequences: - **A dispatcher you create is a pool you own.** Build it once, beside the client, and reuse it. A `new Agent(...)` or `new ProxyAgent(...)` per request opens a fresh pool — and therefore fresh TCP - and TLS handshakes — on every call, which is the same waste as a client per request without looking - like one. + and TLS handshakes — on every call. - **Pool limits live there too** — `connections`, `keepAliveTimeout`, `pipelining` on the `Agent`. Raise `connections` before assuming a provider is slow under a fan-out; the default cap can be the actual bottleneck. @@ -932,21 +851,19 @@ client costs under OAuth — is **typescript-client-initialization**. | request lines in the logs with no logging code | `{APICLIENTTYPENAME}_LOG` is set in that environment — set `logging.level` in code to own it | | a JSON body or a card number in the logs | `logRequestBody`, or a per-call `level`, which turns the body on — see *Logging* | | a failing call takes seconds longer to reject than the first failure | expected on an idempotent call: the default policy retried it — watch it with `retry.onRetry` | -| a `POST` fails on a `503` that a `GET` survives | expected: `POST` is outside the default `httpMethodsToRetry` | -| one handler takes far longer than `retry.timeout` | it is per attempt, and an idempotent call gets up to four — count the calls, then bound the handler with a signal | -| a page loop never returns | no provider-independent bound — see *Never leave a page loop unbounded* | +| a page walk never ends | no provider-independent bound — see *Never leave a page walk unbounded* | +| `PaginationError` naming another origin | the API's next link points off the API's host, and the SDK refuses to follow it — see *Pagination* | | requests still hit the real host under test | the wrong server **group** or **environment** overridden — check `src/servers.ts` | -| auth fails everywhere with credentials you know are right | `serverEnvironment` left to its default, which is the spec's **first** environment — often sandbox | +| auth fails everywhere with credentials you know are right | `serverEnvironment` left to its default, the **first** `ServerEnvironment` member — often sandbox | | the call works locally, fails behind a corporate proxy | Node's `fetch` ignores `HTTP_PROXY` — register `EnvHttpProxyAgent` or pass a `dispatcher` | -| a duplicate write despite an idempotency key | the key is generated inside the retried function — hoist it out; or your own retry layer re-calls the SDK, which mints a new injected key per call | +| a duplicate write despite an idempotency key | the key is generated inside the retried function — hoist it out; or your own retry layer re-calls the SDK, which sends a new `Idempotency-Key` per call | | ~16× the expected round-trips | a retry layer of your own stacked on the SDK's — set `retry: { maxRetries: 0 }` where you own retrying | | a test with one stubbed `503` hangs, or runs out of queued responses | the default policy fetched it four times across ~7 s of backoff — see **typescript-testing** | | a `{placeholder}` survives into the URL | a `baseUrl` you supplied names a variable the group does not declare | | `EncodeError` whose `uri` still shows a `{placeholder}` | a path field was `undefined` — a required field was omitted | | `ConfigurationError` about an unknown environment, thrown by the constructor | `serverEnvironment` is not a declared member | -| `DecodeError` "Expected an empty response body" | an event-stream response with no carrier — call it with `fetch` directly | +| an event-stream loop rejects with `TimeoutError` while the server is still connected | the server stayed silent past `eventStream.idleTimeout` — raise it, or set it to `null` and bound the wait with a `signal` (**typescript-event-streams**) | | a token is fetched on every call | a client built per request — see **typescript-client-initialization** | -| 401 on the first call, fine afterwards | expected: a 401 invalidates the token cache and is not in the default retry set | ## Next diff --git a/plugins/spotify/skills/typescript/typescript-error-handling/SKILL.md b/plugins/spotify/skills/typescript/typescript-error-handling/SKILL.md index db15dba1..32462fab 100644 --- a/plugins/spotify/skills/typescript/typescript-error-handling/SKILL.md +++ b/plugins/spotify/skills/typescript/typescript-error-handling/SKILL.md @@ -1,22 +1,17 @@ --- name: typescript-error-handling -description: Error handling for an APIMatic-generated TypeScript SDK — load before writing any try/catch around an SDK call, an error-translation layer, or middleware. Covers the one error family and its closed err.kind, the four throwables that sit outside it, which types actually reach your catch blocks, reading the status and the declared error body safely, the default arm that degrades instead of throwing, the failures the non-throwing form does not convert, the missing field that is silently undefined rather than an error, and the traps that make an otherwise reasonable catch ladder silently wrong. +description: Load before writing a try/catch around an APIMatic-generated TypeScript SDK call, translating its errors into your own, or reading a status code or error body — the SDK's one error family and its closed `err.kind`, the throwables outside it, per-operation typed error arms and the `"undeclared"` arm, and what `.asApiResult()` still rejects. --- # Error handling for an APIMatic TypeScript SDK -> Throughout this skill, `{...}` is a placeholder for a name you take from your SDK (e.g. `{Api}Client`, -> `{Api}Error`, `{package-name}`, `{Resource}`, `{Operation}`, `{arm}`) — replace it with the concrete -> identifier from the source. -> -> **One skill, every error shape.** This file covers every shape the generator can emit. Which shapes -> YOUR SDK uses — whether an operation declares typed arms or rejects with the base error, what each -> arm is called, which status it covers — are facts of the API definition, not of this skill: take -> them from the operation's page in `map/operations/{resource}.md` and **apply only the guidance that -> matches**. An API can declare typed errors on every operation, on none, or on a mix. +> `{...}` marks a name to take from your SDK (`{Api}Client`, `{Api}Error`, `{package-name}`, +> `{Resource}`, `{Operation}`, `{arm}`). Whether an operation has typed error arms, what they are +> called and which statuses they cover is per operation: read its page in +> `map/operations/{resource}.md` and **apply only the guidance that matches**. Operations are **throw-based** (for a non-throwing alternative, see **The non-throwing form** below), -and every **operational** failure belongs to **one family**: `{Api}Error`, a union over six leaves. +and every **operational** failure belongs to **one family**: `{Api}Error`, a union over seven leaves. One `instanceof {Api}Error` sees all of them, and `err.kind` says which one it is. Four throwables sit **outside** the family — a configuration fault, a codec called directly, a bug, and a caller abort — so a `catch` that tests the family has to rethrow whatever is left. @@ -33,7 +28,7 @@ try { // The API answered with an error status — read err.status and err.payload. break; case "decode": - // The answer did not fit the spec — read err.status and err.cause. + // The answer did not fit its declared type — read err.status and err.cause. break; case "encode": // Nothing was sent — err.cause is the SchemaError that rejected the value. @@ -43,6 +38,9 @@ try { case "auth": // No response was produced — err.kind says which. break; + case "pagination": + // A paged walk could not follow the next link the API sent — the pages before it were delivered. + break; } } else { throw err; // outside the family: an abort's reason, a configuration fault, or a bug @@ -55,28 +53,18 @@ opens with that pair — `"POST https://api.example.com/v1/{resource} failed wit ## What to import, and from where -Everything below comes from **one specifier — the package root**. Deep imports -(`{package-name}/core/…`) do not resolve: the `exports` map exposes `.` and `./package.json` and -nothing else. +Everything below comes from **the package root** — deep imports do not resolve +(**typescript-client-initialization**). | import | what it is | | --- | --- | -| `{Api}Error` | the whole family — a type **and** a value. The type is the union of the six leaves; the value is the abstract class they all extend, so `instanceof` and `err.kind` select the same set. It cannot be constructed or extended. The SDK-branded alias of `CoreError`, which is not exported under its own name | +| `{Api}Error` | the whole family — a type **and** a value. The type is the union of the seven leaves; the value is the abstract class they all extend, so `instanceof` and `err.kind` select the same set. It cannot be constructed or extended. Its real name — usually the API name plus `Error` — is on the `CoreError as …Error` line in `src/index.ts`; `CoreError` itself is not exported | | `ResponseError` | the part of the family the server answered on — `ApiError \| DecodeError`, the two that carry `status` and `headers`. A type and a value, like `{Api}Error` | | `ApiError` | `kind: "api"` — the API answered with an error status. The base every operation without declared error bodies rejects with, and the class every per-operation error extends | | `{Resource}.{Operation}Error` | the generated `ApiError` subclass for an operation that declares error bodies, on the **resource class's merged namespace** — not a free-standing export | -| `DecodeError` `EncodeError` `ConnectionError` `TimeoutError` `AuthError` | the other five leaves | +| `DecodeError` `EncodeError` `ConnectionError` `TimeoutError` `AuthError` `PaginationError` | the other six leaves | | `ConfigurationError` `SchemaError` | outside the family: a constructor fault, and a codec called directly | -| `type ErrorKind` `ErrorPayload` `Declared` `Undeclared` `HttpMethod` | type-only helpers, if you name them in your own signatures | - -`{Api}Error` is the SDK-branded name — **read the real one** from the `CoreError as …Error` line in -`src/index.ts`. It is the API name plus `Error` (`Acme` gives `AcmeError`), escalating to -`{Api}ApiError` and then a numeric suffix when that would collide with something the same clause -already re-exports (an API named `Api` cannot take `ApiError`). - -Everything under `src/core/` is vendored static code, **byte-identical in every generated TypeScript -SDK**, so the behaviours below hold without checking yours. What varies per SDK is which operations -declare arms, and what those arms are called. +| `type ErrorKind` `Declared` `Undeclared` `HttpMethod` | type-only helpers, if you name them in your own signatures | ## The family — every `err.kind` @@ -90,6 +78,7 @@ declare arms, and what those arms are called. | `"connection"` | `ConnectionError` | `fetch` rejected before a response line arrived | — | | `"timeout"` | `TimeoutError` | an attempt ran out its `retry.timeout`, and no retry was left | `timeout` — the budget that ran out | | `"auth"` | `AuthError` | a credential could not be **obtained** | — | +| `"pagination"` | `PaginationError` | a paged walk could not follow the next link the API sent — it was not a URL, or it named another origin | — | Every one carries `kind`, `method`, `uri`, `message` and, where there was an underlying failure, `cause`. `uri` is the absolute URL the call dialled, with the server variables expanded and the path @@ -102,8 +91,7 @@ by its schema arrives as an `EncodeError` whose `uri` still shows the unfilled ` a header or a value that failed its schema. That keeps response bodies and secrets out of logs and stack traces by default, which is a sound default and a trap: a handler that logs `err.message` and nothing else records that something failed and discards every diagnostic. Read `err.payload` (or -`err.cause`) explicitly and log the fields you choose — and on a `4xx` the caller caused, also put the -API's reason in your response. +`err.cause`) explicitly and log the fields you choose. `err.headers` is the `fetch` `Headers` object, not a plain object — look a header up with `err.headers.get("x-request-id")` (case-insensitive). Indexing it (`err.headers["x-request-id"]`) is @@ -111,8 +99,7 @@ always `undefined`, and spreading it gives you nothing. ## Four throwables outside the family -`instanceof {Api}Error` is `false` on each of these, so a `catch` that tests the family and then -stops has swallowed nothing — it just has to **rethrow the rest**, as the ladder at the top does. +`instanceof {Api}Error` is `false` on each of these: - **`ConfigurationError`** comes out of the **client constructor**, synchronously and before any call exists: no reachable `fetch`, a basic-auth username containing a colon (RFC 7617 §2), or an @@ -152,54 +139,35 @@ so a `3xx` lands here too. ### Which error does an operation reject with? -Four places give you the answer, in order of preference: - -1. **`map/operations/{resource}.md`** — the operation's **Error** bullet names the case, and for a - typed operation the **Error arms** bullet lists every arm with the status each covers and whether it - has a body. Start here. -2. **The **Signature** bullet on the same page** — the same fact as the second type argument of the - returned `ApiPromise`. -3. **`api-reference.md`** — per-operation prose, when you need what an arm *means* rather than its - shape. -4. **`src/resources/{resource}.ts`** — the source. The subclass's `static readonly errors` table is - the matcher list itself: one row per arm, each spelling `on` (the status, a `[from, to]` range, or - `"default"`), `kind`, and the decoder. - -All of these ship inside `node_modules/{package-name}/`, so read them there rather than the compiled -`dist/`. - -- **Case A — typed arms.** The spec declared failure bodies, so the generator emitted a subclass named - `{Operation}Error`, exported from the **enclosing class's merged namespace** — you catch - `{Resource}.{Operation}Error`, or `{Api}Client.{Operation}Error` for an operation the spec left - untagged. It redeclares `payload` with the operation's own arms. Narrow on `err.payload.kind`. +Take the case from the operation's **Error** bullet in `map/operations/{resource}.md`: for a typed +operation its **Error arms** bullet lists every arm with the status it covers and whether it has a +body, and the **Signature** bullet shows the same as `E` in `ApiPromise`. `api-reference.md` +says what an arm *means*; the source is `src/resources/{resource}.ts`. All of these ship inside +`node_modules/{package-name}/` — read them there, not in the compiled `dist/`. + +- **Case A — typed arms.** The operation has an `{Operation}Error` subclass of `ApiError` on the + **enclosing class's merged namespace** — catch `{Resource}.{Operation}Error`, or + `{Api}Client.{Operation}Error` for an operation that sits directly on the client. It redeclares + `payload` with the operation's own arms; narrow on `err.payload.kind`. - **Case B — no typed arms.** `E` is the **base `ApiError`**, its payload is always the `"undeclared"` arm, and there is no subclass to catch. -Guessing wrong is *sometimes* a compile error and sometimes not, and the direction that looks safe is -the dangerous one. A subclass that does not exist fails to compile — that guess TypeScript catches. But -naming a **neighbouring** operation's error class compiles cleanly, because it is a real type, and then -never matches at runtime: the rejection sails past your `catch` and surfaces somewhere else, or not at -all. Take the case from the map every time; the compiler is not a check on this. +Take the case and the arms from that operation's own page every time, never a neighbour's: a +neighbouring operation's error class compiles cleanly and never matches at runtime. ### Case A — reading the typed payload -> **This section applies only where the operation declares typed arms.** An operation whose **Error** -> bullet names the base `ApiError` has nothing to narrow — its payload is always `"undeclared"`. -> Skip to **Case B**. - -`err.payload` is a discriminated union with **one arm per failure response the spec declared**, plus -`"undeclared"`. Two things about arm names catch people out: +`err.payload` is a discriminated union: one arm per declared failure response, plus `"undeclared"`. +Arm names come from the body's schema, not the status — a model reference gives the model's name in +lower camel (`validationError`, then `validationError2` for a second status returning the same model), +anything else gives `error{Status}` (`error400`, `error4XX`) — so read them off the map. One arm can +cover many statuses: `4XX` covers `[400, 499]`, so check `err.status` for the exact one. -- **The name comes from the body's schema, not from the status.** An arm whose body is a direct model - reference is named after that model in lower camel (`validationError`); anything else — a - primitive, an array, a map, or no content — is named `error{Status}` (`error400`, `error4XX`, - `errorDefault`). So two statuses that return the *same* model give you two arms whose names differ - only by a numeric suffix (`validationError`, `validationError2`). Read the arm names off the map; - do not derive them from the status. -- **One arm can still cover many statuses** — not because two statuses were merged, but because the - spec declared a *range* or a `default:`. A `4XX` arm covers `[400, 499]`; a `default:` arm covers - **every error status no other arm covers**, `3xx` included. Check `err.status` when you need the - specific one. +**A spec's `default:` response is not an arm.** Every status the other arms miss is `"undeclared"` +with its bytes intact — the `520` a CDN, the `502` a gateway or the `403` a WAF answers on the API's +behalf included, whose HTML page the `default` schema never described. The model the spec named under +`default` is still under `src/models/`; decode `rawBody` through its schema by hand when the status is +one the API itself sent. ```ts import { {Resource} } from "{package-name}"; @@ -225,22 +193,12 @@ try { ``` **`"undeclared"` is always an arm, and it is not a catch-all.** It carries -`{ kind: "undeclared"; rawBody: ArrayBuffer }` and fires **only** for a status no declared arm covers -— or, where the operation declares a `default:` arm, for a body that arm could not decode. A status -that has an arm lands in that arm and leaves `"undeclared"` unreached — so a `catch` that handles only -`"undeclared"` silently drops every typed body. Handle every arm the map lists, and put `"undeclared"` -last. There is no operation whose failure is guaranteed typed: the generator emits the `"undeclared"` -arm unconditionally, so any operation can hand you raw bytes for a status it does not document. - -An arm can declare **no body** (`body: undefined`) — the spec named the status but gave it no schema. -It accepts only an **empty** body: any body on a status it covers (a JSON error message is typical) -rejects with `DecodeError`, even through `.asApiResult()`, and `err.status` still names it (see -**`"decode"`**). On a `"default"` arm that body degrades to `"undeclared"` instead. - -**The arms are per operation, and are not one set across the API.** A description that declares a -different error schema per tag gets a different model — and therefore a differently-named arm — per -tag, so a branch written against one operation's arm does not apply to a sibling's. Take the arms from -that operation's **Error arms** bullet every time; never reuse a set from a neighbouring call. +`{ kind: "undeclared"; rawBody: ArrayBuffer }` and fires **only** for a status no declared arm covers, +so any operation can hand you raw bytes, and a `catch` handling only `"undeclared"` drops every typed +body. Handle every arm the map lists, and put `"undeclared"` last. An arm can declare **no body** +(`body: undefined`); it accepts only an **empty** body — any body on a status it covers (a JSON error +message is typical) rejects with `DecodeError`, even through `.asApiResult()`, and `err.status` still +names it (see **`"decode"`**). Where your boundary treats several arms alike, group them with fall-through cases rather than repeating the body — but only over fields they **all** declare: @@ -286,14 +244,12 @@ with HTML or plain text. Decode it to a string before you try to parse it, and e ### Matcher precedence -For a subclass with several arms, the runtime matches in **three passes**: an exact numeric status -across the whole table first, then the first covering range, and last a `"default"` arm where the -spec declared one. So a specific `404` arm beats a `4XX` arm regardless of declaration order, and a -`default:` arm can never shadow a narrower one. +An exact numeric status wins over a covering range, so a specific `404` arm beats a `4XX` arm +regardless of declaration order. -A body that does not fit the arm it matched is a **`DecodeError`** — except on `"default"`, which -describes no status in particular and so **degrades to the `"undeclared"` arm**, raw bytes and all, -rather than throwing. +A body that does not fit the arm it matched is a **`DecodeError`**. A status no arm covers is the +`"undeclared"` arm, which every subclass ends in; a spec's `default:` response is never a row, so +nothing a middleware answers on the API's behalf can fail a schema the API wrote. ### Catch order @@ -332,7 +288,7 @@ Which status it came on matters a lot, and `err.status` tells you: Mapping both onto one 5xx is wrong half the time — it tells a retrying caller to keep retrying something that can never succeed. Only a **declared** arm can decode-fail: the `"undeclared"` arm reads -raw bytes and never decodes, and a `default:` arm degrades instead of throwing. +raw bytes and never decodes. ```ts if (err instanceof DecodeError) { @@ -353,12 +309,9 @@ let a production ladder quietly absorb it — it should fail loudly in developme **`AuthError` is about obtaining a credential, not about being refused one.** A 401 *from the API* is an `ApiError` like any other status, so one `catch` arm cannot absorb the other. -A 401 does have one auth consequence: it **invalidates whatever that operation's scheme had cached**, -so the **next** call re-acquires. `401` is not in the default `statusCodesToRetry`, so the current -request fails and recovery happens on the following call. To have the current call re-sent with a -fresh token instead, add `401` to `statusCodesToRetry`: every attempt resolves its credential again, so -the retry carries the re-acquired token. A static key is re-sent unchanged, so that only helps a scheme -that fetches its credential. +A 401 from the API also invalidates the scheme's cached credential, so the **next** call re-acquires +(**typescript-authentication**). A single `401` is therefore not a permanent credential failure: do not +tear down the client or alert on one. `AuthError` means the token grant failed, every configured branch of an alternatives requirement failed, PKCE was disabled without a client secret, or your own authorization-code prompt rejected. Its @@ -374,20 +327,26 @@ is still an `AuthError` with the endpoint's `ApiError` on `.cause`, never the ba Otherwise it is an `AuthError` whose `cause` is an `AggregateError` holding what each branch threw, in the order tried. An abort or a timeout escapes immediately rather than being collected. -Auth resolves *before* the request is sent, so an `AuthError` means **nothing was sent** — it is an -auth fault, not a rejection. Check it early in your ladder. +⚠ **An `AuthError` means nothing was sent, and it surfaces from an operation call, not from client +construction.** The token is acquired lazily, before the request exists, so an auth misconfiguration +rejects whichever operation ran first — reading like a problem with that operation — and rejects in +`.asApiResult()` mode too. Check it early in your ladder. -⚠ **The token is acquired lazily, on first use — so an auth misconfiguration surfaces from an -operation call, not from client construction.** The rejection points at whichever operation happened to -run first, which reads like a problem with that operation rather than with the credentials you wired -up. It also rejects in `.asApiResult()` mode, for the same reason: the grant happens before a request -exists to return a result for. +## `"pagination"` — a next link could not be followed + +Raised from inside a paged walk, **between two pages**: the page that carried the link has already been +delivered, and a loop that stops after it never sees this. A `Link` strategy follows a link only when it +resolves, against the URL of the page that carried it, to the same scheme, host and port as the API, so +no credential ever leaves the API. A link to another origin is refused, and so is one that is not a +URL. For a link to another origin, `err.uri` names the call that was refused; for a link that is not a +URL there is no such call, so `err.uri` names the page that carried it and `err.cause` holds the +platform's parse failure. It is a `{Api}Error`, so the ladder at the top already catches it; the +offset, page-number and cursor strategies never raise it. ## A missing field is not an error — it is `undefined` -This is the gap the error types leave, and the one most likely to reach production. A model member the -description did not mark **required** is emitted as `member?: T` over an optional schema entry, so a -response that simply **omits** it validates cleanly. No `DecodeError` is thrown, and nothing warns you: +A model member not marked **required** is `member?: T`, so a response that simply **omits** it +validates cleanly. No `DecodeError` is thrown, and nothing warns you: ```ts const value = await client.{resource}.{operation}({ /* ... */ }); // 200, truncated body @@ -436,20 +395,21 @@ no per-status judgement. Reach for it when an error status is an expected outcom found yet", a `409` meaning "already exists") and you would otherwise be using exceptions for control flow, or when you need `status` and `headers` on the *success* path. -Two mechanics to know: the failure branch is a plain object carrying **the error's own members under -their own names** — `status`, `headers`, `message`, `method`, `uri` and `payload` — never the error -instance, so you narrow on `outcome.payload.kind` exactly as you would on `err.payload.kind`, and a -handler moves between the two forms by swapping the prefix; and `.asApiResult()` must be called on the -value the operation returned, **before any `.then()`**, because `ApiPromise` overrides -`Symbol.species` and the method is gone from what `.then()` hands back (see -**typescript-calling-endpoints**). - -⚠ **This mode is not rejection-free, and the cases it does not convert are the ones people assume it -does.** A decode failure is not an API error status, so it propagates in both modes rather than -becoming an `ok: false` value — a `DecodeError` on a `2xx` body, and a `DecodeError` on a **declared -error arm**, both still reject. So does a failed token acquisition, because the credential is resolved -before anything is sent, and so does a caller abort. `try`/`catch` is still required around -`.asApiResult()`; it narrows what you catch, it does not remove the need to catch. +The failure branch is a plain object carrying **the error's own members under their own names** — +`status`, `headers`, `message`, `method`, `uri` and `payload` — never the error instance, so you narrow +on `outcome.payload.kind` exactly as you would on `err.payload.kind`, and a handler moves between the +two forms by swapping the prefix. Call `.asApiResult()` on the value the operation returned, **before +any `.then()`** (**typescript-calling-endpoints**). + +⚠ **Every failure other than an error status still rejects** — a `DecodeError` (on a `2xx` body or on +a **declared error arm**), a failed token acquisition and a caller abort included — so keep the +`try`/`catch` around `.asApiResult()`. + +**On a paged operation**, `.asApiResult()` is called on the walk and returns `PageableApiResult`: its +`.pages()` yields one `ApiResult` per page, and a failed page is the **last** element it yields; its +item loop ends silently at an error status and contributes no items for it, so an item loop that ends +cannot tell the last page from a failed one. Everything the single-call form still throws, the walk +still throws too, with `PaginationError` beside them. ## Transport failures, and guarding every call site @@ -458,23 +418,15 @@ DNS that failed, a connection that dropped, or an attempt's timeout elapsing — `"connection"` and `"timeout"`, and a `catch` whose only arm is `err instanceof ApiError` lets them escape and take down whatever was running the call. -**Every one of them reaches you after the retries are spent.** On a `GET`, `HEAD`, `PUT` or `OPTIONS` -call the default policy re-sends a `408`, `429`, `500`, `502`, `503` or `504`, a connection failure -and a timeout up to -three times before the call rejects, so what you catch is the **last** attempt's failure — an -`ApiError` for the final status, or a `ConnectionError` or `TimeoutError` — in exactly the shape it -would have had with retrying off. A write outside `httpMethodsToRetry` rejects on its first failure. -Do not retry a family error the SDK already retried; see **typescript-configuration-resilience**. - -**Unlike SDKs that let their HTTP library's exceptions through, this one wraps them.** Whatever your -`fetch` rejects with becomes a `ConnectionError`, with the original on `.cause` — so your boundary -never imports the transport's exception types, and it does not need revisiting when you swap `fetch` -for a wrapper. Two things pass through unwrapped: anything that is already in the family (a -`{Api}Error` your own wrapper threw), and a cancellation — the caller's own abort `reason`, or the -SDK's `TimeoutError` when an attempt's timeout fired, whatever your `fetch` rejected with. If you wrap -`fetch` to add a guard (**typescript-configuration-resilience**), throw a family error from it or -accept that yours will arrive as `err.cause` — and know that a plain error thrown there is a -`ConnectionError` the retry loop retries. +**Each reaches you after the SDK's retries are spent** — as the **last** attempt's failure, in the +shape it would have had with retrying off; do not retry it again (**typescript-configuration-resilience** +owns the policy). + +Whatever your `fetch` rejects with becomes a `ConnectionError` with the original on `.cause`, so your +boundary never imports transport exception types. A family error and a cancellation (your abort +`reason`, or the SDK's `TimeoutError` once an attempt's timeout fired, whatever your `fetch` rejected +with) pass through unwrapped — and a plain error your own `fetch` wrapper throws is a `ConnectionError` +the retry loop retries. **Convert the family to your own error type in one place.** If you wrap the SDK behind your own abstraction (a client interface, a service, a repository), do the conversion at that boundary so the @@ -523,11 +475,6 @@ or modify something and overlook the calls that only read — especially reads o a screen, a scheduled job, a startup or health check). A connection failure during a read fails just as hard as one during a write. A call left unguarded next to one that is guarded is the one that breaks. -⚠ **A rejection you never await is an unhandled rejection**, exactly like any other promise's: -`unhandledRejection` on Node — which by default ends the process — and `unhandledrejection` in a -browser. Await every call, or attach your own handler. `.asApiResult()` marks the promise handled as -its first act, so call it on the value the operation returned, in the same turn. - ## Presenting failures at your boundary — coherent, distinct, leak-free The catches above decide what you catch; this decides what the caller (an HTTP response, a UI layer, @@ -573,10 +520,9 @@ unauthenticated or throttled when they are neither. Those belong in the 5xx buck conflict and not-found are the caller's to fix. And keep the default arm at 5xx: a status you have not mapped is an unknown, not a caller error — the provider can add one without warning you. -**An unreadable body is not one case but two — decide which before you map it.** A `DecodeError` on a -**success** status is genuinely unknown: 5xx. One on an **error** status is not — the provider rejected -the request and only the *detail* was lost, so answering 5xx tells a retrying caller to keep retrying -something that can never succeed. `err.status` is what separates them; the type alone does not. +**An unreadable body is not one case but two** (*`"decode"` — the answer did not fit*): a `DecodeError` on a **success** +status is genuinely unknown, so 5xx; one on an **error** status is the provider's rejection with the +detail lost, so map it by `err.status`. **Never map a decode failure onto a domain absence.** "I could not read the answer" is not "the provider said no." It is tempting on a lookup — an unreadable body and a genuine miss both leave you @@ -607,26 +553,10 @@ if (typeof err === "object" && err !== null && "kind" in err && "uri" in err) { ## Notes -- **Retries are on by default.** An idempotent call is retried on `408`, `429`, `500`, `502`, `503`, - `504`, a dropped - connection and a timeout, honouring `Retry-After`, before it rejects; a write is not, unless its - method is in `httpMethodsToRetry`. The error you catch is the last attempt's. See - **typescript-configuration-resilience**. -- **A single `401` is not a permanent credential failure.** It invalidates the cached token and, by - default, is not re-sent; the caller sees that one `401`, and the *next* call acquires afresh. Do not tear down a - client or alert on one. -- **Failures are logged only when you turn logging on.** Logging is off by default; with - `ClientOptions.logging` on, the SDK writes a `warn` line for a non-`2xx` response and an `error` line - for a call that ends on a fault or on a credential it could not obtain (see - **typescript-configuration-resilience**). Neither is a substitute for handling the error: log what - your own code decided in your `catch`. -- **No raw `Response`.** `status` and `headers` are on `ApiResult` and on a `ResponseError`; the - `fetch` `Response` is deliberately unreachable. -- **A missing credential is not an error.** An unset credential member sends no credential, so the - failure surfaces as an `ApiError` `401` from the API rather than anything at construction — which - reads like an expired token instead of a config bug. This holds for composite schemes too: a - partially configured `all`/`any` scheme sends what it has rather than refusing, so there is no local - "auth could not be satisfied" rejection to catch. See **typescript-client-initialization**. +- **The SDK logs a failure only when its logging is on**, which it is not by default + (**typescript-configuration-resilience**) — log what your own code decided in your `catch`. +- **A missing credential is not an error**: the call goes out without it and the API answers `401` + (**typescript-authentication**). - **SDK errors do not survive a worker or process boundary intact.** `structuredClone` and `postMessage` reduce an `Error` subclass to a plain `Error` — `name`, `message` and `cause` survive; `kind`, `method`, `uri`, `status` and `payload` do not. Convert to your own serializable shape diff --git a/plugins/spotify/skills/typescript/typescript-event-streams/SKILL.md b/plugins/spotify/skills/typescript/typescript-event-streams/SKILL.md new file mode 100644 index 00000000..385baf1e --- /dev/null +++ b/plugins/spotify/skills/typescript/typescript-event-streams/SKILL.md @@ -0,0 +1,144 @@ +--- +name: typescript-event-streams +description: Consuming a server-sent-events (text/event-stream) operation on an APIMatic-generated TypeScript SDK — what EventStream yields (each event's decoded data, nothing else), how the loop must end so the connection is released, narrowing a union on the yielded value, what rejects and when (the loop raises the same error family as the call, and there is no SSE error class), and bounding the wait with the client's idleTimeout. Load before writing the loop over an operation that resolves to an event stream, in addition to `typescript-calling-endpoints`. +--- + +# Event streams on an APIMatic TypeScript SDK + +> Throughout this skill, `{...}` is a placeholder for a name you take from your SDK (e.g. `{resource}`, +> `{operation}`, `{Api}Error`) — replace it with the concrete identifier from the source. + +An operation whose success response is `text/event-stream` returns `ApiPromise, E>` +rather than a value. The promise resolves as soon as the response **headers** arrive, before anything +is read — what is deferred is the body, and the stream holds its connection until it is released. +`T` is the type the spec gives every event's `data`: a string, a model, an array, or a union. + +```ts +const stream = await client.{resource}.{operation}({ /* ... */ }); +for await (const event of stream) { + event; // T — one event's data, already decoded +} +``` + +Iterating yields `T` itself, each event's decoded `data` and nothing else: the `event:` name and +`id:` lines of the wire format are not surfaced, so there is no envelope to unwrap and no `kind` +beyond what `T` declares. Nothing is read ahead of your loop, so a slow loop body slows delivery +rather than buffering events in memory. Where the operation declares a terminating event (the map's +**Returns** bullet names it, such as a `[DONE]` data line), the SDK consumes it, closes the stream and +never yields it; a body that closes before that line arrived is a clean end too. + +## Start here + +**Drain the loop.** Reaching the end releases the connection, so the shortest correct code is a plain +`for await`: + +```ts +for await (const event of await client.{resource}.{operation}({ /* ... */ })) { + handle(event); +} +``` + +**Leaving the loop early releases it too** — `break`, `return`, or a `throw` inside the body all +close the stream before control leaves. A stream you decide not to read at all is released with +`await stream.close()`, and where your runtime declares `Symbol.asyncDispose`, `await using` does +the same at block exit: + +```ts +await using stream = await client.{resource}.{operation}({ /* ... */ }); +for await (const event of stream) { + if (done(event)) break; // the stream is released either way +} +``` + +## How the iteration ends + +| You want | Write | Releases | +|---|---|---| +| the whole stream | a plain `for await` | at the end of the stream | +| to stop at a condition | `break` / `return` inside the loop | as the loop exits | +| a stream you will not read | `await stream.close()` | your `close()` | +| release at block exit | `await using stream = …` | the block | +| to stop from elsewhere | abort the `signal` you passed | the SDK cancels its own reader | + +`close()` is idempotent, and a pending `next()` ends with `done` rather than an error. A stream is +**single-use**: a second `for await` over the same `EventStream` throws a `TypeError`, exactly as a +second read of a web `ReadableStream` does. `stream.toReadableStream()` hands you the same values as a +web `ReadableStream` and takes the stream's one iteration. + +## What the loop yields + +| The success schema is | each `event` is | Narrow with | +|---|---|---| +| `type: string` | `string` — the event's text, verbatim | nothing — it is the value | +| an object schema | `{Model}` | nothing — it is the model | +| an array schema | `{Model}[]` — one batch per event, no wrapper model | nothing | +| a `oneOf` with a discriminator | `{Union}` | `switch (event.kind)` | + +Every event decodes through the **one** schema the spec declares for the stream, whatever name the +server gave it, so a union is narrowed on its own discriminant. An error the API reports *inside* the +stream is an event like any other: the spec declares its shape as an arm of the union, the loop +yields it, and the stream goes on unless you `break`. + +## What can go wrong + +| What failed | Direct call | `.asApiResult()` | +|---|---|---| +| a non-2xx status (the headers) | rejects at the call with `ApiError` (or the operation's typed subclass) | resolves `{ ok: false }` — no rejection | +| a 2xx that is not `text/event-stream` | nothing checks the media type: the call resolves and the body is read as event frames, so a JSON body usually ends the loop cleanly with no event | same | +| an event whose `data` does not fit the schema | the loop rejects with `DecodeError`, stream released | same | +| the connection dies mid-read | the loop rejects with `ConnectionError` | same | +| the body closes before the declared sentinel arrived | the loop ends cleanly; every event the server sent was delivered | same | +| the server sends nothing for `idleTimeout` | the loop rejects with `TimeoutError`, `timeout` = the idle bound | same | +| you abort the `signal` | the pending `next()` rejects with the signal's own `reason` — **not** an `{Api}Error` | same | +| a second iteration of one stream | `TypeError` at the `for await`, a bug | same | + +**There is no SSE error class.** Everything the loop raises is a leaf of the one `{Api}Error` family, +the same `DecodeError`, `ConnectionError` and `TimeoutError` the call itself can raise, narrowed on +`err.kind` exactly as `typescript-error-handling` describes. Put that boundary around the **loop**, not +only the call — the call settles as soon as the headers arrive: + +```ts +try { + const stream = await client.{resource}.{operation}({ /* ... */ }); + for await (const event of stream) { + handle(event); + } +} catch (err) { + if (err instanceof {Api}Error) { + // err.kind is "api" before the stream existed, and "decode", "connection" or "timeout" from the loop + } else { + throw err; // a caller abort or a bug — not ours + } +} +``` + +## Resuming + +The SDK does not read the `id:` lines and the stream carries no resume point. Where the spec declares +a `Last-Event-ID` header, the operation's request type carries it as an optional field the SDK sends +verbatim; what to put in it is yours to track, from the data the events carry, because no event id +reaches your loop. + +## Bounding the wait + +The client's `retry.timeout` stops at the response headers; an event stream has its own clock. +`ClientOptions.eventStream.idleTimeout` (default `60_000` ms) is how long the server may stay silent +while your loop waits for the next event — any bytes reset it, a heartbeat comment included, and it +runs only while an iteration is waiting, so time your loop body spends on an event never counts. +`null` turns it off; `0` is a zero-length window. It is resolved once, as the client is built, and no +call overrides it. For a total budget, pass a `signal` and abort it: the SDK cancels its own reader, +so the stream stops whatever your `fetch` does with the body. + +## The non-throwing form + +`.asApiResult()` resolves to `{ ok: true, status, headers, value }` with `value` the `EventStream` +— the only way to read the opening status and headers of a stream — or `{ ok: false, … }` for an +error status. The loop over `result.value` still rejects for the failures in the table above. + +## Testing an event stream + +Fake `fetch` (`typescript-testing`) and hand the SDK a `Response` whose body is a `ReadableStream` of +event frames under `content-type: text/event-stream` — `data: {...}\n\n`, one blank line ending each +event. The SDK reads the body in the transport's own chunks, so split a frame across two `enqueue` +calls to prove the loop does not depend on where the network cuts, and record what the body's +`cancel` receives to prove that `break` released the connection. diff --git a/plugins/spotify/skills/typescript/typescript-getting-started/SKILL.md b/plugins/spotify/skills/typescript/typescript-getting-started/SKILL.md index dcb7875d..18a1c770 100644 --- a/plugins/spotify/skills/typescript/typescript-getting-started/SKILL.md +++ b/plugins/spotify/skills/typescript/typescript-getting-started/SKILL.md @@ -1,42 +1,37 @@ --- name: "typescript-getting-started" -description: "Spotify Web API TypeScript SDK identity and lookup layer (TypeScript/JavaScript only) — install, the single import specifier `spotify-web-api`, the server environments and the base-URL knob, the auth pattern, the SDK map that ships inside the installed package (`sdk-map.md` + `map/operations/`) and how to traverse it, and the file table naming the one source file owning each fact the map leaves to the source. Load this before answering any Spotify Web API TypeScript SDK contract question or writing any SDK code." +description: "Load before answering any Spotify Web API TypeScript SDK question or writing SDK code — the lookup layer for `spotify-web-api`: install, imports, environments, auth, and how to read the SDK map that ships in the package (`sdk-map.md`, `map/operations/`). TypeScript/JavaScript only." --- # Getting started with the Spotify Web API TypeScript SDK -> **Who this skill is for.** This is the **lookup layer** for anyone writing Spotify Web API TypeScript SDK code — it is yours to follow directly and fully. Ground every contract fact here (in the SDK map, and in the source files it names) rather than in recall, and carry those facts onto a contract sheet before you implement. Load `typescript-integrate-spotify-web-api` for the workflow that wraps this skill. +> **The lookup layer** for Spotify Web API TypeScript SDK code: ground every contract fact here — in the SDK map and the source files it names — never in recall, and carry those facts onto a contract sheet before you implement. `typescript-integrate-spotify-web-api` holds the workflow around it. -This is the **SDK-specific** entry point. For general patterns that apply to any APIMatic-generated TypeScript SDK (client construction, auth, calling endpoints, models, error handling, resilience, testing), see the companion API-agnostic skills: `typescript-client-initialization`, `typescript-authentication`, `typescript-calling-endpoints`, `typescript-models`, `typescript-error-handling`, `typescript-configuration-resilience` and `typescript-testing`. - -**This page and those companion skills are complementary — load both.** This page is authoritative for the SDK's *identity and surface* (what to install, what to import, the resources, which file owns which fact); the companion skills are the *usage layer* on top — the best-practice way to call each piece and the gotchas a signature cannot show. Reading a file in the installed package does not remove the need to load the skill for that step, so at each step below, load the companion *and* confirm names against the installed package. +This page is authoritative for the SDK's identity and surface. The API-agnostic companion skills — `typescript-client-initialization`, `typescript-authentication`, `typescript-calling-endpoints`, `typescript-models`, `typescript-error-handling`, `typescript-configuration-resilience` and `typescript-testing` — are the *usage layer* on top: the way to call each piece and the gotchas a signature cannot show. **Load both:** at each **Integration workflow** step, load the companion it names even after reading the file it covers, and confirm names against the installed package. ## SDK identity -Verified against `package.json` and `sdk-map.md` of the generated package at version `2024.3.3`. **Re-verify after a version bump** — this page is a snapshot, not a live read. +Verified against `package.json` and `sdk-map.md` of the package at version `2024.3.3`. **Re-verify after a version bump** — this page is a snapshot, not a live read. | Fact | Value | | --- | --- | | API | Spotify Web API | | Package name (what you install, and what you import) | `spotify-web-api` — **not on npm**; built from source (see *Install*) | -| Import specifier | `spotify-web-api` — the package root is the **only** entry; deep imports do not resolve | | Source repository | https://github.com/context-plugins/spotify-web-api-typescript-sdk (branch `main` — the ref this map documents) | | Version | `2024.3.3` (API spec version `2024.3.3`) | -| Client class | `SpotifyWebApiClient` (`src/client.ts`) — one class, no sync/async split | -| Options type | `ClientOptions` (`src/client-options.ts`) — types only, no resolver beside it | -| Client construction | `new SpotifyWebApiClient(options: ClientOptions = {})` — the argument is optional, as is **every** field on it, so `new SpotifyWebApiClient()` compiles. Fields: `serverEnvironment` · `serverOptions` · `retry` · `fetch` · `oauth20` · `oauth20Strategy` · `oauth20ClientCredentials` · `oauth20ClientCredentialsStrategy`. `retry` is the `RetryOptions` policy; its defaults retry a GET, HEAD, PUT or OPTIONS call up to `3` times and bound each attempt by `retry.timeout` = `60_000` ms, and every one of them can be changed | +| Client class | `SpotifyWebApiClient` (`src/client.ts`) | +| Options type | `ClientOptions` (`src/client-options.ts`) | +| Client construction | `new SpotifyWebApiClient(options: ClientOptions = {})` — the argument is optional, as is **every** field on it, so `new SpotifyWebApiClient()` compiles. Fields: `serverOptions` · `retry` · `logging` · `fetch` · `oauth20` · `oauth20Strategy` · `oauth20ClientCredentials` · `oauth20ClientCredentialsStrategy`. `retry` is the `RetryOptions` policy | | Auth | **OAuth 2 authorization code** — set `ClientOptions.oauth20`
**OAuth 2 client credentials** — set `ClientOptions.oauth20ClientCredentials` | -| Environments | 2 environments (`ServerEnvironment.Production` *(default)*, `ServerEnvironment.Environment2`) × 1 server group | -| Base-URL config | `serverOptions.baseUrl` (`src/servers.ts`), defaulting to `https://api.spotify.com/v1` | +| Environments | no selector — one environment; 2 server groups | +| Base-URL config | `serverOptions..baseUrl` (`src/servers.ts`) | | Log environment variable | `SPOTIFY_WEB_API_CLIENT_LOG` | | Node floor | `>=20.3` (`engines.node`) | -| Runtime dependency | `zod` (`^4.1.0`), imported as `zod/v4-mini` — the only one | +| Runtime dependency | `zod` (`^4.1.0`) — the only one | | Module format | dual ESM + CommonJS folder dialects (`dist/esm`, `dist/commonjs`) behind one export | -| Typing | the package ships its own `.d.ts` and is generated under strict TypeScript. Callers get full inference — **a type error against this SDK is a real contract violation, not noise** | +| Typing | the package ships its own `.d.ts` — **a type error against this SDK is a real contract violation, not noise** | | Surface | 138 operations · 15 resources · 129 models · 18 open enums · 4 unions · 138 per-operation error subclasses | -The table above is **orientation, not a copy-paste recipe** — it gives you the names and facts (install, import specifier, the auth *pattern*, the base-URL knob), while the actual integration code comes from the companion skills. Load each one as you reach its step (see **Integration workflow** below) and confirm its types against the installed package. - ## Install Install the package straight from the repository the plugin records for it, as it is not published to npm: @@ -47,40 +42,32 @@ npm install git+https://github.com/context-plugins/spotify-web-api-typescript-sd The installed package carries everything its `files` list packs — `src/`, `sdk-map.md` and the pages under `map/operations/` — so **every lookup on this page works as soon as the install finishes**. **Make sure the installed package is built**, as the source on GitHub is not pre-built. -Do not vendor its `src/` into your project, point `tsconfig` `paths` at a throwaway clone, or import from `dist/` directly. Installing the package properly is what makes the `exports` map, the shipped `.d.ts` chain and the dual-dialect resolution behave the way the SDK expects — **and it is what puts the SDK map inside `node_modules`, which is where every lookup below reads it from**. Requires Node `>=20.3` (`engines.node`). +Do not vendor its `src/` into your project, point `tsconfig` `paths` at a throwaway clone, or import from `dist/` directly: the `exports` map, the shipped `.d.ts` chain, the dual-dialect resolution and the SDK map in `node_modules` all depend on a real install. ## Imports — one entry, and only one -**Every** public name is re-exported from the package root — the client, `ClientOptions`, `ServerEnvironment`, 151 model types with the schema value beside each, the error classes, and the runtime types (`ApiPromise`, `ApiResult`, `RequestOptions`, `RetryOptions`, `RequestRetryOptions`, `ErrorPayload`, `Declared`, `Schema`, `EnumSchema`, `Encoded`). +**Every** public name is re-exported from the package root — the client, `ClientOptions`, 151 model types with the schema value beside each, the error classes, and the runtime types (`ApiPromise`, `Pageable`, `PageableApiResult`, `ApiResult`, `RequestOptions`, `RetryOptions`, `RequestRetryOptions`, `Declared`, `Undeclared`, `Schema`, `EnumSchema`, `Encoded`, `JsonValue`). ```ts -import { SpotifyWebApiClient, ServerEnvironment, ApiError, SpotifyWebApiError } from "spotify-web-api"; +import { SpotifyWebApiClient, ApiError, SpotifyWebApiError } from "spotify-web-api"; import type { ClientOptions, AlbumBase } from "spotify-web-api"; ``` Things the specifier alone will not tell you: - **Deep imports do not resolve.** The `exports` map exposes `.` and `./package.json` and nothing else, so `spotify-web-api/models/…` fails (`TS2307`) even though the file exists in the shipped `src/`. Every `Source` path on the SDK map is where to **read** a shape, never what to import. -- **From CommonJS**, the typed spelling is `import sdk = require("spotify-web-api")`. A plain `require` destructure runs but yields `any`. -- **`instanceof` is reliable within one dialect.** A process that loads both (`import` in one file, `require` in another) gets two independent copies of every error class, and `instanceof` across that boundary is `false` — narrow on `err.kind` / `err.payload.kind` / `err.name` there. +- **From CommonJS**, the typed spelling is `import sdk = require("spotify-web-api")`. A plain `require` destructure runs but yields `any`. A process that loads both dialects gets two copies of every error class, so `instanceof` fails across them (`typescript-error-handling`). Under `verbatimModuleSyntax`, names carrying no runtime value (`ClientOptions`, every model type) must be imported with `import type`. Under `exactOptionalPropertyTypes`, **omit or spread** an absent optional field rather than assigning `undefined` to it. -## Environments - -`ClientOptions.serverEnvironment` selects one environment for the whole client (`src/servers.ts`). `ServerEnvironment` is a `const` object with a derived union type — not a TypeScript `enum` — and unlike the model enums it is **closed**, so only its declared members are assignable. +## Hosts -| Group | Environment | Base URL | Override at | -| --- | --- | --- | --- | -| `default` | `production` *(default)* | `https://api.spotify.com/v1` | `serverOptions.baseUrl` | -| `default` | `environment2` | `https://accounts.spotify.com` | `serverOptions.baseUrl` | +This SDK has one environment and so **no environment selector** — there is no `ServerEnvironment` type and no field to set (`src/servers.ts`). The base URL of every server group, the only hosts the SDK knows, is in `sdk-map.md` § *Servers & auth*; reaching any other is a `serverOptions` base-URL override — `serverOptions: { default: { baseUrl: "…" } }` — and nothing in the options then records **which** deployment that is, so make the intent explicit where the client is built. Consequences to state on every contract sheet that touches configuration: -- Constructing the client with no options selects **`ServerEnvironment.Production`**, silently. -- An override merges with the built-in default **per group-and-environment pair, key by key**; a `baseUrl` override replaces the template verbatim, template variable values are percent-encoded into it; server variables are filled in once, as the client is built, and only the path parameters expand per request. -- Each operation is bound to one server group at generation time. A map block carries a **Server** bullet only when its group is not `default`. -- An environment value the SDK does not know throws `ConfigurationError` **from the constructor** — every server group is resolved once, as the client is built — so no operation method throws synchronously. +- An override merges with the built-in default **key by key**; a `baseUrl` override replaces the whole template. +- Each operation belongs to one server group; a map block carries a **Server** bullet only when its group is not `default`. ## Auth pattern (2 schemes) @@ -98,56 +85,30 @@ const client = new SpotifyWebApiClient({ }); ``` -**Every credential field is optional at the type level and that is a trap worth flagging on every sheet.** Omit one and nothing fails at construction — the request simply goes out without that credential and the server decides. Most APIs then answer `401`; one that serves anonymous traffic answers `200` and hides the omission entirely. So a `401` on a call you believed was authenticated is usually an unset field rather than an SDK failure; verify the field is set rather than waiting for a `401` to tell you, and check the operation's **Auth** bullet against what the client was actually given. +**Every credential field is optional.** Omit one and the request goes out without it, with no error at construction; the server answers `401`, or `200` if it serves anonymous traffic. On an unexpected `401`, check the operation's **Auth** bullet against the fields you set. -Three more behaviours the type does not show: - -- **A credential may be a function.** Every field typed `TokenProvider` is re-read on **every** request with no caching, so a key can rotate without rebuilding the client. An empty string counts as absent; a function counts as present without being invoked. -- **Composition is emitted, not configured.** Where the spec puts two schemes in one requirement the SDK sends **both**; where it lists alternatives it sends the **first configured** one, in the order the **Auth** bullet prints them. -- **A 401 invalidates the cached credential.** On a 401 (401 only, not 403) the SDK clears whatever that operation's scheme had cached, so the *next* call re-acquires; the current request still rejects. - -**OAuth 2 fetches and caches its own token.** The token request goes through **the same client** — same `fetch`, same `retry` policy — sends a form-urlencoded body, and decodes the response against a schema rather than casting it. A token is cached until shortly before it expires; a response with no `expires_in` is treated as never expiring (RFC 6749 §5.1); concurrent callers share one in-flight fetch. **A refused token endpoint rejects with `AuthError`**, wrapping the underlying `ApiError` as `cause` — so a bad secret never looks like the business call failing, and `AuthError` is *not* an `ApiError`. The token request is itself a `POST` with its own timeout, retried only when `httpMethodsToRetry` names `POST`. +**OAuth 2 fetches and caches its own token.** The token request goes through **the same client** — same `fetch`, same `retry` policy — as a `POST`, retried only when `httpMethodsToRetry` names `POST`. **A refused token endpoint rejects with `AuthError`**, which is *not* an `ApiError`; the endpoint's `ApiError` is its `cause`. | Flow | Token endpoint | Client credentials travel | | --- | --- | --- | -| `oauth20` | `default` + `/api/token` | as `Authorization: Basic` | -| `oauth20ClientCredentials` | `default` + `/api/token` | as `Authorization: Basic` | - -`oauth20Strategy`, `oauth20ClientCredentialsStrategy` on `ClientOptions` substitute the whole token request (`getToken(credentials, signal)`, plus `tryRefreshToken(…)` where the grant is refreshable); the caching, expiry buffer and single-flight behaviour still apply. +| `oauth20` | `authServer` + `/api/token` | as `Authorization: Basic` | +| `oauth20ClientCredentials` | `authServer` + `/api/token` | as `Authorization: Basic` | -The **token endpoint follows the same base URL** as the operations on its group, so it always tracks the environment or the override — you never configure it separately. Its group is named in the table above, against `src/servers.ts`. +`oauth20Strategy`, `oauth20ClientCredentialsStrategy` on `ClientOptions` substitute the whole token request. The **token endpoint follows the base URL of its group** (named in the table), so it tracks the environment and any override. -See `typescript-authentication` for the full picture. +Credential functions, scheme composition, 401 invalidation, token caching and the token-request strategy's shape: `sdk-map.md` § *Servers & auth* and `typescript-authentication`. ## Resources -Resources are **memoized lazy getters** on the client (`client.`). Their classes are exported only for their merged namespaces — the per-operation request and error types — and for `instanceof`; their constructors take engine internals that are not exported, so reach a resource only through its getter. - -| Attribute | Class | Ops | Operations | -| --- | --- | --- | --- | -| `client.albums` | `Albums` | 9 | `checkUsersSavedAlbums` · `getAnAlbum` · `getAnAlbumsTracks` · `getAnArtistsAlbums` · `getMultipleAlbums` · `getNewReleases` · `getUsersSavedAlbums` · `removeAlbumsUser` · `saveAlbumsUser` | -| `client.tracks` | `Tracks` | 17 | `addTracksToPlaylist` · `checkUsersSavedTracks` · `getAnAlbumsTracks` · `getAnArtistsTopTracks` · `getAudioAnalysis` · `getAudioFeatures` · `getPlaylistsTracks` · `getRecommendations` · `getSeveralAudioFeatures` · `getSeveralTracks` · `getTrack` · `getUsersSavedTracks` · `getUsersTopTracks` · `removeTracksPlaylist` · `removeTracksUser` · `reorderOrReplacePlaylistsTracks` · `saveTracksUser` | -| `client.library` | `Library` | 29 | `changePlaylistDetails` · `checkCurrentUserFollows` · `checkUsersSavedAlbums` · `checkUsersSavedAudiobooks` · `checkUsersSavedEpisodes` · `checkUsersSavedShows` · `checkUsersSavedTracks` · `createPlaylist` · `followArtistsUsers` · `getAListOfCurrentUsersPlaylists` · `getFollowed` · `getUsersSavedAlbums` · `getUsersSavedAudiobooks` · `getUsersSavedEpisodes` · `getUsersSavedShows` · `getUsersSavedTracks` · `getUsersTopArtists` · `getUsersTopTracks` · `removeAlbumsUser` · `removeAudiobooksUser` · `removeEpisodesUser` · `removeShowsUser` · `removeTracksUser` · `saveAlbumsUser` · `saveAudiobooksUser` · `saveEpisodesUser` · `saveShowsUser` · `saveTracksUser` · `unfollowArtistsUsers` | -| `client.artists` | `Artists` | 10 | `checkCurrentUserFollows` · `followArtistsUsers` · `getAnArtist` · `getAnArtistsAlbums` · `getAnArtistsRelatedArtists` · `getAnArtistsTopTracks` · `getFollowed` · `getMultipleArtists` · `getUsersTopArtists` · `unfollowArtistsUsers` | -| `client.audiobooks` | `Audiobooks` | 7 | `checkUsersSavedAudiobooks` · `getAnAudiobook` · `getAudiobookChapters` · `getMultipleAudiobooks` · `getUsersSavedAudiobooks` · `removeAudiobooksUser` · `saveAudiobooksUser` | -| `client.chapters` | `Chapters` | 3 | `getAChapter` · `getAudiobookChapters` · `getSeveralChapters` | -| `client.categoriesApi` | `CategoriesApi` | 3 | `getACategoriesPlaylists` · `getACategory` · `getCategories` | -| `client.episodes` | `Episodes` | 7 | `checkUsersSavedEpisodes` · `getAShowsEpisodes` · `getAnEpisode` · `getMultipleEpisodes` · `getUsersSavedEpisodes` · `removeEpisodesUser` · `saveEpisodesUser` | -| `client.genres` | `Genres` | 1 | `getRecommendationGenres` | -| `client.marketsApi` | `MarketsApi` | 1 | `getAvailableMarkets` | -| `client.player` | `Player` | 15 | `addToQueue` · `getAUsersAvailableDevices` · `getInformationAboutTheUsersCurrentPlayback` · `getQueue` · `getRecentlyPlayed` · `getTheUsersCurrentlyPlayingTrack` · `pauseAUsersPlayback` · `seekToPositionInCurrentlyPlayingTrack` · `setRepeatModeOnUsersPlayback` · `setVolumeForUsersPlayback` · `skipUsersPlaybackToNextTrack` · `skipUsersPlaybackToPreviousTrack` · `startAUsersPlayback` · `toggleShuffleForUsersPlayback` · `transferAUsersPlayback` | -| `client.playlists` | `Playlists` | 16 | `addTracksToPlaylist` · `changePlaylistDetails` · `checkIfUserFollowsPlaylist` · `createPlaylist` · `followPlaylist` · `getACategoriesPlaylists` · `getAListOfCurrentUsersPlaylists` · `getFeaturedPlaylists` · `getListUsersPlaylists` · `getPlaylist` · `getPlaylistCover` · `getPlaylistsTracks` · `removeTracksPlaylist` · `reorderOrReplacePlaylistsTracks` · `unfollowPlaylist` · `uploadCustomPlaylistCover` | -| `client.users` | `Users` | 12 | `checkCurrentUserFollows` · `checkIfUserFollowsPlaylist` · `followArtistsUsers` · `followPlaylist` · `getCurrentUsersProfile` · `getFollowed` · `getListUsersPlaylists` · `getUsersProfile` · `getUsersTopArtists` · `getUsersTopTracks` · `unfollowArtistsUsers` · `unfollowPlaylist` | -| `client.search` | `Search` | 1 | `search` | -| `client.shows` | `Shows` | 7 | `checkUsersSavedShows` · `getAShow` · `getAShowsEpisodes` · `getMultipleShows` · `getUsersSavedShows` · `removeShowsUser` · `saveShowsUser` | - -Every operation has the same call shape — `op(request, options?)`, one **flat, channel-blind** request object first and `RequestOptions` (`{ signal, retry, logging }`) second — and returns `ApiPromise`. - -⚠ **The request type name is not uniformly `Request`.** A name that collides inside its namespace is promoted to `RequestParams` instead — no operation in this SDK takes that spelling at this version. Take the name from the operation's **Signature** bullet on its map page; never construct it from the method name. +Resources are **memoized lazy getters** on the client (`client.`); reach one only through its getter. Its class is exported for its merged namespace — the per-operation request and error types — and for `instanceof`, not for construction. + +15 resources: `sdk-map.md` § *Operations — by resource* names every operation, with the page that documents it. + +Every operation has the same call shape — `op(request, options?)`, one **flat, channel-blind** request object first and `RequestOptions` (`{ signal, retry, logging }`) second — and returns `ApiPromise`, or `Pageable` for a paged operation. No operation is paged — every one of them is a single request. ## SDK map — look up first, open the file second -The SDK ships a generated map, and `package.json`'s `files` list includes it, so **installing the package gives you the map** — no clone is needed. It sits at the package root, the directory holding `package.json` and the `src/` tree: +The map sits at the package root, the directory holding `package.json` and the `src/` tree: - **`sdk-map.md`** — the index: client construction with the full `ClientOptions` table, the *Not on this SDK* table, the one error family with `ApiResult` and `.asApiResult()`, wire serialization for every channel, servers and auth, runtime and packaging, and the link table into the operations pages. - **`map/operations/.md`** — one page per resource, one `###` block per operation, with bullets in the fixed order **Server**, **Signature**, **Wire** (verb and route), **Auth**, **Request body**, **SDK-sent**, **Returns**, **Error**, **Error arms** — then a **Fields** table giving every request field its channel, wire name, type, required flag and default, and a **Type sources** table naming the declaring file and schema value of every type the operation mentions. @@ -160,19 +121,17 @@ node -e "console.log(require.resolve('spotify-web-api/package.json'))" Failing that it is at `node_modules/spotify-web-api/`. **If the resolve fails, or the directory it prints carries no `sdk-map.md`, the map is still in the SDK's own repository** — , branch `main`. A registry id is a claim on a shared index rather than proof of identity, so it can resolve to an unrelated package or to a release predating the map; the repository is the copy that is this SDK by construction. Read it there, and if neither route yields a map, mark the fact `UNVERIFIED` and say what would settle it rather than answering from memory. -Every `Source` path on the map is relative to that package root, so `src/models/.ts` opens as written from there — the package ships its `src/` tree, so the path resolves inside `node_modules/spotify-web-api/` exactly as the map writes it. An import specifier ending `.js` inside that source is the NodeNext spelling of the sibling `.ts` file. - -**The map is the locator; the source files are the shapes.** Read the map first — signatures, routes, request fields with their channels and defaults, return types, error arms, and which file declares a type are all answered there without opening a single `.ts` file. Then open the one file the map names for what it deliberately does not carry: a model's members, whether each is required, optional or nullable, and an enum's members with their wire values — the `as const` object in the enum's own file (for an enum inside a model, the file the model imports it from). The map says so itself — *"Shapes live only in the source … Do not derive the path from the type name."* +Every `Source` path on the map is relative to that package root (`node_modules/spotify-web-api/`). An import specifier ending `.js` inside that source is the NodeNext spelling of the sibling `.ts` file. -**`sdk-map.md` carries the invariants every operation block assumes, so read it before any `map/operations/` page**; the pages are written to be read beside it. And **silence means the default**: the index states what holds for every operation — the call shape, the flat channel-blind request object, the `ApiPromise` return, the default server group, no pagination and no streaming — and a block departs from one only by saying so. Take the default and move on rather than opening the source to confirm it. +**Read `sdk-map.md` before any `map/operations/` page.** It states what holds for every operation, and **silence means the default**: a block departs from it only by saying so — a paged operation's **Signature** returns `Pageable` and its **Returns** bullet names the strategy and what ends the walk — so take the default rather than opening the source to confirm it. **The map carries shapes; what an operation *means* lives elsewhere.** When *what* to pass depends on meaning — which values a field accepts beyond its type, a rule that couples two fields, what a defaulted header actually selects — the map will not settle it. Read that operation's entry in `api-reference.md` at the package root, keyed by the same signature, *before* writing the sheet row, and record what you found. A value you already "know" for a field the map types as a plain `string` is a lookup, not a recall — the memory ban applies to it. ## Contract facts — the map first, then the source file -**Six of these are map lookups — don't open a source file for them:** an operation's signature; its request fields with channel, wire name, required flag and default; its return type; its error subclass and the arms with the status each covers; the `ClientOptions` fields and their defaults; and the environments, base URLs and auth wiring. +**The map is the locator; the source files are the shapes.** These are map lookups — don't open a source file for them: an operation's signature and route; its request fields with channel, wire name, required flag and default; its return type; its error subclass and the arms with the status each covers; the `ClientOptions` fields and their defaults; the environments, base URLs and auth wiring; and which file declares a type. -The table below covers everything else, and the full body behind a map row. Paths are relative to `node_modules/spotify-web-api/`: +Open the one file the map's **Type sources** table names — never derive the path from the type name — for what the map does not carry: a model's members and whether each is required, optional or nullable, and an enum's members with their wire values — the `as const` object in the enum's own file (for an enum inside a model, the file the model imports it from). The table below covers that, everything else, and the full body behind a map row. Paths are relative to `node_modules/spotify-web-api/`: | Question | File | | --- | --- | @@ -186,6 +145,8 @@ The table below covers everything else, and the full body behind a map row. Path | The transport: the attempt loop, `fetch` resolution, 401 invalidation, 2xx-vs-error split | `src/core/raw-client.ts` | | Error classes and `ErrorKind` | `src/core/errors.ts`, `src/core/api-error.ts` | | `ApiPromise`, `ApiResult`, `.asApiResult()`, the `Symbol.species` behaviour | `src/core/api-promise.ts` | +| `Pageable` and `PageableApiResult` — the lazy walk a paged operation returns, `.pages()`, and `.asApiResult()` on a walk | `src/core/pagination/pageable.ts` | +| The four paging states — offset, page, cursor and link — and the stop rule each applies | `src/core/pagination/states/offset-state.ts`, `src/core/pagination/states/page-state.ts`, `src/core/pagination/states/cursor-state.ts`, `src/core/pagination/states/link-state.ts` | | `RequestOptions` (it is `{ signal, retry, logging }` and nothing else) | `src/core/api-request.ts` | | `RetryOptions` and its defaults, `RequestRetryOptions`, backoff, `Retry-After`, `RetryAttempt` | `src/core/retry.ts` | | `LoggingOptions` and its defaults (`defaultLoggingOptions`), `RequestLoggingOptions`, `Logger`, `LogDetails` | `src/core/logging.ts` | @@ -202,37 +163,44 @@ Keep lookups cheap — the rules that keep a session's context small: - **Never grep, glob or `find` the package to *locate* a type** — the map is the locator, and it says so. Grep only *inside* the file its **Type sources** table names, for the symbol. A sweep for a cross-cutting *shape* is a different question and is fine: "every field typed `unknown`", "every required-nullable member" are things nothing indexes, and one targeted `grep -rn` over `src/models/` is the right tool — record what it found on the sheet. - Trust the compiler over this page: if a name here ever fails to type-check, re-read the file the table above names and report the drift; never patch around it from memory. +## Validation — what `validate` checks + +Every model's schema const — the value export beside its type — carries `encode`, `decode` and `validate`. `validate(value)` runs `encode`'s rules without the conversion and without the throw, and returns `{ success: true }` or `{ success: false, message }`, the message naming every failing field under its full path and why. + +**This SDK enforces the spec's value constraints on `validate`.** A model or union whose spec declares one — `minLength`/`maxLength`, `pattern`, `format` (`email`, `hostname`, `ipv4`, `ipv6`, `uri`, `uri-reference`, `json-pointer`), `minimum`/`maximum`, `exclusiveMinimum`/`exclusiveMaximum`, `multipleOf`, `minItems`/`maxItems`/`uniqueItems`, `minProperties`/`maxProperties`, and the keywords on an array's `items` and a map's `additionalProperties` — carries it on its public schema: `audioAnalysisObjectSchema.validate(value)` reports it and `encode` throws on it. A model that nests a constrained one checks the nested value too and reports its fields under their full path. The operations do **not** apply those constraints: they encode and decode through a structural twin the module keeps for itself, `audioAnalysisObjectInternalSchema`, which the package root does not export, so a value the service would accept is never refused on the way out, and a service ahead of the spec is never refused on the way in. A schema's own file says which it is: a constrained one declares the twin beside the public one. An operation whose own request fields carry a constraint exports a request schema beside its request type — `Albums.getAnAlbumsTracksRequestSchema` — which the operation never runs: pass the request object to its `validate` before the call, the way a model's schema checks a model. Every other schema is structural only, and its `validate` checks shape alone. + ## Sensitive data — check the request models before you log anything -Whether this API's **request** models carry fields you must never log — card or bank numbers, personal data, message content — is a shape question: each request model's declaring file (the map's **Type sources** table names it) lists every field. If the scope touches such a field, four generator facts decide your logging posture (all in `typescript-configuration-resilience`): a JSON request body is logged **verbatim** when `logRequestBody` is on, with no redaction; a form body is masked only by deny-list; a per-call `RequestOptions.logging` level turns the request body on for that call, whatever the client set; and leaving `ClientOptions.logging` without a `logger` or a `level` arms the `SPOTIFY_WEB_API_CLIENT_LOG` environment variable, which turns logging and both header switches on with no code change and no deploy — though never the body. So on any build that can carry such a field: `logRequestBody` stays off, no call on those paths passes a per-call level, `ClientOptions.logging.level` is set explicitly in production, and your own diagnostics never echo a request body on those paths. +Whether this API's **request** models carry fields you must never log — card or bank numbers, personal data, message content — is a shape question: each request model's declaring file (the map's **Type sources** table names it) lists every field. If the scope touches such a field: `logRequestBody` stays off, because it logs a JSON request body **verbatim** and masks a form body only by deny-list; no call on those paths passes a per-call `RequestOptions.logging` level, which turns the request body on for that call whatever the client set; `ClientOptions.logging.level` is set explicitly in production, because without a `logger` or a `level` the `SPOTIFY_WEB_API_CLIENT_LOG` environment variable turns logging and both header switches on with no code change; and your own diagnostics never echo a request body on those paths (`typescript-configuration-resilience` has the details). The SDK never logs a response body, but your own code may. Responses are often safer — many APIs return masked variants of what requests carry raw — but that too is a model-shape fact: check the response model's file before assuming. ## Integration workflow — load the companion skill at each step -Before you write the code for each step, load the named companion skill — even if you have already read the relevant file. Each step calls out the trap the signature hides (in *parens*). A typical integration reaches them in this order: +Before you write the code for each step, load the named companion skill — even if you have already read the relevant file. A typical integration reaches them in this order: -1. **Client construction & lifetime** — load **typescript-client-initialization** before you write `new SpotifyWebApiClient(…)`. (*The signature won't tell you:* every option is optional, so a client built with no arguments compiles and talks to the default environment with no credential; the client must be **long-lived and app-scoped**, never rebuilt per request, because the resource getters and the OAuth 2 token cache live on it; there is no `close()` or `dispose()` — it owns no pool, only a `fetch`; and when no `fetch` is reachable the **constructor** throws `ConfigurationError`, not the first call.) -2. **Authentication** — load **typescript-authentication** before you set credentials. The 2 schemes are `oauth20`, `oauth20ClientCredentials` on `ClientOptions`. (*The signature won't tell you:* the field is optional — omit it and every request goes out unauthenticated with no failure at construction; the token is fetched lazily and cached on the client; a **failed token fetch** raises `AuthError`, which is not an `ApiError` and **bypasses `.asApiResult()` entirely**; and a 401 invalidates the cache without retrying the current call. Load secrets from the environment or a secret store, never hardcode.) -3. **Calling an endpoint** — load **typescript-calling-endpoints** before the first `client..(…)` call. (*The signature won't tell you:* the request object is **flat and channel-blind** — a field named `body` *is* the whole request body and every other field is fanned out to path, query or header by the SDK, so nothing is nested by channel; **an omitted field that has a default is still sent, with that default**; **43 operations resolve to `undefined`**; and `.asApiResult()` must be called on the value the operation returned, because `ApiPromise` overrides `Symbol.species` and `.then()`/`.catch()` hand back a plain `Promise` with the method gone.) -4. **Models** — load **typescript-models** the moment a request/response member is not a plain string or number. (*The signature won't tell you:* models are plain `type`s built from object literals — no constructor, no builder; `f?: T` means omit the key, while `f: T | null` is **required and nullable** and `null` is a distinct value; enums are **open** (`const` companion plus a union admitting `(string & {})`), so the schema validates the base type only and an unknown server value round-trips instead of throwing — use `.values` to test membership yourself; and every type has a schema companion usable in both directions.) -5. **Error handling** — load **typescript-error-handling** before you write any `try/catch`. (*The signature won't tell you:* every operational failure is **one family**, `SpotifyWebApiError`, narrowed on `err.kind` — `"api"` is an API error status, carried by `ApiError` and its per-operation subclasses — while four throwables sit outside it (`ConfigurationError` from the constructor, `SchemaError` from a codec called directly, a `TypeError` for a bug, and a caller abort's own `reason`), so a `catch` that tests the family has to rethrow the rest; **arm tags are schema-derived, not statuses** (see the sheet checklist below); a malformed 2xx body rejects with `DecodeError`, not `ApiError`, and `.asApiResult()` does not convert it; and a missing response field the schema permits is silently `undefined` rather than any error at all.) -6. **Configuration & resilience** — load **typescript-configuration-resilience** when you set the base URL, timeouts, retries, proxies, TLS, or logging. (*The signature won't tell you:* **retrying is on by default** — the default policy retries a GET, HEAD, PUT or OPTIONS call on `408`, `429`, `500`, `502`, `503` and `504` and on a dropped connection or timeout, and every one of those is a `RetryOptions` field you can change; a write is repeated only when `httpMethodsToRetry` names its method; `retry: { maxRetries: 0 }` turns it off, one call overrides it through `RequestOptions.retry`, and a `401` is not retried by default; `retry.timeout` bounds **one attempt**, up to its response headers, not the whole call, and `0` is a zero-length deadline while a value `setTimeout` cannot honour falls back to the default; **logging is off by default** — `ClientOptions.logging` turns it on with a `logger` or a `level`, and so does the `SPOTIFY_WEB_API_CLIENT_LOG` environment variable when code sets neither, but a request body is logged only when code sets `logRequestBody`, and then a JSON body **verbatim**, with no redaction; **there are no hooks, middleware or interceptors** — `ClientOptions.fetch` is the one transport extension point, `onRetry` being the only built-in callback; and a `fetch` replacement is called with the attempt's `Request` and no `init`, so one that does not forward that `Request`, or its `signal`, makes both each attempt's timeout and every `RequestOptions.signal` inert.) -7. **Testing** — load **typescript-testing** before you stub the SDK. (*The signature won't tell you:* the seam is **`ClientOptions.fetch`**, not the client class and not the resource classes — whose constructors take unexported engine internals, so they cannot be instantiated in a test; stub bodies in **wire shape** and let the SDK decode them; assert on the request the SDK actually built, headers included; and cover the failure kinds an `ApiError`-only test misses, `DecodeError` above all.) +1. **Client construction & lifetime** — load **typescript-client-initialization** before you write `new SpotifyWebApiClient(…)`. The client is **long-lived and app-scoped**, never rebuilt per request, because the resource getters and the OAuth 2 token cache live on it. +2. **Authentication** — load **typescript-authentication** before you set credentials. The 2 schemes are `oauth20`, `oauth20ClientCredentials` on `ClientOptions`. Load secrets from the environment or a secret store, never hardcode. +3. **Calling an endpoint** — load **typescript-calling-endpoints** before the first `client..(…)` call. +4. **Models** — load **typescript-models** the moment a request/response member is not a plain string or number. +5. **Error handling** — load **typescript-error-handling** before you write any `try/catch`. Every operational failure is **one family**, `SpotifyWebApiError`, narrowed on `err.kind`. +6. **Configuration & resilience** — load **typescript-configuration-resilience** when you set the base URL, timeouts, retries, proxies, TLS, or logging, or walk a paged operation. +7. **Testing** — load **typescript-testing** before you stub the SDK. The seam is **`ClientOptions.fetch`**. ## What a contract sheet must carry for this SDK Beyond the usual signatures and model members, a contract sheet for the Spotify Web API TypeScript SDK is incomplete without these, because each one is a decision the implementer cannot make correctly from the signature alone. -1. **Which host each deployment talks to**, and where that is set. The members are `ServerEnvironment.Production`, `ServerEnvironment.Environment2`, defaulting to `ServerEnvironment.Production` when the field is unset. +1. **Which host each deployment talks to**, and where that is set. Any host but the one this SDK knows is a `serverOptions` base-URL override (see *Hosts*) — give the override path on the sheet. 2. **43 operations resolve to `undefined`** — `await` gives you nothing to inspect, so **`.asApiResult()` is the only way to observe their status and headers** — decide the mode at write time, not by retrofit. 3. **The exact request type name per operation**, taken from the **Signature** bullet. -4. **Every request field with its channel, wire name and default**, because the request object is flat and channel-blind and the SDK fans fields out. An omitted field that has a default is still sent with that default, so a defaulted header shapes the response whether or not the sheet mentions it. The generator injects an `Idempotency-Key` on every non-GET operation that does not declare that header itself — minted once per call and invisible to you. Every retry of that call re-sends the **same** key, which is what makes naming a write in `httpMethodsToRetry` safe where the provider deduplicates on it; but the next call mints a new one, so a call your own code repeats is two submissions. Any caller-supplied idempotency or request-id field is the only idempotency that spans calls, and `RequestOptions` is `{ signal, retry, logging }` only. -5. **Required vs optional vs required-nullable** for every model member the task sets — `f: T` required, `f?: T` omit the key, `f: T | null` required and nullable. And that under `exactOptionalPropertyTypes` an absent optional is **omitted or spread**, never assigned `undefined`. -6. **The error arms for each operation in scope, with the status each covers — and the warning that arm tags are schema-derived, not status codes.** Every operation rejects with its own `ApiError` subclass narrowed on `err.payload.kind`, and a tag comes from the arm's **body schema**: an arm whose body is a direct model reference is named after that model in lower camel (`"validationError"`), and every other body — a primitive, an array, a map, or no content — is named `"error{Status}"` (`"error400"`, `"error4XX"`, `"errorDefault"`), with a numeric suffix on the second of two arms that would otherwise land on the same name. The same tag means different statuses on different operations, and the same status carries different tags — so a tag is only meaningful beside the arm table it came from, and a shared helper that switches on `kind` across operations is a bug. 138 of 138 operations declare typed error bodies; the rest reject with the base `ApiError`. Every operation also carries an always-present `"undeclared"` arm holding `rawBody: ArrayBuffer`, for which **matcher precedence** matters: an exact numeric status is looked up across the whole table first, then the first covering range, and last a `"default"` arm where the spec declared one — whose body, if it does not fit, falls to `"undeclared"` rather than throwing. -7. **That a malformed or drifted 2xx body rejects with `DecodeError`, not `ApiError`, in both response modes** — `.asApiResult()` converts an HTTP error status, never any other failure. Any sheet row for a call whose result is used must name the members the implementer has to assert on, because a thin or truncated body decodes without complaint and the hole surfaces later. +4. **Every request field with its channel, wire name and default**, because the request object is flat and channel-blind and the SDK fans fields out. An omitted field that has a default is still sent with that default, so a defaulted header shapes the response whether or not the sheet mentions it. Every non-GET operation sends an `Idempotency-Key` header, minted once per call and invisible to you, unless it takes that header as a request field — `typescript-configuration-resilience` has what that key does and does not deduplicate. Any caller-supplied idempotency or request-id field is the only idempotency that spans calls, and `RequestOptions` is `{ signal, retry, logging }` only. +5. **Required vs optional vs required-nullable** for every model member the task sets — `f: T` required, `f?: T` omit the key, `f: T | null` required and nullable. +6. **The error arms for each operation in scope, with the status each covers — and the warning that arm tags are schema-derived, not status codes.** Every operation rejects with its own `ApiError` subclass narrowed on `err.payload.kind`. A tag comes from the arm's body schema and is resolved per operation, so the same tag means different statuses on different operations, and a shared helper that switches on `kind` across operations is a bug — `typescript-error-handling` has the naming rule, the always-present `"undeclared"` arm and the matcher precedence. 138 of 138 operations declare typed error bodies; the rest reject with the base `ApiError`. +7. **That a malformed or drifted 2xx body rejects with `DecodeError`, not `ApiError`, in both response modes** — and the members the implementer has to assert on, because a thin or truncated body decodes without complaint. 8. **The retry policy this integration needs.** Retrying is on by default — `ClientOptions.retry` sets it for the client and `RequestOptions.retry` overrides it per call — so the sheet says whether the defaults fit, which writes (if any) join `httpMethodsToRetry`, since a write is repeated only when the policy names its method, and the per-attempt timeout. -9. **The logging this integration needs.** Logging is off by default — `ClientOptions.logging` sets it for the client and `RequestOptions.logging` sets one call's level — so the sheet says whether it stays off and, where it is on, the level, the logger, and whether headers and the request body are logged: a JSON request body is logged verbatim, with no redaction. -10. **That the SDK performs no pagination and no streaming at all**, and that `ClientOptions.fetch` is the one seam where either can be added — so whatever the task needs there is yours to build or deliberately omit. Say which. -11. A **REQUIRED READING** block naming the `typescript-*` companions that govern the steps, with inline `MUST load` pointers. +9. **The logging this integration needs.** Logging is off by default — `ClientOptions.logging` sets it for the client and `RequestOptions.logging` sets one call's level — so the sheet says whether it stays off and, where it is on, the level, the logger, and whether headers and the request body are logged (**Sensitive data**, above). +10. **That the SDK performs no streaming at all**, and that `ClientOptions.fetch` is the one seam where it can be added — so whatever the task needs there is yours to build or deliberately omit. Say which. +11. **That no operation is paged** — every call is one request, so any list the task pages is driven by hand, with a bound of its own. +12. A **REQUIRED READING** block naming the `typescript-*` companions that govern the steps, with inline `MUST load` pointers. diff --git a/plugins/spotify/skills/typescript/typescript-integrate-spotify-web-api/SKILL.md b/plugins/spotify/skills/typescript/typescript-integrate-spotify-web-api/SKILL.md index c2f9b0df..b96889fc 100644 --- a/plugins/spotify/skills/typescript/typescript-integrate-spotify-web-api/SKILL.md +++ b/plugins/spotify/skills/typescript/typescript-integrate-spotify-web-api/SKILL.md @@ -1,21 +1,28 @@ --- name: "typescript-integrate-spotify-web-api" -description: "MANDATORY FIRST STEP for Spotify Web API TypeScript SDK work in a TypeScript or JavaScript project — load this BEFORE you write any code; TypeScript SDK ONLY, never load it for any other language. Applies when asked to integrate Spotify Web API in TypeScript/Node — check users saved albums, get an album, get an albums tracks, get an artists albums, get multiple albums, get new releases, or when the Spotify Web API TypeScript SDK errors, fails to compile, or behaves unexpectedly. Knowing the SDK exists is NOT a substitute for loading this, because it carries five binding gates stated NOWHERE else and not inferable from the package — (1) load typescript-getting-started, confirm `spotify-web-api` actually resolves and read the SDK map that ships inside it before any lookup, (2) the exact plan-file path (spotify-web-api-plan.md at the repo root) and the no-project-file-edits window until a contract sheet with no open lookups exists there and you have read it, (3) the mandatory load of every typescript-* companion skill the sheet names, (4) the host decision, which this SDK forces once and irreversibly — constructing the client with no options silently selects ServerEnvironment.Production, and (5) the memory ban, where every signature, request field, channel, header default, error arm and enum member comes from a lookup and never from recall or runtime introspection." +description: "MANDATORY FIRST STEP for Spotify Web API TypeScript SDK (`spotify-web-api`) work in a TypeScript or JavaScript project: load before writing any code — integrating Spotify Web API (check users saved albums, get an album, get an albums tracks), or when the SDK errors, fails to compile or behaves unexpectedly. Sets the plan-first workflow, the contract sheet and which companion skills to load. TypeScript/JavaScript only; never load it for another language." --- # Spotify Web API TypeScript SDK — Integration workflow (lookup layer + contract sheet) -You do the SDK lookups yourself: `typescript-getting-started` is your **lookup layer** — load it and ground every contract fact in it (and in the source files its table names) before writing code. The `typescript-*` companion skills are a different thing: they are API-agnostic *usage* guidance, they are yours to load, and Step 1c below makes loading them mandatory. - ## Your lookup layer -- **`typescript-getting-started`** is the entry point for every SDK need. It carries the SDK's identity (package name, version, Node floor, how it installs), the single import specifier and what the root exports, the server environments and the base-URL knob, the auth pattern, the resources, and a **file table** naming the one file that owns each kind of fact. Load it first, always. -- **The SDK map is your lookup surface, and you open it yourself.** The SDK ships `sdk-map.md` and `map/operations/` at its package root — and because `package.json`'s `files` list includes them, **installing the package puts the map in `node_modules/spotify-web-api/`**. There is nothing to clone and no helper agent to delegate to. `typescript-getting-started` tells you how to traverse it: read `sdk-map.md` once, then the one resource page your operations live on. -- **The installed package is the ground truth; the file table is only the locator.** Confirm it resolves before you rely on a lookup — `node -e "console.log(require.resolve('spotify-web-api/package.json'))"`. **If the resolve fails, or the directory it prints carries no `sdk-map.md`, the map is still in the SDK's own repository** — , branch `main`. Read it there, and only if neither route yields a map mark the fact `UNVERIFIED`, say what would settle it, and do not fill the hole from memory. This SDK is **not published to a registry**, so the install is a build from its source — . `typescript-getting-started`'s *Install* section carries what to run. -- **Read scoped.** Search for the one symbol and read the lines around it rather than whole files, and never copy a design comment's rationale onto a contract sheet — the sheet carries facts an implementer must obey, not the reasoning behind them. -- **Write a contract sheet with no open lookups** before you implement: exact signatures with the right request type name, every request field with its channel, wire name and default, required-vs-optional-vs-nullable members, the error arms per operation with the status each covers, and enum members for the operations in scope. `typescript-getting-started` ends with a checklist of what a sheet for this SDK is incomplete without — treat that as the checklist for your own sheet, and collect every in-scope operation in ONE pass rather than re-opening a map page per field. +- **`typescript-getting-started`** is the entry point for every SDK need: identity, install, imports, environments, auth, resources, and a **file table** naming the one file that owns each kind of fact. Load it first, always. +- **The SDK map is your lookup surface.** The SDK ships `sdk-map.md` and `map/operations/` at its package root — and because `package.json`'s `files` list includes them, **installing the package puts the map in `node_modules/spotify-web-api/`**. `typescript-getting-started` tells you how to traverse it: read `sdk-map.md` once, then the one resource page your operations live on. +- **The installed package is the ground truth; the file table is only the locator.** Confirm it resolves before you rely on a lookup — `node -e "console.log(require.resolve('spotify-web-api/package.json'))"`. **If the resolve fails, or the directory it prints carries no `sdk-map.md`, the map is still in the SDK's own repository** — , branch `main`. Read it there, and only if neither route yields a map mark the fact `UNVERIFIED` and say what would settle it. This SDK is **not published to a registry**, so the install is a build from its source — . `typescript-getting-started`'s *Install* section carries what to run. +- **Write a contract sheet with no open lookups** before you implement: exact signatures with the right request type name, every request field with its channel, wire name and default, required-vs-optional-vs-nullable members, the error arms per operation with the status each covers, which operations are paged and the bound each walk takes, and enum members for the operations in scope. `typescript-getting-started` ends with a checklist of what a sheet for this SDK is incomplete without — treat that as the checklist for your own sheet, and collect every in-scope operation in ONE pass rather than re-opening a map page per field. + +## The planner agent + +`spotify-web-api-planner` ships with this plugin. It writes `spotify-web-api-plan.md` — the plan and its contract sheet — and revises it in place; it writes no project code. Start it the first of these ways your host allows: + +1. **Your subagent tool lists it.** Some hosts list a plugin's agents under the plugin's name, as `spotify:spotify-web-api-planner`; start it by whichever of the two names your subagent tool lists. +2. **It isn't listed, or you can't start a subagent.** Tell the user in one line that you are writing the plan yourself, then do so as *Step 1* describes. Don't stop to ask. + +However you start it: -**Scope guard:** the APIMatic-generated Spotify Web API **TypeScript SDK** (package and import specifier `spotify-web-api`, client `SpotifyWebApiClient`) in **TypeScript or JavaScript projects only**. Unrelated API, or any language other than TypeScript/JavaScript — do nothing; this skill does not apply. +- **Start it on the same model you are running on.** If your subagent tool takes a model, pass your own model; if it has no model option, leave its default. Tell the user in one line which model you started it on. +- **Start it once per integration.** A plan revision is a follow-up message to that same agent; re-start it, carrying the clarification and the plan path, only where your host cannot message it. Never start a second one for the same integration. ## Workflow @@ -23,26 +30,30 @@ You do the SDK lookups yourself: `typescript-getting-started` is your **lookup l ### Step 1 — Plan first (always, for any implementation work) -Your FIRST action is to load `typescript-getting-started` and work through the user's full request (all features in scope — one plan covers the whole implementation). Load `typescript-error-handling` before you write the plan too: table 1b.4 is decided from it. Then write the plan and its contract sheet to `/spotify-web-api-plan.md` — that absolute path, not a location you pick later. +Your FIRST action, once the SDK is installed (installing it is a prerequisite the gate allows, below, and it follows the toolchain check and the baseline), is to start **`spotify-web-api-planner`**, as *The planner agent* says, once, with the user's full request — all features in scope; one plan covers the whole implementation — and the name of this skill, `typescript-integrate-spotify-web-api`. Dictate in its task the absolute project root and the absolute path it must write to — `/spotify-web-api-plan.md`, that absolute path, not a location you pick later. It loads `typescript-getting-started` and `typescript-error-handling` — table 1b.4 is decided from it — writes the plan and its contract sheet as Steps 1 to 1c describe, and returns the file's path. -**Do the read-only prerequisites in the same pass — they need no SDK knowledge and touch no project file:** +**If you couldn't start the planner** (case 2 in *The planner agent*), load both skills yourself, work through the request, and write the file at that path. + +**Do these two read-only prerequisites before you install the SDK — the install changes the tree they read:** -- the repo survey (read-only exploration of conventions, layering, **module format — ESM or CJS, which changes how the SDK is imported and whether `instanceof` on its error classes is trustworthy**, and the runtime: Node, a bundled browser app, or an edge runtime) — capture each convention as *pattern + the ONE exemplar file path to imitate*, NOT inline code snippets: you will read the exemplar at edit time anyway, so a snippet dump gets paid for twice; - **establish the toolchain before you need it**: the package manager, whether `spotify-web-api` is already a dependency and at what version, the `tsconfig` flags that change what compiles here (`exactOptionalPropertyTypes`, `verbatimModuleSyntax`, `strict`), and the exact commands that run the project's build, type check, lint and tests. Getting this wrong later costs a broken install mid-implementation — and an uninstalled package costs you the lookup layer itself, since the map ships inside it; -- a baseline run of the project's checks (`tsc --noEmit`, the test runner, the linter — whatever it has) on the UNTOUCHED tree, so later failures are attributable to your changes; -- credentials/environment verification (per the task's secret-handling rules) — **including which host this deployment will actually talk to**, since constructing the client with no options silently selects `ServerEnvironment.Production`, and the other environment is reached only by setting it; -- **a read-only smoke of each in-scope operation against the real credential**, run from your scratchpad, not the project, once the map has given you the signatures and before you finalise the sheet. A plan-, region- or entitlement-gated endpoint answers `403` here — the map presents every operation uniformly and cannot know which ones your credential may call — and learning that now reorders the plan rather than the build. Skip only operations whose side effects you cannot reverse; +- a baseline run of the project's checks (`tsc --noEmit`, the test runner, the linter — whatever it has) on the UNTOUCHED tree, so later failures are attributable to your changes. + +**Do the rest while the planner works — they need no SDK knowledge and touch no project file:** + +- the repo survey (read-only exploration of conventions, layering, **module format — ESM or CJS, which changes how the SDK is imported and whether `instanceof` on its error classes is trustworthy**, and the runtime: Node, a bundled browser app, or an edge runtime) — capture each convention as *pattern + the ONE exemplar file path to imitate*, NOT inline code snippets: you will read the exemplar at edit time anyway, so a snippet dump gets paid for twice; +- credentials/environment verification (per the task's secret-handling rules) — **including which host this deployment will actually talk to**, since this SDK has one environment and no `ServerEnvironment`, so **any other host is a `serverOptions` base-URL override rather than an environment value**; - setting up your task tracking. -Never use the planning phase to get a "head start" on implementation: **creating or editing ANY project file before the gate below is a defect**, no matter how obvious the code seems. +**HARD GATE — no project-file creation or edits until:** the planner has RETURNED, `spotify-web-api-plan.md` EXISTS at the repo root (check it — a helper can misreport where it saved), its contract sheet has **no open lookups**, and you have read it. If you wrote the plan yourself, the gate is the same without the return. **Creating or editing ANY project file before then is a defect**, however obvious the code seems; the read-only prerequisite work above is allowed meanwhile. -**HARD GATE — no project-file creation or edits until:** `spotify-web-api-plan.md` EXISTS at the repo root, its contract sheet has **no open lookups**, and you have read it. The gate bars coding "meanwhile"; it does not bar the read-only prerequisite work above. Starting to code before the sheet exists defeats the entire plan-first design. +**What the gate does not cover:** installing `spotify-web-api` into the project, installing the toolchain, and the files those writes produce (`node_modules/`, a lockfile the installer updates) are **prerequisites, not project-file edits** — the map lives inside the installed package — and they are the only writes permitted before the gate. -**What the gate does not cover:** installing `spotify-web-api` into the project, installing the toolchain, and the files those writes produce (`node_modules/`, a lockfile the installer updates) are **prerequisites, not project-file edits**. On a greenfield repo they are the only way to reach the lookup layer at all — the map lives inside the installed package — and they are the only writes permitted before the gate. Nothing you author by hand may change. +**One read-only prerequisite waits for the signatures: a smoke of each in-scope operation against the real credential**, run from your scratchpad, not the project, once the planner has returned and you have read the sheet, with the signatures it records, and before your first project edit — or, if you are writing the plan yourself, once the map has given you the signatures and before you finalise the sheet. A plan-, region- or entitlement-gated endpoint answers `403` here — the map presents every operation uniformly and cannot know which ones your credential may call — and learning that now reorders the plan rather than the build. Send each `403` to the SAME planner as a revision, as *Step 1c* sends a blocker, and implement from its reply; if you wrote the plan yourself, revise the sheet in place. Skip only operations whose side effects you cannot reverse. ### Step 1b — The tables the contract sheet must carry (fill these in before you write any code) -The per-operation rows describe **what each operation is**. The tables below carry what those rows cannot: a write that may reach the provider twice or whose outcome you may not learn, a rule that spans two operations, and a field nobody asked for. Fill in every one that applies before any code exists. +The per-operation rows describe **what each operation is**. The tables below carry what those rows cannot: a write that may reach the provider twice or whose outcome you may not learn, a rule that spans two operations, and a field nobody asked for. Fill in every one that applies. #### 1b.1 — DURABLE WRITES @@ -57,7 +68,7 @@ One row in each table below per operation in scope that creates, sends or change **Where that rejection is caught**: the `catch` for what the store raises on the second claim, recognised by the driver's error code rather than its message; the losing caller then uses the record the winner wrote. -The SDK sends an `Idempotency-Key` minted once per call, and its own retries resend that key — but a second click or a retry of your own is a new call with a new key, so the provider cannot join the two. The key goes beside the claim, never in place of it; where the operation declares its own key, send the reference stored on the claim (see `typescript-configuration-resilience`). +The SDK's own `Idempotency-Key` is new on every call (*Making a write safe under retries* in `typescript-configuration-resilience`), so it goes beside the claim, never in place of it; where the operation declares its own key, send the reference stored on the claim. **UNKNOWN OUTCOMES** — what settles a write the provider may have acted on without your code learning the answer. @@ -66,7 +77,7 @@ The SDK sends an `Idempotency-Key` minted once per call, and its own retries res ⚠⚠ A `ConnectionError` or `TimeoutError` on a write is *unknown*, not *failed*: the provider may already have acted. Reporting a failure is not a legal entry, and neither is leaving the caller to check or retry. Settle it in that write's own `catch`: re-read by the reference you sent — found, settle from what the provider holds; not found, or the re-read itself fails, still unknown, never failed. Telling the caller the outcome is unknown comes after the re-read, never instead of it. If the provider offers no way to find the write, that is a **Blocker** in Assumptions & Blockers, not a row. -A write that never left has nothing to re-read — a credential that could not be obtained (`AuthError`) or a value that would not encode (`EncodeError`) — and must reach a different outcome. Re-reading after every error is not the safe default: "any error might mean it went through" is false for a request that never left, so a refused credential gets its own outcome and no re-read. **The test that fails the connection** asserts the re-read request was made; a second test, a never-sent failure on the same write, asserts it was not. +A write that never left — a credential that could not be obtained (`AuthError`) or a value that would not encode (`EncodeError`) — has nothing to re-read and gets its own outcome. **The test that fails the connection** asserts the re-read request was made; a second test, a never-sent failure on the same write, asserts it was not. Write `TBD` in **Where in the code** and **The test that fails the connection** while you plan — every row. Once the code compiles, replace each `TBD` individually: the claim write, then the SDK call it precedes; the `catch`, then the re-read it makes. ⚠⚠ A `TBD` left behind, a name that is not in the code, or one note covering several rows is **not addressed**; if the code does not do what the row says, fix the code, then the cell. @@ -118,44 +129,42 @@ Logging the reason is not returning it: log it **and** put it in the response. End the contract sheet with a **REQUIRED READING** block whose rows carry inline `MUST load ` pointers. **Load every `typescript-*` skill the sheet names, now, before you start implementing** — not lazily at the step that needs it. The sheet deliberately does *not* carry the how-to: it names the hazard and hands you the skill that resolves it, so an unloaded pointer is a gap in what you know, not a formality. -**A fixed floor applies regardless of what the sheet says** — the sheet can add to it, never remove from it: `typescript-error-handling` always (every integration writes an error boundary, and this SDK's one error family is narrowed on its closed `kind`, with four throwables outside it that a family test has to rethrow); `typescript-client-initialization` before the client is constructed; `typescript-testing` before the first test file you create or edit, *including* a throwaway verification script that fakes `fetch`. A sheet row that excuses one of these ("out of scope", "no test suite requested") is not a substitute for loading it. +**A fixed floor applies regardless of what the sheet says** — the sheet can add to it, never remove from it: `typescript-error-handling` always (every integration writes an error boundary); `typescript-client-initialization` before the client is constructed; `typescript-testing` before the first test file you create or edit, *including* a throwaway verification script that fakes `fetch`. -These are API-agnostic usage skills; loading them is not a substitute for the lookup layer, and reading a file in the installed package does not remove the need to load the skill for that step. Contract *facts* still come only from your sheet or a fresh lookup. +These are API-agnostic usage skills; loading them is not a substitute for the lookup layer, and reading a file in the installed package does not remove the need to load the skill for that step. Before implementing, check the plan's **Assumptions & Blockers** section: -- Blocker or major assumption → surface it to the user in plain language, get their answer, and revise `spotify-web-api-plan.md` in place. +- Blocker or major assumption → surface it to the user in plain language, get their answer, and send it to the SAME planner as a follow-up message (re-start it, carrying the clarification and the plan path, only where your host cannot message it). It revises `spotify-web-api-plan.md` in place and replies with the changed rows verbatim: work from that reply, not a re-read of the file. If you wrote the plan yourself, revise it in place. - Minor assumptions only → proceed. Full re-planning only on genuine scope change; for a single missing fact mid-implementation, do the lookup, never guess. ### Step 2 — Implement from the contract sheet -1. Read `spotify-web-api-plan.md` once. Treat its contracts as authoritative — do not re-derive or "double-check" them from memory. When a lookup revises a row, update the file so the sheet and the code never disagree. -2. **Decide which environment this deployment talks to, explicitly, before the first call.** Constructing the client with no options selects `ServerEnvironment.Production` **silently**, so an unset field is indistinguishable from a deliberate choice of the default. Bind it to configuration and fail startup if the (environment, credential) pair is not the one this deployment intends — a credential pointed at the wrong host is not a defect any call site can correct. -3. **Build the client once and hold it.** Resources are memoized lazy getters on it and the OAuth 2 token cache lives on it, so rebuilding one per request throws that state away. There is no `close()` — it owns a `fetch`, not a pool. -4. **Pick the response mode per call, deliberately.** Every operation returns `ApiPromise`: `await` it and an error status rejects, or call `.asApiResult()` **on the value the operation returned** for the non-throwing `ApiResult` — the only way to see the status and headers of a *success*, and therefore the only way to observe anything at all from the **43 operations that resolve to `undefined`** (every operation whose success declares no body — the map's **Returns** bullet names them). `ApiPromise` overrides `Symbol.species`, so `.then()`/`.catch()`/`.finally()` hand back a plain `Promise` with the method gone — the mode is chosen at write time, never retrofitted. -5. Implement sequentially, following the repo's own conventions and layering. You loaded the companion skills the sheet named in Step 1c — implement each step in line with the one that governs it. Take every contract *fact* (signatures, field names, channels, error arms, enum members) from the contract sheet or a fresh lookup — never re-derive one from a companion. -6. After every change: run the project's **type checker** (`tsc --noEmit`) as well as its tests. The package ships its own types and is generated under strict TypeScript, so a type error against it is a real contract violation, not noise — it is the compile-time backstop the whole map-first discipline leans on. **Treat a clean type check as the gate you do not skip.** If the project has no type check configured, run `tsc --noEmit` over the files you touched; if you genuinely cannot, say so in your final report rather than silently substituting a smoke run. Fix non-SDK errors yourself. -7. **Any error involving an SDK type or member** — `TS2339` (property does not exist), `TS2345`/`TS2322` (argument or assignment mismatch), `TS2551` (did you mean), `TS2307` (cannot find module — usually a deep import), `TS2739`/`TS2741` (missing required members), or an unexpected rejection at runtime — → go back to `typescript-getting-started`'s map section and file table, and read the one page or file that owns the fact. Do not attempt more than one self-fix of an SDK-name error before doing that lookup: rewriting from the same knowledge that produced the error is guessing. Remember which failures are **not** `ApiError`: a malformed body is `DecodeError`, a value that would not encode `EncodeError`, a dropped connection `ConnectionError`, an attempt's timeout `TimeoutError` (both only after any retries are spent), a credential that could not be **obtained** `AuthError` — every one of them in the `SpotifyWebApiError` family, told apart by `err.kind` — and an unknown `serverEnvironment` throws `ConfigurationError` out of the client constructor, before any call exists. So an exception that does not look like an API error may still be one of the SDK's failure kinds. +1. Read `spotify-web-api-plan.md` once and treat its contracts as authoritative. When a lookup revises a row, update the file so the sheet and the code never disagree. +2. **Decide which host this deployment talks to, explicitly, before the first call.** Nothing in the options records **which** deployment a base-URL override is, so bind it to configuration and fail startup if the (host, credential) pair is not the one this deployment intends. +3. **Build the client once and hold it.** Resources are memoized lazy getters on it and the OAuth 2 token cache lives on it, so rebuilding one per request throws that state away. +4. **Pick the response mode per call, deliberately.** Every operation returns `ApiPromise`: `await` it and an error status rejects, or call `.asApiResult()` on the value the operation returned for the non-throwing `ApiResult` — the only way to see the status and headers of a *success*, and therefore the only way to observe anything at all from the **43 operations that resolve to `undefined`** (every operation whose success declares no body — the map's **Returns** bullet names them). `typescript-calling-endpoints` has the mechanics. No operation is paged. +5. Implement sequentially, following the repo's own conventions and layering and the companion skill that governs each step. +6. After every change: run the project's **type checker** (`tsc --noEmit`) as well as its tests. The package ships its own types, so a type error against it is a real contract violation, not noise — it is the compile-time backstop the whole map-first discipline leans on. **Treat a clean type check as the gate you do not skip.** If the project has no type check configured, run `tsc --noEmit` over the files you touched; if you genuinely cannot, say so in your final report rather than silently substituting a smoke run. Fix non-SDK errors yourself. +7. **Any error involving an SDK type or member** — `TS2339` (property does not exist), `TS2345`/`TS2322` (argument or assignment mismatch), `TS2551` (did you mean), `TS2307` (cannot find module — usually a deep import), `TS2739`/`TS2741` (missing required members), or an unexpected rejection at runtime — → go back to `typescript-getting-started`'s map section and file table, and read the one page or file that owns the fact. Do not attempt more than one self-fix of an SDK-name error before doing that lookup: rewriting from the same knowledge that produced the error is guessing. A failure that is not an `ApiError` — `DecodeError`, `EncodeError`, `ConnectionError`, `TimeoutError`, `AuthError` — is still in the `SpotifyWebApiError` family, told apart by `err.kind` (`typescript-error-handling`). 8. Once the code is complete, open each member the **DUPLICATE CLAIMS** and **UNKNOWN OUTCOMES** rows name and confirm it runs when that write runs. Where the code falls short of a row, fix the code, not the row. -9. **Observability and sensitive data.** Logging is **off by default** and is configured through `ClientOptions.logging`: say whether the integration turns it on, at what level, and which correlation id from the provider's error bodies reaches your own logs. A JSON request body is logged **verbatim** when `logRequestBody` is on, and a form body is masked only by deny-list, so a key you have not listed prints in the clear. If the scope carries data you would not want in a log — each request model's declaring file lists every field in scope — `logRequestBody` stays off, no call on those paths passes a per-call level, which turns the body on, **and** `ClientOptions.logging.level` is set explicitly, so the `SPOTIFY_WEB_API_CLIENT_LOG` environment variable cannot switch logging on from outside the code (see `typescript-getting-started`). +9. **Observability and sensitive data.** Logging is **off by default** and is configured through `ClientOptions.logging`: say whether the integration turns it on, at what level, and which correlation id from the provider's error bodies reaches your own logs. If the scope carries data you would not want in a log, follow the **Sensitive data** rules in `typescript-getting-started`. 10. Run the project's tests; verify the integration end to end the way the task demands. Retrying is **on by default**, so if the task needs a different policy, tune it through `ClientOptions.retry` rather than wrapping the call. The SDK has no hooks or middleware, so anything the task needs there is yours to build on the `ClientOptions.fetch` seam or to deliberately omit — say which you did for both. ### Step 3 — Answering pure questions -A standalone Spotify Web API question with no code change: look it up in `typescript-getting-started` (and the map page or file its table names), then give the grounded answer, citing where it came from. When several questions arrive batched, answer them in one pass. Never answer from memory, even for "easy" questions. +A standalone Spotify Web API question with no code change: look it up in `typescript-getting-started` (and the map page or file its table names), then give the grounded answer, citing where it came from. When several questions arrive batched, answer them in one pass. ## Anti-patterns — never do these -- **Always load `typescript-getting-started` first.** It is your lookup layer, not optional background. (The `typescript-*` companions are the complement: load the ones the sheet names, per Step 1c.) Don't re-derive a contract *fact* from a companion — exact signatures, request fields, channels, error arms and enum members come from the sheet or a fresh lookup. -- **Never write any Spotify Web API or SDK fact from memory** — every signature, field name, wire header, enum member, and error arm in your code must come from the contract sheet or a lookup. And **never write a call from memory "to fix later".** -- **Never switch on an error arm tag across operations.** A tag is derived from the arm's **body schema**, never from its status: an arm whose body is a direct model reference is named after that model in lower camel (`"validationError"`), and every other body — a primitive, an array, a map, or no content — is named `"error{Status}"` (`"error400"`, `"error4XX"`, `"errorDefault"`), with a numeric suffix on the second of two arms that would otherwise land on the same name. Tags are resolved **per operation**, so the same tag covers different statuses on different operations — a shared handler keyed on `err.payload.kind` is a bug. Read the status from `err.status`, and narrow on `kind` only against the arm table of that one operation. +- **Never create or edit a project file while `spotify-web-api-planner` is running**, and never start a second one for the same integration. +- **Never write or state any Spotify Web API or SDK fact from memory** — every signature, field name, wire header, enum member, and error arm must come from the contract sheet or a fresh lookup, never from recall or from a companion skill. And **never write a call from memory "to fix later".** +- **Never switch on an error arm tag across operations.** A tag comes from the arm's **body schema**, not its status, and is resolved **per operation**, so the same tag covers different statuses on different operations — a shared handler keyed on `err.payload.kind` is a bug (`typescript-error-handling` has the naming rule). Read the status from `err.status`, and narrow on `kind` only against the arm table of that one operation. +- **Never hand-advance a paging field on a paged operation, and never leave a walk unbounded.** An operation whose **Signature** returns `Pageable` is walked with `for await` or `.pages()`: the SDK seeds the first page from the request and advances the state itself, so a loop that re-calls the operation with the next page number walks the rest of the list again on every call and repeats its items. A walk ends only when the API stops handing out pages, so it carries a bound of your own — a page cap, an item cap or a deadline. - **Don't web-search Spotify Web API topics to find an implementation detail** — the installed package's own map and source are the ground truth, and the file table tells you where to look. Public Spotify Web API docs describe the HTTP API, not this SDK's generated surface, and the two disagree on names, on which fields are required, and on what the SDK sends by default. - **Never introspect the SDK at run time to discover its shape.** `Object.keys`, logging a client instance, or a REPL poke is the TypeScript-flavoured version of decompiling the package: it answers what exists, never what is *supported*, and it invites `#`-private fields and unexported engine types into your code. Read the map, then the file it names. -- **Don't grep the package to *locate* a type** — the SDK map is the locator (and says so: *"Do not derive the path from the type name"*); grep only *inside* the file its **Type sources** table names, for the symbol. A sweep for a *shape* is a different thing, and is fine: "every field typed `unknown`", "every required-nullable member" are cross-cutting questions nothing indexes, and one targeted `grep -rn` over `src/models/` is the right tool for them — record what it found on the sheet. -- **Don't deep-import from the package** (`spotify-web-api/models/…`). The package root is the only entry and deep specifiers do not resolve; the map's `Source` paths are for reading, not importing. +- **Don't grep the package to *locate* a type, deep-import from it (`spotify-web-api/models/…`), or vendor its `src/`** — `typescript-getting-started`'s *Contract facts*, *Imports* and *Install* sections say what to do instead. - **Don't assume a name is a global.** The package root re-exports every public type, so an unaliased import shadows any same-named global for the rest of the file — check the name against the map before importing it plain. -- **Don't vendor the SDK's `src/` into the project, point `tsconfig` `paths` at a throwaway clone, or import from `dist/` directly** to make a lookup possible. Install it properly (see `typescript-getting-started`); a clone-based shortcut breaks every import the moment the clone is deleted, and it does not put the map where the lookups expect it. -- **Don't create or edit project files before the HARD GATE** in Step 1 — plan and contract sheet first, code second. diff --git a/plugins/spotify/skills/typescript/typescript-models/SKILL.md b/plugins/spotify/skills/typescript/typescript-models/SKILL.md index ca6fed29..ebf4bc57 100644 --- a/plugins/spotify/skills/typescript/typescript-models/SKILL.md +++ b/plugins/spotify/skills/typescript/typescript-models/SKILL.md @@ -1,6 +1,6 @@ --- -name: typescript-models -description: Working with models in an APIMatic-generated TypeScript SDK — building request bodies from plain object literals, required members and optional-versus-nullable fields, open enums, discriminated and undiscriminated unions, the four date codecs, and the schema companion beside every type. Load before constructing a request payload or mapping SDK models onto your own domain types. +name: "typescript-models" +description: "Load before building a request payload for an APIMatic-generated TypeScript SDK or mapping its models onto your own types — object-literal models, optional versus nullable fields, open enums, discriminated and plain unions, date codecs, bytes, unknown fields, and the schema companion beside every type." --- # Working with models in an APIMatic TypeScript SDK @@ -14,19 +14,15 @@ import { type {Model}, {model}Schema } from "{package-name}"; const body: {Model} = { {requiredField}: "..." }; ``` -**There is exactly one spelling.** No companion dict type, no builder, no factory and no static -helper: an object literal is how every model is built, at every nesting level. And **nothing is -frozen** — no property is emitted `readonly`, so a decoded response is an ordinary mutable object. -Mutating one is allowed but is not a wire operation: what you changed reaches the API only by passing -the value to an operation, or by re-encoding it yourself. +An object literal is how every model is built, at every nesting level. **Nothing is `readonly` or +frozen**: a decoded response is an ordinary mutable object, and a change reaches the API only when you +pass the value to an operation, or re-encode it yourself. -Two exports per model — the type and a `{model}Schema` value — and both come from the **package -root**; deep imports do not resolve. This skill covers the **non-obvious model shapes** that trip -integrations up. The patterns are generic across APIMatic TypeScript SDKs; take the real type and -field names from the contract sheet — the **Models** section of `sdk-map.md` and the **Type sources** -table on the operation's block in `map/operations/*.md`, both grounded in the `src/models/` the -package ships — never from a compiled `dist/`, and never from a path derived off the type name. The -`Source` column is where to **read** a shape, never what to import. +Two exports per model — the type and a `{model}Schema` value — both from the **package root** +(**typescript-client-initialization**). Take the real type and field names from the **Models** section +of `sdk-map.md` or an operation's **Type sources** table in `map/operations/*.md` — never from a +compiled `dist/`, and never from a path derived off the type name. The `Source` column is where to +**read** a shape, never what to import. > Throughout this skill, `{...}` is a placeholder for a name you take from your SDK (e.g. `{Model}`, > `{Union}`, `{Variant}`, `{Enum}`, `{package-name}`) — replace it with the concrete identifier from @@ -34,18 +30,17 @@ package ships — never from a compiled `dist/`, and never from a path derived o ## Where a model lives -| Group (as `sdk-map.md` names it) | Directory | What is emitted | +| Group (as `sdk-map.md` names it) | Directory | What it is | | --- | --- | --- | | Objects, and `allOf` (flattened) | `src/models/` | one `type` with the properties, plus its schema | | Enums (open; const companion plus schema) | `src/models/` | `as const` object + open type alias + schema | | Discriminated unions (`oneOf`) | `src/models/unions/` | union of tag-narrowed arms + dispatching schema | | Unions without a discriminant (`anyOf`) | `src/models/unions/` | a bare union type + an accepting schema | -Two consequences worth internalising. **`allOf` is flattened** into one plain object type — every -constituent's properties restated on one type, with no inheritance, no base type to assign to and -nothing recording the composition. And **an object schema that `allOf` subtypes made a polymorphic -base is emitted as a discriminated union**, not as a base type, so it lands under `unions/` too: -there is nothing to upcast to, and you narrow on the tag instead. +**`allOf` is flattened** into one plain object type — every constituent's properties on one type, with +no inheritance and no base type to assign to. **A polymorphic base** (an object that `allOf` subtypes +derive from) is a discriminated union under `unions/`, not a base type: there is nothing to upcast to, +and you narrow on the tag instead. ## Required, optional, nullable @@ -68,29 +63,27 @@ const ok: {Model} = { id: "1" }; // const also: {Model} = { id: "1", ...(label !== undefined ? { label } : {}) }; // conditional ``` -At run time an explicit `undefined` is dropped from the JSON anyway (a property with a spec default -sends its default instead, below), so that one is a type-level constraint. `null` is not: a nullable field set to `null` sends JSON `null`, which is a different +At run time an explicit `undefined` is treated as omitted anyway, so that one is a type-level +constraint. `null` is not: a nullable field set to `null` sends JSON `null`, which is a different request from an absent key — the distinction that matters on a PATCH. -**A model property with a spec default is optional in the type and `s.defaulted(...)` in its schema.** -Omitting it, or passing `undefined`, still sends the default (on a partial update, send its current value +**A model property whose schema is `s.defaulted(...)` has a default.** It is optional in the type; +omitting it, or passing `undefined`, still sends the default (on a partial update, send its current value instead), and a response that omits it reads back as the default. ### Reading one back -An absent optional is simply `undefined` (one with a spec default reads back that default) — there -is no sentinel value to import and nothing to -compare against, so `?.` and `??` are the whole toolkit, and, on a property without a spec default, `!== undefined` is the precise test when -"present but empty" and "absent" are different facts. Under `noUncheckedIndexedAccess` an array index -is `T | undefined` too, so guard `items[0]` before reaching through it. +An absent optional is simply `undefined` — there is no sentinel value to import and nothing to +compare against, so `?.` and `??` are the whole toolkit, and, on a property with no default, +`!== undefined` is the precise test when "present but empty" and "absent" are different facts. Under +`noUncheckedIndexedAccess` an array index is `T | undefined` too, so guard `items[0]` before reaching +through it. -⚠ **A response type whose spec marks nothing required decodes an empty body without complaint** — -every property reads back `undefined`, or its default, and nothing throws. A truncated or partial body is therefore -not an error, it is a model full of `undefined`; check the properties you actually depend on. A -property that is required on a request type and optional on the response type is normal and -intentional — two schemas for one concept — so never infer the response shape from the request shape. -Both are in the map: the operation's **Fields** table for the request, the **Type sources** file for -the response. +⚠ **A response type with no required properties decodes an empty or truncated body without +complaint** — every property reads `undefined`, or its default, and nothing throws; check the properties +you depend on. Request and response types for one concept can differ in requiredness, so never infer the +response shape from the request shape: read each from the map (the operation's **Fields** table for the +request, the **Type sources** file for the response). ## Polymorphic union types: discriminated and undiscriminated @@ -111,13 +104,10 @@ An `anyOf` becomes a bare union with nothing to switch on — `export type {Unio — and its schema tries the arms in **declaration order**, first match winning, so overlapping arms are resolved by order. -⚠ **A payload matching no arm throws.** Both kinds fail the decode — through an operation as a -`DecodeError` whose `cause` is the `SchemaError`, through a schema you call directly as the -`SchemaError` itself — an unrecognized tag has no arm to dispatch to, and an undiscriminated union that matches nothing has no -arm to fall back on. You do not get a null union or an unset variant. A provider that adds a variant -your SDK predates turns into a decode failure on a call that was previously fine, so a union field is -a place to expect regeneration pressure. See **typescript-error-handling** for where that surfaces in -a catch ladder. +⚠ **A payload matching no arm throws** — through an operation as a `DecodeError` whose `cause` is the +`SchemaError`, through a schema you call directly as the `SchemaError` itself. There is no null or +unset variant, so a variant the provider adds later breaks a call that used to work. See +**typescript-error-handling** for where that surfaces in a catch ladder. ### Construct @@ -151,8 +141,7 @@ that renamed it has the rename applied on the way out, so the type alias spells the schema names what was sent. Take the exact tag and arm names from the **Unions** table in `sdk-map.md` (`Union` · `Variants` · `Narrow with` · `Source`) rather than deriving them. -A union the spec left unconstrained degrades to `unknown`. That is the generator reporting that the -spec constrained nothing, not a bug. +A union with nothing constrained is typed `unknown`. ## Collections @@ -162,7 +151,7 @@ convert. | Value | On the wire | | --- | --- | -| omitted / `undefined` | key absent, or the spec default if it has one | +| omitted / `undefined` | key absent, or its default if it has one | | `null` on a nullable field | `null` | | `[]` | `[]` | | `{}` | `{}` | @@ -197,7 +186,7 @@ convert. money as a **`string`** scaled to the currency (`"10.00"`) — where yours does, keep it a string end to end: formatting it through `Number` and back is what silently turns `"10.10"` into `10.1`. -- **A field the spec pinned to one value** is typed as that literal and checked with +- **A field pinned to one value** is typed as that literal and checked with `s.literal(...)`: `status: "accepted"` admits that one value and nothing else, in either direction. ## Bytes @@ -210,38 +199,31 @@ const body: {Model} = { payload: new TextEncoder().encode("hello") }; const text = new TextDecoder().decode(model.payload); ``` -That is for base64-in-JSON fields only, and it is **not** the file-upload carrier. The engine does -send raw-binary and multipart bodies, but a file there is a `FileInput` — bytes the transport frames -rather than a value a schema encodes — and the two deliberately never unify: a decoded `Uint8Array` -field is not assignable to a file field, and `new Uint8Array(value)` is the one-copy bridge (see -**typescript-calling-endpoints**). +That is for base64-in-JSON fields only, and it is **not** the file-upload carrier: a raw-binary body +or multipart file takes a `FileInput` (**typescript-calling-endpoints**), and a decoded `Uint8Array` +field is not assignable to one — `new Uint8Array(value)` is the one-copy bridge. ## What the schema checks — and what it does not -Model schemas are built on `zod/v4-mini`, and what they verify is much narrower than what the API -definition said. Checked: the **primitive type** of each property, the presence of required keys, the -four date formats, base64, a pinned literal, and a union's arms. Not checked — because the generator -does not transcribe these at all, so there is no attribute to read and no validator to invoke: +Checked by an operation, in both directions: the **primitive type** of each property, the presence of +required keys, the four date formats, base64, a pinned literal, and a union's arms. **Never checked by +an operation**: - **String formats.** A uuid, email, uri, hostname, ip, password, json-pointer, regex-constrained - string and a bare `time` are all emitted as plain `string` with `s.string()`. Nothing validates the - shape in either direction: an email field accepts `"not an email"` and sends it. -- **Bounds and lengths.** No `minLength`, `maxLength`, `minimum`, `maximum`, `multipleOf`, - `uniqueItems` or `pattern` reaches the generated code. -- **`additionalProperties: false`.** Not enforced; see *Unknown / future fields* below. - -The provider is therefore the only enforcer of those, and it enforces them as a `400` you have to -interpret. Where you want a client-side guard — worth it on user-supplied input before a write, where -a rejected request costs a round-trip and an error path — write it at your own boundary and read the -constraints from `api-reference.md`, which does carry the API's documented contract. - -What the schema *does* check, it checks in **both** directions: encoding runs before the request is -built, so an invalid model rejects the call with an `EncodeError` — its `cause` the `SchemaError` -naming the field — and **nothing is sent**. Read that failure as the SDK -catching your mistake at the point you made it, not as an upstream fault — the compiler catches the -shape and the schema catches the values, and between them very little reaches the network wrong. In -production, catch it at the boundary where *you* assemble a payload from external input and treat it -as a 4xx on your own API. + string and a bare `time` travel as plain `string`: an email field is sent as `"not an email"`. +- **Bounds and lengths** — `minLength`, `maxLength`, `minimum`, `maximum`, `multipleOf`, + `uniqueItems`, `pattern`. +- **`additionalProperties: false`** — see *Unknown / future fields* below. + +An operation never refuses a value for one of those; the provider does, as a `400` you have to +interpret. **`{model}Schema.validate` does check the formats, bounds and lengths the spec declares** — +see *Checking a value before you send it* below — so pass user-supplied input through it before a +write, where a rejected request costs a round-trip and an error path. `api-reference.md` carries the +documented contract either way. + +An invalid model rejects the call with `EncodeError` — its `cause` the `SchemaError` naming the field — +and **nothing is sent**. In production, catch it at the boundary where *you* assemble a payload from +external input and treat it as a 4xx on your own API. ## Enums @@ -256,14 +238,14 @@ export const {enum}Schema = s.enumOf<{Enum}>({Enum}); - **The name is a value and a type at once.** Import it *without* `type` wherever you use its members — `import { {Enum}, {enum}Schema } from "{package-name}"` — since a type-only import makes - `{Enum}.Active` a compile error. Prefer the member over the bare literal: a spec change that + `{Enum}.Active` a compile error. Prefer the member over the bare literal: an SDK update that renames the value then fails to compile instead of failing in production. - **The type is open.** The `(string & {})` tail — `(number & {})` on a number enum — means any value of the base type is assignable. - **The schema validates the base type only, never membership.** A string enum accepts any string, a - number enum any number, so a value the provider added after generation round-trips instead of - throwing. That is deliberate, and it is why a `switch` over a **received** enum value needs a - `default` arm — the opposite of a discriminated union, whose unrecognized tag does throw. + number enum any number, so a value newer than the SDK round-trips instead of throwing. That is + deliberate, and it is why a `switch` over a **received** enum value needs a `default` arm — the + opposite of a discriminated union, whose unrecognized tag does throw. ```ts if ({enum}Schema.values.includes(received)) { /* a member this SDK knows */ } @@ -296,29 +278,27 @@ divergences are listed once, in the **Wire-name divergences** table in `sdk-map. ## Unknown / future fields -Model schemas are built on a **loose** object, so keys the model does not declare are **kept**, not -stripped, in both directions — a field the provider added after this SDK was generated survives -decoding and round-trips back out on encode. `additionalProperties: false` changes nothing about -this. - -There is no typed bag to read them from, though, and no member on the type: +A model whose spec schema is open — `additionalProperties` absent, `true`, or a schema — keeps the +keys it does not declare in one optional field, `additionalProperties?: Record`. `T` is +`JsonValue` when the spec gave no value schema, otherwise the declared type, and each value is +validated against it. The field is present only when the wire carried an extra, and its keys are +**wire** names — nothing maps the casing here: ```ts -// Decoding: the key is on the object but not in the type. -const extra = (model as Record)["x_experimental"]; - -// Encoding: extra keys on a value you pass are sent. Excess-property checking catches them on a -// fresh object literal, but not on a value that arrived through a variable. +const extra = model.additionalProperties?.x_experimental; ``` -The keys are **wire names** — there is no property, so nothing maps the casing for you here. And a -field you depend on that has no typed property is a regeneration signal: prefer regenerating the SDK -from a spec that describes it over building program logic on stringly-typed lookups. +On the way out, extras you write into the record are sent beside the declared fields; a value that +is not a `T`, or a key the model already declares, is an `EncodeError` before any request is sent. +Read the field's name off the model: a spec that declares its own `additionalProperties` property +keeps it, and the record is `additionalProperties2`. A model whose spec says +`additionalProperties: false` has no record, yet an unknown key on it still passes through both +directions, invisible to the type. -The same symmetry is a debugging trap on the way out: a **misspelled** property is not an error -either, it is an extra key that gets sent and ignored. So when a value you set is not taking effect, -check the spelling against the type before suspecting the API — excess-property checking only catches -it on a fresh object literal, never on a value that reached the call through a variable. +A **misspelled** property is not an error either: it is an extra key that is sent and ignored. +Excess-property checking catches it only on a fresh object literal, never on a value that reached the +call through a variable — so when a value you set is not taking effect, check the spelling against +the type before suspecting the API. ## The schema companion @@ -333,7 +313,36 @@ const back = {model}Schema.decode(JSON.parse(JSON.stringify(wire))); Both directions throw `SchemaError` on mismatch and produce nothing partial. Using a schema on inbound data the SDK did not hand you — a webhook body, a queue message, a cached blob — is the -intended use, and gives you exactly the validation the SDK applies to a response. +intended use. For a model whose spec declares value constraints it is stricter than a response, not +the same: `{model}Schema` enforces them on `decode` as it does on `encode`, while an operation +decodes through the structural twin, so a payload that breaks a `pattern` or a bound passes through +an operation and throws here. Catch `SchemaError` on that path if a payload the service already +accepted should not be dropped for a constraint. + +### Checking a value before you send it + +```ts +const result = {model}Schema.validate(model); +if (!result.success) { + // "name: Invalid input; dispatch.lockerCode: expected regex format" + console.error(result.message); +} +``` + +`validate` runs `encode`'s rules without the conversion and without the throw, and is the **only** +place a value constraint the spec declares (`minLength`, `pattern`, `minimum`, `uniqueItems`, a +checked `format`, …) is applied — a keyword on an array's `items` or a map's +`additionalProperties` included, checked on each item or value and reported under its index or +key (`tags.0`, `attributes.carrier`). An operation never applies one: it sends and receives +through a structural twin, `{model}InternalSchema`, so a value the service would accept is never +refused on the way out, and a service that is ahead of the spec is never refused on the way in. A +model that +nests a constrained one validates the nested value too and reports its fields under their full +path. + +An operation whose request fields carry constraints of their own exports +`{Group}.{operation}RequestSchema` beside its request type, and that schema's `validate` does apply +them: pass the request object to it before the call (**typescript-calling-endpoints**). Do **not** `JSON.stringify` a model directly for storage, or hand a raw model to anything that will encode it — a web framework's response serializer, a cache, a queue. `JSON.stringify` writes @@ -349,3 +358,4 @@ schema surface, and the failures each date codec produces. - Pass models to an operation → **typescript-calling-endpoints** - `SchemaError`, and the `DecodeError` or `EncodeError` it arrives on → **typescript-error-handling** + diff --git a/plugins/spotify/skills/typescript/typescript-models/reference.md b/plugins/spotify/skills/typescript/typescript-models/reference.md index e6dc98c6..5c881b1a 100644 --- a/plugins/spotify/skills/typescript/typescript-models/reference.md +++ b/plugins/spotify/skills/typescript/typescript-models/reference.md @@ -1,49 +1,27 @@ # Models reference (APIMatic TypeScript) -Condensed reference for the shapes in **typescript-models**. The schema combinators live in -`src/core/validation/` — vendored static code, identical in every generated TypeScript SDK — and are -reached through the `s` namespace inside generated model modules. `s` re-exports `zod/v4-mini` -(`string`, `number`, `boolean`, `array`, `record`, `union`, `nullable`, `optional`, `literal`, -`unknown`) plus the SDK's own entries (`object`, `enumOf`, `discriminatedUnion`, `of`, `lazy`, -`optionalNullable`, `defaulted`, `dateTime`, `rfc1123DateTime`, `unixSecondsDateTime`, `dateOnly`, `bytes`). +Lookup tables beside **typescript-models**, which carries the rules. Model modules build their +schemas from the `s` namespace (`src/core/validation/`, the same in every APIMatic TypeScript SDK): +`zod/v4-mini`'s `string`, `number`, `boolean`, `array`, `record`, `union`, `nullable`, `optional`, +`literal`, `unknown`, plus the SDK's `object`, `enumOf`, `discriminatedUnion`, `of`, `lazy`, +`optionalNullable`, `defaulted`, `dateTime`, `rfc1123DateTime`, `unixSecondsDateTime`, `dateOnly` and +`bytes`. Confirm concrete type and field names in `src/models/`. -## The two exports per model - -```ts -import { type {Model}, {model}Schema } from "{package-name}"; -``` - -One `type` and one schema value, both re-exported from the package root. Take the pair from an -operation's **Type sources** table (`Type` · `Schema value` · `Source`) in `map/operations/*.md`, or -from the **Models** section of `sdk-map.md`. The type-name-to-path transform is not reversible, so do -not guess the path. - -**An enum is the exception to the `type` import.** Its name is a value *and* a type, so -`import { {Enum}, {enum}Schema }` — with `type`, `{Enum}.Active` does not compile. Every other model -type carries no runtime value, so under `verbatimModuleSyntax` it must be imported as -`import { type {Model} }` or `import type { {Model} }`; the schema const is always a value import. - -The package ships `dist` (with declaration files), `src`, `README.md`, `api-reference.md`, -`sdk-map.md` and `map`, so the readable TypeScript and the contract sheets are all inside -`node_modules/{package-name}/`. - -No property is emitted `readonly` and no model is frozen: a decoded response is a plain mutable -object, and mutating it changes nothing on the wire by itself. - ## Spec kind to TypeScript type | API definition kind | Model type | Schema entry | | --- | --- | --- | -| string, password, regex-constrained, email, uri, ip, hostname, json-pointer, uuid | `string` | `s.string()` — **format unchecked** | -| `time` | `string` | `s.string()` — unchecked | +| string, password, uuid, regex-constrained | `string` | `s.string()` | +| email, uri, ip, hostname, json-pointer | `string` | `s.string()` — the format is a value check, see *Deriving a changed copy* | +| `time` | `string` | `s.string()` | | `date` | `string` | `s.dateOnly()` | | `date-time` (ISO 8601 / RFC 1123 / unix) | `Date` | `s.dateTime()` / `s.rfc1123DateTime()` / `s.unixSecondsDateTime()` | | int32, int64 | `number` | `s.int()` | | float, double, big-decimal | `number` | `s.float64()` | | boolean | `boolean` | `s.boolean()` | | binary, file — as a declared field | `Uint8Array` | `s.bytes()` (base64) | -| a value the spec fixed | that literal type | `s.literal(value)` | +| a pinned value | that literal type | `s.literal(value)` | | free-form object | `Record` | `s.record(s.string(), s.unknown())` | | array of `T` | `T[]` | `s.array(...)` | | map of `T` | `Record` | `s.record(s.string(), ...)` | @@ -53,66 +31,58 @@ object, and mutating it changes nothing on the wire by itself. Nullability folds onto whatever the row produced: `T | null` with `s.nullable(...)`. It is never folded onto `unknown`, which already admits `null`. +A value constraint the spec declares on a row — a length, a pattern, a checked format, a numeric +bound — never changes the type; where it is enforced is stated under *Deriving a changed copy*. + ## Field declaration cheat sheet | Declared | Schema entry | Building it | | --- | --- | --- | | `f: T` | the entry itself | always provide | | `f?: T` | `s.optional(...)` | **omit the key** (not `f: undefined`) | -| `f?: T` | `s.defaulted(...)` | omitting it sends the spec default; set the value you mean | +| `f?: T` | `s.defaulted(...)` | omitting it sends its default; set the value you mean | | `f: T \| null` | `s.nullable(...)` | provide `null` to send JSON `null` | | `f?: T \| null` | `s.optionalNullable(...)` | omit, or provide `null` | -```ts -// Conditional optional field, exactOptionalPropertyTypes-safe: -const body: {Model} = { id, ...(note !== undefined ? { note } : {}) }; -``` - -Run time is more forgiving than the type system — an explicit `undefined` is dropped from the JSON, except where a spec default is sent instead — -but do not rely on it: the SDK's own tsconfig sets `exactOptionalPropertyTypes` (and -`verbatimModuleSyntax`, `noUncheckedIndexedAccess`, `strict`), and a consumer that does the same will -not compile. - -`s.defaulted(entry, value)` marks a model property or a request field with a spec default; the SDK fills -the default on encode and decode. - ## Deriving a changed copy ```ts const updated = { ...model, {field}: "..." }; ``` -Nothing validates a spread — the schema runs when you pass the value to an operation or call `encode` -yourself, and that is where a bad value surfaces. The copy is **shallow**: nested models and arrays -are shared with the original, so mutating one mutates both. Undeclared keys the source carried are -copied along, which is what keeps a read-modify-write round-trip from dropping server-side state the -SDK does not model. - -## Reading a response model - -- **An absent optional is `undefined`**, unless it has a spec default. No sentinel, no wrapper, so `?.` / `??` are enough, and, - without a default, `!== undefined` is the precise test where "absent" and "present but empty" differ. -- **A response type whose spec marks nothing required accepts `{}`.** `{model}Schema.decode({})` - succeeds and every property is `undefined` or its default; a truncated body raises nothing. Check the properties - you depend on. -- **Required on the request, optional on the response is normal.** Two schemas, one concept — read - each from its own place in the map rather than assuming they match. -- Under `noUncheckedIndexedAccess`, `items[0]` is `T | undefined`; guard it before reaching through. -- An undeclared key that arrived on the wire is on the object but not in the type — reach it with a - widening cast, and only when you must. +Nothing validates a spread — the shape is checked when you pass the value to an operation or call +`encode` yourself, and that is where a wrong type surfaces. A value constraint the spec declares +(`minLength`, `pattern`, `minimum`, a checked `format`, …) is **not** checked by an operation; +`{model}Schema` checks it — `validate(value)` reports it, `encode` and `decode` throw on it. The copy +is **shallow**: nested models and arrays are shared with the original, so mutating one mutates both. +Undeclared keys the source carried are copied along, which is what keeps a read-modify-write +round-trip from dropping server-side state the SDK does not model. ## Schema surface ```ts type Schema> = { - readonly decode: (value: unknown) => T; // wire shape -> model - readonly encode: (value: unknown) => W; // model shape -> wire + readonly decode: (value: unknown) => T; // wire shape -> model + encode(value: T): W; // model shape -> wire + validate(value: T): ValidationResult; // encode's rules, no conversion, no throw }; +type ValidationResult = { success: true } | { success: false; message: string }; + type EnumSchema = Schema & { readonly values: readonly T[] }; ``` -`Schema`, `EnumSchema` and `Encoded` are re-exported from the package root as types. +`Schema`, `EnumSchema`, `Encoded` and `ValidationResult` are re-exported from the package root as +types. + +`validate` runs the same rules `encode` runs and reports instead of throwing: `message` lists every +failing field with its reason (`code: expected regex format; attributes: must have at most 10 +properties`), the same list a `SchemaError` from `encode` carries after its leading sentence. On a +model whose spec declares value constraints, `{model}Schema` enforces them and `validate` is how you +check a value before sending it; the operations encode and decode through a structural twin, +`{model}InternalSchema`, exported from the model's module but not from the package root, so a +constraint is never applied on the way out or on the way in. On every other model `validate` checks +shape alone. `Encoded` — the wire projection: @@ -124,228 +94,33 @@ type EnumSchema = Schema & { readonly values: readonly T[] }; | object | each property projected | | anything else | itself | -Both directions throw `SchemaError` on mismatch and produce nothing partial. The message is prefixed -`Wire value could not be decoded.` or `Type could not be encoded for the wire.`, followed by -`path: expected X, received T` per issue — `T` the type that arrived, never the value (`` -where there is no path). It keeps no copy of the offending value; `.cause` is the underlying zod error -with the structured issue list. Through an operation it arrives one level down, on the `cause` of a -`DecodeError` or an `EncodeError`. Request encoding runs before the HTTP call, so an encode failure -means **nothing was sent**. - -## Key renaming - -The `_keysMap` entry inside a generated `s.object({ ... })` literal maps TypeScript property names -to wire keys, and is applied on decode and encode both. Only properties that moved appear: - -```ts -export const {model}Schema = s.object<{Model}>({ - createdAt: s.dateTime(), - isActive: s.optional(s.boolean()), - _keysMap: { createdAt: "created_at", isActive: "is_active" }, -}); -``` - -You never write wire keys. Reach for `_keysMap` — or the **Wire-name divergences** table in -`sdk-map.md` — only when reading a captured HTTP body. +A `SchemaError` message is prefixed `Wire value could not be decoded.` or `Type could not be encoded +for the wire.`, followed by `path: expected X` per issue — `X` the type, format or set of values the +schema expected; neither the value nor its type is named (`` where there is no path). `.cause` +is the underlying zod error with the structured issue list. ## Enums -```ts -export const {Enum} = { Active: "active", Retired: "retired" } as const; -export type {Enum} = (typeof {Enum})[keyof typeof {Enum}] | (string & {}); -export const {enum}Schema = s.enumOf<{Enum}>({Enum}); -``` - -| Property | Behaviour | -| --- | --- | -| Type | **open** — the `(string & {})` / `(number & {})` tail admits any value of the base type | -| Wire value | the member's value, verbatim (`"active"`, or `1` for a number enum) | -| Decoding | checks the **base type only** — `s.enumOf` builds a string or a number check from the members and validates nothing else, so an unknown member is accepted | -| Known set | `{enum}Schema.values` — `readonly {Enum}[]`, in declaration order | -| Member names | generated identifiers; a number enum's members are `_0`, `_1`, … | - -```ts -import { {Enum}, {enum}Schema } from "{package-name}"; - -body.status = {Enum}.Active; // preferred -body.status = "active"; // compiles, but survives a rename -const known = {enum}Schema.values.includes(fromServer); // runtime membership test -``` - -Because unknown members decode, a `switch` over a received enum value **needs a `default` arm**, and -an `if`/`else if` chain over the members with no final `else` silently does nothing for a value newer -than the SDK. - -There is **no coercion helper** — no `fromValue`, no closed lookup that raises — because a member *is* -its wire value: - -```ts -{Enum}.Active === "active"; // true -`${{Enum}.Active}`; // "active" — safe in a log line, a URL, a query string -type Known = (typeof {Enum})[keyof typeof {Enum}]; // the closed set, at type level -``` - -Mapping an SDK enum onto your own, tolerating the open arm: - -```ts -function toDomain(value: {Enum}): MyEnum { - switch (value) { - case {Enum}.Active: return MyEnum.A; - case {Enum}.Retired: return MyEnum.B; - default: return MyEnum.Unknown; // covers values newer than this SDK - } -} -``` - -## Discriminated unions (`oneOf`, and a polymorphic base) - -```ts -// src/models/unions/{union}.ts -export type {Union} = ({ArmA} & { {tag}: "a" }) | ({ArmB} & { {tag}: "b" }); - -export const {union}Schema = s.discriminatedUnion<{Union}>("{wire_tag}", { - a: {armA}Schema, - b: {armB}Schema, -}); -``` - -- The arms are the variant types **intersected with the tag literal**; the variant type itself does - not declare the tag, so a value typed `{ArmA}` is not assignable to `{Union}`. -- **Narrow with `switch` on the tag.** The arms are exhaustive, so no fallback arm is needed. -- **Build by writing the arm's literal, tag included** — the schema writes the tag onto the wire from - the value you pass, and dispatches on it when decoding. -- The schema's key is the **wire** discriminator and each entry's key is the wire tag **value**. The - tag name on the **decoded** object can differ, where a variant renamed the discriminator; the type - alias spells what arrives. -- A polymorphic base (an object schema that `allOf` subtypes with a discriminator derive from) is - emitted here **as a discriminated union**, not as a base type. There is nothing to upcast to. -- ⚠ A tag matching no arm is a decode failure — a `SchemaError`, on a `DecodeError`'s `cause` through - an operation — not an unset variant. - -```ts -switch (value.{tag}) { - case "a": return handleA(value); // narrowed to the {ArmA} arm - case "b": return handleB(value); -} -``` - -## Undiscriminated unions (`anyOf`) - -```ts -export type {Union} = string | {Model}; -export const {union}Schema = s.of<{Union}>(s.union([s.string(), s.lazy(() => {model}Schema)])); -``` - -- Nothing narrows the arms — use `typeof`, `in`, or `Array.isArray`. -- Decoding accepts a value matching **any** arm, and **the first match in declaration order wins**, - so overlapping arms resolve by order. -- Build by passing a value of any arm directly. There is no wrapper and no factory. -- A union the spec left unconstrained degrades to `unknown`. -- ⚠ A value matching no arm is a decode failure — a `SchemaError`, on a `DecodeError`'s `cause` - through an operation. +An `if`/`else if` chain over the members with no final `else` silently does nothing for a value newer +than the SDK. `type Known = (typeof {Enum})[keyof typeof {Enum}]` is the closed set at type level. ## Dates -| Schema | Model type | Wire | Notes | -| --- | --- | --- | --- | -| `s.dateTime()` | `Date` | `"2024-06-17T15:30:00Z"` | ISO 8601, **offset required**; encodes via `toISOString()` | -| `s.rfc1123DateTime()` | `Date` | `"Mon, 17 Jun 2024 15:30:00 GMT"` | strict IMF-fixdate (two-digit day, `GMT`); encodes via `toUTCString()` | -| `s.unixSecondsDateTime()` | `Date` | `1718638200` | epoch **seconds**; a numeric string also decodes; encodes floored to whole seconds | -| `s.dateOnly()` | `string` | `"2024-06-17"` | a **string**, not a `Date`; the `YYYY-MM-DD` shape is checked | - -```ts -body.createdAt = new Date("2024-06-17T15:30:00Z"); // Date-typed fields -body.birthDate = "1990-04-02"; // dateOnly field — a string -``` +- `s.dateTime()` requires an offset on decode; encodes via `toISOString()`. +- `s.rfc1123DateTime()` is strict IMF-fixdate (two-digit day, `GMT`); encodes via `toUTCString()`. +- `s.unixSecondsDateTime()` also decodes a numeric string; encodes floored to whole seconds. +- `s.dateOnly()` checks the `YYYY-MM-DD` shape. `s.bytes()` rejects non-base64 input on decode. Failures to expect: -- `"2024-06-17"` into an `s.dateTime()` field → `SchemaError` (date-only, no offset). -- `"2024-06-17T15:30:00"` into an `s.dateTime()` field → `SchemaError` (no offset). +- `"2024-06-17"` or `"2024-06-17T15:30:00"` into an `s.dateTime()` field → `SchemaError` (no offset). - `"Mon, 7 Jun 2024 15:30:00 GMT"` into `s.rfc1123DateTime()` → `SchemaError` (day must be two digits). - Epoch **milliseconds** into `s.unixSecondsDateTime()` → no error; it decodes to a date ~50,000 years out. Divide by 1000, or pass a `Date`. -Read the field's combinator in `src/models/{model}.ts` to know which applies — the `Date` type alone -does not say. - -## Bytes - -```ts -// Field declared: payload: Uint8Array (schema: s.bytes()) -body.payload = new TextEncoder().encode("hello"); // encoded to base64 on the wire -const text = new TextDecoder().decode(model.payload); // decoded from base64 for you -``` - -Base64-in-JSON fields only. Non-base64 input fails on decode. This is not the file-upload carrier: -a raw-binary body and a multipart file part both take a `FileInput`, which is framed rather than -encoded, and a decoded `Uint8Array` is deliberately not assignable to one. - -## Collections - -| Field | Type | Pass | -| --- | --- | --- | -| array | `T[]` | a plain array | -| map / free-form object | `Record` | a plain object | -| unconstrained value | `unknown` | anything; nothing is checked | - -| Value | On the wire | -| --- | --- | -| omitted / `undefined` | key absent, or the spec default if it has one | -| `null` on a nullable field | `null` | -| `[]` | `[]` | -| `{}` | `{}` | - ## Recursive and self-referential models -Generated schemas wrap a reference that nests inside another validator in `s.lazy(() => otherSchema)`, -so a model that refers to itself (a tree node, a nested comment) works with no special handling. -Nothing is required of you; the type is just a normal recursive `type`. - -## Undeclared keys (passthrough) - -Model schemas are built on a **loose** object, so undeclared keys survive both directions: - -```ts -// Decoding: an undeclared response key is on the object but not in the type. -const extra = (model as Record)["x_experimental"]; - -// Encoding: extra keys on a value you pass are sent. -// (Excess-property checking catches this on a fresh literal, not on a variable.) -``` - -There is no typed `additionalProperties` bag, and `additionalProperties: false` is not enforced — it -has no visible effect at all. A key you need but the type lacks means the spec does not describe it. - -## What is never validated - -`s.string()` carries no format check and no length or pattern check; `s.int()` and -`s.float64()` carry no `minimum`, `maximum` or `multipleOf` check; arrays carry no `uniqueItems` check. -The generator does not transcribe those -constraints, so there is nothing to read and nothing to invoke — they are enforced only by the -provider, as a `400`. `api-reference.md` carries the documented contract; put your own guard at your -own boundary if you want one before the round-trip. - -## Round-tripping - -```ts -const wire = {model}Schema.encode(model); // wire-shaped plain object -const json = JSON.stringify(wire); -const back = {model}Schema.decode(JSON.parse(json)); -``` - -`JSON.stringify(model)` directly is **not** the wire shape: - -| Model value | Through `encode` | Through `JSON.stringify` directly | -| --- | --- | --- | -| a renamed property | the wire key | the TypeScript key | -| a `Date` on an RFC-1123 or unix-seconds field | that field's format | an ISO string — wrong format | -| a `Uint8Array` | base64 `string` | `{"0":104,"1":105}` — the bytes are gone | - -So decoding a directly-stringified model fails on the renamed keys and the date formats, silently. The -same applies to handing a raw model to anything else that encodes — a framework's response -serializer, a cache, a queue: map it to your own type at the boundary, or hand out `encode`'s result. +A self-referential model (a tree node, a nested comment) needs no special handling: generated schemas +wrap a nested reference in `s.lazy(() => otherSchema)`. -Using a schema on inbound data you did not get from the SDK — a webhook body, a queue message, a -cached blob — is the intended use, and gives you the same validation the SDK applies to responses. diff --git a/plugins/spotify/skills/typescript/typescript-testing/SKILL.md b/plugins/spotify/skills/typescript/typescript-testing/SKILL.md index 2475f409..1a11d09c 100644 --- a/plugins/spotify/skills/typescript/typescript-testing/SKILL.md +++ b/plugins/spotify/skills/typescript/typescript-testing/SKILL.md @@ -1,6 +1,6 @@ --- name: typescript-testing -description: Testing code that calls an APIMatic-generated TypeScript SDK — which seam to fake (`ClientOptions.fetch`, or an interceptor at the global-fetch layer), stubbing bodies in wire shape, asserting the request the SDK actually built, covering the error and decode-failure paths, turning the on-by-default retry policy off (or testing it deliberately), and keeping tests independent of SDK internals. Load before writing tests for the integration layer. +description: Load before writing tests for code that calls an APIMatic-generated TypeScript SDK — faking `ClientOptions.fetch` or intercepting global `fetch`, wire-shaped stub bodies, asserting the request the SDK built, error, decode and auth failure paths, OAuth token stubs, paged walks, and the on-by-default retries. --- # Testing code that uses an APIMatic TypeScript SDK @@ -95,16 +95,15 @@ matters, or pass a `logger` that records its calls when the test is *about* what `Response` is global on Node 18+. Credentials can be dummy values, or omitted entirely — nothing validates them when the transport is stubbed, unless the test is *about* the credential. -**Do not mock the client, its resource classes, or reach for its internals.** `#rawClient` and the -other private fields are genuinely unreachable, and a hand-rolled double of `{Api}Client` cannot catch -the mistakes that actually happen — a wrong path parameter, a body that does not encode, a header you -forgot. Faking `fetch` exercises the real request-building pipeline; that is the whole point. Never -construct a resource class either: it is exported only for its merged namespace and for `instanceof`, -and its constructor takes engine internals that are not exported. +**Fake `fetch`, not the client.** A hand-rolled double of `{Api}Client` or a resource class (which you +cannot construct — **typescript-calling-endpoints**) cannot catch the mistakes that actually happen — a +wrong path parameter, a body that does not encode, a header you forgot; a fake `fetch` runs the real +request pipeline. -> **If your client has an OAuth 2 scheme, the first request your stub sees is the token request**, not -> your operation. See **Fake an OAuth token endpoint** below before writing the first test — a -> single-response fake fails there in a confusing way. +> **With an OAuth 2 scheme, the first request your stub sees is the token request**, not your +> operation. A single-response fake hands your operation's body to the token decoder, and the call +> fails with an `AuthError` (cause: a `DecodeError` about `access_token`) that reads like bad +> credentials. See **Fake an OAuth token endpoint** below. ## Stub bodies are in WIRE shape, not model shape @@ -130,7 +129,7 @@ expect(() => {model}Schema.decode(fixture)).not.toThrow(); // validate a hand- Prefer the first: build the fixture as a typed model and encode it, so a member rename breaks the fixture instead of passing a stale test. Validate any fixture you hand-write and reuse — it catches -fixture rot when the SDK is regenerated. Both schema consts are exported from the package root. +fixture rot when the SDK is updated. Both schema consts are exported from the package root. ## Test a success path @@ -194,9 +193,9 @@ if ("rawBody" in e.payload) expect(new TextDecoder().decode(e.payload.rawBody)). ``` **Take the arm union from the contract sheet per operation.** `"undeclared"` is reachable in Case A -too — any status the operation's matchers do not cover falls to it — so an error test copied from a -sibling operation can pass for the wrong reason, landing in the `"undeclared"` branch and asserting -nothing about the typed body you meant to check. +too — any status the operation's matchers do not cover falls to it, a spec's `default` response +being no matcher — so an error test copied from a sibling operation can pass for the wrong reason, +landing in the `"undeclared"` branch and asserting nothing about the typed body you meant to check. Use `try`/`catch` rather than a rejection matcher: matcher support for narrowing a rejected value differs between runners, and the `catch` form reads the same everywhere. @@ -225,11 +224,9 @@ it("reports the failure without throwing", async () => { }); ``` -On success the value is `outcome.value` (not `.data`), and `outcome.headers` is the only way to read -**response headers** — so this is also the mode to test in when your code depends on a header on the -*success* path. `.asApiResult()` does **not** make the call non-throwing: everything in the next -section still rejects, and it must be called on the value the operation returned, before any -`.then()`. +`outcome.headers` is the only way to read **response headers** on the *success* path, so test in this +mode when your code depends on one. Everything in *Cover the failures that are not an `ApiError`* +still rejects in this mode. ## Assert the outgoing request @@ -254,21 +251,20 @@ it("sends the right request", async () => { - **The SDK hands the fake one `Request` and no `init`.** Its `url` is absolute, so `new URL(request.url)` gives you `pathname` and `searchParams` for free rather than substring-matching a URL string. A fake that reads `init` reads nothing. -- **Header names are lowercased.** The SDK normalizes every layer — the endpoint's, the auth scheme's - and the client's defaults — before merging, which is what makes the merge case-insensitive, and - `request.headers` is a `Headers`. Read it through `request.headers.get(...)`; a plain - `request.headers["Authorization"]` is both the wrong type and the wrong case. +- **Read headers through `request.headers.get(...)`** — `request.headers` is a `Headers` with + lowercased names, so a plain `request.headers["Authorization"]` is both the wrong type and the wrong + case. - **The body is already serialized by the time the fake sees it.** The captured `body` is the request - body's **text** (or `undefined`), which is all a JSON, form-urlencoded or text body needs, and it - uses **wire aliases**, because that is what encoding produces. Assert on the parsed string; do not + body's **text** (or `undefined`), which is all a JSON, form-urlencoded or text body needs, with **wire + aliases** and wire dates, because that is what encoding produces — assert on the parsed string; do not "fix" the aliases in the test. Read a multipart or binary body back off the captured `request` instead: a multipart one with `await request.formData()`, and a binary one with `new Uint8Array(await request.arrayBuffer())` — its text is lossy. A multipart `content-type` carries a generated boundary, so match it as a prefix, never with `toBe`. Compare a file part by its contents, `await new Response(form.get("{field}")).text()`: one sent without a file name may come back as a string or a `File`. -- **A list-valued query or form parameter has a per-parameter wire style.** The `StyledParam` the - generator emitted for it in `src/resources/{resource}.ts` carries a `style`: `plain` (the default — +- **A list-valued query or form parameter has a per-parameter wire style.** Its `StyledParam` in + `src/resources/{resource}.ts` carries a `style`: `plain` (the default — `name=a&name=b`), `indexed` (`name[0]=a`, percent-encoded in the raw URL as `name%5B0%5D=a`), `unindexed` (`name[]=a`), or `csv` / `tsv` / `psv` (one joined value). Read it before asserting: @@ -290,14 +286,48 @@ Worth asserting once, somewhere, because they are silent when wrong: - **The value actually reached the wire.** Request models encode loosely too, so an extra or misspelled optional member is carried into the body rather than rejected. Only an assertion on the captured `body` catches it. -- **A body that cannot encode never reaches your fake.** Encoding happens *before* the request is - dispatched, so the call rejects with `EncodeError` and `stub.calls` stays **empty**. Same for a path - parameter left `undefined` — its schema rejects it, also as an `EncodeError`, before anything is - sent. Assert `stub.calls` is empty in those tests. -- **`retry.timeout` never rides the request.** It is a per-attempt budget in **milliseconds**, set on - the client or on one call through `RequestOptions.retry`, and it reaches the wire only as the - `Request`'s `signal`. A test asserting a timeout on a captured request is asserting something that - was never there. +- **An encode failure never reaches your fake** — a bad body and an `undefined` path parameter alike + reject with `EncodeError` and leave `stub.calls` **empty**; assert that in those tests. +- **`retry.timeout` never rides the request**; the fake sees it only as the `Request`'s `signal`. + +## Test a paged operation + +A paged operation sends one request per page, so queue one response per page and let the walk run. +`retry: { maxRetries: 0 }` keeps it to one request per page, and a queue that runs out is the signal +that a walk did not stop where you expected: + +```ts +it("walks every page", async () => { + const { client, stub } = clientReturning( + jsonResponse(200, { items: [{ id: "1" }, { id: "2" }], nextCursor: "c2" }), + jsonResponse(200, { items: [{ id: "3" }], nextCursor: null }), + ); + + const ids: string[] = []; + for await (const item of client.{resource}.{operation}({ limit: 2 })) ids.push(item.id); + + expect(ids).toEqual(["1", "2", "3"]); + expect(stub.calls).toHaveLength(2); + expect(stub.calls[1]!.url.searchParams.get("cursor")).toBe("c2"); // the SDK advanced the state +}); +``` + +Stub the stop signal the operation's strategy reads — a `null` or absent next cursor, a `hasMore` of +`false`, a page shorter than its `limit`, or an empty page — in **wire shape**, like any other body; +the operation's **Returns** bullet names the strategy and the condition that ends its walk. A `Link`-header +strategy reads the `Link` response header, and the SDK follows a link only on the client's own origin: + +```ts +new Response(JSON.stringify(body), { + status: 200, + headers: { Link: '<{baseUrl}/{path}?cursor=c2>; rel="next"' }, // the base URL the client was built with +}) +``` + +A failed page is tested like any failed call: queue an error status in the position of the page that +fails, and the walk throws `ApiError` (or the operation's own subclass) after yielding the pages before +it. Nothing is sent until a loop starts, so a test that calls the operation and never iterates asserts +that `stub.calls` is empty. ## Cover the failures that are not an `ApiError` @@ -312,9 +342,7 @@ reachable from the fake, which makes these paths genuinely testable rather than | `kind: "decode"` | return a body that violates the schema (wrong type, bad date, a non-empty `200` where `undefined` is expected) | | `kind: "encode"` | pass a request value its schema refuses — nothing reaches the fake | | `kind: "auth"` | answer the **token** request with an error status (see below) | - -A caller abort is **not** a `kind`: aborting the signal you passed in `RequestOptions` rejects with that -signal's own `reason`, outside the family. +| `kind: "pagination"` | answer a page of a `Link`-strategy walk with a next link on another origin — a `Link` header naming a host that is not the client's base URL | ```ts import { {Api}Error } from "{package-name}"; @@ -335,11 +363,9 @@ it("maps a transport failure", async () => { }); ``` -⚠ **A timeout or abort test needs a fake that honours the `Request`'s `signal`.** The SDK aborts the -signal it put on the `Request` and relies on `fetch` to settle; a fake that returns a never-resolving -promise and ignores the signal simply hangs the test until the runner kills it. What the fake rejects -with does not matter — the SDK reads the reason off its own signal — so a timeout is a `TimeoutError` -the retry loop retries, which is why the test below sets `maxRetries: 0`. +⚠ **A timeout or abort test needs a fake that honours the `Request`'s `signal`**: one that ignores it +hangs the test until the runner kills it. What the fake rejects with does not matter — a timeout is a +`TimeoutError` the retry loop retries, which is why the test below sets `maxRetries: 0`. ```ts const hangingFetch: typeof globalThis.fetch = (input, init) => @@ -356,10 +382,8 @@ it("times out", async () => { }); ``` -That is faster and more deterministic than fake timers, and it exercises the real abort path. For a -caller abort, keep the default timeout, abort your own `AbortController` passed in `RequestOptions`, and -assert the call rejects with exactly the `reason` you passed — it is not an `{Api}Error`, and it is -never retried. +A caller abort is **not** a `kind`: abort your own `AbortController` passed in `RequestOptions` and +assert the call rejects with exactly the `reason` you passed — not an `{Api}Error`, and never retried. **A decode failure bypasses *both* response modes.** A 2xx body that does not satisfy the schema rejects with `DecodeError`; `.asApiResult()` does **not** turn it into an `ok: false` result. Test that your @@ -427,7 +451,7 @@ const stub = stubFetch((url) => ); ``` -Or bypass acquisition entirely with a stub token strategy — the generator's supported injection point +Or bypass acquisition entirely with a stub token strategy — a supported extension point (**typescript-authentication**) — so the fake only ever sees your operation: ```ts @@ -449,18 +473,12 @@ needs `redirectUri` and `promptForAuthorizationCode` (e.g. `async () => "code"`) Facts that make these tests behave: -- **Forgetting the token request is the most common way a first test fails confusingly.** A - single-response fake hands your operation's body to the *token* decoder, and you get an `AuthError` - whose `cause` is a `DecodeError` about a missing `access_token` — which reads like wrong credentials - when the fake simply answered the wrong request. - The token **response** is wire-shaped (`access_token`, `token_type`, `expires_in`); the token - **request** is a `POST` with a form-urlencoded string body, and by default the client id and secret - ride in a Basic `Authorization` header rather than in that body. + request's shape is in **typescript-authentication**. - The token endpoint may live on a **different server group**, so match on the path, not the host — read the group's URL from `DEFAULT_SERVER_OPTIONS` in `src/servers.ts`. - The token is **cached on the scheme**, so only the first call fetches one: a test making two calls - against one client sees three requests, not four. Build a fresh client per test to reset it. A - missing or non-positive `expires_in` means the cached token never expires. + against one client sees three requests, not four. Build a fresh client per test to reset it. - The token request and the operation each run on their own `retry.timeout`, so a tiny timeout in an OAuth test can fire on the token request — which ends the call with a `TimeoutError` for the token endpoint, not retried unless `httpMethodsToRetry` names `POST`. @@ -480,18 +498,13 @@ agent.get("{base-origin}").intercept({ path: "{operation-path}", method: "POST" .reply(201, { id: "1" }, { headers: { "content-type": "application/json" } }); ``` -Pick one and be consistent. An interceptor asserts on real URLs and is closer to the wire; the fake -`fetch` is dependency-free, faster, and does not care what HTTP stack is underneath. Two constraints: -an interceptor works **only while no `fetch` option is supplied** — a custom `fetch` bypasses it -entirely — and the client resolves `globalThis.fetch` **in its constructor**, so patching the global -after the client is built has no effect. +Pick one approach. An interceptor sees nothing once a `fetch` option is supplied, and one that patches +`globalThis.fetch` must be installed before the client is built (**typescript-client-initialization**). ## Keeping tests independent of SDK internals -- **Never deep-import.** The package's `exports` map exposes `.` and `./package.json` and nothing else, - so `{package-name}/models/…` does not resolve at all. Everything you need — the client, the options, - every model type and its `{model}Schema`, the error classes, `ServerEnvironment` — is re-exported - from the package root. Reading a file under `src/` is for *learning* the shape, never for importing. +- **Import only from the package root** (**typescript-client-initialization**); read `src/` to learn a + shape, never to import from it. - **Never assert on an error's `message`.** An `ApiError`'s is the call and its status — `POST https://… failed with 400` — which moves whenever the base URL or the route does. It is not a contract. Assert `err.status` and the narrowed `err.payload`. @@ -515,9 +528,9 @@ const client = new {Api}Client({ }); ``` -**Override every group the test touches.** Redirecting `default` does not move a token endpoint that -lives on its own group — it will reach for the real host and the test will either fail slowly or, -worse, succeed against production. `src/servers.ts` lists the groups and their environments. +**Override every group the test touches** — a token endpoint on its own group otherwise reaches the +real host (**typescript-configuration-resilience**). `src/servers.ts` lists the groups and their +environments. Against a **live sandbox**, keep those tests separate from unit tests, skip them when credentials are absent, and never assert on ids or timestamps the provider generates: @@ -547,17 +560,10 @@ unless you mean to. `Response` needs no `content-type` header; setting one is harmless documentation. What matters is that the body parses and satisfies the schema. A binary response is the exception: its result reports `content-type` and the `content-disposition` file name, so stub them when your code reads them. -- **Matcher precedence:** an exact-status arm wins over a range or `"5XX"` wildcard arm. A test that - stubs a status covered by both is asserting the exact one. -- **A `401` invalidates the cached OAuth token and is not retried by default.** A test that stubs a - `401` sees one failed operation — and the *next* call in the same test re-fetches a token, so queue - another `tokenResponse()` for it. -- **Retries are on by default, and silent unless logging is on.** On a client built without - `retry: { maxRetries: 0 }`, a stubbed `408`, `429`, `500`, `502`, `503` or `504` — or a thrown - error — on a `GET`, `HEAD`, - `PUT` or `OPTIONS` call is fetched up to four times, across about 7 s of backoff. A queue that runs out - throws, and that throw is itself a connection failure the loop retries. When the test *is* about - your retry policy, queue one response per attempt, pass `delay: 0` so it runs at once, and count +- A stubbed `401` invalidates the cached OAuth token, so the *next* call in the same test fetches a new + one — queue another `tokenResponse()` for it. +- **Testing the retry policy itself**: drop `maxRetries: 0`, queue one response per attempt (a queue + that runs out throws, and the loop retries that as a connection failure), pass `delay: 0`, and count requests: ```ts const stub = stubFetch(queue(jsonResponse(503, {}), jsonResponse(503, {}), jsonResponse(200, { id: "1" }))); @@ -566,24 +572,12 @@ unless you mean to. await client.{resource}.{operation}({ /* ... */ }); // an operation whose method is in the gate expect(stub.calls).toHaveLength(3); ``` - A stubbed `Retry-After` header overrides `delay`, so leave it off unless the test is about it; a test - about the backoff itself wants `maxJitter: 0` and fake timers. Cover the cases that are easiest to get - wrong: a write outside the gate is sent **once**, a widened write re-sends the **same** - `Idempotency-Key` on every attempt, and an aborted request stops retrying. -- **A test environment with no global `fetch` fails in the constructor**, not on the first call — the - client throws `ConfigurationError` when it can resolve no implementation. Passing a fake avoids this entirely. -- **`instanceof` is dialect-scoped.** If the test setup loads the SDK through `require` and the code - under test through `import` (or vice versa), `instanceof` is `false` across that boundary. Narrow on - `err.kind` / `err.payload.kind` there, or fix the config to use one dialect. + A stubbed `Retry-After` overrides `delay`; a backoff test wants `maxJitter: 0` and fake timers. Worth + covering: a write outside the gate is sent **once**, a widened write re-sends the **same** + `Idempotency-Key`, and an abort stops retrying. - **Never guess a base URL.** With a fake `fetch` nothing is dialled and the host is irrelevant; if you match on URLs, take the prefix from `DEFAULT_SERVER_OPTIONS` rather than from memory — environments - differ per API, and some SDKs ship a sandbox environment that already points at localhost. + differ per API. - Mocking libraries work too — the seam is a plain function, so a `vi.fn()` / `jest.fn()` returning a `Response` satisfies it. The hand-written stub above gives you typed captured requests and ordered responses for free. -- **Keep one client across the calls of a test** as in production, so the token cache and the memoized - resource getters behave the same shape they will at runtime - (**typescript-client-initialization**). -- To look up an operation's signature, its field channels, route or error arms, take them from the - contract sheet — `map/operations/{resource}.md` inside `node_modules/{package-name}/`, which carries - all four — not the compiled `dist/`, and not memory.