@syncular/server-hono 0.0.6-224 → 0.0.6-227

package/README.md

@@ -56,6 +56,32 @@ Use a function origin only when you need dynamic policy logic.
 When `routes.websocket.allowedOrigins` is unset, realtime websocket upgrades
 inherit static `routes.cors` origins automatically.
 
+## OpenAPI and Scalar
+
+Serve a generated OpenAPI document:
+
+```ts
+import { Hono } from 'hono';
+import { createOpenAPIHandler } from '@syncular/server-hono';
+
+const app = new Hono();
+app.get('/openapi.json', createOpenAPIHandler(app, { title: 'Syncular API' }));
+```
+
+Or mount both the OpenAPI document and a Scalar reference page:
+
+```ts
+import { Hono } from 'hono';
+import { createOpenAPIDocsRoutes } from '@syncular/server-hono';
+
+const app = new Hono();
+app.route('/', createOpenAPIDocsRoutes(app, { title: 'Syncular API' }));
+```
+
+That serves:
+- `/openapi.json`
+- `/spec`
+
 ## Links
 
 - GitHub: https://github.com/syncular/syncular

package/dist/openapi.d.ts

@@ -3,8 +3,8 @@
  *
  * Provides utilities for generating and serving OpenAPI specifications.
  */
-import type { Hono } from 'hono';
-interface OpenAPIConfig {
+import { type Handler, Hono } from 'hono';
+export interface OpenAPIConfig {
     title?: string;
     version?: string;
     description?: string;
@@ -13,6 +13,15 @@ interface OpenAPIConfig {
         description?: string;
     }>;
 }
+export interface ScalarReferenceConfig {
+    url?: string;
+    cdn?: string;
+}
+export interface OpenAPIDocsRoutesConfig extends OpenAPIConfig {
+    openAPIPath?: string;
+    scalarPath?: string;
+    scalar?: ScalarReferenceConfig;
+}
 /**
  * Create an OpenAPI spec handler that can be used with Hono routes.
  *
@@ -36,10 +45,28 @@ interface OpenAPIConfig {
  * ```
  */
 export declare function createOpenAPIHandler(app: Hono, config?: OpenAPIConfig): import("hono").MiddlewareHandler<import("hono/types").BlankEnv, "/", import("hono/types").BlankInput>;
+/**
+ * Create a Scalar API reference handler that points at an OpenAPI document.
+ */
+export declare function createScalarReferenceHandler(config?: ScalarReferenceConfig): Handler;
+/**
+ * Create a small Hono app that serves both `/openapi.json` and `/spec`.
+ *
+ * @example
+ * ```typescript
+ * import { Hono } from 'hono';
+ * import { createOpenAPIDocsRoutes } from '@syncular/server-hono';
+ *
+ * const app = new Hono();
+ * app.route('/', createOpenAPIDocsRoutes(app, {
+ *   title: 'Syncular API',
+ * }));
+ * ```
+ */
+export declare function createOpenAPIDocsRoutes(app: Hono, config?: OpenAPIDocsRoutesConfig): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
 /**
  * Generate OpenAPI document from a Hono app instance.
  * This is useful for build-time spec generation.
  */
 export declare function generateOpenAPIDocument(app: Hono, config?: OpenAPIConfig): Promise<unknown>;
-export {};
 //# sourceMappingURL=openapi.d.ts.map

package/dist/openapi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAGjC,UAAU,aAAa;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACxD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,GAAE,aAAkB,yGAazE;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,IAAI,EACT,MAAM,GAAE,aAAkB,GACzB,OAAO,CAAC,OAAO,CAAC,CAalB"}
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,KAAK,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAM1C,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACxD;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,uBAAwB,SAAQ,aAAa;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,qBAAqB,CAAC;CAChC;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,GAAE,aAAkB,yGAazE;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,GAAE,qBAA0B,GACjC,OAAO,CAKT;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,IAAI,EACT,MAAM,GAAE,uBAA4B,8EAgBrC;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,IAAI,EACT,MAAM,GAAE,aAAkB,GACzB,OAAO,CAAC,OAAO,CAAC,CAalB"}

package/dist/openapi.js

@@ -3,7 +3,13 @@
  *
  * Provides utilities for generating and serving OpenAPI specifications.
  */
+import { Scalar } from '@scalar/hono-api-reference';
+import { Hono } from 'hono';
 import { generateSpecs, openAPIRouteHandler } from 'hono-openapi';
+const DEFAULT_SCALAR_CDN = 'https://cdn.jsdelivr.net/npm/@scalar/api-reference@latest';
+function normalizeRoutePath(path) {
+    return path.startsWith('/') ? path : `/${path}`;
+}
 /**
  * Create an OpenAPI spec handler that can be used with Hono routes.
  *
@@ -39,6 +45,40 @@ export function createOpenAPIHandler(app, config = {}) {
         },
     });
 }
+/**
+ * Create a Scalar API reference handler that points at an OpenAPI document.
+ */
+export function createScalarReferenceHandler(config = {}) {
+    return Scalar({
+        url: config.url ?? '/openapi.json',
+        cdn: config.cdn ?? DEFAULT_SCALAR_CDN,
+    });
+}
+/**
+ * Create a small Hono app that serves both `/openapi.json` and `/spec`.
+ *
+ * @example
+ * ```typescript
+ * import { Hono } from 'hono';
+ * import { createOpenAPIDocsRoutes } from '@syncular/server-hono';
+ *
+ * const app = new Hono();
+ * app.route('/', createOpenAPIDocsRoutes(app, {
+ *   title: 'Syncular API',
+ * }));
+ * ```
+ */
+export function createOpenAPIDocsRoutes(app, config = {}) {
+    const docsApp = new Hono();
+    const openAPIPath = normalizeRoutePath(config.openAPIPath ?? '/openapi.json');
+    const scalarPath = normalizeRoutePath(config.scalarPath ?? '/spec');
+    docsApp.get(openAPIPath, createOpenAPIHandler(app, config));
+    docsApp.get(scalarPath, createScalarReferenceHandler({
+        url: config.scalar?.url ?? openAPIPath,
+        cdn: config.scalar?.cdn,
+    }));
+    return docsApp;
+}
 /**
  * Generate OpenAPI document from a Hono app instance.
  * This is useful for build-time spec generation.

package/dist/openapi.js.map

@@ -1 +1 @@
-{"version":3,"file":"openapi.js","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AASlE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAS,EAAE,MAAM,GAAkB,EAAE,EAAE;IAC1E,OAAO,mBAAmB,CAAC,GAAG,EAAE;QAC9B,aAAa,EAAE;YACb,IAAI,EAAE;gBACJ,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,cAAc;gBACrC,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,OAAO;gBAClC,WAAW,EACT,MAAM,CAAC,WAAW;oBAClB,4DAA4D;aAC/D;YACD,OAAO,EAAE,MAAM,CAAC,OAAO;SACxB;KACF,CAAC,CAAC;AAAA,CACJ;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,GAAS,EACT,MAAM,GAAkB,EAAE,EACR;IAClB,OAAO,aAAa,CAAC,GAAG,EAAE;QACxB,aAAa,EAAE;YACb,IAAI,EAAE;gBACJ,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,cAAc;gBACrC,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,OAAO;gBAClC,WAAW,EACT,MAAM,CAAC,WAAW;oBAClB,4DAA4D;aAC/D;YACD,OAAO,EAAE,MAAM,CAAC,OAAO;SACxB;KACF,CAAC,CAAC;AAAA,CACJ"}
+{"version":3,"file":"openapi.js","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACpD,OAAO,EAAgB,IAAI,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAElE,MAAM,kBAAkB,GACtB,2DAA2D,CAAC;AAoB9D,SAAS,kBAAkB,CAAC,IAAY,EAAU;IAChD,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;AAAA,CACjD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAS,EAAE,MAAM,GAAkB,EAAE,EAAE;IAC1E,OAAO,mBAAmB,CAAC,GAAG,EAAE;QAC9B,aAAa,EAAE;YACb,IAAI,EAAE;gBACJ,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,cAAc;gBACrC,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,OAAO;gBAClC,WAAW,EACT,MAAM,CAAC,WAAW;oBAClB,4DAA4D;aAC/D;YACD,OAAO,EAAE,MAAM,CAAC,OAAO;SACxB;KACF,CAAC,CAAC;AAAA,CACJ;AAED;;GAEG;AACH,MAAM,UAAU,4BAA4B,CAC1C,MAAM,GAA0B,EAAE,EACzB;IACT,OAAO,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC,GAAG,IAAI,eAAe;QAClC,GAAG,EAAE,MAAM,CAAC,GAAG,IAAI,kBAAkB;KACtC,CAAC,CAAC;AAAA,CACJ;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,uBAAuB,CACrC,GAAS,EACT,MAAM,GAA4B,EAAE,EACpC;IACA,MAAM,OAAO,GAAG,IAAI,IAAI,EAAE,CAAC;IAC3B,MAAM,WAAW,GAAG,kBAAkB,CAAC,MAAM,CAAC,WAAW,IAAI,eAAe,CAAC,CAAC;IAC9E,MAAM,UAAU,GAAG,kBAAkB,CAAC,MAAM,CAAC,UAAU,IAAI,OAAO,CAAC,CAAC;IAEpE,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE,oBAAoB,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;IAC5D,OAAO,CAAC,GAAG,CACT,UAAU,EACV,4BAA4B,CAAC;QAC3B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,IAAI,WAAW;QACtC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG;KACxB,CAAC,CACH,CAAC;IAEF,OAAO,OAAO,CAAC;AAAA,CAChB;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,GAAS,EACT,MAAM,GAAkB,EAAE,EACR;IAClB,OAAO,aAAa,CAAC,GAAG,EAAE;QACxB,aAAa,EAAE;YACb,IAAI,EAAE;gBACJ,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,cAAc;gBACrC,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,OAAO;gBAClC,WAAW,EACT,MAAM,CAAC,WAAW;oBAClB,4DAA4D;aAC/D;YACD,OAAO,EAAE,MAAM,CAAC,OAAO;SACxB;KACF,CAAC,CAAC;AAAA,CACJ"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/server-hono",
-  "version": "0.0.6-224",
+  "version": "0.0.6-227",
   "description": "Hono adapter for the Syncular server with OpenAPI support",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -59,20 +59,21 @@
     "release": "bunx syncular-publish"
   },
   "dependencies": {
+    "@scalar/hono-api-reference": "^0.10.2",
     "@hono/standard-validator": "^0.2.2",
     "@standard-community/standard-json": "^0.3.5",
     "@standard-community/standard-openapi": "^0.2.9",
-    "@syncular/console": "0.0.6-224",
-    "@syncular/core": "0.0.6-224",
-    "@syncular/server": "0.0.6-224",
+    "@syncular/console": "0.0.6-227",
+    "@syncular/core": "0.0.6-227",
+    "@syncular/server": "0.0.6-227",
     "@types/json-schema": "^7.0.15",
     "hono-openapi": "^1.2.0",
     "openapi-types": "^12.1.3"
   },
   "devDependencies": {
     "@syncular/config": "0.0.0",
-    "@syncular/dialect-pglite": "0.0.6-224",
-    "@syncular/server-dialect-postgres": "0.0.6-224",
+    "@syncular/dialect-pglite": "0.0.6-227",
+    "@syncular/server-dialect-postgres": "0.0.6-227",
     "kysely": "*",
     "zod": "*"
   },

package/src/__tests__/openapi.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'bun:test';
+import { Hono } from 'hono';
+import {
+  createOpenAPIDocsRoutes,
+  createOpenAPIHandler,
+  createScalarReferenceHandler,
+} from '../openapi';
+
+describe('OpenAPI helpers', () => {
+  it('serves an OpenAPI document with configured metadata', async () => {
+    const sourceApp = new Hono();
+    const app = new Hono();
+
+    app.get(
+      '/openapi.json',
+      createOpenAPIHandler(sourceApp, {
+        title: 'Test API',
+        version: '1.2.3',
+        description: 'Test description',
+      })
+    );
+
+    const response = await app.request('/openapi.json');
+    expect(response.status).toBe(200);
+
+    const document = await response.json();
+    expect(document.info).toEqual({
+      title: 'Test API',
+      version: '1.2.3',
+      description: 'Test description',
+    });
+  });
+
+  it('serves a Scalar API reference that points at the configured document', async () => {
+    const app = new Hono();
+    app.get(
+      '/spec',
+      createScalarReferenceHandler({
+        url: '/docs/openapi.json',
+      })
+    );
+
+    const response = await app.request('/spec');
+    expect(response.status).toBe(200);
+
+    const html = await response.text();
+    expect(html).toContain('/docs/openapi.json');
+  });
+
+  it('creates paired OpenAPI and Scalar routes', async () => {
+    const sourceApp = new Hono();
+    const app = new Hono();
+
+    app.route(
+      '/',
+      createOpenAPIDocsRoutes(sourceApp, {
+        title: 'Docs API',
+        version: '9.9.9',
+        openAPIPath: '/api-docs.json',
+        scalarPath: '/docs',
+      })
+    );
+
+    const openApiResponse = await app.request('/api-docs.json');
+    expect(openApiResponse.status).toBe(200);
+    const document = await openApiResponse.json();
+    expect(document.info).toEqual({
+      title: 'Docs API',
+      version: '9.9.9',
+      description: 'Sync infrastructure API for real-time data synchronization',
+    });
+
+    const docsResponse = await app.request('/docs');
+    expect(docsResponse.status).toBe(200);
+    const html = await docsResponse.text();
+    expect(html).toContain('/api-docs.json');
+  });
+});

package/src/openapi.ts

@@ -4,16 +4,35 @@
  * Provides utilities for generating and serving OpenAPI specifications.
  */
 
-import type { Hono } from 'hono';
+import { Scalar } from '@scalar/hono-api-reference';
+import { type Handler, Hono } from 'hono';
 import { generateSpecs, openAPIRouteHandler } from 'hono-openapi';
 
-interface OpenAPIConfig {
+const DEFAULT_SCALAR_CDN =
+  'https://cdn.jsdelivr.net/npm/@scalar/api-reference@latest';
+
+export interface OpenAPIConfig {
   title?: string;
   version?: string;
   description?: string;
   servers?: Array<{ url: string; description?: string }>;
 }
 
+export interface ScalarReferenceConfig {
+  url?: string;
+  cdn?: string;
+}
+
+export interface OpenAPIDocsRoutesConfig extends OpenAPIConfig {
+  openAPIPath?: string;
+  scalarPath?: string;
+  scalar?: ScalarReferenceConfig;
+}
+
+function normalizeRoutePath(path: string): string {
+  return path.startsWith('/') ? path : `/${path}`;
+}
+
 /**
  * Create an OpenAPI spec handler that can be used with Hono routes.
  *
@@ -51,6 +70,52 @@ export function createOpenAPIHandler(app: Hono, config: OpenAPIConfig = {}) {
   });
 }
 
+/**
+ * Create a Scalar API reference handler that points at an OpenAPI document.
+ */
+export function createScalarReferenceHandler(
+  config: ScalarReferenceConfig = {}
+): Handler {
+  return Scalar({
+    url: config.url ?? '/openapi.json',
+    cdn: config.cdn ?? DEFAULT_SCALAR_CDN,
+  });
+}
+
+/**
+ * Create a small Hono app that serves both `/openapi.json` and `/spec`.
+ *
+ * @example
+ * ```typescript
+ * import { Hono } from 'hono';
+ * import { createOpenAPIDocsRoutes } from '@syncular/server-hono';
+ *
+ * const app = new Hono();
+ * app.route('/', createOpenAPIDocsRoutes(app, {
+ *   title: 'Syncular API',
+ * }));
+ * ```
+ */
+export function createOpenAPIDocsRoutes(
+  app: Hono,
+  config: OpenAPIDocsRoutesConfig = {}
+) {
+  const docsApp = new Hono();
+  const openAPIPath = normalizeRoutePath(config.openAPIPath ?? '/openapi.json');
+  const scalarPath = normalizeRoutePath(config.scalarPath ?? '/spec');
+
+  docsApp.get(openAPIPath, createOpenAPIHandler(app, config));
+  docsApp.get(
+    scalarPath,
+    createScalarReferenceHandler({
+      url: config.scalar?.url ?? openAPIPath,
+      cdn: config.scalar?.cdn,
+    })
+  );
+
+  return docsApp;
+}
+
 /**
  * Generate OpenAPI document from a Hono app instance.
  * This is useful for build-time spec generation.