mixins

Files (1)

• SKILL.md

SKILL.md (first lines)

# Vovk.ts OpenAPI mixins

Mixins turn any OpenAPI 3.x spec into typed client module behaving exactly like native Vovk RPC module — same `{ params, query, body }` call shape, same client surface, same type-inference helpers (`VovkBody`, `VovkOutput`, …). Can run mixins standalone (no Next.js) as pure codegen tool.

**LLM tool exposure works out of the box.** Pass mixin modules straight to `deriveTools` — for function calling *and* for MCP. Each derived tool gets a merged `inputSchema` that is both a Standard Schema and a Standard JSON Schema, rebuilt from the mixin's OpenAPI-derived JSON Schema.

The one real difference from a procedure-backed controller: that schema's `validate` checks the `{ body, query, params }` **envelope only** — required slots present, no unknown keys — and defers slot values to execution time, where the generated client's AJV validation and the remote API enforce them. Controllers validate values up front because they carry your original Zod / Valibot / ArkType schemas.

> v3 required hand-written `createTool` wrappers for the MCP path. That is obsolete: `createTool` was removed in v4 and mixins now carry the schema MCP needs.

## Prefer the official SDK when one exists

**Recommend official client library first.** Hand-maintained SDKs like `stripe`, `@octokit/rest`, `@aws-sdk/*`, `@google-cloud/*` ship with auth flows, retries, pagination helpers, webhook signature verification, edge-case handling that generated client can't match — and track upstream API changes faster than any spec snapshot. If vendor publishes official SDK, use it.

Mixins right tool when:

- **No official SDK exists** — internal services, niche vendors, legacy APIs that only publish OpenAPI document.
- **LLM tool exposure** — `deriveTools` works directly for function calling and MCP alike (see note at top). For GitHub-style APIs `@octokit/rest` still better tool body, but mixin remains useful when third-party API has no official SDK.
- **Spec-as-source-of-truth** — internal microservices where OpenAPI doc is generated and you want client drift to surface as TypeScript error at build time.

For everything else (Stripe charges, S3 uploads, Octokit pagination), reach for official package.

## Declaring a mixin

Mixin declared as **pseudo-segment** under `outputConfig.segments.<name>.openAPIMixin`. Key (`petstore` below) becomes segment folder name in segmented-client mode. Generated module name comes from `getModuleName` (default `'api'`), not from segment key.

```ts filename="vovk.config.js"
// @ts-check
/** @type {import('vovk').VovkConfig} */
const config = {
  outputConfig: {
    imports: {
      validateOnClient: 'vovk-ajv', // optional client-side validation
    },
    segments: {
      petstore: {
        openAPIMixin: {
          source: {
            url: 'https://petstore3.swagger.io/api/v3/openapi.json',
            fallback: './.openapi-cache/petstore.json',
          },
          getModuleName: 'PetstoreAPI',
          getMethodName: 'auto',
          apiRoot: 'https://petstore3.swagger.io/api/v3',
        },
      },
    },
  },
};
export default config;
```

Run `npx vovk generate` (or keep `vovk dev` running) → mixin emitted alongside native RPC modules.

```ts
import { PetstoreAPI } from '@/client';

const pets = await PetstoreAPI.findPetsByStatus({ query: { status: 'available' } });
```

> **Import path depends on client layout.** Code samples here import from `'@/client'`: the composed client generated into `src/client` (or `client/` when the app isn't in `src/app`). Custom `composedClient.outDir` changes the path. With **segmented client**, each mixin lives in own folder named after pseudo-segment key, e.g. `@/client/petstore`. Call shape + types identical in both. See **`rpc`** skill for full comparison.

## Source variants

`source` is object — pick exactly one shape.

**`{ url, fallback? }`** — fetched at generate time. Optional `fallback` path caches last-seen spec locally; if remote URL unreachable on next generate, Vovk reads fallback. Commit fallback to keep CI green when upstream spec host is down.

```ts
source: {
  url: 'https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json',
  fallback: './.openapi-cache/github.json',
}
```

**`{ file }`** — local spec checked into repo. Both JSON + YAML accepted (Vovk sniffs by leading char: `{` / `[` → JSON, else YAML).

```ts
source: { file: './openapi/internal.yaml' }
```

**`{ object }`** — inline JS value. Useful when spec built or transformed by another tool in same project.

```ts
import spec from './openapi/internal.json' with { type: 'json' };
// ...
openAPIMixin: { source: { object: spec }, ... }
```

## Module and method naming

`getModuleName` controls JS name of generated module; `getMethodName` controls each method. Both accept preset string or function.

**Preset strings — `getModuleName`:**

| Value | Effect |
|---|---|
| `'api'` *(default)* | Every operation goes into single `api` module. |
| any other literal (e.g. `'PetstoreAPI'`) | Hard-coded single module name — useful for small third-party APIs. |

**Preset strings — `getMethodName`:**

| Value | Effect |
|---|---|
| `'camel-case-operation-id'` | Always camelCase the `operationId`. Throws if `operationId` missing. Use only when every operation has one. |
| `'auto'` *(default)* | One mode handles all cases: pass `operationId` through if already camelCase, camelCase it if snake_case, otherwise synthesize from `METHOD + path`. Safe for messy specs. |

`'auto'` is itself the auto-detecting mode — no separate layer picks between two presets. Reach for `'camel-case-operation-id'` only when you want throw-on-missing behavior; otherwise leave default. For more structured needs (splitting operations across multiple modules, custom prefixes), use function — see below.

**Function form** — receives `{ operationObject, method, path, openAPIObject }`, returns string. Use when operation IDs are structured + you want to split into multiple modules. GitHub REST API is canonical example for the technique (`issues/list-for-org` → `GithubIssuesAPI.listForOrg`) — though for actual GitHub work, prefer `@octokit/rest` over a mixin:

```ts filename="vovk.config.js"
import camelCase from 'lodash/camelCase.js';
import startCase from 'lodash/startCase.js';

openAPIMixin: {
  source: { url: '...', fallback: '...' },
  getModuleName: ({ operationObject }) => {
    const [ns] = operationObject.operationId?.split('/') ?? ['unknown'];

From finom/vovk, MIT.

More from finom/vovk