feat(hey-api): Hey API Integration

apps/content/.vitepress/config.ts

@@ -173,6 +173,7 @@ export default defineConfig({
           collapsed: true,
           items: [
             { text: 'Pinia Colada', link: '/docs/pinia-colada' },
+            { text: 'Hey API', link: '/docs/hey-api' },
             { text: 'NestJS', link: '/docs/openapi/nest/implement-contract' },
             { text: 'Playgrounds', link: '/docs/playgrounds' },
             { text: 'Comparison', link: '/docs/comparison' },

apps/content/docs/hey-api.md

@@ -0,0 +1,71 @@
+---
+title: Hey API Integration
+description: Easily convert a Hey API generated client into an oRPC client to take full advantage of the oRPC ecosystem.
+---
+
+# Hey API Integration
+
+Easily convert a [Hey API](https://heyapi.dev/) generated client into an oRPC client to take full advantage of the oRPC ecosystem.
+
+## Installation
+
+::: code-group
+
+```sh [npm]
+npm install @orpc/hey-api@latest
+```
+
+```sh [yarn]
+yarn add @orpc/hey-api@latest
+```
+
+```sh [pnpm]
+pnpm add @orpc/hey-api@latest
+```
+
+```sh [bun]
+bun add @orpc/hey-api@latest
+```
+
+```sh [deno]
+deno install npm:@orpc/hey-api@latest
+```
+
+:::
+
+## Generating an Hey API Client
+
+To generate a Hey API client, run the following command:
+
+```sh
+npx @hey-api/openapi-ts \
+  -i https://get.heyapi.dev/hey-api/backend \
+  -o src/client \
+  -c @hey-api/client-fetch
+```
+
+This command uses the OpenAPI spec at `https://get.heyapi.dev/hey-api/backend` and outputs the generated client into the `src/client` directory.
+And make sure you have `@hey-api/client-fetch` installed.
+
+::: info
+For more information on Hey API, please refer to the [official documentation](https://heyapi.dev/).
+:::
+
+## Converting to an oRPC Client
+
+Once the client is generated, convert it to an oRPC client using the `toORPCClient` function:
+
+```ts
+import { experimental_toORPCClient } from '@orpc/hey-api'
+import * as sdk from 'src/client/sdk.gen'
+
+export const client = experimental_toORPCClient(sdk)
+
+const { body } = await client.listPlanets()
+```
+
+This `client` now behaves like any standard oRPC [server-side client](/docs/client/server-side) or [client-side client](/docs/client/client-side), allowing you to use it with any oRPC-compatible library.
+
+## Error Handling
+
+Internally, oRPC passes the `throwOnError` option to the Hey API client. If the original Hey API client throws an error, oRPC will forward it as is without modification ensuring consistent error handling.

eslint.config.js

@@ -3,6 +3,7 @@ import pluginBan from 'eslint-plugin-ban'
 
 export default antfu({
   formatters: true,
+  ignores: ['packages/hey-api/tests/client/**'],
 }, {
   plugins: { ban: pluginBan },
   rules: {

package.json

@@ -42,6 +42,7 @@
     "eslint-plugin-format": "^1.0.0",
     "jsdom": "^26.0.0",
     "lint-staged": "^16.0.0",
+    "msw": "^2.8.4",
     "simple-git-hooks": "^2.11.1",
     "typescript": "^5.8.3",
     "unbuild": "^3.5.0",

packages/hey-api/.gitignore

@@ -0,0 +1,26 @@
+# Hidden folders and files
+.*
+!.gitignore
+!.*.example
+
+# Common generated folders
+logs/
+node_modules/
+out/
+dist/
+dist-ssr/
+build/
+coverage/
+temp/
+
+# Common generated files
+*.log
+*.log.*
+*.tsbuildinfo
+*.vitest-temp.json
+vite.config.ts.timestamp-*
+vitest.config.ts.timestamp-*
+
+# Common manual ignore files
+*.local
+*.pem

packages/hey-api/README.md

@@ -0,0 +1,78 @@
+<div align="center">
+  <image align="center" src="https://orpc.unnoq.com/logo.webp" width=280 alt="oRPC logo" />
+</div>
+
+<h1></h1>
+
+<div align="center">
+  <a href="https://codecov.io/gh/unnoq/orpc">
+    <img alt="codecov" src="https://codecov.io/gh/unnoq/orpc/branch/main/graph/badge.svg">
+  </a>
+  <a href="https://www.npmjs.com/package/@orpc/hey-api">
+    <img alt="weekly downloads" src="https://img.shields.io/npm/dw/%40orpc%2Fhey-api?logo=npm" />
+  </a>
+  <a href="https://github.com/unnoq/orpc/blob/main/LICENSE">
+    <img alt="MIT License" src="https://img.shields.io/github/license/unnoq/orpc?logo=open-source-initiative" />
+  </a>
+  <a href="https://discord.gg/TXEbwRBvQn">
+    <img alt="Discord" src="https://img.shields.io/discord/1308966753044398161?color=7389D8&label&logo=discord&logoColor=ffffff" />
+  </a>
+</div>
+
+<h3 align="center">Typesafe APIs Made Simple 🪄</h3>
+
+**oRPC is a powerful combination of RPC and OpenAPI**, makes it easy to build APIs that are end-to-end type-safe and adhere to OpenAPI standards
+
+---
+
+## Highlights
+
+- **🔗 End-to-End Type Safety**: Ensure type-safe inputs, outputs, and errors from client to server.
+- **📘 First-Class OpenAPI**: Built-in support that fully adheres to the OpenAPI standard.
+- **📝 Contract-First Development**: Optionally define your API contract before implementation.
+- **⚙️ Framework Integrations**: Seamlessly integrate with TanStack Query (React, Vue, Solid, Svelte), Pinia Colada, and more.
+- **🚀 Server Actions**: Fully compatible with React Server Actions on Next.js, TanStack Start, and other platforms.
+- **🔠 Standard Schema Support**: Works out of the box with Zod, Valibot, ArkType, and other schema validators.
+- **🗃️ Native Types**: Supports native types like Date, File, Blob, BigInt, URL, and more.
+- **⏱️ Lazy Router**: Enhance cold start times with our lazy routing feature.
+- **📡 SSE & Streaming**: Enjoy full type-safe support for SSE and streaming.
+- **🌍 Multi-Runtime Support**: Fast and lightweight on Cloudflare, Deno, Bun, Node.js, and beyond.
+- **🔌 Extendability**: Easily extend functionality with plugins, middleware, and interceptors.
+- **🛡️ Reliability**: Well-tested, TypeScript-based, production-ready, and MIT licensed.
+
+## Documentation
+
+You can find the full documentation [here](https://orpc.unnoq.com).
+
+## Packages
+
+- [@orpc/contract](https://www.npmjs.com/package/@orpc/contract): Build your API contract.
+- [@orpc/server](https://www.npmjs.com/package/@orpc/server): Build your API or implement API contract.
+- [@orpc/client](https://www.npmjs.com/package/@orpc/client): Consume your API on the client with type-safety.
+- [@orpc/nest](https://www.npmjs.com/package/@orpc/nest): Deeply integrate oRPC with NestJS.
+- [@orpc/react](https://www.npmjs.com/package/@orpc/react): Utilities for integrating oRPC with React and React Server Actions.
+- [@orpc/react-query](https://www.npmjs.com/package/@orpc/react-query): Integration with [React Query](https://tanstack.com/query/latest/docs/framework/react/overview).
+- [@orpc/vue-query](https://www.npmjs.com/package/@orpc/vue-query): Integration with [Vue Query](https://tanstack.com/query/latest/docs/framework/vue/overview).
+- [@orpc/solid-query](https://www.npmjs.com/package/@orpc/solid-query): Integration with [Solid Query](https://tanstack.com/query/latest/docs/framework/solid/overview).
+- [@orpc/svelte-query](https://www.npmjs.com/package/@orpc/svelte-query): Integration with [Svelte Query](https://tanstack.com/query/latest/docs/framework/svelte/overview).
+- [@orpc/vue-colada](https://www.npmjs.com/package/@orpc/vue-colada): Integration with [Pinia Colada](https://pinia-colada.esm.dev/).
+- [@orpc/openapi](https://www.npmjs.com/package/@orpc/openapi): Generate OpenAPI specs and handle OpenAPI requests.
+- [@orpc/zod](https://www.npmjs.com/package/@orpc/zod): More schemas that [Zod](https://zod.dev/) doesn't support yet.
+- [@orpc/valibot](https://www.npmjs.com/package/@orpc/valibot): OpenAPI spec generation from [Valibot](https://valibot.dev/).
+- [@orpc/arktype](https://www.npmjs.com/package/@orpc/arktype): OpenAPI spec generation from [ArkType](https://arktype.io/).
+
+## `@orpc/hey-api`
+
+Integration with [Hey API](https://heyapi.dev/).
+
+## Sponsors
+
+<p align="center">
+  <a href="https://cdn.jsdelivr.net/gh/unnoq/unnoq/sponsors.svg">
+    <img src='https://cdn.jsdelivr.net/gh/unnoq/unnoq/sponsors.svg'/>
+  </a>
+</p>
+
+## License
+
+Distributed under the MIT License. See [LICENSE](https://github.com/unnoq/orpc/blob/main/LICENSE) for more information.

packages/hey-api/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@orpc/hey-api",
+  "type": "module",
+  "version": "0.0.0",
+  "license": "MIT",
+  "homepage": "https://orpc.unnoq.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unnoq/orpc.git",
+    "directory": "packages/hey-api"
+  },
+  "keywords": [
+    "unnoq",
+    "orpc",
+    "Hey API"
+  ],
+  "publishConfig": {
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.mts",
+        "import": "./dist/index.mjs",
+        "default": "./dist/index.mjs"
+      }
+    }
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "unbuild",
+    "build:watch": "pnpm run build --watch",
+    "type:check": "tsc -b",
+    "prepare": "openapi-ts -i ./tests/spec.json -o ./tests/client -c @hey-api/client-fetch"
+  },
+  "peerDependencies": {
+    "@hey-api/client-fetch": "*"
+  },
+  "dependencies": {
+    "@orpc/client": "workspace:*",
+    "@orpc/shared": "workspace:*"
+  },
+  "devDependencies": {
+    "@hey-api/client-fetch": "^0.10.1",
+    "@hey-api/openapi-ts": "^0.67.6"
+  }
+}

packages/hey-api/src/index.ts

@@ -0,0 +1 @@
+export * from './to-orpc-client'

packages/hey-api/src/to-orpc-client.test-d.ts

@@ -0,0 +1,47 @@
+import type { NestedClient } from '../../client/src/types'
+import type { Planet } from '../tests/client/types.gen'
+import * as sdk from '../tests/client/sdk.gen'
+import { experimental_toORPCClient } from './to-orpc-client'
+
+describe('toORPCClient', () => {
+  const client = experimental_toORPCClient({
+    ...sdk,
+    somethingElse: 123,
+  })
+
+  const c = sdk.listPlanets()
+
+  it('satisfies nested client', () => {
+    const _b: NestedClient<Record<never, never>> = client
+  })
+
+  it('inputs', async () => {
+    client.listPlanets()
+
+    client.listPlanets({
+      query: {
+        limit: 10,
+        offset: 0,
+      },
+    })
+
+    client.listPlanets({
+      query: {
+        // @ts-expect-error - invalid type
+        limit: 'invalid',
+      },
+    })
+
+    client.getPlanet({ path: { planetId: 'earth' } })
+    // @ts-expect-error - path is required
+    client.getPlanet()
+    // @ts-expect-error - invalid type
+    client.getPlanet({ path: { planetId: 123 } })
+  })
+
+  it('outputs', async () => {
+    expectTypeOf(await client.listPlanets()).toEqualTypeOf<{ body: Planet[], request: Request, response: Response }>()
+    expectTypeOf(await client.getPlanet({ path: { planetId: 'earth' } })).toEqualTypeOf<{ body: Planet, request: Request, response: Response }>()
+    expectTypeOf(await client.createPlanet({ body: { name: 'Earth' } })).toEqualTypeOf<{ body: Planet, request: Request, response: Response }>()
+  })
+})