@iadev93/zuno-express 0.0.12 → 0.0.13

package/README.md

@@ -22,12 +22,18 @@ Peer dependency:
 ```ts
 import express from "express";
 import { createZunoExpress } from "@iadev93/zuno-express";
+import { createZunoServerState } from "@iadev93/zuno/server";
 
 const app = express();
 app.use(express.json());
 
+const server = createZunoServerState();
 const zuno = createZunoExpress({
-  batchSync: true // Optional: Enable batching
+  server,
+  authorize: ({ request, action }) => {
+    // Replace with your session, API-key, or tenant policy.
+    return Boolean(request.user) && (action === "read" || request.user.canWrite);
+  },
 });
 
 // Unified handlers
@@ -46,6 +52,10 @@ app.listen(3000);
 
 Returns an object containing the following Express handlers:
 
+Each call creates isolated server state by default. Pass `server` when several routers or custom endpoints must share the same authoritative universe. The returned object exposes the selected instance as `zuno.server`.
+
+The optional `authorize` hook runs before SSE/snapshot reads and mutation writes. Returning `false` produces a `403 FORBIDDEN` response without reading or mutating server state.
+
 #### `sse` (GET)
 Handles persistent SSE connections, heartbeats, and initial synchronization.
 

package/dist/index.d.mts

@@ -1,18 +1,29 @@
 import { IncomingHttpHeaders } from 'node:http';
+import { ZunoServerState } from '@iadev93/zuno/server';
 import { Request, Response } from 'express';
 
+type ZunoExpressAuthorizationContext = {
+    action: "read" | "write";
+    request: Request;
+    event?: unknown;
+};
 /**
  * Options for creating an Express router for Zuno.
  */
 type CreateZunoExpressOptions = {
     /** Optional custom headers to be sent with the SSE response. */
     headers?: IncomingHttpHeaders;
+    /** Isolated authoritative server state. A new instance is created by default. */
+    server?: ZunoServerState;
+    /** Provider-agnostic authorization hook for snapshots, SSE, and mutations. */
+    authorize?: (context: ZunoExpressAuthorizationContext) => boolean | Promise<boolean>;
 };
 /**
  * Creates a Zuno Express instance.
  * Returns both granular handlers and a convenience `mount` helper.
  */
 declare function createZunoExpress(opts?: CreateZunoExpressOptions): {
+    server: ZunoServerState;
     /**
      * Optional convenience method to mount all Zuno handlers at once.
      * @param app The Express App or Router to mount the handlers on.
@@ -26,17 +37,17 @@ declare function createZunoExpress(opts?: CreateZunoExpressOptions): {
      * SSE connection handler.
      * Usage: app.get('/custom/sse', zuno.sse);
      */
-    sse: (req: Request, res: Response) => void;
+    sse: (req: Request, res: Response) => Promise<void>;
     /**
      * Sync POST handler.
      * Usage: app.post('/custom/sync', zuno.sync);
      */
-    sync: (req: Request, res: Response) => void;
+    sync: (req: Request, res: Response) => Promise<void>;
     /**
      * Snapshot GET handler.
      * Usage: app.get('/custom/snapshot', zuno.snapshot);
      */
-    snapshot: (req: Request, res: Response) => void;
+    snapshot: (req: Request, res: Response) => Promise<void>;
 };
 /**
  * A standalone helper to mount Zuno handlers on an Express app/router.
@@ -47,6 +58,7 @@ declare function mountZuno(app: {
 }, opts?: CreateZunoExpressOptions & {
     basePath?: string;
 }): {
+    server: ZunoServerState;
     /**
      * Optional convenience method to mount all Zuno handlers at once.
      * @param app The Express App or Router to mount the handlers on.
@@ -60,17 +72,17 @@ declare function mountZuno(app: {
      * SSE connection handler.
      * Usage: app.get('/custom/sse', zuno.sse);
      */
-    sse: (req: Request, res: Response) => void;
+    sse: (req: Request, res: Response) => Promise<void>;
     /**
      * Sync POST handler.
      * Usage: app.post('/custom/sync', zuno.sync);
      */
-    sync: (req: Request, res: Response) => void;
+    sync: (req: Request, res: Response) => Promise<void>;
     /**
      * Snapshot GET handler.
      * Usage: app.get('/custom/snapshot', zuno.snapshot);
      */
-    snapshot: (req: Request, res: Response) => void;
+    snapshot: (req: Request, res: Response) => Promise<void>;
 };
 
-export { type CreateZunoExpressOptions, createZunoExpress, mountZuno };
+export { type CreateZunoExpressOptions, type ZunoExpressAuthorizationContext, createZunoExpress, mountZuno };

package/dist/index.d.ts

@@ -1,18 +1,29 @@
 import { IncomingHttpHeaders } from 'node:http';
+import { ZunoServerState } from '@iadev93/zuno/server';
 import { Request, Response } from 'express';
 
+type ZunoExpressAuthorizationContext = {
+    action: "read" | "write";
+    request: Request;
+    event?: unknown;
+};
 /**
  * Options for creating an Express router for Zuno.
  */
 type CreateZunoExpressOptions = {
     /** Optional custom headers to be sent with the SSE response. */
     headers?: IncomingHttpHeaders;
+    /** Isolated authoritative server state. A new instance is created by default. */
+    server?: ZunoServerState;
+    /** Provider-agnostic authorization hook for snapshots, SSE, and mutations. */
+    authorize?: (context: ZunoExpressAuthorizationContext) => boolean | Promise<boolean>;
 };
 /**
  * Creates a Zuno Express instance.
  * Returns both granular handlers and a convenience `mount` helper.
  */
 declare function createZunoExpress(opts?: CreateZunoExpressOptions): {
+    server: ZunoServerState;
     /**
      * Optional convenience method to mount all Zuno handlers at once.
      * @param app The Express App or Router to mount the handlers on.
@@ -26,17 +37,17 @@ declare function createZunoExpress(opts?: CreateZunoExpressOptions): {
      * SSE connection handler.
      * Usage: app.get('/custom/sse', zuno.sse);
      */
-    sse: (req: Request, res: Response) => void;
+    sse: (req: Request, res: Response) => Promise<void>;
     /**
      * Sync POST handler.
      * Usage: app.post('/custom/sync', zuno.sync);
      */
-    sync: (req: Request, res: Response) => void;
+    sync: (req: Request, res: Response) => Promise<void>;
     /**
      * Snapshot GET handler.
      * Usage: app.get('/custom/snapshot', zuno.snapshot);
      */
-    snapshot: (req: Request, res: Response) => void;
+    snapshot: (req: Request, res: Response) => Promise<void>;
 };
 /**
  * A standalone helper to mount Zuno handlers on an Express app/router.
@@ -47,6 +58,7 @@ declare function mountZuno(app: {
 }, opts?: CreateZunoExpressOptions & {
     basePath?: string;
 }): {
+    server: ZunoServerState;
     /**
      * Optional convenience method to mount all Zuno handlers at once.
      * @param app The Express App or Router to mount the handlers on.
@@ -60,17 +72,17 @@ declare function mountZuno(app: {
      * SSE connection handler.
      * Usage: app.get('/custom/sse', zuno.sse);
      */
-    sse: (req: Request, res: Response) => void;
+    sse: (req: Request, res: Response) => Promise<void>;
     /**
      * Sync POST handler.
      * Usage: app.post('/custom/sync', zuno.sync);
      */
-    sync: (req: Request, res: Response) => void;
+    sync: (req: Request, res: Response) => Promise<void>;
     /**
      * Snapshot GET handler.
      * Usage: app.get('/custom/snapshot', zuno.snapshot);
      */
-    snapshot: (req: Request, res: Response) => void;
+    snapshot: (req: Request, res: Response) => Promise<void>;
 };
 
-export { type CreateZunoExpressOptions, createZunoExpress, mountZuno };
+export { type CreateZunoExpressOptions, type ZunoExpressAuthorizationContext, createZunoExpress, mountZuno };

package/dist/index.js

@@ -1,2 +1,2 @@
-'use strict';var server=require('@iadev93/zuno/server');function i(o){let{headers:r={}}=o??{},t={sse:(e,n)=>server.createSSEConnection(e,n,r),sync:(e,n)=>{let u=e.body,s=server.applyStateEvent(u);if(!s.ok){n.status(409).json({ok:false,reason:s.reason,current:s.current});return}n.status(200).json({ok:true,event:s.event});},snapshot:(e,n)=>server.sendSnapshot(e,n)};return {...t,mount:(e,n="/zuno")=>{e.get(`${n}/sse`,t.sse),e.get(`${n}/snapshot`,t.snapshot),e.post(`${n}/sync`,t.sync);}}}function g(o,r){let{basePath:t="/zuno",...e}=r??{},n=i(e);return n.mount(o,t),n}exports.createZunoExpress=i;exports.mountZuno=g;//# sourceMappingURL=index.js.map
+'use strict';var server=require('@iadev93/zuno/server');function x(u){let{headers:i={},server:o=server.createZunoServerState(),authorize:r=()=>true}=u??{},s=e=>e.status(403).json({ok:false,reason:"FORBIDDEN"}),a={sse:async(e,n)=>{if(!await r({action:"read",request:e})){s(n);return}server.createSSEConnection(e,n,i,o);},sync:async(e,n)=>{let p=e.body;if(!await r({action:"write",request:e,event:p})){s(n);return}let t=server.applyStateEvent(p,o);if(!t.ok){n.status(t.reason==="VERSION_CONFLICT"?409:400).json({ok:false,reason:t.reason,...t.reason==="VERSION_CONFLICT"?{current:t.current}:{errors:t.errors}});return}n.status(200).json({ok:true,event:t.event});},snapshot:async(e,n)=>{if(!await r({action:"read",request:e})){s(n);return}server.sendSnapshot(e,n,o);}};return {...a,server:o,mount:(e,n="/zuno")=>{e.get(`${n}/sse`,a.sse),e.get(`${n}/snapshot`,a.snapshot),e.post(`${n}/sync`,a.sync);}}}function S(u,i){let{basePath:o="/zuno",...r}=i??{},s=x(r);return s.mount(u,o),s}exports.createZunoExpress=x;exports.mountZuno=S;//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"names":["createZunoExpress","opts","headers","handlers","req","res","createSSEConnection","incoming","result","applyStateEvent","sendSnapshot","app","basePath","mountZuno","rest","zuno"],"mappings":"wDAqBO,SAASA,CAAAA,CAAkBC,EAAiC,CAClE,GAAM,CAAE,OAAA,CAAAC,EAAU,EAAG,CAAA,CAAID,CAAAA,EAAQ,EAAC,CAM5BE,CAAAA,CAAW,CAKhB,GAAA,CAAK,CAACC,CAAAA,CAAcC,CAAAA,GACnBC,0BAAAA,CAAoBF,CAAAA,CAAKC,EAAKH,CAAO,CAAA,CAMtC,IAAA,CAAM,CAACE,EAAcC,CAAAA,GAAkB,CACtC,IAAME,CAAAA,CAAWH,EAAI,IAAA,CACfI,CAAAA,CAASC,sBAAAA,CAAgBF,CAAQ,EAEvC,GAAI,CAACC,CAAAA,CAAO,EAAA,CAAI,CACfH,CAAAA,CAAI,MAAA,CAAO,GAAG,CAAA,CAAE,KAAK,CACpB,EAAA,CAAI,KAAA,CACJ,MAAA,CAAQG,EAAO,MAAA,CACf,OAAA,CAASA,CAAAA,CAAO,OACjB,CAAC,CAAA,CACD,MACD,CAEAH,CAAAA,CAAI,OAAO,GAAG,CAAA,CAAE,IAAA,CAAK,CAAE,GAAI,IAAA,CAAM,KAAA,CAAOG,CAAAA,CAAO,KAAM,CAAC,EACvD,CAAA,CAMA,QAAA,CAAU,CAACJ,CAAAA,CAAcC,CAAAA,GAAkBK,mBAAAA,CAAaN,CAAAA,CAAKC,CAAG,CACjE,CAAA,CAEA,OAAO,CACN,GAAGF,CAAAA,CAMH,KAAA,CAAO,CACNQ,CAAAA,CAIAC,EAAW,OAAA,GACP,CACJD,CAAAA,CAAI,GAAA,CAAI,GAAGC,CAAQ,CAAA,IAAA,CAAA,CAAQT,CAAAA,CAAS,GAAG,EACvCQ,CAAAA,CAAI,GAAA,CAAI,CAAA,EAAGC,CAAQ,YAAaT,CAAAA,CAAS,QAAQ,CAAA,CACjDQ,CAAAA,CAAI,KAAK,CAAA,EAAGC,CAAQ,CAAA,KAAA,CAAA,CAAST,CAAAA,CAAS,IAAI,EAC3C,CACD,CACD,CAKO,SAASU,CAAAA,CACfF,CAAAA,CAIAV,CAAAA,CACC,CACD,GAAM,CAAE,QAAA,CAAAW,CAAAA,CAAW,OAAA,CAAS,GAAGE,CAAK,CAAA,CAAIb,CAAAA,EAAQ,GAC1Cc,CAAAA,CAAOf,CAAAA,CAAkBc,CAAI,CAAA,CACnC,OAAAC,CAAAA,CAAK,KAAA,CAAMJ,CAAAA,CAAKC,CAAQ,EACjBG,CACR","file":"index.js","sourcesContent":["import type { IncomingHttpHeaders } from \"node:http\";\nimport type { ZunoStateEvent } from \"@iadev93/zuno\";\nimport {\n\tapplyStateEvent,\n\tcreateSSEConnection,\n\tsendSnapshot,\n} from \"@iadev93/zuno/server\";\nimport type { Request, Response } from \"express\";\n\n/**\n * Options for creating an Express router for Zuno.\n */\nexport type CreateZunoExpressOptions = {\n\t/** Optional custom headers to be sent with the SSE response. */\n\theaders?: IncomingHttpHeaders;\n};\n\n/**\n * Creates a Zuno Express instance.\n * Returns both granular handlers and a convenience `mount` helper.\n */\nexport function createZunoExpress(opts?: CreateZunoExpressOptions) {\n\tconst { headers = {} } = opts ?? {};\n\n\t/**\n\t * Granular handlers for maximum control.\n\t * You can mount these manually to any route or wrap them in custom middleware.\n\t */\n\tconst handlers = {\n\t\t/**\n\t\t * SSE connection handler.\n\t\t * Usage: app.get('/custom/sse', zuno.sse);\n\t\t */\n\t\tsse: (req: Request, res: Response) =>\n\t\t\tcreateSSEConnection(req, res, headers),\n\n\t\t/**\n\t\t * Sync POST handler.\n\t\t * Usage: app.post('/custom/sync', zuno.sync);\n\t\t */\n\t\tsync: (req: Request, res: Response) => {\n\t\t\tconst incoming = req.body as ZunoStateEvent;\n\t\t\tconst result = applyStateEvent(incoming);\n\n\t\t\tif (!result.ok) {\n\t\t\t\tres.status(409).json({\n\t\t\t\t\tok: false,\n\t\t\t\t\treason: result.reason,\n\t\t\t\t\tcurrent: result.current,\n\t\t\t\t});\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tres.status(200).json({ ok: true, event: result.event });\n\t\t},\n\n\t\t/**\n\t\t * Snapshot GET handler.\n\t\t * Usage: app.get('/custom/snapshot', zuno.snapshot);\n\t\t */\n\t\tsnapshot: (req: Request, res: Response) => sendSnapshot(req, res),\n\t};\n\n\treturn {\n\t\t...handlers,\n\t\t/**\n\t\t * Optional convenience method to mount all Zuno handlers at once.\n\t\t * @param app The Express App or Router to mount the handlers on.\n\t\t * @param basePath The base path for the Zuno routes (defaults to \"/zuno\").\n\t\t */\n\t\tmount: (\n\t\t\tapp: {\n\t\t\t\tget: (...args: unknown[]) => unknown;\n\t\t\t\tpost: (...args: unknown[]) => unknown;\n\t\t\t},\n\t\t\tbasePath = \"/zuno\",\n\t\t) => {\n\t\t\tapp.get(`${basePath}/sse`, handlers.sse);\n\t\t\tapp.get(`${basePath}/snapshot`, handlers.snapshot);\n\t\t\tapp.post(`${basePath}/sync`, handlers.sync);\n\t\t},\n\t};\n}\n\n/**\n * A standalone helper to mount Zuno handlers on an Express app/router.\n */\nexport function mountZuno(\n\tapp: {\n\t\tget: (...args: unknown[]) => unknown;\n\t\tpost: (...args: unknown[]) => unknown;\n\t},\n\topts?: CreateZunoExpressOptions & { basePath?: string },\n) {\n\tconst { basePath = \"/zuno\", ...rest } = opts ?? {};\n\tconst zuno = createZunoExpress(rest);\n\tzuno.mount(app, basePath);\n\treturn zuno;\n}\n"]}
+{"version":3,"sources":["../src/index.ts"],"names":["createZunoExpress","opts","headers","server","createZunoServerState","authorize","forbidden","res","handlers","req","createSSEConnection","incoming","result","applyStateEvent","sendSnapshot","app","basePath","mountZuno","rest","zuno"],"mappings":"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","file":"index.js","sourcesContent":["import type { IncomingHttpHeaders } from \"node:http\";\nimport type { ZunoStateEvent } from \"@iadev93/zuno\";\nimport {\n\tapplyStateEvent,\n\tcreateSSEConnection,\n\tcreateZunoServerState,\n\tsendSnapshot,\n\ttype ZunoServerState,\n} from \"@iadev93/zuno/server\";\nimport type { Request, Response } from \"express\";\n\nexport type ZunoExpressAuthorizationContext = {\n\taction: \"read\" | \"write\";\n\trequest: Request;\n\tevent?: unknown;\n};\n\n/**\n * Options for creating an Express router for Zuno.\n */\nexport type CreateZunoExpressOptions = {\n\t/** Optional custom headers to be sent with the SSE response. */\n\theaders?: IncomingHttpHeaders;\n\t/** Isolated authoritative server state. A new instance is created by default. */\n\tserver?: ZunoServerState;\n\t/** Provider-agnostic authorization hook for snapshots, SSE, and mutations. */\n\tauthorize?: (\n\t\tcontext: ZunoExpressAuthorizationContext,\n\t) => boolean | Promise<boolean>;\n};\n\n/**\n * Creates a Zuno Express instance.\n * Returns both granular handlers and a convenience `mount` helper.\n */\nexport function createZunoExpress(opts?: CreateZunoExpressOptions) {\n\tconst {\n\t\theaders = {},\n\t\tserver = createZunoServerState(),\n\t\tauthorize = () => true,\n\t} = opts ?? {};\n\tconst forbidden = (res: Response) =>\n\t\tres.status(403).json({ ok: false, reason: \"FORBIDDEN\" });\n\n\t/**\n\t * Granular handlers for maximum control.\n\t * You can mount these manually to any route or wrap them in custom middleware.\n\t */\n\tconst handlers = {\n\t\t/**\n\t\t * SSE connection handler.\n\t\t * Usage: app.get('/custom/sse', zuno.sse);\n\t\t */\n\t\tsse: async (req: Request, res: Response) => {\n\t\t\tif (!(await authorize({ action: \"read\", request: req }))) {\n\t\t\t\tforbidden(res);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tcreateSSEConnection(req, res, headers, server);\n\t\t},\n\n\t\t/**\n\t\t * Sync POST handler.\n\t\t * Usage: app.post('/custom/sync', zuno.sync);\n\t\t */\n\t\tsync: async (req: Request, res: Response) => {\n\t\t\tconst incoming = req.body as ZunoStateEvent;\n\t\t\tif (\n\t\t\t\t!(await authorize({ action: \"write\", request: req, event: incoming }))\n\t\t\t) {\n\t\t\t\tforbidden(res);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tconst result = applyStateEvent(incoming, server);\n\n\t\t\tif (!result.ok) {\n\t\t\t\tres.status(result.reason === \"VERSION_CONFLICT\" ? 409 : 400).json({\n\t\t\t\t\tok: false,\n\t\t\t\t\treason: result.reason,\n\t\t\t\t\t...(result.reason === \"VERSION_CONFLICT\"\n\t\t\t\t\t\t? { current: result.current }\n\t\t\t\t\t\t: { errors: result.errors }),\n\t\t\t\t});\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tres.status(200).json({ ok: true, event: result.event });\n\t\t},\n\n\t\t/**\n\t\t * Snapshot GET handler.\n\t\t * Usage: app.get('/custom/snapshot', zuno.snapshot);\n\t\t */\n\t\tsnapshot: async (req: Request, res: Response) => {\n\t\t\tif (!(await authorize({ action: \"read\", request: req }))) {\n\t\t\t\tforbidden(res);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tsendSnapshot(req, res, server);\n\t\t},\n\t};\n\n\treturn {\n\t\t...handlers,\n\t\tserver,\n\t\t/**\n\t\t * Optional convenience method to mount all Zuno handlers at once.\n\t\t * @param app The Express App or Router to mount the handlers on.\n\t\t * @param basePath The base path for the Zuno routes (defaults to \"/zuno\").\n\t\t */\n\t\tmount: (\n\t\t\tapp: {\n\t\t\t\tget: (...args: unknown[]) => unknown;\n\t\t\t\tpost: (...args: unknown[]) => unknown;\n\t\t\t},\n\t\t\tbasePath = \"/zuno\",\n\t\t) => {\n\t\t\tapp.get(`${basePath}/sse`, handlers.sse);\n\t\t\tapp.get(`${basePath}/snapshot`, handlers.snapshot);\n\t\t\tapp.post(`${basePath}/sync`, handlers.sync);\n\t\t},\n\t};\n}\n\n/**\n * A standalone helper to mount Zuno handlers on an Express app/router.\n */\nexport function mountZuno(\n\tapp: {\n\t\tget: (...args: unknown[]) => unknown;\n\t\tpost: (...args: unknown[]) => unknown;\n\t},\n\topts?: CreateZunoExpressOptions & { basePath?: string },\n) {\n\tconst { basePath = \"/zuno\", ...rest } = opts ?? {};\n\tconst zuno = createZunoExpress(rest);\n\tzuno.mount(app, basePath);\n\treturn zuno;\n}\n"]}

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import {sendSnapshot,createSSEConnection,applyStateEvent}from'@iadev93/zuno/server';function i(o){let{headers:r={}}=o??{},t={sse:(e,n)=>createSSEConnection(e,n,r),sync:(e,n)=>{let u=e.body,s=applyStateEvent(u);if(!s.ok){n.status(409).json({ok:false,reason:s.reason,current:s.current});return}n.status(200).json({ok:true,event:s.event});},snapshot:(e,n)=>sendSnapshot(e,n)};return {...t,mount:(e,n="/zuno")=>{e.get(`${n}/sse`,t.sse),e.get(`${n}/snapshot`,t.snapshot),e.post(`${n}/sync`,t.sync);}}}function g(o,r){let{basePath:t="/zuno",...e}=r??{},n=i(e);return n.mount(o,t),n}export{i as createZunoExpress,g as mountZuno};//# sourceMappingURL=index.mjs.map
+import {createZunoServerState,sendSnapshot,applyStateEvent,createSSEConnection}from'@iadev93/zuno/server';function x(u){let{headers:i={},server:o=createZunoServerState(),authorize:r=()=>true}=u??{},s=e=>e.status(403).json({ok:false,reason:"FORBIDDEN"}),a={sse:async(e,n)=>{if(!await r({action:"read",request:e})){s(n);return}createSSEConnection(e,n,i,o);},sync:async(e,n)=>{let p=e.body;if(!await r({action:"write",request:e,event:p})){s(n);return}let t=applyStateEvent(p,o);if(!t.ok){n.status(t.reason==="VERSION_CONFLICT"?409:400).json({ok:false,reason:t.reason,...t.reason==="VERSION_CONFLICT"?{current:t.current}:{errors:t.errors}});return}n.status(200).json({ok:true,event:t.event});},snapshot:async(e,n)=>{if(!await r({action:"read",request:e})){s(n);return}sendSnapshot(e,n,o);}};return {...a,server:o,mount:(e,n="/zuno")=>{e.get(`${n}/sse`,a.sse),e.get(`${n}/snapshot`,a.snapshot),e.post(`${n}/sync`,a.sync);}}}function S(u,i){let{basePath:o="/zuno",...r}=i??{},s=x(r);return s.mount(u,o),s}export{x as createZunoExpress,S as mountZuno};//# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"names":["createZunoExpress","opts","headers","handlers","req","res","createSSEConnection","incoming","result","applyStateEvent","sendSnapshot","app","basePath","mountZuno","rest","zuno"],"mappings":"oFAqBO,SAASA,CAAAA,CAAkBC,EAAiC,CAClE,GAAM,CAAE,OAAA,CAAAC,EAAU,EAAG,CAAA,CAAID,CAAAA,EAAQ,EAAC,CAM5BE,CAAAA,CAAW,CAKhB,GAAA,CAAK,CAACC,CAAAA,CAAcC,CAAAA,GACnBC,mBAAAA,CAAoBF,CAAAA,CAAKC,EAAKH,CAAO,CAAA,CAMtC,IAAA,CAAM,CAACE,EAAcC,CAAAA,GAAkB,CACtC,IAAME,CAAAA,CAAWH,EAAI,IAAA,CACfI,CAAAA,CAASC,eAAAA,CAAgBF,CAAQ,EAEvC,GAAI,CAACC,CAAAA,CAAO,EAAA,CAAI,CACfH,CAAAA,CAAI,MAAA,CAAO,GAAG,CAAA,CAAE,KAAK,CACpB,EAAA,CAAI,KAAA,CACJ,MAAA,CAAQG,EAAO,MAAA,CACf,OAAA,CAASA,CAAAA,CAAO,OACjB,CAAC,CAAA,CACD,MACD,CAEAH,CAAAA,CAAI,OAAO,GAAG,CAAA,CAAE,IAAA,CAAK,CAAE,GAAI,IAAA,CAAM,KAAA,CAAOG,CAAAA,CAAO,KAAM,CAAC,EACvD,CAAA,CAMA,QAAA,CAAU,CAACJ,CAAAA,CAAcC,CAAAA,GAAkBK,YAAAA,CAAaN,CAAAA,CAAKC,CAAG,CACjE,CAAA,CAEA,OAAO,CACN,GAAGF,CAAAA,CAMH,KAAA,CAAO,CACNQ,CAAAA,CAIAC,EAAW,OAAA,GACP,CACJD,CAAAA,CAAI,GAAA,CAAI,GAAGC,CAAQ,CAAA,IAAA,CAAA,CAAQT,CAAAA,CAAS,GAAG,EACvCQ,CAAAA,CAAI,GAAA,CAAI,CAAA,EAAGC,CAAQ,YAAaT,CAAAA,CAAS,QAAQ,CAAA,CACjDQ,CAAAA,CAAI,KAAK,CAAA,EAAGC,CAAQ,CAAA,KAAA,CAAA,CAAST,CAAAA,CAAS,IAAI,EAC3C,CACD,CACD,CAKO,SAASU,CAAAA,CACfF,CAAAA,CAIAV,CAAAA,CACC,CACD,GAAM,CAAE,QAAA,CAAAW,CAAAA,CAAW,OAAA,CAAS,GAAGE,CAAK,CAAA,CAAIb,CAAAA,EAAQ,GAC1Cc,CAAAA,CAAOf,CAAAA,CAAkBc,CAAI,CAAA,CACnC,OAAAC,CAAAA,CAAK,KAAA,CAAMJ,CAAAA,CAAKC,CAAQ,EACjBG,CACR","file":"index.mjs","sourcesContent":["import type { IncomingHttpHeaders } from \"node:http\";\nimport type { ZunoStateEvent } from \"@iadev93/zuno\";\nimport {\n\tapplyStateEvent,\n\tcreateSSEConnection,\n\tsendSnapshot,\n} from \"@iadev93/zuno/server\";\nimport type { Request, Response } from \"express\";\n\n/**\n * Options for creating an Express router for Zuno.\n */\nexport type CreateZunoExpressOptions = {\n\t/** Optional custom headers to be sent with the SSE response. */\n\theaders?: IncomingHttpHeaders;\n};\n\n/**\n * Creates a Zuno Express instance.\n * Returns both granular handlers and a convenience `mount` helper.\n */\nexport function createZunoExpress(opts?: CreateZunoExpressOptions) {\n\tconst { headers = {} } = opts ?? {};\n\n\t/**\n\t * Granular handlers for maximum control.\n\t * You can mount these manually to any route or wrap them in custom middleware.\n\t */\n\tconst handlers = {\n\t\t/**\n\t\t * SSE connection handler.\n\t\t * Usage: app.get('/custom/sse', zuno.sse);\n\t\t */\n\t\tsse: (req: Request, res: Response) =>\n\t\t\tcreateSSEConnection(req, res, headers),\n\n\t\t/**\n\t\t * Sync POST handler.\n\t\t * Usage: app.post('/custom/sync', zuno.sync);\n\t\t */\n\t\tsync: (req: Request, res: Response) => {\n\t\t\tconst incoming = req.body as ZunoStateEvent;\n\t\t\tconst result = applyStateEvent(incoming);\n\n\t\t\tif (!result.ok) {\n\t\t\t\tres.status(409).json({\n\t\t\t\t\tok: false,\n\t\t\t\t\treason: result.reason,\n\t\t\t\t\tcurrent: result.current,\n\t\t\t\t});\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tres.status(200).json({ ok: true, event: result.event });\n\t\t},\n\n\t\t/**\n\t\t * Snapshot GET handler.\n\t\t * Usage: app.get('/custom/snapshot', zuno.snapshot);\n\t\t */\n\t\tsnapshot: (req: Request, res: Response) => sendSnapshot(req, res),\n\t};\n\n\treturn {\n\t\t...handlers,\n\t\t/**\n\t\t * Optional convenience method to mount all Zuno handlers at once.\n\t\t * @param app The Express App or Router to mount the handlers on.\n\t\t * @param basePath The base path for the Zuno routes (defaults to \"/zuno\").\n\t\t */\n\t\tmount: (\n\t\t\tapp: {\n\t\t\t\tget: (...args: unknown[]) => unknown;\n\t\t\t\tpost: (...args: unknown[]) => unknown;\n\t\t\t},\n\t\t\tbasePath = \"/zuno\",\n\t\t) => {\n\t\t\tapp.get(`${basePath}/sse`, handlers.sse);\n\t\t\tapp.get(`${basePath}/snapshot`, handlers.snapshot);\n\t\t\tapp.post(`${basePath}/sync`, handlers.sync);\n\t\t},\n\t};\n}\n\n/**\n * A standalone helper to mount Zuno handlers on an Express app/router.\n */\nexport function mountZuno(\n\tapp: {\n\t\tget: (...args: unknown[]) => unknown;\n\t\tpost: (...args: unknown[]) => unknown;\n\t},\n\topts?: CreateZunoExpressOptions & { basePath?: string },\n) {\n\tconst { basePath = \"/zuno\", ...rest } = opts ?? {};\n\tconst zuno = createZunoExpress(rest);\n\tzuno.mount(app, basePath);\n\treturn zuno;\n}\n"]}
+{"version":3,"sources":["../src/index.ts"],"names":["createZunoExpress","opts","headers","server","createZunoServerState","authorize","forbidden","res","handlers","req","createSSEConnection","incoming","result","applyStateEvent","sendSnapshot","app","basePath","mountZuno","rest","zuno"],"mappings":"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","file":"index.mjs","sourcesContent":["import type { IncomingHttpHeaders } from \"node:http\";\nimport type { ZunoStateEvent } from \"@iadev93/zuno\";\nimport {\n\tapplyStateEvent,\n\tcreateSSEConnection,\n\tcreateZunoServerState,\n\tsendSnapshot,\n\ttype ZunoServerState,\n} from \"@iadev93/zuno/server\";\nimport type { Request, Response } from \"express\";\n\nexport type ZunoExpressAuthorizationContext = {\n\taction: \"read\" | \"write\";\n\trequest: Request;\n\tevent?: unknown;\n};\n\n/**\n * Options for creating an Express router for Zuno.\n */\nexport type CreateZunoExpressOptions = {\n\t/** Optional custom headers to be sent with the SSE response. */\n\theaders?: IncomingHttpHeaders;\n\t/** Isolated authoritative server state. A new instance is created by default. */\n\tserver?: ZunoServerState;\n\t/** Provider-agnostic authorization hook for snapshots, SSE, and mutations. */\n\tauthorize?: (\n\t\tcontext: ZunoExpressAuthorizationContext,\n\t) => boolean | Promise<boolean>;\n};\n\n/**\n * Creates a Zuno Express instance.\n * Returns both granular handlers and a convenience `mount` helper.\n */\nexport function createZunoExpress(opts?: CreateZunoExpressOptions) {\n\tconst {\n\t\theaders = {},\n\t\tserver = createZunoServerState(),\n\t\tauthorize = () => true,\n\t} = opts ?? {};\n\tconst forbidden = (res: Response) =>\n\t\tres.status(403).json({ ok: false, reason: \"FORBIDDEN\" });\n\n\t/**\n\t * Granular handlers for maximum control.\n\t * You can mount these manually to any route or wrap them in custom middleware.\n\t */\n\tconst handlers = {\n\t\t/**\n\t\t * SSE connection handler.\n\t\t * Usage: app.get('/custom/sse', zuno.sse);\n\t\t */\n\t\tsse: async (req: Request, res: Response) => {\n\t\t\tif (!(await authorize({ action: \"read\", request: req }))) {\n\t\t\t\tforbidden(res);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tcreateSSEConnection(req, res, headers, server);\n\t\t},\n\n\t\t/**\n\t\t * Sync POST handler.\n\t\t * Usage: app.post('/custom/sync', zuno.sync);\n\t\t */\n\t\tsync: async (req: Request, res: Response) => {\n\t\t\tconst incoming = req.body as ZunoStateEvent;\n\t\t\tif (\n\t\t\t\t!(await authorize({ action: \"write\", request: req, event: incoming }))\n\t\t\t) {\n\t\t\t\tforbidden(res);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tconst result = applyStateEvent(incoming, server);\n\n\t\t\tif (!result.ok) {\n\t\t\t\tres.status(result.reason === \"VERSION_CONFLICT\" ? 409 : 400).json({\n\t\t\t\t\tok: false,\n\t\t\t\t\treason: result.reason,\n\t\t\t\t\t...(result.reason === \"VERSION_CONFLICT\"\n\t\t\t\t\t\t? { current: result.current }\n\t\t\t\t\t\t: { errors: result.errors }),\n\t\t\t\t});\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tres.status(200).json({ ok: true, event: result.event });\n\t\t},\n\n\t\t/**\n\t\t * Snapshot GET handler.\n\t\t * Usage: app.get('/custom/snapshot', zuno.snapshot);\n\t\t */\n\t\tsnapshot: async (req: Request, res: Response) => {\n\t\t\tif (!(await authorize({ action: \"read\", request: req }))) {\n\t\t\t\tforbidden(res);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tsendSnapshot(req, res, server);\n\t\t},\n\t};\n\n\treturn {\n\t\t...handlers,\n\t\tserver,\n\t\t/**\n\t\t * Optional convenience method to mount all Zuno handlers at once.\n\t\t * @param app The Express App or Router to mount the handlers on.\n\t\t * @param basePath The base path for the Zuno routes (defaults to \"/zuno\").\n\t\t */\n\t\tmount: (\n\t\t\tapp: {\n\t\t\t\tget: (...args: unknown[]) => unknown;\n\t\t\t\tpost: (...args: unknown[]) => unknown;\n\t\t\t},\n\t\t\tbasePath = \"/zuno\",\n\t\t) => {\n\t\t\tapp.get(`${basePath}/sse`, handlers.sse);\n\t\t\tapp.get(`${basePath}/snapshot`, handlers.snapshot);\n\t\t\tapp.post(`${basePath}/sync`, handlers.sync);\n\t\t},\n\t};\n}\n\n/**\n * A standalone helper to mount Zuno handlers on an Express app/router.\n */\nexport function mountZuno(\n\tapp: {\n\t\tget: (...args: unknown[]) => unknown;\n\t\tpost: (...args: unknown[]) => unknown;\n\t},\n\topts?: CreateZunoExpressOptions & { basePath?: string },\n) {\n\tconst { basePath = \"/zuno\", ...rest } = opts ?? {};\n\tconst zuno = createZunoExpress(rest);\n\tzuno.mount(app, basePath);\n\treturn zuno;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iadev93/zuno-express",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -16,14 +16,14 @@
   },
   "peerDependencies": {
     "express": "^5.0.0",
-    "@iadev93/zuno": "0.0.10"
+    "@iadev93/zuno": "0.0.11"
   },
   "devDependencies": {
     "@types/express": "^5.0.0",
     "@types/node": "^20.0.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
-    "@iadev93/zuno": "0.0.10"
+    "@iadev93/zuno": "0.0.11"
   },
   "keywords": [
     "zuno",