mixins

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 (jsonSchemasObjectToSingleJSONSchemaOnlySpec in packages/vovk/src/validation/json-schema-only-spec.ts, selected in packages/vovk/src/tools/derive-tools.ts when a handler has no definition).

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.

Scope

Covers:

• Declaring mixins under outputConfig.segments.<name>.openAPIMixin.
• source variants: remote URL (with fallback), local file, inline object.
• getModuleName / getMethodName — preset strategies + function form.
• apiRoot + authorization via withDefaults.
• Per-mixin fetcher + AJV strict-mode loosening for messy specs.
• Mixins namespace for components/schemas types.
• Composed vs segmented output (pointer to rpc skill).
• LLM tool exposure: deriveTools direct, for function-calling and MCP alike (pointer to tools skill).

Out of scope:

• Authoring own procedures → procedure skill.
• RPC client call shape, customFetcher, per-call init → rpc skill.
• AI tool derivation details → tools skill.
• Writing OpenAPI specs by hand — this skill consumes them.

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-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.

import { PetstoreAPI } from '@/client';

const pets = await PetstoreAPI.getPets({ query: { limit: 10 } });

Import path depends on client layout. Code samples here import from '@/client': the composed client generated into src/client (or client/ without a src folder). 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.

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).

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

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

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:

Preset strings — getMethodName:

'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:

import camelCase from 'lodash/camelCase.js';
import startCase from 'lodash/startCase.js';

openAPIMixin: {
  source: { url: '...', fallback: '...' },
  getModuleName: ({ operationObject }) => {
    const [ns] = operationObject.operationId?.split('/') ?? ['unknown'];
    return `Github${startCase(camelCase(ns)).replace(/ /g, '')}API`;
  },
  getMethodName: ({ operationObject }) => {
    const [, name] = operationObject.operationId?.split('/') ?? ['', 'ERROR'];
    return camelCase(name);
  },
},

Result: GithubIssuesAPI.listForOrg, GithubReposAPI.removeStatusCheckContexts, etc. — imported from generated client like any native module.

apiRoot and authorization

apiRoot sets default base URL for mixin. Required if OAS document has no servers property; if document has servers, Vovk picks first entry unless overridden.

For auth, prefer withDefaults over per-call plumbing. Every generated API module exposes withDefaults({ init?, apiRoot? }), returns new module with options deeply merged into every call:

import { PetstoreAPI } from '@/client';

const PetstoreAPIWithAuth = PetstoreAPI.withDefaults({
  init: { headers: { Authorization: `Bearer ${process.env.PETSTORE_TOKEN}` } },
  apiRoot: 'https://api.example.com', // optional override
});

await PetstoreAPIWithAuth.updatePet({ body: { name: 'Doggo' } });

Also the preferred pattern for LLM exposure — wrap the module with withDefaults first, then hand the authorized module to deriveTools, so LLM-triggered calls go out authenticated and the token never reaches the model.

Per-call override fine for one-off cases:

await PetstoreAPI.getPetById({
  params: { petId: 1 },
  apiRoot: 'https://staging.example.com',
  init: { headers: { Authorization: `Bearer ${token}` } },
});

Never embed API secrets in browser bundle. Keep authorized calls server-side (server components, route handlers, server actions, controllers, services), or proxy through your own Vovk segment + add auth header there.

Per-mixin fetcher and AJV tuning

For auth needing dynamic logic (token refresh, signing), use custom fetcher scoped to mixin's segment. Fetcher runs request, performs client-side validation, prepares headers — see rpc skill for full contract.

outputConfig: {
  segments: {
    petstore: {
      openAPIMixin: { /* ... */ },
      imports: { fetcher: './src/lib/petstoreFetcher' },
    },
  },
},

Third-party specs often include non-standard keywords that trip AJV's strict mode. Loosen globally:

libs: {
  /** @type {import('vovk-ajv').VovkAjvConfig} */
  ajv: { options: { strict: false } },
},

Client-side validation opt-out per call

Content truncated.