Skip to main content

@rtorcato/cf-common

Interfaces​

AiGatewayConfig​

Defined in: index.ts:7

Which gateway to call. token is only needed for an authenticated gateway.

Properties​

accountId​

accountId: string

Defined in: index.ts:8

gatewayId​

gatewayId: string

Defined in: index.ts:9

token?​

optional token?: string

Defined in: index.ts:11

An API token with AI Gateway Run, sent as cf-aig-authorization.


AiGatewayClient​

Defined in: index.ts:21

A typed client over one AI Gateway's provider endpoints.

Methods​

url()​

url(provider?): string

Defined in: index.ts:23

The gateway's base URL, or a provider's endpoint when provider is given.

Parameters​
provider?​

string

Returns​

string

fetch()​

fetch(provider, path, init?, options?): Promise<Response>

Defined in: index.ts:31

Send a request to provider through the gateway and return the response, so a streamed body is still readable. path is the provider's own path (for openai, /chat/completions). A network error or a non-2xx status throws a non-exposed 502 AI_GATEWAY_FAILED. Redirects are never followed (an init.redirect is overridden), so a 3xx fails the same way.

Parameters​
provider​

string

path​

string

init?​

RequestInit<CfProperties<unknown>>

options?​

AiGatewayOptions

Returns​

Promise<Response>

json()​

json<T>(provider, path, body, options?): Promise<T>

Defined in: index.ts:42

POST body as JSON and return the parsed response, typed as T (asserted, not validated). Also throws AI_GATEWAY_FAILED on a non-JSON response.

Type Parameters​
T​

T

Parameters​
provider​

string

path​

string

body​

unknown

options?​

AiGatewayOptions

Returns​

Promise<T>

Type Aliases​

AiGatewayOptions​

AiGatewayOptions = Omit<GatewayOptions, "id">

Defined in: index.ts:18

Per-request gateway settings. The names match the gateway option of the Workers AI binding's run() (minus id), so the same object works for both.

Functions​

gatewayUrl()​

gatewayUrl(config, provider?): string

Defined in: index.ts:70

Build a gateway URL: https://gateway.ai.cloudflare.com/v1/<account>/<gateway>, plus /<provider> when given. An empty id or a ./.. one throws a non-exposed 500 AI_GATEWAY_INVALID, since the ids come from config.

Example​

gatewayUrl({ accountId, gatewayId: 'prod' }, 'openai')
// https://gateway.ai.cloudflare.com/v1/<accountId>/prod/openai

Parameters​

config​

Pick<AiGatewayConfig, "accountId" | "gatewayId">

provider?​

string

Returns​

string


gatewayHeaders()​

gatewayHeaders(options?, token?): Record<string, string>

Defined in: index.ts:85

Turn AiGatewayOptions (and an optional gateway token) into the cf-aig-* request headers. Unset options add no header.

Example​

fetch(url, { headers: { ...gatewayHeaders({ cacheTtl: 300, metadata: { user: 'u_1' } }) } })

Parameters​

options?​

AiGatewayOptions = {}

token?​

string

Returns​

Record<string, string>


createAiGateway()​

createAiGateway(config): AiGatewayClient

Defined in: index.ts:133

A client for one AI Gateway: provider calls go through the gateway's endpoint with the cf-aig-* headers set from typed options. Use it for external providers (OpenAI, Anthropic, …) and for Workers AI over REST; from a Worker with an AI binding, runAi(ai, model, inputs, { gateway: { id, … } }) routes through the gateway without it.

Every failure throws a non-exposed 502 CloudflareError with code AI_GATEWAY_FAILED; the upstream status and body are on cause. Neither the gateway token nor the provider key appears in the error.

Example​

const gateway = createAiGateway({ accountId, gatewayId: 'prod' })
const completion = await gateway.json<ChatCompletion>(
'openai',
'/chat/completions',
{ model: 'gpt-4o-mini', messages: [{ role: 'user', content: 'hi' }] },
{ cacheTtl: 3600 }
)

Parameters​

config​

AiGatewayConfig

Returns​

AiGatewayClient