speakeasy-api/skills

Overview

This skill guides implementing SDK lifecycle hooks to customize request and response behavior in Speakeasy-generated SDKs. It explains hook types, registration patterns, and practical examples for adding headers, telemetry, security signatures, and error handling. The guidance applies across languages and preserves custom hooks through SDK regeneration.

How this skill works

Hooks are small components that intercept SDK lifecycle events (init, before request creation, before send, after success, after error). You implement the appropriate interface in src/hooks/, register the hook in src/hooks/registration.ts, and the SDK will call your hook at the configured lifecycle point. Hooks can modify Request/Response objects, inject headers, sign requests, emit telemetry, or transform errors without changing generated core code.

When to use it

• Add custom headers (User-Agent, correlation IDs) to every request
• Implement telemetry, logging, or observability at the SDK level
• Add custom authentication (HMAC signing, token refresh, API key injection)
• Transform responses or errors before they reach the caller
• Configure SDK defaults during client initialization

Best practices

• Keep each hook focused on a single responsibility (auth, telemetry, user-agent)
• Clone Request/Response before reading or modifying body streams to avoid consumption
• Use fire-and-forget for non-critical telemetry to avoid blocking the request pipeline
• Register hooks in src/hooks/registration.ts; this file is preserved on regeneration
• Write unit tests for hooks using mock Request/Response and hook contexts

Example use cases

• Custom User-Agent hook that appends app name/version to outgoing requests
• Telemetry hook that sends operation metrics asynchronously without awaiting
• HMAC signing hook that adds X-Timestamp and X-Signature headers using a secret
• AfterSuccess hook that clones and inspects response.json() to emit warnings
• AfterError hook that applies retry logic or maps HTTP errors to domain errors