import type { Context } from "npm:hono@3"; import { Hono } from "npm:hono@3"; import { z } from "npm:zod"; import { zodToJsonSchema } from "npm:zod-to-json-schema"; export type HttpVerb = "get" | "post" | "put" | "delete" | "patch"; /** * Base interface for defining an endpoint. * This does not include request or response schemas. */ export interface EndpointDefBase { verb: HttpVerb; path: string; desc: string; operationId: string; } /** * Used o define an endpoint with request and response schemas * along with descriptions for each. */ export interface EndpointDefinition extends EndpointDefBase { requestSchema: z.Schema | null; requestDesc: string | null; responseSchema: z.Schema | null; responseDesc: string | null; } /** * Used to define an input-only endpoint with a request schema, * but no response schema. */ export interface InEndpointDefinition extends EndpointDefBase { requestSchema: TRequestSchema; } /** * Used to define an output-only endpoint with a response schema, * but no request schema. */ export interface OutEndpointDefinition extends EndpointDefBase { responseSchema: TResponseSchema; } /** * Used to define an input/output endpoint with both a request and * response schema. */ export interface InOutEndpointDefinition extends EndpointDefBase { requestSchema: TRequestSchema; responseSchema: TResponseSchema; } /** * The API info object that is used to describe the API to the GPT. */ export interface ApiInfo { /** * The URL of the API. This should match the URL of your Val. */ url: string; /** * The name of the API. It gives the GPT an idea about the purpose of the API. */ title: string; /** * A short description of the API. It gives the GPT an idea about the purpose of the API. */ description: string; /** * The version of the API. Required by the OpenAPI spec. */ version: string; /** * An optional function that returns the policy to be used available at `/privacypolicy`. */ policyGetter?: (() => string) | (() => Promise); } /** * Returns the JSON schema for a Zod schema. * @param schema The Zod schema to convert. * @returns The generated JSON schema. */ function getSchemaDesc(schema: z.Schema | null) { if (!schema) return null; return zodToJsonSchema(schema, { name: "schema", target: "openApi3", }).definitions?.schema ?? null; } /** * Describes the schema of an endpoint. */ interface EndpointSchema { description: string; operationId: string; requestBody?: { description: string; required: boolean; content: { [key: string]: { schema: ReturnType; }; }; } | null; responses: { [key: string]: { description: string; content: { [key: string]: { schema: ReturnType; }; }; }; }; } /** * Describes the paths of an OpenAPI spec. */ type Paths = { [key: string]: Partial< { [key in HttpVerb]: EndpointSchema; } >; }; /** * Assembles the paths of an OpenAPI spec from endpoint definitions. * @param endpoints The endpoint definitions to use. * @returns The paths of the OpenAPI spec. */ function getPathsDesc(endpoints: EndpointDefinition[]): Paths { const paths: Paths = {}; for (const endpoint of endpoints) { // This is to allow multiple endpoints with the same path but different verbs if (!paths[endpoint.path]) { paths[endpoint.path] = {}; } paths[endpoint.path][endpoint.verb] = { description: endpoint.desc, operationId: endpoint.operationId, requestBody: endpoint.requestSchema ? { description: endpoint.requestDesc ?? "Request body", required: true, content: { "application/json": { schema: getSchemaDesc(endpoint.requestSchema), }, }, } : undefined, responses: { "200": { description: endpoint.responseDesc ?? "Success", content: { "application/json": { schema: getSchemaDesc(endpoint.responseSchema), }, }, }, }, }; } return paths; } /** * Generates an OpenAPI spec for the defined API. * @param url The URL of the API. * @param title The title of the API. * @param description The description of the API. * @param version The version of the API. * @param endpoints The endpoint definitions to use. * @returns The OpenAPI spec. */ function getOpenApiSpec( url: string, title: string, description: string, version: string, endpoints: EndpointDefinition[], ) { return { openapi: "3.1.0", info: { title, description, version, }, servers: [ { url, }, ], paths: getPathsDesc(endpoints), }; } /** * A class representing a GPT API. It provides methods for registering * endpoints and serving the API. */ export class GptApi { private app = new Hono(); private info: ApiInfo; private endpoints: EndpointDefinition[] = []; /** * Creates a new GptApi instance. * @param info Configuration for the API. */ constructor(info: ApiInfo) { this.info = info; this.app.get("/gpt/schema", (ctx) => { const spec = getOpenApiSpec( this.info.url, this.info.title, this.info.description, this.info.version, this.endpoints, ); return ctx.text(JSON.stringify(spec, null, 2)); }); if (info.policyGetter != null) { const policyGetter = info.policyGetter; this.app.get("/privacypolicy", async (ctx) => { let content = await policyGetter(); content = content.trim(); if (content.endsWith("")) { return ctx.html(content); } else { return ctx.text(content); } }); } this.app.get("/", (ctx) => { return ctx.text(`OpenAPI spec: ${this.info.url}/gpt/schema\nPrivacy policy: ${this.info.url}/privacypolicy\n`); }); } /** * Register an endpoint that accepts JSON input and returns * only a status code. * @param endpointDef Definition of the endpoint. * @param handler Function that handles the request. */ jsonToNothing( endpointDef: InEndpointDefinition, handler: (ctx: Context, reqBody: z.infer, apiKey: string | null) => Promise, ) { const handlerWrapper = async (ctx: Context) => { const requestBody = await ctx.req.json(); // Validate request data const parsedRequestData = endpointDef.requestSchema.parse(requestBody) as z.infer; // TODO: Handle invalid data format const apiKey = this.extractApiKey(ctx); const statusCode = await handler(ctx, parsedRequestData, apiKey); return ctx.body(null, statusCode as StatusCode); }; // Transform to EndpointDefinition const eDef = endpointDef as unknown as EndpointDefinition; eDef.requestDesc = endpointDef.requestSchema.description ?? "Request body"; eDef.responseSchema = null; eDef.responseDesc = null; // TODO: Verify request schema is in place this.registerHandler(eDef, handlerWrapper); } /** * Register an endpoint that ignores all inputs and * returns a specific JSON response. * @param endpointDef Definition of the endpoint. * @param handler Function that handles the request. */ nothingToJson( endpointDef: OutEndpointDefinition, handler: (ctx: Context, apiKey: string | null) => Promise>, ) { const handlerWrapper = async (ctx: Context) => { const apiKey = this.extractApiKey(ctx); const response = await handler(ctx, apiKey); // Validate response data const parsedResponseData = endpointDef.responseSchema.parse(response) as z.infer; return ctx.json(parsedResponseData); }; // Transform to EndpointDefinition const eDef = endpointDef as unknown as EndpointDefinition; eDef.requestSchema = null; eDef.requestDesc = null; eDef.responseDesc = endpointDef.responseSchema.description ?? "Response body"; // TODO: Verify response stuff is in place this.registerHandler(eDef, handlerWrapper); } /** * Register an endpoint that accepts a JSON request and * returns a specific JSON response. * @param endpointDef Definition of the endpoint. * @param handler Function that handles the request. */ jsonToJson( endpointDef: InOutEndpointDefinition, handler: ( ctx: Context, reqBody: z.infer, apiKey: string | null, ) => Promise>, ) { // TODO: Verify request and response is in place const handlerWrapper = async (ctx: Context) => { const requestBody = await ctx.req.json(); // Validate request data const parsedRequestData = endpointDef.requestSchema.parse(requestBody) as z.infer; // TODO: Handle invalid data format const apiKey = this.extractApiKey(ctx); const response = await handler(ctx, parsedRequestData, apiKey); // Validate response data const parsedResponseData = endpointDef.responseSchema.parse(response) as z.infer; return ctx.json(parsedResponseData); }; // Transform to EndpointDefinition const eDef = endpointDef as unknown as EndpointDefinition; eDef.requestDesc = endpointDef.requestSchema.description ?? "Request body"; eDef.responseDesc = endpointDef.responseSchema.description ?? "Response body"; this.registerHandler(eDef, handlerWrapper); } /** * Regusters a handler for a verb + path combo. * @param endpointDef Definition of the endpoint. * @param handler Function that handles the request. */ private registerHandler( endpointDef: EndpointDefinition, handler: (ctx: Context) => Response | Promise, ) { this.endpoints.push(endpointDef); const verb = endpointDef.verb; const path = endpointDef.path; switch (verb) { case "get": this.app.get(path, handler); break; case "post": this.app.post(path, handler); break; case "put": this.app.put(path, handler); break; case "delete": this.app.delete(path, handler); break; case "patch": this.app.patch(path, handler); break; default: throw new Error(`HTTP verb ${verb} not supported`); } } /** * Returns a function that can be used to serve the API. * * @example ValTown usage: * ```ts * export default gptApi.serve(); * ``` * * @example Deno usage: * ``` * const { fetch } = gptApi.serve(); * export default { fetch }; * ``` */ serve(): typeof Hono.prototype.fetch { return this.app.fetch; } /** * Extracts API key from Bearer Auth header. */ private extractApiKey(ctx: Context): string | null { const authHeader = ctx.req.header("Authorization"); if (!authHeader || !authHeader.startsWith("Bearer ")) { return null; } const apiKey = authHeader.split(" ")[1]; return apiKey; } }

gptApiFramework