@donghanh/hono 0.3.3 → 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.3",
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",
@@ -32,7 +32,7 @@ const servers = [{ url: "https://api.example.com" }];
32
32
  const basePath = "/api/gpt";
33
33
 
34
34
  describe("generateOpenApi common", () => {
35
- test("emits 3.1.0 spec with info + servers + bearerAuth + empty schemas", () => {
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,7 +46,9 @@ describe("generateOpenApi common", () => {
46
46
  type: "http",
47
47
  scheme: "bearer",
48
48
  });
49
- expect(spec.components.schemas).toEqual({});
49
+ // components.schemas always includes OperationResponse (validator requires object)
50
+ expect(typeof spec.components.schemas).toBe("object");
51
+ expect(spec.components.schemas.OperationResponse).toBeDefined();
50
52
  });
51
53
 
52
54
  test("includeDescription is off by default — no description field", () => {
@@ -106,6 +108,86 @@ describe("generateOpenApi common", () => {
106
108
  expect(s.length).toBeLessThanOrEqual(120);
107
109
  });
108
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") }),
165
+ info,
166
+ servers,
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
+
109
191
  test("custom bearerSchemeName", () => {
110
192
  const spec = generateOpenApi({
111
193
  registry: registry({ a: makeOp("a") }),
@@ -134,6 +216,7 @@ describe("generateOpenApi pathStyle: 'per-op'", () => {
134
216
  const spec = generateOpenApi({
135
217
  ...opts,
136
218
  registry: registry({ a: makeOp("a", { auth: "required" }) }),
219
+ includeDiscoveryEndpoints: false,
137
220
  }) as any;
138
221
  expect(Object.keys(spec.paths)).toEqual(["/api/gpt/query/a"]);
139
222
  expect(spec.paths["/api/gpt/query/a"].get.security).toEqual([
@@ -145,6 +228,7 @@ describe("generateOpenApi pathStyle: 'per-op'", () => {
145
228
  const spec = generateOpenApi({
146
229
  ...opts,
147
230
  registry: registry({ a: makeOp("a", { auth: "none" }) }),
231
+ includeDiscoveryEndpoints: false,
148
232
  }) as any;
149
233
  expect(Object.keys(spec.paths)).toEqual(["/api/gpt/public/query/a"]);
150
234
  expect(spec.paths["/api/gpt/public/query/a"].get.security).toEqual([]);
@@ -154,6 +238,7 @@ describe("generateOpenApi pathStyle: 'per-op'", () => {
154
238
  const spec = generateOpenApi({
155
239
  ...opts,
156
240
  registry: registry({ a: makeOp("a", { auth: "optional" }) }),
241
+ includeDiscoveryEndpoints: false,
157
242
  }) as any;
158
243
  const ks = Object.keys(spec.paths).sort();
159
244
  expect(ks).toEqual(["/api/gpt/public/query/a", "/api/gpt/query/a"]);
@@ -190,6 +275,7 @@ describe("generateOpenApi pathStyle: 'parametric' (default)", () => {
190
275
  info,
191
276
  servers,
192
277
  basePath,
278
+ includeDiscoveryEndpoints: false,
193
279
  }) as any;
194
280
  const ks = Object.keys(spec.paths);
195
281
  expect(ks).toEqual(["/api/gpt/query/{operation}"]);
@@ -209,6 +295,7 @@ describe("generateOpenApi pathStyle: 'parametric' (default)", () => {
209
295
  info,
210
296
  servers,
211
297
  basePath,
298
+ includeDiscoveryEndpoints: false,
212
299
  }) as any;
213
300
  const ks = Object.keys(spec.paths).sort();
214
301
  expect(ks).toEqual([
package/src/openapi.ts CHANGED
@@ -17,8 +17,32 @@ 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
  /**
@@ -86,6 +110,8 @@ export function generateOpenApi(config: GenerateOpenApiConfig): object {
86
110
  servers,
87
111
  basePath = "",
88
112
  bearerSchemeName = "bearerAuth",
113
+ securityScheme = { type: "http", scheme: "bearer" },
114
+ includeDiscoveryEndpoints = true,
89
115
  describeVariables = true,
90
116
  includeDescription = false,
91
117
  maxDescriptionLength = 300,
@@ -129,21 +155,7 @@ export function generateOpenApi(config: GenerateOpenApiConfig): object {
129
155
  description: "Successful response.",
130
156
  content: {
131
157
  "application/json": {
132
- schema: {
133
- type: "object",
134
- properties: {
135
- data: { type: "object" },
136
- suggestedActions: {
137
- type: "array",
138
- items: { type: "object" },
139
- },
140
- nextSteps: { type: "string" },
141
- operations: {
142
- type: "array",
143
- items: { type: "object" },
144
- },
145
- },
146
- },
158
+ schema: { $ref: "#/components/schemas/OperationResponse" },
147
159
  },
148
160
  },
149
161
  },
@@ -151,19 +163,7 @@ export function generateOpenApi(config: GenerateOpenApiConfig): object {
151
163
  description: "Validation or execution error.",
152
164
  content: {
153
165
  "application/json": {
154
- schema: {
155
- type: "object",
156
- properties: {
157
- errors: {
158
- type: "array",
159
- items: {
160
- type: "object",
161
- properties: { message: { type: "string" } },
162
- },
163
- },
164
- operationDetail: { type: "object" },
165
- },
166
- },
166
+ schema: { $ref: "#/components/schemas/OperationResponse" },
167
167
  },
168
168
  },
169
169
  },
@@ -243,21 +243,224 @@ export function generateOpenApi(config: GenerateOpenApiConfig): object {
243
243
  }
244
244
  }
245
245
 
246
+ if (includeDiscoveryEndpoints) {
247
+ emitDiscoveryEndpoints(paths, basePath, noSec, successResponse);
248
+ }
249
+
246
250
  return {
247
251
  openapi: "3.1.0",
248
252
  info,
249
253
  servers,
250
254
  paths,
251
255
  components: {
252
- schemas: {},
256
+ schemas: {
257
+ OperationResponse: operationResponseSchema,
258
+ },
253
259
  securitySchemes: {
254
- [bearerSchemeName]: {
255
- type: "http",
256
- 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"] },
289
+ },
290
+ },
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
+ },
257
311
  },
258
312
  },
259
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,
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,
260
462
  };
463
+ void successResponse;
261
464
  }
262
465
 
263
466
  function emitParametric(