@donghanh/hono 0.3.0 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@donghanh/hono",
3
- "version": "0.3.0",
3
+ "version": "0.3.2",
4
4
  "description": "Hono routes for GPT Store and LLM chat — renderers for ChatGPT and OpenAI-compatible APIs",
5
5
  "license": "MIT",
6
6
  "type": "module",
package/src/gpt.test.ts CHANGED
@@ -69,6 +69,57 @@ async function req(
69
69
  return { status: res.status, body };
70
70
  }
71
71
 
72
+ describe("gptRoutes /operations/:name detail", () => {
73
+ test("by default returns only the op detail", async () => {
74
+ const app = gptRoutes({
75
+ registry: makeApp({
76
+ a: makeOp("a"),
77
+ b: makeOp("b"),
78
+ }),
79
+ executor: (async () => ({})) as Executor,
80
+ authenticate: async () => ({ userId: "x" }),
81
+ });
82
+ const { status, body } = await req(app, "/operations/a");
83
+ expect(status).toBe(200);
84
+ expect((body as { id: string }).id).toBe("a");
85
+ expect((body as { operations?: unknown }).operations).toBeUndefined();
86
+ });
87
+
88
+ test("includeOperationsInDetail appends siblings list", async () => {
89
+ const app = gptRoutes({
90
+ registry: makeApp({
91
+ a: makeOp("a", { auth: "required" }),
92
+ b: makeOp("b", { auth: "none" }),
93
+ c: makeOp("c", { auth: "optional" }),
94
+ }),
95
+ executor: (async () => ({})) as Executor,
96
+ authenticate: async () => ({ userId: "x" }),
97
+ includeOperationsInDetail: true,
98
+ });
99
+ const { body } = await req(app, "/operations/a");
100
+ const b = body as {
101
+ id: string;
102
+ operations: Array<{
103
+ id: string;
104
+ type: string;
105
+ auth?: string;
106
+ description: string;
107
+ }>;
108
+ };
109
+ expect(b.id).toBe("a");
110
+ expect(b.operations).toHaveLength(3);
111
+ // Each entry has name, auth (when set), description, type
112
+ const byId = Object.fromEntries(b.operations.map((o) => [o.id, o]));
113
+ expect(byId.a.auth).toBe("required");
114
+ expect(byId.b.auth).toBe("none");
115
+ expect(byId.c.auth).toBe("optional");
116
+ for (const o of b.operations) {
117
+ expect(typeof o.description).toBe("string");
118
+ expect(typeof o.type).toBe("string");
119
+ }
120
+ });
121
+ });
122
+
72
123
  describe("gptRoutes /operations listing", () => {
73
124
  test("includes auth for each op when set", async () => {
74
125
  const registry = makeApp({
package/src/gpt.ts CHANGED
@@ -11,6 +11,12 @@ export interface GptRoutesConfig {
11
11
  authenticate: Authenticate;
12
12
  encodeVariables?: (vars: Record<string, unknown>) => string;
13
13
  responseSchemas?: Record<string, object>;
14
+ /**
15
+ * Include the compact operations list in `GET /operations/:name` responses
16
+ * so the model sees siblings when inspecting a single op. Default `false` —
17
+ * opt in when you want detail lookups to be self-sufficient.
18
+ */
19
+ includeOperationsInDetail?: boolean;
14
20
  /** Hook to enrich the JSON response (e.g. inject display text) */
15
21
  enrichResponse?: (
16
22
  result: Record<string, unknown>,
@@ -44,6 +50,7 @@ export function gptRoutes(config: GptRoutesConfig): Hono {
44
50
  encodeVariables,
45
51
  responseSchemas,
46
52
  enrichResponse,
53
+ includeOperationsInDetail,
47
54
  } = config;
48
55
 
49
56
  const app = new Hono();
@@ -86,6 +93,9 @@ export function gptRoutes(config: GptRoutesConfig): Hono {
86
93
  );
87
94
  }
88
95
 
96
+ if (includeOperationsInDetail) {
97
+ return c.json({ ...detail, operations: registry.list() });
98
+ }
89
99
  return c.json(detail);
90
100
  });
91
101
 
package/src/index.ts CHANGED
@@ -6,6 +6,12 @@ export type { McpRoutesConfig, WidgetConfig } from "./mcp";
6
6
  export { mcpRoutes } from "./mcp";
7
7
  export type { AuthError, Authenticate, AuthResult } from "./middleware";
8
8
  export { isAuthError } from "./middleware";
9
+ export type {
10
+ GenerateOpenApiConfig,
11
+ OpenApiInfo,
12
+ OpenApiServer,
13
+ } from "./openapi";
14
+ export { generateOpenApi } from "./openapi";
9
15
  export type { ChatGptResult, SuggestedAction } from "./renderers/chatgpt";
10
16
  export { renderForChatGpt } from "./renderers/chatgpt";
11
17
  export type { LlmAction, LlmResult } from "./renderers/llm";
@@ -0,0 +1,196 @@
1
+ import { describe, expect, test } from "bun:test";
2
+ import type { OperationComponent, OperationConfig } from "@donghanh/core";
3
+ import { App, Brief, buildRegistry, Message } from "@donghanh/core";
4
+ import { generateOpenApi } from "./openapi";
5
+
6
+ function makeOp(
7
+ id: string,
8
+ overrides: Partial<OperationConfig> = {},
9
+ ): OperationComponent {
10
+ const op = ((_p: { data: unknown }) =>
11
+ Brief({
12
+ children: [Message({ children: "ok" })],
13
+ })) as unknown as OperationComponent;
14
+ op.operationConfig = {
15
+ id,
16
+ type: "query",
17
+ description: `${id} desc`,
18
+ instruction: `call ${id}`,
19
+ input: { type: "object", properties: {} },
20
+ responseKey: id,
21
+ ...overrides,
22
+ };
23
+ return op;
24
+ }
25
+
26
+ function registry(ops: Record<string, OperationComponent>) {
27
+ return buildRegistry(App({ operations: ops }));
28
+ }
29
+
30
+ const info = { title: "Test API", version: "1.0.0" };
31
+ const servers = [{ url: "https://api.example.com" }];
32
+ const basePath = "/api/gpt";
33
+
34
+ describe("generateOpenApi", () => {
35
+ test("emits 3.1.0 spec with info + servers + bearerAuth scheme", () => {
36
+ const spec = generateOpenApi({
37
+ registry: registry({ a: makeOp("a") }),
38
+ info,
39
+ servers,
40
+ basePath,
41
+ }) as any;
42
+ expect(spec.openapi).toBe("3.1.0");
43
+ expect(spec.info).toEqual(info);
44
+ expect(spec.servers).toEqual(servers);
45
+ expect(spec.components.securitySchemes.bearerAuth).toEqual({
46
+ type: "http",
47
+ scheme: "bearer",
48
+ });
49
+ });
50
+
51
+ test("auth=required emits default path only with bearerAuth", () => {
52
+ const spec = generateOpenApi({
53
+ registry: registry({ a: makeOp("a", { auth: "required" }) }),
54
+ info,
55
+ servers,
56
+ basePath,
57
+ }) as any;
58
+ expect(Object.keys(spec.paths)).toEqual(["/api/gpt/query/a"]);
59
+ expect(spec.paths["/api/gpt/query/a"].get.security).toEqual([
60
+ { bearerAuth: [] },
61
+ ]);
62
+ });
63
+
64
+ test("auth=none emits /public path with empty security", () => {
65
+ const spec = generateOpenApi({
66
+ registry: registry({ a: makeOp("a", { auth: "none" }) }),
67
+ info,
68
+ servers,
69
+ basePath,
70
+ }) as any;
71
+ expect(Object.keys(spec.paths)).toEqual(["/api/gpt/public/query/a"]);
72
+ expect(spec.paths["/api/gpt/public/query/a"].get.security).toEqual([]);
73
+ });
74
+
75
+ test("auth=optional emits BOTH default and /public paths", () => {
76
+ const spec = generateOpenApi({
77
+ registry: registry({ a: makeOp("a", { auth: "optional" }) }),
78
+ info,
79
+ servers,
80
+ basePath,
81
+ }) as any;
82
+ const ks = Object.keys(spec.paths).sort();
83
+ expect(ks).toEqual(["/api/gpt/public/query/a", "/api/gpt/query/a"]);
84
+ expect(spec.paths["/api/gpt/query/a"].get.security).toEqual([
85
+ { bearerAuth: [] },
86
+ ]);
87
+ expect(spec.paths["/api/gpt/public/query/a"].get.security).toEqual([]);
88
+ });
89
+
90
+ test("mutation emits POST with requestBody", () => {
91
+ const spec = generateOpenApi({
92
+ registry: registry({ m: makeOp("m", { type: "mutation" }) }),
93
+ info,
94
+ servers,
95
+ basePath,
96
+ }) as any;
97
+ const entry = spec.paths["/api/gpt/mutate/m"];
98
+ expect(entry.post.requestBody).toBeDefined();
99
+ expect(entry.post.parameters).toBeUndefined();
100
+ });
101
+
102
+ test("query has $variables parameter", () => {
103
+ const spec = generateOpenApi({
104
+ registry: registry({ q: makeOp("q") }),
105
+ info,
106
+ servers,
107
+ basePath,
108
+ }) as any;
109
+ const p = spec.paths["/api/gpt/query/q"].get.parameters;
110
+ expect(p).toHaveLength(1);
111
+ expect(p[0].name).toBe("$variables");
112
+ expect(p[0].in).toBe("query");
113
+ });
114
+
115
+ test("description combines op description + instruction", () => {
116
+ const spec = generateOpenApi({
117
+ registry: registry({ a: makeOp("a") }),
118
+ info,
119
+ servers,
120
+ basePath,
121
+ }) as any;
122
+ const op = spec.paths["/api/gpt/query/a"].get;
123
+ expect(op.summary).toBe("a desc");
124
+ expect(op.description).toContain("a desc");
125
+ expect(op.description).toContain("call a");
126
+ });
127
+
128
+ test("operationId is unique per method+opId", () => {
129
+ const spec = generateOpenApi({
130
+ registry: registry({
131
+ a: makeOp("a", { auth: "optional" }),
132
+ }),
133
+ info,
134
+ servers,
135
+ basePath,
136
+ }) as any;
137
+ const authedId = spec.paths["/api/gpt/query/a"].get.operationId;
138
+ const publicId = spec.paths["/api/gpt/public/query/a"].get.operationId;
139
+ expect(authedId).toBe("get_a");
140
+ expect(publicId).toBe("get_a"); // Same handler, different path — OAS allows same operationId across paths
141
+ });
142
+
143
+ test("mixed registry — three auth tiers coexist", () => {
144
+ const spec = generateOpenApi({
145
+ registry: registry({
146
+ priv: makeOp("priv", { auth: "required" }),
147
+ mixed: makeOp("mixed", { auth: "optional" }),
148
+ pub: makeOp("pub", { auth: "none" }),
149
+ }),
150
+ info,
151
+ servers,
152
+ basePath,
153
+ }) as any;
154
+ const ks = Object.keys(spec.paths).sort();
155
+ expect(ks).toEqual([
156
+ "/api/gpt/public/query/mixed",
157
+ "/api/gpt/public/query/pub",
158
+ "/api/gpt/query/mixed",
159
+ "/api/gpt/query/priv",
160
+ ]);
161
+ });
162
+
163
+ test("includeSiblingsInDescription appends sibling list to each path description", () => {
164
+ const spec = generateOpenApi({
165
+ registry: registry({
166
+ a: makeOp("a", { auth: "required" }),
167
+ b: makeOp("b", { auth: "none", type: "mutation" }),
168
+ c: makeOp("c", { auth: "optional" }),
169
+ }),
170
+ info,
171
+ servers,
172
+ basePath,
173
+ includeSiblingsInDescription: true,
174
+ }) as any;
175
+ const description = spec.paths["/api/gpt/query/a"].get.description;
176
+ expect(description).toContain("Other operations");
177
+ // Contains id, type, auth, and description for each sibling
178
+ expect(description).toContain("`a` (query, auth: required) — a desc");
179
+ expect(description).toContain("`b` (mutation, auth: none) — b desc");
180
+ expect(description).toContain("`c` (query, auth: optional) — c desc");
181
+ });
182
+
183
+ test("custom bearerSchemeName", () => {
184
+ const spec = generateOpenApi({
185
+ registry: registry({ a: makeOp("a") }),
186
+ info,
187
+ servers,
188
+ basePath,
189
+ bearerSchemeName: "oauthToken",
190
+ }) as any;
191
+ expect(spec.components.securitySchemes.oauthToken).toBeDefined();
192
+ expect(spec.paths["/api/gpt/query/a"].get.security).toEqual([
193
+ { oauthToken: [] },
194
+ ]);
195
+ });
196
+ });
package/src/openapi.ts ADDED
@@ -0,0 +1,234 @@
1
+ import type { Registry } from "@donghanh/core";
2
+
3
+ export interface OpenApiInfo {
4
+ title: string;
5
+ description?: string;
6
+ version: string;
7
+ }
8
+
9
+ export interface OpenApiServer {
10
+ url: string;
11
+ description?: string;
12
+ }
13
+
14
+ export interface GenerateOpenApiConfig {
15
+ registry: Registry;
16
+ info: OpenApiInfo;
17
+ servers: OpenApiServer[];
18
+ /** Mount path prefix, e.g. "/api/gpt". Omit trailing slash. Defaults to "". */
19
+ basePath?: string;
20
+ /** Name of the bearer security scheme. Defaults to "bearerAuth". */
21
+ bearerSchemeName?: string;
22
+ /** When true, adds an info note about the $variables encoding (default true). */
23
+ describeVariables?: boolean;
24
+ /**
25
+ * When true, append a "Other operations" section listing sibling op ids +
26
+ * descriptions to each path's OpenAPI `description`. Helps ChatGPT Actions
27
+ * learn the full surface from any single path. Default false.
28
+ */
29
+ includeSiblingsInDescription?: boolean;
30
+ }
31
+
32
+ type Sec = Array<Record<string, string[]>>;
33
+
34
+ type Operation = {
35
+ operationId: string;
36
+ summary: string;
37
+ description?: string;
38
+ security: Sec;
39
+ parameters?: Array<Record<string, unknown>>;
40
+ requestBody?: Record<string, unknown>;
41
+ responses: Record<string, unknown>;
42
+ };
43
+
44
+ type PathItem = Partial<Record<"get" | "post", Operation>>;
45
+
46
+ /**
47
+ * Generate an OpenAPI 3.1 spec from a donghanh registry. Emits per-operation
48
+ * concrete paths so ChatGPT Actions can target each op independently.
49
+ *
50
+ * - `auth: "required"` (default) → path under `${basePath}/query/...` with bearerAuth
51
+ * - `auth: "optional"` → two entries: the default path with bearerAuth AND `/public/...` with no security
52
+ * - `auth: "none"` → single entry under `${basePath}/public/...` with no security
53
+ */
54
+ export function generateOpenApi(config: GenerateOpenApiConfig): object {
55
+ const {
56
+ registry,
57
+ info,
58
+ servers,
59
+ basePath = "",
60
+ bearerSchemeName = "bearerAuth",
61
+ describeVariables = true,
62
+ includeSiblingsInDescription = false,
63
+ } = config;
64
+
65
+ const ops = registry.list();
66
+
67
+ const siblingsBlock = includeSiblingsInDescription
68
+ ? `\n\nOther operations:\n${ops
69
+ .map(
70
+ (o) =>
71
+ `- \`${o.id}\` (${o.type}, auth: ${o.auth ?? "required"}) — ${o.description}`,
72
+ )
73
+ .join("\n")}`
74
+ : "";
75
+ const paths: Record<string, PathItem> = {};
76
+
77
+ const variablesParam = {
78
+ name: "$variables",
79
+ in: "query" as const,
80
+ required: false,
81
+ description: describeVariables
82
+ ? "Variables encoded as JSON or TOON (one field per line), URI-encoded. See GET /operations/{name} for each op's input schema."
83
+ : undefined,
84
+ schema: { type: "string" },
85
+ };
86
+
87
+ const variablesBody = {
88
+ required: false,
89
+ content: {
90
+ "application/json": {
91
+ schema: {
92
+ type: "object",
93
+ properties: {
94
+ $variables: {
95
+ type: "string",
96
+ description: describeVariables
97
+ ? "Variables encoded as JSON string or TOON format."
98
+ : undefined,
99
+ },
100
+ },
101
+ },
102
+ },
103
+ },
104
+ };
105
+
106
+ const successResponse = {
107
+ "200": {
108
+ description: "Successful response.",
109
+ content: {
110
+ "application/json": {
111
+ schema: {
112
+ type: "object",
113
+ properties: {
114
+ data: { type: "object" },
115
+ suggestedActions: {
116
+ type: "array",
117
+ items: { type: "object" },
118
+ },
119
+ nextSteps: { type: "string" },
120
+ operations: {
121
+ type: "array",
122
+ items: { type: "object" },
123
+ },
124
+ },
125
+ },
126
+ },
127
+ },
128
+ },
129
+ "400": {
130
+ description: "Validation or execution error.",
131
+ content: {
132
+ "application/json": {
133
+ schema: {
134
+ type: "object",
135
+ properties: {
136
+ errors: {
137
+ type: "array",
138
+ items: {
139
+ type: "object",
140
+ properties: { message: { type: "string" } },
141
+ },
142
+ },
143
+ operationDetail: { type: "object" },
144
+ },
145
+ },
146
+ },
147
+ },
148
+ },
149
+ "401": {
150
+ description: "Unauthenticated. Only emitted on paths that require auth.",
151
+ },
152
+ "404": {
153
+ description: "Operation not found (or requires auth on /public paths).",
154
+ },
155
+ };
156
+
157
+ const emit = (
158
+ path: string,
159
+ method: "get" | "post",
160
+ op: (typeof ops)[number],
161
+ security: Sec,
162
+ ) => {
163
+ const detail = registry.detail(op.id);
164
+ const pascal = op.id
165
+ .split(/[-_]/)
166
+ .map((s) => (s ? s[0].toUpperCase() + s.slice(1) : ""))
167
+ .join("");
168
+ const entry: Operation = {
169
+ operationId: `${method}_${op.id}`.replace(/[^A-Za-z0-9_]/g, "_"),
170
+ summary: op.description,
171
+ description:
172
+ (detail?.instruction
173
+ ? `${op.description}\n\n${detail.instruction}`
174
+ : op.description) + siblingsBlock,
175
+ security,
176
+ responses: successResponse,
177
+ };
178
+ if (method === "get") {
179
+ entry.parameters = [variablesParam];
180
+ } else {
181
+ entry.requestBody = variablesBody;
182
+ }
183
+ // Tag by op type to help OpenAPI UIs group them.
184
+ (entry as Record<string, unknown>).tags = [op.type];
185
+ // Hint: unused `pascal` to keep id stable if we later switch to camelCase.
186
+ void pascal;
187
+
188
+ let item = paths[path];
189
+ if (!item) {
190
+ item = {};
191
+ paths[path] = item;
192
+ }
193
+ item[method] = entry;
194
+ };
195
+
196
+ const authedSec: Sec = [{ [bearerSchemeName]: [] }];
197
+ const noSec: Sec = [];
198
+
199
+ for (const op of ops) {
200
+ const method: "get" | "post" = op.type === "query" ? "get" : "post";
201
+ const auth = op.auth ?? "required";
202
+
203
+ const methodPath = op.type === "query" ? "query" : "mutate";
204
+ const defaultPath = `${basePath}/${methodPath}/${op.id}`;
205
+ const publicPath = `${basePath}/public/${methodPath}/${op.id}`;
206
+
207
+ if (auth === "none") {
208
+ emit(publicPath, method, op, noSec);
209
+ continue;
210
+ }
211
+ if (auth === "required") {
212
+ emit(defaultPath, method, op, authedSec);
213
+ continue;
214
+ }
215
+ // optional → expose both
216
+ emit(defaultPath, method, op, authedSec);
217
+ emit(publicPath, method, op, noSec);
218
+ }
219
+
220
+ return {
221
+ openapi: "3.1.0",
222
+ info,
223
+ servers,
224
+ paths,
225
+ components: {
226
+ securitySchemes: {
227
+ [bearerSchemeName]: {
228
+ type: "http",
229
+ scheme: "bearer",
230
+ },
231
+ },
232
+ },
233
+ };
234
+ }