customize-sdk-hooks

Files (1)

• SKILL.md

SKILL.md (first lines)

# Customize SDK Hooks

## When to Use

Use this skill when you need to **add custom code logic** to the generated SDK:

- Add custom headers (User-Agent, correlation IDs) to every SDK request via code
- Implement telemetry, logging, or observability at the SDK level
- Add custom authentication logic (HMAC signatures, token refresh) that runs in SDK code
- Transform responses or errors before they reach the caller
- Implement custom request/response middleware
- User says: "SDK hooks", "add custom logic", "intercept requests with code", "HMAC signing hook", "telemetry in SDK"

**NOT for**:
- OpenAPI spec modifications (see `manage-openapi-overlays`)
- Runtime SDK client config (see `configure-sdk-options`)

## Inputs

- **Hook type**: Which lifecycle event to intercept (init, before request, after success, after error)
- **SDK language**: The target language of the generated SDK (TypeScript, Go, Python, Java, C#, Ruby, PHP, etc.)
- **Custom logic**: The behavior to inject at the hook point

## Outputs

- Hook implementation file(s) in `src/hooks/` (or language equivalent)
- Updated `src/hooks/registration.ts` to register the new hook
- The hook is preserved across SDK regenerations

## Prerequisites

- A Speakeasy-generated SDK (any supported language)
- Understanding of the SDK's request/response lifecycle
- The `src/hooks/` directory exists in the generated SDK (created by default)

## Hook Types

| Hook | When Called | Common Use Cases |
|------|-----------|-----------------|
| `SDKInitHook` | SDK client initialization | Configure defaults, validate config, set base URL |
| `BeforeCreateRequestHook` | Before the HTTP request object is created | Modify input parameters, inject defaults |
| `BeforeRequestHook` | Before the HTTP request is sent | Add headers, logging, telemetry, sign requests |
| `AfterSuccessHook` | After a successful HTTP response | Transform response, emit warnings, log metrics |
| `AfterErrorHook` | After an HTTP error response | Error transformation, retry logic, error logging |

### Hook Interfaces (TypeScript)

```typescript
// SDKInitHook
interface SDKInitHook {
  sdkInit(opts: SDKInitOptions): SDKInitOptions;
}

// BeforeCreateRequestHook
interface BeforeCreateRequestHook {
  beforeCreateRequest(hookCtx: BeforeCreateRequestHookContext, input: any): any;
}

// BeforeRequestHook
interface BeforeRequestHook {
  beforeRequest(
    hookCtx: BeforeRequestHookContext,
    request: Request
  ): Request;
}

// AfterSuccessHook
interface AfterSuccessHook {
  afterSuccess(
    hookCtx: AfterSuccessHookContext,
    response: Response
  ): Response;
}

// AfterErrorHook
interface AfterErrorHook {
  afterError(
    hookCtx: AfterErrorHookContext,
    response: Response | null,
    error: unknown
  ): { response: Response | null; error: unknown };
}
```

## Directory Structure

```
src/
  hooks/
    types.ts          # Generated - DO NOT EDIT (hook interfaces/types)
    registration.ts   # Custom - YOUR registrations (preserved on regen)
    custom_useragent.ts   # Custom - your hook implementations
    telemetry.ts          # Custom - your hook implementations
```

**Key rule**: `registration.ts` and any custom hook files you create are preserved
during SDK regeneration. The `types.ts` file is regenerated and should not be modified.

## Registration Pattern

All hooks are registered in `src/hooks/registration.ts`. This file is created once
by the generator and never overwritten. You add your hooks here:

```typescript
// src/hooks/registration.ts
import { Hooks } from "./types.js";
import { CustomUserAgentHook } from "./custom_useragent.js";
import { TelemetryHook } from "./telemetry.js";

/*
 * This file is only ever generated once on the first generation and then is free
 * to be modified. Any hooks you wish to add should be registered in the
 * initHooks function. Feel free to define them in this file or in separate files
 * in the hooks folder.
 */

export function initHooks(hooks: Hooks) {
  hooks.registerBeforeRequestHook(new CustomUserAgentHook());
  hooks.registerAfterSuccessHook(new TelemetryHook());

From speakeasy-api/sdk-generation-skills, Apache-2.0.

More from speakeasy-api/sdk-generation-skills