@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?
optionaltoken?: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?
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?
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 }
)