api-client-development_skill

Overview

This skill covers building typed API clients from OpenAPI specs with authentication and OAuth scope handling tailored for SCAPI and similar Salesforce Commerce APIs. It shows how to generate TypeScript types, create openapi-fetch clients, inject middleware, and encapsulate tenant-specific OAuth scope logic. The goal is predictable, testable clients that keep auth details inside the SDK and out of CLI commands.

How this skill works

Generate TypeScript types from OpenAPI specs using openapi-typescript and create a client with openapi-fetch. Apply middleware for authentication and logging; when using OAuth, wrap the provided strategy with additional scopes via OAuthStrategy.withAdditionalScopes so the client supplies required scopes automatically. Provide tenant ID utilities to translate between organizationId path parameters and raw tenant IDs and to build tenant-scoped OAuth strings.

When to use it

• You need a typed HTTP client for a REST API described by an OpenAPI spec.
• APIs require tenant-specific OAuth scopes (SCAPI patterns) that should be managed by the client.
• You want consistent auth, logging, and error extraction across multiple API clients.
• You need to write unit tests that mock API responses without changing auth logic.
• CLI commands should remain simple and not manage OAuth scope details.

Best practices

• Keep OAuth scope requirements inside the client factory; expose an optional scopes override on the config.
• Use tenant ID utilities (toOrganizationId, toTenantId, buildTenantScope) to avoid inconsistent prefixes.
• Always destructure response along with error from client calls so getApiErrorMessage can produce clean messages.
• Use MSW (Mock Service Worker) to test client behavior and avoid real network calls in unit tests.
• Generate types from specs as part of the SDK package scripts and commit the generated outputs when stable.

Example use cases

• Create a Custom APIs client that injects sfcc.custom-apis plus tenant scope and returns a typed Client<paths>.
• Build a CLI command that calls createCustomApisClient and passes an OAuthStrategy instance without configuring scopes.
• Write tests that provide a mock AuthStrategy and use MSW to return deterministic API fixtures.
• Add a new SCAPI client: add spec, update generate:types, implement factory with scope injection, export, test.