feat(openapi): OpenAPILink (#303)

This is a simple OpenAPI without special feature, can come with
limitations for non-jsonable request/response

Closes: #163

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **Documentation**
- Enhanced the installation and setup guide for OpenAPILink with clear
multi-package manager instructions.
- Added detailed sections covering limitations, CORS policy
requirements, client context usage, and keep-alive behavior.
- Introduced new sections for OpenAPILink functionality and
serialization options.

- **New Features**
- Introduced new package dependencies to expand OpenAPI client
capabilities and improve modularity.
- Added new exports for the fetch module and enhanced serialization
options in the OpenAPI client.

- **Bug Fixes**
- Refined error handling with updated status code validations, ensuring
more consistent response behavior.
- Improved header merging logic to handle various scenarios effectively.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: unnoq

apps/content/docs/openapi/client/openapi-link.md

@@ -7,6 +7,145 @@ description: Details on using OpenAPILink in oRPC clients.
 
 OpenAPILink enables communication with an [OpenAPIHandler](/docs/openapi/openapi-handler) on your server using HTTP/Fetch.
 
+## Installation
+
+::: code-group
+
+```sh [npm]
+npm install @orpc/openapi-client@latest
+```
+
+```sh [yarn]
+yarn add @orpc/openapi-client@latest
+```
+
+```sh [pnpm]
+pnpm add @orpc/openapi-client@latest
+```
+
+```sh [bun]
+bun add @orpc/openapi-client@latest
+```
+
+```sh [deno]
+deno install npm:@orpc/openapi-client@latest
+```
+
+:::
+
+## Setup
+
+To use `OpenAPILink`, you must have a [contract router](/docs/contract-first/define-contract#contract-router) and a server configured with an [OpenAPIHandler](/docs/openapi/openapi-handler).
+
+::: info
+A normal [router](/docs/router) works as a contract router as long as it does not include a [lazy router](/docs/router#lazy-router). You can also unlazy a router using the [unlazyRouter](/docs/advanced/mocking#using-the-implementer) utility.
+:::
+
+```ts twoslash
+import { contract } from './shared/planet'
+// ---cut---
+import type { JsonifiedClient } from '@orpc/openapi-client'
+import type { ContractRouterClient } from '@orpc/contract'
+import { createORPCClient } from '@orpc/client'
+import { OpenAPILink } from '@orpc/openapi-client/fetch'
+
+const link = new OpenAPILink(contract, {
+  url: 'http://localhost:3000/api',
+  headers: () => ({
+    'x-api-key': 'my-api-key',
+  }),
+  // fetch: <-- polyfill fetch if needed
+})
+
+const client: JsonifiedClient<ContractRouterClient<typeof contract>> = createORPCClient(link)
+```
+
+:::warning
+Wrap your client with `JsonifiedClient` to ensure it accurately reflects the server responses.
+:::
+
+## Limitations
+
+Unlike [RPCLink](/docs/client/rpc-link), `OpenAPILink` has some constraints:
+
+- Payloads containing a `Blob` or `File` (outside the root level) must use `multipart/form-data` and serialized using [Bracket Notation](/docs/openapi/bracket-notation).
+- For `GET` requests, the payload must be sent as `URLSearchParams` and serialized using [Bracket Notation](/docs/openapi/bracket-notation).
+
+:::warning
+In these cases, both the request and response are subject to the limitations of [Bracket Notation Limitations](/docs/openapi/bracket-notation#limitations). Additionally, oRPC converts data to strings (exclude `null` and `undefined` will not be represented).
+:::
+
+## CORS policy
+
+`OpenAPILink` requires access to the `Content-Disposition` to distinguish file responses from other responses whe file has a common MIME type like `application/json`, `plain/text`, etc. To enable this, include `Content-Disposition` in your CORS policy's `Access-Control-Expose-Headers`:
+
+```ts
+const handler = new OpenAPIHandler(router, {
+  plugins: [
+    new CORSPlugin({
+      exposeHeaders: ['Content-Disposition'],
+    }),
+  ],
+})
+```
+
+## Using Client Context
+
+Client context lets you pass extra information when calling procedures and dynamically modify RPCLink’s behavior.
+
+```ts twoslash
+import { contract } from './shared/planet'
+// ---cut---
+import type { JsonifiedClient } from '@orpc/openapi-client'
+import type { ContractRouterClient } from '@orpc/contract'
+import { createORPCClient } from '@orpc/client'
+import { OpenAPILink } from '@orpc/openapi-client/fetch'
+
+interface ClientContext {
+  something?: string
+}
+
+const link = new OpenAPILink<ClientContext>(contract, {
+  url: 'http://localhost:3000/api',
+  headers: async ({ context }) => ({
+    'x-api-key': context?.something ?? ''
+  })
+})
+
+const client: JsonifiedClient<ContractRouterClient<typeof contract, ClientContext>> = createORPCClient(link)
+
+const result = await client.planet.list(
+  { limit: 10 },
+  { context: { something: 'value' } }
+)
+```
+
 :::info
-Interested in OpenAPILink support? Help us prioritize this feature by casting your vote on [Github](https://github.com/unnoq/orpc/issues/163)
+If a property in `ClientContext` is required, oRPC enforces its inclusion when calling procedures.
+:::
+
+## SSE Like Behavior
+
+Unlike traditional SSE, the [Event Iterator](/docs/event-iterator) does not automatically retry on error. To enable automatic retries, refer to the [Client Retry Plugin](/docs/plugins/client-retry).
+
+## Event Iterator Keep Alive
+
+:::warning
+These options for sending [Event Iterator](/docs/event-iterator) from **client to the server**, not from **the server to client** as used in [RPCHandler Event Iterator Keep Alive](/docs/rpc-handler#event-iterator-keep-alive) or [OpenAPIHandler Event Iterator Keep Alive](/docs/openapi/openapi-handler#event-iterator-keep-alive).
+
+**In 99% of cases, you don't need to configure these options.**
 :::
+
+To keep [Event Iterator](/docs/event-iterator) connections alive, `RPCLink` periodically sends a ping comment to the server. You can configure this behavior using the following options:
+
+- `eventIteratorKeepAliveEnabled` (default: `true`) – Enables or disables pings.
+- `eventIteratorKeepAliveInterval` (default: `5000`) – Time between pings (in milliseconds).
+- `eventIteratorKeepAliveComment` (default: `''`) – Custom content for ping messages.
+
+```ts
+const link = new OpenAPILink({
+  eventIteratorKeepAliveEnabled: true,
+  eventIteratorKeepAliveInterval: 5000, // 5 seconds
+  eventIteratorKeepAliveComment: '',
+})
+```

apps/content/package.json

@@ -11,6 +11,8 @@
     "@orpc/arktype": "workspace:*",
     "@orpc/client": "workspace:*",
     "@orpc/contract": "workspace:*",
+    "@orpc/openapi": "workspace:*",
+    "@orpc/openapi-client": "workspace:*",
     "@orpc/react-query": "workspace:*",
     "@orpc/server": "workspace:*",
     "@orpc/valibot": "workspace:*",

packages/client/src/adapters/fetch/rpc-link.ts

@@ -1,4 +1,4 @@
-import type { ClientContext, ClientLink, ClientOptions } from '../../types'
+import type { ClientContext } from '../../types'
 import type { StandardRPCLinkOptions } from '../standard'
 import type { LinkFetchClientOptions } from './link-fetch-client'
 import { StandardLink, StandardRPCJsonSerializer, StandardRPCLinkCodec, StandardRPCSerializer } from '../standard'
@@ -7,19 +7,13 @@ import { LinkFetchClient } from './link-fetch-client'
 export interface RPCLinkOptions<T extends ClientContext>
   extends StandardRPCLinkOptions<T>, LinkFetchClientOptions<T> {}
 
-export class RPCLink<T extends ClientContext> implements ClientLink<T> {
-  private readonly standardLink: StandardLink<T>
-
+export class RPCLink<T extends ClientContext> extends StandardLink<T> {
   constructor(options: RPCLinkOptions<T>) {
     const jsonSerializer = new StandardRPCJsonSerializer(options)
     const serializer = new StandardRPCSerializer(jsonSerializer)
     const linkCodec = new StandardRPCLinkCodec(serializer, options)
     const linkClient = new LinkFetchClient(options)
 
-    this.standardLink = new StandardLink(linkCodec, linkClient, options)
-  }
-
-  async call(path: readonly string[], input: unknown, options: ClientOptions<T>): Promise<unknown> {
-    return this.standardLink.call(path, input, options)
+    super(linkCodec, linkClient, options)
   }
 }

packages/client/src/adapters/standard/rpc-link-codec.test.ts

@@ -1,8 +1,11 @@
+import * as StandardServer from '@orpc/standard-server'
 import { ORPCError } from '../../error'
 import { StandardRPCJsonSerializer } from './rpc-json-serializer'
 import { StandardRPCLinkCodec } from './rpc-link-codec'
 import { StandardRPCSerializer } from './rpc-serializer'
 
+const mergeStandardHeadersSpy = vi.spyOn(StandardServer, 'mergeStandardHeaders')
+
 beforeEach(() => {
   vi.clearAllMocks()
 })
@@ -81,45 +84,20 @@ describe('standardRPCLinkCodec', () => {
       expect(serializeSpy).toBeCalledWith(input)
     })
 
-    describe('last-event-id', async () => {
-      it('should set', async () => {
-        const codec = new StandardRPCLinkCodec(serializer, {
-          url: 'http://localhost:3000',
-          method,
-          headers: () => ({ 'x-custom-header': 'custom-value' }),
-        })
-
-        const request = await codec.encode(['test'], 'input', { context: {}, lastEventId: '1' })
-
-        expect(request.headers['x-custom-header']).toEqual('custom-value')
-        expect(request.headers['last-event-id']).toEqual('1')
-      })
-
-      it('should merged', async () => {
-        const codec = new StandardRPCLinkCodec(serializer, {
-          url: 'http://localhost:3000',
-          method,
-          headers: () => ({ 'x-custom-header': 'custom-value', 'last-event-id': '2' }),
-        })
-
-        const request = await codec.encode(['test'], 'input', { context: {}, lastEventId: '1' })
-
-        expect(request.headers['x-custom-header']).toEqual('custom-value')
-        expect(request.headers['last-event-id']).toEqual(['2', '1'])
+    it('last-event-id', async () => {
+      const codec = new StandardRPCLinkCodec(serializer, {
+        url: 'http://localhost:3000',
+        method,
+        headers: () => ({ 'x-custom-header': 'custom-value' }),
       })
 
-      it('should merged 2', async () => {
-        const codec = new StandardRPCLinkCodec(serializer, {
-          url: 'http://localhost:3000',
-          method,
-          headers: () => ({ 'x-custom-header': 'custom-value', 'last-event-id': ['2', '3'] }),
-        })
+      const request = await codec.encode(['test'], 'input', { context: {}, lastEventId: '1' })
 
-        const request = await codec.encode(['test'], 'input', { context: {}, lastEventId: '1' })
+      expect(request.headers['last-event-id']).toEqual('1')
 
-        expect(request.headers['x-custom-header']).toEqual('custom-value')
-        expect(request.headers['last-event-id']).toEqual(['2', '3', '1'])
-      })
+      expect(mergeStandardHeadersSpy).toBeCalledWith({ 'x-custom-header': 'custom-value' }, { 'last-event-id': '1' })
+      expect(mergeStandardHeadersSpy).toBeCalledTimes(1)
+      expect(request.headers).toBe(mergeStandardHeadersSpy.mock.results[0]!.value)
     })
   })
 
@@ -207,7 +185,7 @@ describe('standardRPCLinkCodec', () => {
         status: 403,
         headers: {},
         body: () => Promise.resolve(serialized),
-      })).rejects.toThrow('Invalid RPC error response format.')
+      })).rejects.toThrow('MALFORMED_ORPC_ERROR_RESPONSE')
 
       expect(deserializeSpy).toBeCalledTimes(1)
       expect(deserializeSpy).toBeCalledWith(serialized)

packages/client/src/adapters/standard/rpc-link-codec.ts

@@ -1,8 +1,8 @@
-import type { StandardHeaders, StandardLazyResponse, StandardRequest } from '@orpc/standard-server'
 import type { ClientContext, ClientOptions, HTTPMethod } from '../../types'
 import type { StandardRPCSerializer } from './rpc-serializer'
 import type { StandardLinkCodec } from './types'
 import { isAsyncIteratorObject, stringifyJSON, value, type Value } from '@orpc/shared'
+import { mergeStandardHeaders, type StandardHeaders, type StandardLazyResponse, type StandardRequest } from '@orpc/standard-server'
 import { ORPCError } from '../../error'
 import { toHttpPath } from './utils'
 
@@ -76,20 +76,12 @@ export class StandardRPCLinkCodec<T extends ClientContext> implements StandardLi
 
   async encode(path: readonly string[], input: unknown, options: ClientOptions<T>): Promise<StandardRequest> {
     const expectedMethod = await value(this.expectedMethod, options, path, input)
-    const headers = { ...await value(this.headers, options, path, input) }
+    let headers = await value(this.headers, options, path, input)
     const baseUrl = await value(this.baseUrl, options, path, input)
     const url = new URL(`${baseUrl.toString().replace(/\/$/, '')}${toHttpPath(path)}`)
 
     if (options.lastEventId !== undefined) {
-      if (Array.isArray(headers['last-event-id'])) {
-        headers['last-event-id'] = [...headers['last-event-id'], options.lastEventId]
-      }
-      else if (headers['last-event-id'] !== undefined) {
-        headers['last-event-id'] = [headers['last-event-id'], options.lastEventId]
-      }
-      else {
-        headers['last-event-id'] = options.lastEventId
-      }
+      headers = mergeStandardHeaders(headers, { 'last-event-id': options.lastEventId })
     }
 
     const serialized = this.serializer.serialize(input)
@@ -155,8 +147,9 @@ export class StandardRPCLinkCodec<T extends ClientContext> implements StandardLi
         throw ORPCError.fromJSON(deserialized)
       }
 
-      throw new Error('Invalid RPC error response format.', {
-        cause: deserialized,
+      throw new ORPCError('MALFORMED_ORPC_ERROR_RESPONSE', {
+        status: response.status,
+        data: deserialized,
       })
     }
 

packages/client/src/error.test.ts

@@ -41,8 +41,11 @@ describe('oRPCError', () => {
   })
 
   it('oRPCError throw when invalid status', () => {
-    expect(() => new ORPCError('BAD_GATEWAY', { status: 100 })).toThrowError()
-    expect(() => new ORPCError('BAD_GATEWAY', { status: -1 })).toThrowError()
+    expect(() => new ORPCError('BAD_GATEWAY', { status: 200 })).toThrowError()
+    expect(() => new ORPCError('BAD_GATEWAY', { status: 299 })).toThrowError()
+
+    expect(() => new ORPCError('BAD_GATEWAY', { status: 300 })).not.toThrowError()
+    expect(() => new ORPCError('BAD_GATEWAY', { status: 199 })).not.toThrowError()
   })
 
   it('toJSON', () => {

packages/client/src/error.ts

@@ -104,8 +104,8 @@ export class ORPCError<TCode extends ORPCErrorCode, TData> extends Error {
   readonly data: TData
 
   constructor(code: TCode, ...[options]: MaybeOptionalOptions<ORPCErrorOptions<TData>>) {
-    if (options?.status && (options.status < 400 || options.status >= 600)) {
-      throw new Error('[ORPCError] The error status code must be in the 400-599 range.')
+    if (options?.status && (options.status >= 200 && options.status < 300)) {
+      throw new Error('[ORPCError] The error status code must not be in the 200-299 range.')
     }
 
     const message = fallbackORPCErrorMessage(code, options?.message)

packages/openapi-client/package.json

@@ -24,12 +24,18 @@
         "types": "./dist/adapters/standard/index.d.mts",
         "import": "./dist/adapters/standard/index.mjs",
         "default": "./dist/adapters/standard/index.mjs"
+      },
+      "./fetch": {
+        "types": "./dist/adapters/fetch/index.d.mts",
+        "import": "./dist/adapters/fetch/index.mjs",
+        "default": "./dist/adapters/fetch/index.mjs"
       }
     }
   },
   "exports": {
     ".": "./src/index.ts",
-    "./standard": "./src/adapters/standard/index.ts"
+    "./standard": "./src/adapters/standard/index.ts",
+    "./fetch": "./src/adapters/fetch/index.ts"
   },
   "files": [
     "dist"
@@ -41,7 +47,11 @@
   },
   "dependencies": {
     "@orpc/client": "workspace:*",
+    "@orpc/contract": "workspace:*",
     "@orpc/shared": "workspace:*",
     "@orpc/standard-server": "workspace:*"
+  },
+  "devDependencies": {
+    "@orpc/server": "workspace:*"
   }
 }

packages/openapi-client/src/adapters/fetch/index.ts

@@ -0,0 +1 @@
+export * from './openapi-link'