@donghanh/hono 0.3.2 → 0.3.4

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.2",
3
+ "version": "0.3.4",
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",
@@ -31,8 +31,8 @@ const info = { title: "Test API", version: "1.0.0" };
31
31
  const servers = [{ url: "https://api.example.com" }];
32
32
  const basePath = "/api/gpt";
33
33
 
34
- describe("generateOpenApi", () => {
35
- test("emits 3.1.0 spec with info + servers + bearerAuth scheme", () => {
34
+ describe("generateOpenApi common", () => {
35
+ test("emits 3.1.0 spec with info + servers + default bearer scheme", () => {
36
36
  const spec = generateOpenApi({
37
37
  registry: registry({ a: makeOp("a") }),
38
38
  info,
@@ -46,14 +46,177 @@ describe("generateOpenApi", () => {
46
46
  type: "http",
47
47
  scheme: "bearer",
48
48
  });
49
+ // components.schemas always includes OperationResponse (validator requires object)
50
+ expect(typeof spec.components.schemas).toBe("object");
51
+ expect(spec.components.schemas.OperationResponse).toBeDefined();
49
52
  });
50
53
 
51
- test("auth=required emits default path only with bearerAuth", () => {
54
+ test("includeDescription is off by default — no description field", () => {
52
55
  const spec = generateOpenApi({
53
- registry: registry({ a: makeOp("a", { auth: "required" }) }),
56
+ registry: registry({ a: makeOp("a") }),
57
+ info,
58
+ servers,
59
+ basePath,
60
+ pathStyle: "per-op",
61
+ }) as any;
62
+ const entry = spec.paths["/api/gpt/query/a"].get;
63
+ expect(entry.description).toBeUndefined();
64
+ expect(entry.summary).toBe("a desc");
65
+ });
66
+
67
+ test("includeDescription: true emits description built from desc+instruction", () => {
68
+ const spec = generateOpenApi({
69
+ registry: registry({ a: makeOp("a") }),
70
+ info,
71
+ servers,
72
+ basePath,
73
+ pathStyle: "per-op",
74
+ includeDescription: true,
75
+ }) as any;
76
+ const d = spec.paths["/api/gpt/query/a"].get.description as string;
77
+ expect(d).toContain("a desc");
78
+ expect(d).toContain("call a");
79
+ });
80
+
81
+ test("description truncated at maxDescriptionLength when included", () => {
82
+ const spec = generateOpenApi({
83
+ registry: registry({
84
+ a: makeOp("a", { instruction: "x".repeat(500) }),
85
+ }),
86
+ info,
87
+ servers,
88
+ basePath,
89
+ pathStyle: "per-op",
90
+ includeDescription: true,
91
+ }) as any;
92
+ const d = spec.paths["/api/gpt/query/a"].get.description as string;
93
+ expect(d.length).toBeLessThanOrEqual(300);
94
+ expect(d.endsWith("…")).toBe(true);
95
+ });
96
+
97
+ test("summary capped at 120 chars", () => {
98
+ const spec = generateOpenApi({
99
+ registry: registry({
100
+ a: makeOp("a", { description: "y".repeat(200) }),
101
+ }),
102
+ info,
103
+ servers,
104
+ basePath,
105
+ pathStyle: "per-op",
106
+ }) as any;
107
+ const s = spec.paths["/api/gpt/query/a"].get.summary as string;
108
+ expect(s.length).toBeLessThanOrEqual(120);
109
+ });
110
+
111
+ test("emits discovery endpoints by default (listOperations + getOperationDetail)", () => {
112
+ const spec = generateOpenApi({
113
+ registry: registry({ a: makeOp("a") }),
114
+ info,
115
+ servers,
116
+ basePath,
117
+ }) as any;
118
+ expect(spec.paths["/api/gpt/operations"].get.operationId).toBe(
119
+ "listOperations",
120
+ );
121
+ expect(spec.paths["/api/gpt/operations/{name}"].get.operationId).toBe(
122
+ "getOperationDetail",
123
+ );
124
+ expect(spec.paths["/api/gpt/operations"].get.security).toEqual([]);
125
+ expect(spec.paths["/api/gpt/operations/{name}"].get.security).toEqual([]);
126
+ });
127
+
128
+ test("includeDiscoveryEndpoints: false omits them", () => {
129
+ const spec = generateOpenApi({
130
+ registry: registry({ a: makeOp("a") }),
131
+ info,
132
+ servers,
133
+ basePath,
134
+ includeDiscoveryEndpoints: false,
135
+ }) as any;
136
+ expect(spec.paths["/api/gpt/operations"]).toBeUndefined();
137
+ expect(spec.paths["/api/gpt/operations/{name}"]).toBeUndefined();
138
+ });
139
+
140
+ test("emits OperationResponse component schema referenced by paths", () => {
141
+ const spec = generateOpenApi({
142
+ registry: registry({ a: makeOp("a") }),
143
+ info,
144
+ servers,
145
+ basePath,
146
+ pathStyle: "per-op",
147
+ }) as any;
148
+ expect(spec.components.schemas.OperationResponse.type).toBe("object");
149
+ expect(
150
+ spec.components.schemas.OperationResponse.properties.suggestedActions,
151
+ ).toBeDefined();
152
+ expect(
153
+ spec.components.schemas.OperationResponse.properties.nextSteps,
154
+ ).toBeDefined();
155
+ expect(
156
+ spec.paths["/api/gpt/query/a"].get.responses["200"].content[
157
+ "application/json"
158
+ ].schema.$ref,
159
+ ).toBe("#/components/schemas/OperationResponse");
160
+ });
161
+
162
+ test("securityScheme override for oauth2 flow", () => {
163
+ const spec = generateOpenApi({
164
+ registry: registry({ a: makeOp("a") }),
54
165
  info,
55
166
  servers,
56
167
  basePath,
168
+ securityScheme: {
169
+ type: "oauth2",
170
+ flows: {
171
+ authorizationCode: {
172
+ authorizationUrl: "https://example.com/oauth/authorize",
173
+ tokenUrl: "https://example.com/oauth/token",
174
+ scopes: {},
175
+ },
176
+ },
177
+ },
178
+ }) as any;
179
+ expect(spec.components.securitySchemes.bearerAuth).toEqual({
180
+ type: "oauth2",
181
+ flows: {
182
+ authorizationCode: {
183
+ authorizationUrl: "https://example.com/oauth/authorize",
184
+ tokenUrl: "https://example.com/oauth/token",
185
+ scopes: {},
186
+ },
187
+ },
188
+ });
189
+ });
190
+
191
+ test("custom bearerSchemeName", () => {
192
+ const spec = generateOpenApi({
193
+ registry: registry({ a: makeOp("a") }),
194
+ info,
195
+ servers,
196
+ basePath,
197
+ pathStyle: "per-op",
198
+ bearerSchemeName: "oauthToken",
199
+ }) as any;
200
+ expect(spec.components.securitySchemes.oauthToken).toBeDefined();
201
+ expect(spec.paths["/api/gpt/query/a"].get.security).toEqual([
202
+ { oauthToken: [] },
203
+ ]);
204
+ });
205
+ });
206
+
207
+ describe("generateOpenApi pathStyle: 'per-op'", () => {
208
+ const opts = {
209
+ info,
210
+ servers,
211
+ basePath,
212
+ pathStyle: "per-op" as const,
213
+ };
214
+
215
+ test("auth=required emits default path only with bearerAuth", () => {
216
+ const spec = generateOpenApi({
217
+ ...opts,
218
+ registry: registry({ a: makeOp("a", { auth: "required" }) }),
219
+ includeDiscoveryEndpoints: false,
57
220
  }) as any;
58
221
  expect(Object.keys(spec.paths)).toEqual(["/api/gpt/query/a"]);
59
222
  expect(spec.paths["/api/gpt/query/a"].get.security).toEqual([
@@ -63,36 +226,28 @@ describe("generateOpenApi", () => {
63
226
 
64
227
  test("auth=none emits /public path with empty security", () => {
65
228
  const spec = generateOpenApi({
229
+ ...opts,
66
230
  registry: registry({ a: makeOp("a", { auth: "none" }) }),
67
- info,
68
- servers,
69
- basePath,
231
+ includeDiscoveryEndpoints: false,
70
232
  }) as any;
71
233
  expect(Object.keys(spec.paths)).toEqual(["/api/gpt/public/query/a"]);
72
234
  expect(spec.paths["/api/gpt/public/query/a"].get.security).toEqual([]);
73
235
  });
74
236
 
75
- test("auth=optional emits BOTH default and /public paths", () => {
237
+ test("auth=optional emits both default and /public paths", () => {
76
238
  const spec = generateOpenApi({
239
+ ...opts,
77
240
  registry: registry({ a: makeOp("a", { auth: "optional" }) }),
78
- info,
79
- servers,
80
- basePath,
241
+ includeDiscoveryEndpoints: false,
81
242
  }) as any;
82
243
  const ks = Object.keys(spec.paths).sort();
83
244
  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
245
  });
89
246
 
90
247
  test("mutation emits POST with requestBody", () => {
91
248
  const spec = generateOpenApi({
249
+ ...opts,
92
250
  registry: registry({ m: makeOp("m", { type: "mutation" }) }),
93
- info,
94
- servers,
95
- basePath,
96
251
  }) as any;
97
252
  const entry = spec.paths["/api/gpt/mutate/m"];
98
253
  expect(entry.post.requestBody).toBeDefined();
@@ -101,96 +256,100 @@ describe("generateOpenApi", () => {
101
256
 
102
257
  test("query has $variables parameter", () => {
103
258
  const spec = generateOpenApi({
259
+ ...opts,
104
260
  registry: registry({ q: makeOp("q") }),
105
- info,
106
- servers,
107
- basePath,
108
261
  }) as any;
109
262
  const p = spec.paths["/api/gpt/query/q"].get.parameters;
110
263
  expect(p).toHaveLength(1);
111
264
  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
265
  });
266
+ });
127
267
 
128
- test("operationId is unique per method+opId", () => {
268
+ describe("generateOpenApi pathStyle: 'parametric' (default)", () => {
269
+ test("collapses all query ops under one /query/{operation} path with enum", () => {
129
270
  const spec = generateOpenApi({
130
271
  registry: registry({
131
- a: makeOp("a", { auth: "optional" }),
272
+ a: makeOp("a", { auth: "required" }),
273
+ b: makeOp("b", { auth: "required" }),
132
274
  }),
133
275
  info,
134
276
  servers,
135
277
  basePath,
278
+ includeDiscoveryEndpoints: false,
136
279
  }) 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
280
+ const ks = Object.keys(spec.paths);
281
+ expect(ks).toEqual(["/api/gpt/query/{operation}"]);
282
+ const opParam = spec.paths["/api/gpt/query/{operation}"].get.parameters[0];
283
+ expect(opParam.name).toBe("operation");
284
+ expect(opParam.in).toBe("path");
285
+ expect(opParam.schema.enum).toEqual(["a", "b"]);
141
286
  });
142
287
 
143
- test("mixed registry — three auth tiers coexist", () => {
288
+ test("emits /public/{operation} when any op is auth=none or optional", () => {
144
289
  const spec = generateOpenApi({
145
290
  registry: registry({
146
291
  priv: makeOp("priv", { auth: "required" }),
147
- mixed: makeOp("mixed", { auth: "optional" }),
148
292
  pub: makeOp("pub", { auth: "none" }),
293
+ both: makeOp("both", { auth: "optional" }),
149
294
  }),
150
295
  info,
151
296
  servers,
152
297
  basePath,
298
+ includeDiscoveryEndpoints: false,
153
299
  }) as any;
154
300
  const ks = Object.keys(spec.paths).sort();
155
301
  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",
302
+ "/api/gpt/public/query/{operation}",
303
+ "/api/gpt/query/{operation}",
160
304
  ]);
305
+ // Default enum contains authed ops: required + optional (not "none")
306
+ expect(
307
+ spec.paths["/api/gpt/query/{operation}"].get.parameters[0].schema.enum,
308
+ ).toEqual(["priv", "both"]);
309
+ // Public enum contains guest-callable ops: none + optional (not "required")
310
+ expect(
311
+ spec.paths["/api/gpt/public/query/{operation}"].get.parameters[0].schema
312
+ .enum,
313
+ ).toEqual(["pub", "both"]);
161
314
  });
162
315
 
163
- test("includeSiblingsInDescription appends sibling list to each path description", () => {
316
+ test("separate /mutate/{operation} path for mutations", () => {
164
317
  const spec = generateOpenApi({
165
318
  registry: registry({
166
- a: makeOp("a", { auth: "required" }),
167
- b: makeOp("b", { auth: "none", type: "mutation" }),
168
- c: makeOp("c", { auth: "optional" }),
319
+ m: makeOp("m", { type: "mutation" }),
169
320
  }),
170
321
  info,
171
322
  servers,
172
323
  basePath,
173
- includeSiblingsInDescription: true,
174
324
  }) 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");
325
+ expect(spec.paths["/api/gpt/mutate/{operation}"]).toBeDefined();
326
+ expect(
327
+ spec.paths["/api/gpt/mutate/{operation}"].post.requestBody,
328
+ ).toBeDefined();
181
329
  });
182
330
 
183
- test("custom bearerSchemeName", () => {
331
+ test("no description field by default (ChatGPT-safe)", () => {
184
332
  const spec = generateOpenApi({
185
333
  registry: registry({ a: makeOp("a") }),
186
334
  info,
187
335
  servers,
188
336
  basePath,
189
- bearerSchemeName: "oauthToken",
190
337
  }) as any;
191
- expect(spec.components.securitySchemes.oauthToken).toBeDefined();
192
- expect(spec.paths["/api/gpt/query/a"].get.security).toEqual([
193
- { oauthToken: [] },
194
- ]);
338
+ const entry = spec.paths["/api/gpt/query/{operation}"].get;
339
+ expect(entry.description).toBeUndefined();
340
+ });
341
+
342
+ test("includeDescription: true emits a short description", () => {
343
+ const spec = generateOpenApi({
344
+ registry: registry({ a: makeOp("a") }),
345
+ info,
346
+ servers,
347
+ basePath,
348
+ includeDescription: true,
349
+ }) as any;
350
+ const d = spec.paths["/api/gpt/query/{operation}"].get
351
+ .description as string;
352
+ expect(typeof d).toBe("string");
353
+ expect(d.length).toBeLessThanOrEqual(300);
195
354
  });
196
355
  });
package/src/openapi.ts CHANGED
@@ -17,16 +17,68 @@ export interface GenerateOpenApiConfig {
17
17
  servers: OpenApiServer[];
18
18
  /** Mount path prefix, e.g. "/api/gpt". Omit trailing slash. Defaults to "". */
19
19
  basePath?: string;
20
- /** Name of the bearer security scheme. Defaults to "bearerAuth". */
20
+ /** Name of the security scheme entry under components.securitySchemes. Defaults to "bearerAuth". */
21
21
  bearerSchemeName?: string;
22
+ /**
23
+ * Full security scheme object to place under components.securitySchemes.
24
+ * Defaults to `{ type: "http", scheme: "bearer" }`. Pass an oauth2 flow
25
+ * object to match ChatGPT Custom GPT OAuth requirements:
26
+ *
27
+ * securityScheme: {
28
+ * type: "oauth2",
29
+ * flows: {
30
+ * authorizationCode: {
31
+ * authorizationUrl: "https://example.com/oauth/authorize",
32
+ * tokenUrl: "https://example.com/oauth/token",
33
+ * scopes: {},
34
+ * },
35
+ * },
36
+ * }
37
+ */
38
+ securityScheme?: Record<string, unknown>;
39
+ /**
40
+ * Include the discovery endpoints (`GET /operations` and
41
+ * `GET /operations/{name}`) in the generated spec. Default true — the
42
+ * GPT relies on these to learn available operations and their input
43
+ * schemas before invoking one.
44
+ */
45
+ includeDiscoveryEndpoints?: boolean;
22
46
  /** When true, adds an info note about the $variables encoding (default true). */
23
47
  describeVariables?: boolean;
24
48
  /**
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.
49
+ * When true, each path emits a `description` built from the op's
50
+ * description + instruction. Default `false` — only `summary` is emitted,
51
+ * which keeps the spec compact and sidesteps ChatGPT Actions' 300-char
52
+ * description limit. Turn on when you want richer Action instructions in
53
+ * the OAS. (For listing sibling operations, prefer `includeOperationsInDetail`
54
+ * on `gptRoutes` — the GPT fetches `GET /operations/:name` to learn
55
+ * available ops, a cleaner channel than inlining them into OAS.)
56
+ */
57
+ includeDescription?: boolean;
58
+ /**
59
+ * Max length for each path's OpenAPI `description` when emitted. ChatGPT
60
+ * Actions rejects descriptions over 300 characters, so the default is 300.
61
+ * No effect when `includeDescription` is false.
28
62
  */
29
- includeSiblingsInDescription?: boolean;
63
+ maxDescriptionLength?: number;
64
+ /**
65
+ * How to lay out paths:
66
+ * - "parametric" (default) — single path with `{operation}` as a path param,
67
+ * matching gptRoutes' route shape (`/query/:operation`). 2–4 paths total
68
+ * regardless of registry size; the model picks the op by filling the
69
+ * `operation` param. Mirrors the existing REST shape and matches the
70
+ * convention most donghanh apps already use in their ChatGPT Action config.
71
+ * - "per-op" — one OAS path per operation, e.g. `/query/start`,
72
+ * `/public/query/check-offer`. Each op gets its own summary + description,
73
+ * so ChatGPT Actions discovers them as separate actions. Larger spec;
74
+ * useful when you want each op to be a discrete ChatGPT Action.
75
+ */
76
+ pathStyle?: "parametric" | "per-op";
77
+ }
78
+
79
+ function truncate(s: string, max: number): string {
80
+ if (s.length <= max) return s;
81
+ return `${s.slice(0, Math.max(0, max - 1))}…`;
30
82
  }
31
83
 
32
84
  type Sec = Array<Record<string, string[]>>;
@@ -58,20 +110,15 @@ export function generateOpenApi(config: GenerateOpenApiConfig): object {
58
110
  servers,
59
111
  basePath = "",
60
112
  bearerSchemeName = "bearerAuth",
113
+ securityScheme = { type: "http", scheme: "bearer" },
114
+ includeDiscoveryEndpoints = true,
61
115
  describeVariables = true,
62
- includeSiblingsInDescription = false,
116
+ includeDescription = false,
117
+ maxDescriptionLength = 300,
118
+ pathStyle = "parametric",
63
119
  } = config;
64
120
 
65
121
  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
122
  const paths: Record<string, PathItem> = {};
76
123
 
77
124
  const variablesParam = {
@@ -108,21 +155,7 @@ export function generateOpenApi(config: GenerateOpenApiConfig): object {
108
155
  description: "Successful response.",
109
156
  content: {
110
157
  "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
- },
158
+ schema: { $ref: "#/components/schemas/OperationResponse" },
126
159
  },
127
160
  },
128
161
  },
@@ -130,19 +163,7 @@ export function generateOpenApi(config: GenerateOpenApiConfig): object {
130
163
  description: "Validation or execution error.",
131
164
  content: {
132
165
  "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
- },
166
+ schema: { $ref: "#/components/schemas/OperationResponse" },
146
167
  },
147
168
  },
148
169
  },
@@ -161,29 +182,24 @@ export function generateOpenApi(config: GenerateOpenApiConfig): object {
161
182
  security: Sec,
162
183
  ) => {
163
184
  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
185
  const entry: Operation = {
169
186
  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,
187
+ summary: truncate(op.description, 120),
175
188
  security,
176
189
  responses: successResponse,
177
190
  };
191
+ if (includeDescription) {
192
+ const full = detail?.instruction
193
+ ? `${op.description}\n\n${detail.instruction}`
194
+ : op.description;
195
+ entry.description = truncate(full, maxDescriptionLength);
196
+ }
178
197
  if (method === "get") {
179
198
  entry.parameters = [variablesParam];
180
199
  } else {
181
200
  entry.requestBody = variablesBody;
182
201
  }
183
- // Tag by op type to help OpenAPI UIs group them.
184
202
  (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
203
 
188
204
  let item = paths[path];
189
205
  if (!item) {
@@ -196,25 +212,39 @@ export function generateOpenApi(config: GenerateOpenApiConfig): object {
196
212
  const authedSec: Sec = [{ [bearerSchemeName]: [] }];
197
213
  const noSec: Sec = [];
198
214
 
199
- for (const op of ops) {
200
- const method: "get" | "post" = op.type === "query" ? "get" : "post";
201
- const auth = op.auth ?? "required";
215
+ if (pathStyle === "parametric") {
216
+ emitParametric(paths, basePath, authedSec, noSec, ops, {
217
+ includeDescription,
218
+ maxDescriptionLength,
219
+ variablesParam,
220
+ variablesBody,
221
+ successResponse,
222
+ });
223
+ } else {
224
+ for (const op of ops) {
225
+ const method: "get" | "post" = op.type === "query" ? "get" : "post";
226
+ const auth = op.auth ?? "required";
202
227
 
203
- const methodPath = op.type === "query" ? "query" : "mutate";
204
- const defaultPath = `${basePath}/${methodPath}/${op.id}`;
205
- const publicPath = `${basePath}/public/${methodPath}/${op.id}`;
228
+ const methodPath = op.type === "query" ? "query" : "mutate";
229
+ const defaultPath = `${basePath}/${methodPath}/${op.id}`;
230
+ const publicPath = `${basePath}/public/${methodPath}/${op.id}`;
206
231
 
207
- if (auth === "none") {
208
- emit(publicPath, method, op, noSec);
209
- continue;
210
- }
211
- if (auth === "required") {
232
+ if (auth === "none") {
233
+ emit(publicPath, method, op, noSec);
234
+ continue;
235
+ }
236
+ if (auth === "required") {
237
+ emit(defaultPath, method, op, authedSec);
238
+ continue;
239
+ }
240
+ // optional → expose both
212
241
  emit(defaultPath, method, op, authedSec);
213
- continue;
242
+ emit(publicPath, method, op, noSec);
214
243
  }
215
- // optional → expose both
216
- emit(defaultPath, method, op, authedSec);
217
- emit(publicPath, method, op, noSec);
244
+ }
245
+
246
+ if (includeDiscoveryEndpoints) {
247
+ emitDiscoveryEndpoints(paths, basePath, noSec, successResponse);
218
248
  }
219
249
 
220
250
  return {
@@ -223,12 +253,335 @@ export function generateOpenApi(config: GenerateOpenApiConfig): object {
223
253
  servers,
224
254
  paths,
225
255
  components: {
256
+ schemas: {
257
+ OperationResponse: operationResponseSchema,
258
+ },
226
259
  securitySchemes: {
227
- [bearerSchemeName]: {
228
- type: "http",
229
- scheme: "bearer",
260
+ [bearerSchemeName]: securityScheme,
261
+ },
262
+ },
263
+ };
264
+ }
265
+
266
+ const operationResponseSchema = {
267
+ type: "object",
268
+ properties: {
269
+ data: { type: "object", description: "Operation result data" },
270
+ errors: {
271
+ type: "array",
272
+ description: "Included on error responses.",
273
+ items: {
274
+ type: "object",
275
+ properties: { message: { type: "string" } },
276
+ },
277
+ },
278
+ operations: {
279
+ type: "array",
280
+ description:
281
+ "All available operations (always present in every response).",
282
+ items: {
283
+ type: "object",
284
+ properties: {
285
+ id: { type: "string" },
286
+ type: { type: "string", enum: ["query", "mutation"] },
287
+ description: { type: "string" },
288
+ auth: { type: "string", enum: ["none", "optional", "required"] },
230
289
  },
231
290
  },
232
291
  },
292
+ suggestedActions: {
293
+ type: "array",
294
+ description:
295
+ "Context-aware suggested next operations with pre-filled variables.",
296
+ items: {
297
+ type: "object",
298
+ properties: {
299
+ id: { type: "string" },
300
+ type: { type: "string", enum: ["query", "mutation"] },
301
+ description: { type: "string" },
302
+ variables: { type: "object" },
303
+ $variables: {
304
+ type: "string",
305
+ description: "Variables pre-encoded as a string, ready to reuse.",
306
+ },
307
+ input: {
308
+ type: "object",
309
+ description: "JSON Schema for this operation's variables",
310
+ },
311
+ },
312
+ },
313
+ },
314
+ display: {
315
+ type: "string",
316
+ description:
317
+ "Pre-rendered text in the user's locale. Suggested wording — adapt tone freely but keep amounts and names accurate.",
318
+ },
319
+ nextSteps: {
320
+ type: "string",
321
+ description:
322
+ "Contextual instructions for the assistant. Follow these exactly.",
323
+ },
324
+ operationDetail: {
325
+ type: "object",
326
+ description:
327
+ "Included on error responses. Contains the operation's input schema and instruction so you can fix your request and retry.",
328
+ properties: {
329
+ instruction: { type: "string" },
330
+ input: { type: "object" },
331
+ },
332
+ },
333
+ responseSchema: {
334
+ type: "object",
335
+ description:
336
+ "JSON Schema for the response data. Included on the start response when configured.",
337
+ },
338
+ },
339
+ };
340
+
341
+ function emitDiscoveryEndpoints(
342
+ paths: Record<string, PathItem>,
343
+ basePath: string,
344
+ noSec: Sec,
345
+ successResponse: Record<string, unknown>,
346
+ ): void {
347
+ paths[`${basePath}/operations`] = {
348
+ get: {
349
+ operationId: "listOperations",
350
+ summary: "Discover available operations",
351
+ security: noSec,
352
+ parameters: [
353
+ {
354
+ name: "search",
355
+ in: "query",
356
+ required: false,
357
+ description: "Filter operations by keyword in id or description.",
358
+ schema: { type: "string" },
359
+ },
360
+ {
361
+ name: "type",
362
+ in: "query",
363
+ required: false,
364
+ description: "Filter by operation type.",
365
+ schema: { type: "string", enum: ["query", "mutation"] },
366
+ },
367
+ ],
368
+ responses: {
369
+ "200": {
370
+ description: "List of available operations",
371
+ content: {
372
+ "application/json": {
373
+ schema: {
374
+ type: "object",
375
+ properties: {
376
+ operations: {
377
+ type: "array",
378
+ items: {
379
+ type: "object",
380
+ properties: {
381
+ id: { type: "string" },
382
+ type: {
383
+ type: "string",
384
+ enum: ["query", "mutation"],
385
+ },
386
+ description: { type: "string" },
387
+ auth: {
388
+ type: "string",
389
+ enum: ["none", "optional", "required"],
390
+ },
391
+ },
392
+ },
393
+ },
394
+ },
395
+ },
396
+ },
397
+ },
398
+ },
399
+ },
400
+ } as Operation,
233
401
  };
402
+
403
+ paths[`${basePath}/operations/{name}`] = {
404
+ get: {
405
+ operationId: "getOperationDetail",
406
+ summary: "Get full details for a specific operation",
407
+ security: noSec,
408
+ parameters: [
409
+ {
410
+ name: "name",
411
+ in: "path",
412
+ required: true,
413
+ description: "Operation slug.",
414
+ schema: { type: "string" },
415
+ },
416
+ ],
417
+ responses: {
418
+ "200": {
419
+ description: "Operation detail",
420
+ content: {
421
+ "application/json": {
422
+ schema: {
423
+ type: "object",
424
+ properties: {
425
+ id: { type: "string" },
426
+ type: { type: "string", enum: ["query", "mutation"] },
427
+ description: { type: "string" },
428
+ instruction: { type: "string" },
429
+ input: { type: "object" },
430
+ response: { type: "object" },
431
+ auth: {
432
+ type: "string",
433
+ enum: ["none", "optional", "required"],
434
+ },
435
+ operations: {
436
+ type: "array",
437
+ description:
438
+ "Present when includeOperationsInDetail is enabled on gptRoutes.",
439
+ items: {
440
+ type: "object",
441
+ properties: {
442
+ id: { type: "string" },
443
+ type: { type: "string", enum: ["query", "mutation"] },
444
+ description: { type: "string" },
445
+ auth: {
446
+ type: "string",
447
+ enum: ["none", "optional", "required"],
448
+ },
449
+ },
450
+ },
451
+ },
452
+ },
453
+ },
454
+ },
455
+ },
456
+ },
457
+ "404": {
458
+ description: "Unknown operation",
459
+ },
460
+ },
461
+ } as Operation,
462
+ };
463
+ void successResponse;
464
+ }
465
+
466
+ function emitParametric(
467
+ paths: Record<string, PathItem>,
468
+ basePath: string,
469
+ authedSec: Sec,
470
+ noSec: Sec,
471
+ ops: ReturnType<Registry["list"]>,
472
+ ctx: {
473
+ includeDescription: boolean;
474
+ maxDescriptionLength: number;
475
+ variablesParam: Record<string, unknown>;
476
+ variablesBody: Record<string, unknown>;
477
+ successResponse: Record<string, unknown>;
478
+ },
479
+ ): void {
480
+ const queryIds = ops.filter((o) => o.type === "query").map((o) => o.id);
481
+ const mutationIds = ops.filter((o) => o.type === "mutation").map((o) => o.id);
482
+ const authedQueryIds = ops
483
+ .filter((o) => o.type === "query" && (o.auth ?? "required") !== "none")
484
+ .map((o) => o.id);
485
+ const authedMutationIds = ops
486
+ .filter((o) => o.type === "mutation" && (o.auth ?? "required") !== "none")
487
+ .map((o) => o.id);
488
+ const publicQueryIds = ops
489
+ .filter((o) => o.type === "query" && (o.auth ?? "required") !== "required")
490
+ .map((o) => o.id);
491
+ const publicMutationIds = ops
492
+ .filter(
493
+ (o) => o.type === "mutation" && (o.auth ?? "required") !== "required",
494
+ )
495
+ .map((o) => o.id);
496
+
497
+ const opParam = (enumIds: string[]): Record<string, unknown> => ({
498
+ name: "operation",
499
+ in: "path",
500
+ required: true,
501
+ description: `Operation slug. One of: ${enumIds.join(", ")}.`,
502
+ schema: { type: "string", enum: enumIds },
503
+ });
504
+
505
+ const make = (
506
+ opName: string,
507
+ summary: string,
508
+ _method: "get" | "post",
509
+ security: Sec,
510
+ enumIds: string[],
511
+ bodyBased: boolean,
512
+ description: string,
513
+ ): Operation => {
514
+ const entry: Operation = {
515
+ operationId: opName,
516
+ summary: truncate(summary, 120),
517
+ security,
518
+ responses: ctx.successResponse as Record<string, unknown>,
519
+ parameters: bodyBased
520
+ ? [opParam(enumIds)]
521
+ : [opParam(enumIds), ctx.variablesParam],
522
+ };
523
+ if (ctx.includeDescription) {
524
+ entry.description = truncate(description, ctx.maxDescriptionLength);
525
+ }
526
+ if (bodyBased) entry.requestBody = ctx.variablesBody;
527
+ return entry;
528
+ };
529
+
530
+ if (queryIds.length) {
531
+ if (authedQueryIds.length) {
532
+ paths[`${basePath}/query/{operation}`] = {
533
+ get: make(
534
+ "queryOperation",
535
+ "Execute a query operation",
536
+ "get",
537
+ authedSec,
538
+ authedQueryIds,
539
+ false,
540
+ "Execute a read-only query by name. Pass variables as a JSON or TOON string in $variables.",
541
+ ),
542
+ };
543
+ }
544
+ if (publicQueryIds.length) {
545
+ paths[`${basePath}/public/query/{operation}`] = {
546
+ get: make(
547
+ "publicQueryOperation",
548
+ "Execute a public query operation",
549
+ "get",
550
+ noSec,
551
+ publicQueryIds,
552
+ false,
553
+ "Execute a public query by name — no authentication required.",
554
+ ),
555
+ };
556
+ }
557
+ }
558
+
559
+ if (mutationIds.length) {
560
+ if (authedMutationIds.length) {
561
+ paths[`${basePath}/mutate/{operation}`] = {
562
+ post: make(
563
+ "mutateOperation",
564
+ "Execute a mutation operation",
565
+ "post",
566
+ authedSec,
567
+ authedMutationIds,
568
+ true,
569
+ "Execute a mutation by name. Pass variables in the JSON body's $variables field.",
570
+ ),
571
+ };
572
+ }
573
+ if (publicMutationIds.length) {
574
+ paths[`${basePath}/public/mutate/{operation}`] = {
575
+ post: make(
576
+ "publicMutateOperation",
577
+ "Execute a public mutation operation",
578
+ "post",
579
+ noSec,
580
+ publicMutationIds,
581
+ true,
582
+ "Execute a public mutation by name — no authentication required.",
583
+ ),
584
+ };
585
+ }
586
+ }
234
587
  }