@edgeone/types

TypeScript types for EdgeOne Makers — function handler signatures and project configuration types. EdgeOne Makers 的函数 handler 类型与项目配置类型。

• Main entry — function handler types: AgentHandler / CloudFunctionHandler / EdgeFunctionHandler / EdgeMiddlewareHandler context types 主入口 —— 函数 handler 类型：Agent / Cloud / Edge / 中间件的 context 类型
• @edgeone/types/config subpath — config types: EdgeoneConfig / TefConfig + defineConfig / validateConfig + edgeone.schema.json 子路径 —— 配置类型：EdgeoneConfig / TefConfig + defineConfig / validateConfig + edgeone.schema.json

Install / 安装

npm install -D @edgeone/types

Requires Request / Response types: include "DOM" in tsconfig lib, or use @edgeone/ef-types (the default in CLI init templates). 需要环境里有 Request / Response 类型：tsconfig lib 含 "DOM"，或使用 @edgeone/ef-types（CLI init 模板默认配置）。

Function handler types / 函数 handler 类型

Cloud / Node functions / Cloud / Node 函数

import type { CloudFunctionHandler } from '@edgeone/types';

export const onRequest: CloudFunctionHandler = async (context) => {
  const query = context.request?.query;
  return new Response(JSON.stringify({ query, region: context.server.region }));
};

Supports method-level handlers onRequestGet/Post/Put/Delete/Patch/Head/Options with the same signature. 支持 onRequestGet/Post/Put/Delete/Patch/Head/Options 方法级 handler，签名相同。

Agent

import type { AgentHandler } from '@edgeone/types';

export const onRequest: AgentHandler = async (context) => {
  await context.store.appendMessage({
    conversationId: context.conversation_id,
    role: 'user',
    content: 'hello',
  });
  return new Response('ok');
};

Edge functions / Edge 函数

import type { EdgeFunctionHandler } from '@edgeone/types';

export const onRequest: EdgeFunctionHandler = (context) => {
  return new Response(JSON.stringify({ params: context.params, eo: context.eo }));
};

Edge middleware / Edge 中间件

import type { EdgeMiddlewareConfig, EdgeMiddlewareHandler } from '@edgeone/types';

export const config: EdgeMiddlewareConfig = { matcher: ['/api/*'] };

export const middleware: EdgeMiddlewareHandler = async (context) => {
  return new Response('next', { headers: { 'x-middleware-next': '1' } });
};

Types only / 仅用类型

import type { AgentContext, CloudFunctionContext, EdgeFunctionContext } from '@edgeone/types';

Config types / 配置类型（@edgeone/types/config subpath）

edgeone.config.ts

import { defineConfig } from '@edgeone/types/config';

export default defineConfig({
  outputDirectory: 'dist',
  buildCommand: 'npm run build',
  installCommand: 'npm install',
  nodeVersion: '20',
  schedules: [{ name: 'tick', cron: '*/5 * * * *', path: '/api/cron/tick' }],
});

In scripts / tests / 脚本与测试中使用

import { validateConfig } from '@edgeone/types/config';
import type { TefConfig, CloudFunctionsConfig } from '@edgeone/types/config';

• validateConfig(input) — strict validation (tefConfigSchema.safeParse); fails on any invalid input 严格校验（tefConfigSchema.safeParse），非法即失败
• Lenient filtering (dropping invalid entries) is handled by the CLI's internal parse(); this package does not duplicate that logic 宽松过滤（丢弃非法配置项）由 CLI 内部 parse() 负责，本包不复制该逻辑

JSON Schema

edgeone.schema.json is shipped with the package (generated from the zod schema). Reference it in edgeone.json for IDE validation:

{
  "$schema": "https://cdnstatic.tencentcs.com/edgeone/pages/docs/edgeone.schema.json",
  "outputDirectory": "dist"
}

Configs generated by the CLI automatically inject the hosted $schema URL (works everywhere); for offline/local use reference node_modules/@edgeone/types/edgeone.schema.json, or run edgeone schema to write a local copy and register the VS Code association. CLI 生成的配置会自动注入托管 $schema URL（全局可用）；离线或本地调试可引用 node_modules/@edgeone/types/edgeone.schema.json，或运行 edgeone schema 在项目内生成本地副本 并注册 VS Code 关联。

Versioned subpaths / 版本化子路径

• @edgeone/types — current API (function types) / 当前 API（函数类型）
• @edgeone/types/config — config types + schema artifacts / 配置类型 + schema 产物
• @edgeone/types/v1 — versioned entry for function types / 函数类型版本化入口
• @edgeone/types/v1/types — types only / 仅类型

Type list / 类型清单

• Functions (main entry) / 函数（主入口）：AgentContext、AgentContextRequest、AgentHandler、AgentMemory、PagesStore、MemoryMessage、ConversationMeta、OpenAISession、ClaudeSessionStore、AgentContextTracer、AgentContextUtils、CloudFunctionContext、CloudFunctionAgentContext、CloudFunctionParams、CloudFunctionServerInfo、EdgeoneRequest、CloudFunctionHandler、EdgeFunctionContext、EdgeFunctionEoContext、EdgeFunctionParams、EdgeFunctionHandler、EdgeMiddlewareContext、EdgeMiddlewareHandler、EdgeMiddlewareConfig
• Config (/config) / 配置（/config）：EdgeoneConfig/TefConfig、TefBuildConfig、TefDevConfig、TefDevSiteConfig、TefPublishConfig、TefRuleCondition、TefRuleConfig、NodeFunctionsConfig、SandboxConfig、EnvConfig、CloudFunctionsRegionsConfig、TefConfHeaders、TefConfRedirects、TefConfRewrites、FunctionConfig、CloudFunctionNodejsConfig、CloudFunctionRuntimeConfig、CloudFunctionsConfig、AgentsConfig、ScheduleItemConfig、SchedulesConfig；defineConfig / validateConfig；zod schemas（tefConfigSchema 等）

Development / 开发

npm install
npm run build        # esbuild JS + tsc declarations + edgeone.schema.json
npm test             # vitest (config validation)
npm run test:types   # strict tsc type assertions + runtime shape alignment

Publish: npm publish（public npm）。