feat: examples plugin

[mrlubos]

No description provided.

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hey-api-docs	Ready	Preview, Comment	Apr 15, 2026 11:37am

[changeset-bot]

🦋 Changeset detected

Latest commit: d116eac

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@hey-api/openapi-ts	Patch
@hey-api/shared	Patch
@hey-api/openapi-python	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pullfrog]

TL;DR — Adds a new @hey-api/examples plugin (stub handler, types, and config wired into the plugin registry) and extracts base URL resolution logic from the client-core plugin into a shared getBaseUrl() utility in @hey-api/shared. Also renames the mocker plugin tag to source across both TS and Python packages.

Key changes

• Add @hey-api/examples plugin scaffold — New plugin with config.ts, types.ts, and index.ts registered in the plugin map and type declarations; handler is a no-op stub for now.
• Extract getBaseUrl() into @hey-api/shared — Moves base URL resolution (server lookup, URL validation, path normalization) out of client-core/client.ts into a reusable getBaseUrl() function in packages/shared/src/utils/url.ts.
• Rename mocker tag to source — The PluginTag union replaces 'mocker' with 'source' (and adds 'handler'); PluginMockNames becomes PluginSourceNames in both TS and Python plugin types. @faker-js/faker now uses the 'source' tag.
• Rename orpc.yaml spec files to rpc.yaml — Spec files and all test references updated from orpc.yaml to rpc.yaml; spec titles changed from "oRPC example" to "RPC example".
• Add mockers.yaml test spec — New OpenAPI 3.1.1 spec with example keywords on schemas and responses for testing mocker/example generation.
• Minor style: arrow functions → function declarations — createClientConfigType, createClientOptions, and serverToBaseUrlType converted from const arrow functions to function declarations.

_{Summary ｜ 23 files ｜ 1 commit ｜ base: main ← feat/plugin-examples}

New @hey-api/examples plugin

Before: No plugin for generating example values from OpenAPI specs.
After: @hey-api/examples is registered as a 'source'-tagged plugin with camelCase naming and includeInEntry: false defaults. The handler is a no-op stub — generation logic will follow in a subsequent PR.

The plugin follows the same structural pattern as @faker-js/faker: a config.ts with defaultConfig and defineConfig, a types.ts defining UserConfig, Config, and HeyApiExamplesPlugin, and a barrel index.ts. It's wired into the plugin config map, the Plugins namespace in index.ts, and the @hey-api/shared module augmentation.

config.ts · types.ts · index.ts · plugins/config.ts

Shared getBaseUrl() utility

Before: Base URL resolution lived inline in client-core/client.ts as a private resolveBaseUrlString function with URL parsing and path normalization baked into the caller.
After: getBaseUrl(config, ir) in @hey-api/shared encapsulates server lookup, template-variable filtering, protocol/host validation, and trailing-slash normalization — available to any plugin.

The client-core plugin now calls getBaseUrl(plugin.config.baseUrl ?? true, plugin.context.ir) and uses the new $if chaining API on $.object() to conditionally set baseUrl and throwOnError properties, replacing the imperative if blocks.

What does getBaseUrl filter out?

URLs containing { (server variable templates) are skipped. Bare / is skipped. Absolute URLs must have both protocol and host. Relative paths get trailing slashes trimmed.

url.ts · client.ts

Plugin tag taxonomy update

Before: Plugin tags included 'mocker'; type alias was PluginMockNames.
After: 'mocker' replaced by 'source' and 'handler' added to the PluginTag union. PluginMockNames renamed to PluginSourceNames in both TypeScript and Python packages.

This broadens the tag semantics — 'source' now covers any plugin that generates source artifacts (fakers, examples), while 'handler' is a new category for request handler plugins like MSW ('msw' added to the codegen-core module augmentation).

shared/plugins/types.ts · plugins/types.ts

  ^{｜ View workflow run ｜ via Pullfrog ｜ 𝕏}

[pullfrog]

Important

YAML typo in mockers.yaml and a subtle behavioral change in getBaseUrl worth verifying.

Early-stage draft — the scaffolding looks solid. Three items worth addressing before this lands.

Task list (6/6 completed)

• Read and understand the PR diff — identify major areas of change
• Deep-dive into new plugin files (@hey-api/examples)
• Review changes to existing plugin infrastructure and client-core
• Review test changes and spec additions
• Review shared package changes
• Self-critique and submit review

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ 𝕏}

[codecov]

Codecov Report

❌ Patch coverage is 36.00000% with 16 lines in your changes missing coverage. Please review.
✅ Project coverage is 40.04%. Comparing base (adb5e15) to head (d116eac).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
packages/shared/src/utils/url.ts	0.00%	5 Missing and 9 partials ⚠️
...napi-ts/src/plugins/@hey-api/client-core/client.ts	80.00%	1 Missing ⚠️
...openapi-ts/src/plugins/@hey-api/examples/config.ts	66.66%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3772      +/-   ##
==========================================
- Coverage   40.08%   40.04%   -0.05%     
==========================================
  Files         522      523       +1     
  Lines       19323    19321       -2     
  Branches     5767     5761       -6     
==========================================
- Hits         7746     7737       -9     
+ Misses       9374     9373       -1     
- Partials     2203     2211       +8     

Flag	Coverage Δ
unittests	40.04% <36.00%> (-0.05%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[pkg-pr-new]

Open in StackBlitz

@hey-api/codegen-core

npm i https://pkg.pr.new/@hey-api/codegen-core@3772

@hey-api/json-schema-ref-parser

npm i https://pkg.pr.new/@hey-api/json-schema-ref-parser@3772

@hey-api/nuxt

npm i https://pkg.pr.new/@hey-api/nuxt@3772

@hey-api/openapi-ts

npm i https://pkg.pr.new/@hey-api/openapi-ts@3772

@hey-api/shared

npm i https://pkg.pr.new/@hey-api/shared@3772

@hey-api/spec-types

npm i https://pkg.pr.new/@hey-api/spec-types@3772

@hey-api/types

npm i https://pkg.pr.new/@hey-api/types@3772

@hey-api/vite-plugin

npm i https://pkg.pr.new/@hey-api/vite-plugin@3772

commit: d116eac