@zooid/server 0.0.1 → 0.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zooid/server",
-  "version": "0.0.1",
+  "version": "0.0.9",
   "type": "module",
   "license": "MIT",
   "author": "Ori Ben",
@@ -21,12 +21,13 @@
     "ulidx": "^2.4.1",
     "yaml": "^2.8.2",
     "zod": "^4.3.6",
-    "@zooid/web": "0.0.1",
-    "@zooid/types": "0.0.1"
+    "@zooid/types": "0.0.9",
+    "@zooid/web": "0.0.9"
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.12.13",
     "@cloudflare/workers-types": "^4.20260217.0",
+    "@vitest/coverage-istanbul": "^3.2.4",
     "wrangler": "^4.66.0"
   },
   "scripts": {

package/src/db/queries.test.ts

@@ -120,7 +120,7 @@ describe('Event queries', () => {
       expect(result.events[0].type).toBe('signal');
     });
 
-    it('supports cursor-based pagination', async () => {
+    it('returns the most recent events when no cursor/since (tail behavior)', async () => {
       for (let i = 0; i < 5; i++) {
         await createEvent(env.DB, {
           channelId: 'test-channel',
@@ -129,7 +129,29 @@ describe('Event queries', () => {
         });
       }
 
-      const page1 = await pollEvents(env.DB, 'test-channel', { limit: 2 });
+      const result = await pollEvents(env.DB, 'test-channel', { limit: 2 });
+      expect(result.events).toHaveLength(2);
+      // Should be the last 2 events (i=3, i=4) in chronological order
+      expect(JSON.parse(result.events[0].data).i).toBe(3);
+      expect(JSON.parse(result.events[1].data).i).toBe(4);
+      expect(result.has_more).toBe(false);
+      expect(result.cursor).toBeNull();
+    });
+
+    it('supports cursor-based forward pagination', async () => {
+      for (let i = 0; i < 5; i++) {
+        await createEvent(env.DB, {
+          channelId: 'test-channel',
+          type: 'evt',
+          data: { i },
+        });
+      }
+
+      // Use since to anchor pagination (ASC mode)
+      const page1 = await pollEvents(env.DB, 'test-channel', {
+        limit: 2,
+        since: '2000-01-01T00:00:00Z',
+      });
       expect(page1.events).toHaveLength(2);
       expect(page1.has_more).toBe(true);
       expect(page1.cursor).toBeTruthy();
@@ -492,9 +514,9 @@ describe('Server meta queries', () => {
       expect(meta.owner).toBe('bob');
 
       // Verify only one row exists
-      const result = await env.DB
-        .prepare('SELECT COUNT(*) as count FROM server_meta')
-        .first<{ count: number }>();
+      const result = await env.DB.prepare(
+        'SELECT COUNT(*) as count FROM server_meta',
+      ).first<{ count: number }>();
       expect(result!.count).toBe(1);
     });
   });

package/src/db/queries.ts

@@ -1,4 +1,3 @@
-
 import type {
   Channel,
   ChannelListItem,
@@ -31,7 +30,15 @@ export async function createChannel(
     .prepare(
       `INSERT INTO channels (id, name, description, tags, is_public, schema, strict) VALUES (?, ?, ?, ?, ?, ?, ?)`,
     )
-    .bind(channel.id, channel.name, channel.description ?? null, tags, isPublic, schema, strict)
+    .bind(
+      channel.id,
+      channel.name,
+      channel.description ?? null,
+      tags,
+      isPublic,
+      schema,
+      strict,
+    )
     .run();
 
   const row = await db
@@ -46,12 +53,13 @@ export async function getChannel(
   db: D1Database,
   id: string,
 ): Promise<Channel | null> {
-  return db.prepare(`SELECT * FROM channels WHERE id = ?`).bind(id).first<Channel>();
+  return db
+    .prepare(`SELECT * FROM channels WHERE id = ?`)
+    .bind(id)
+    .first<Channel>();
 }
 
-export async function listChannels(
-  db: D1Database,
-): Promise<ChannelListItem[]> {
+export async function listChannels(db: D1Database): Promise<ChannelListItem[]> {
   const rows = await db
     .prepare(
       `SELECT
@@ -120,9 +128,7 @@ export async function createPublisher(
   const id = generateUlid();
 
   await db
-    .prepare(
-      `INSERT INTO publishers (id, channel_id, name) VALUES (?, ?, ?)`,
-    )
+    .prepare(`INSERT INTO publishers (id, channel_id, name) VALUES (?, ?, ?)`)
     .bind(id, channelId, name)
     .run();
 
@@ -249,7 +255,12 @@ export async function pollEvents(
     bindings.push(options.type);
   }
 
-  const sql = `SELECT * FROM events WHERE ${conditions.join(' AND ')} ORDER BY id ASC LIMIT ?`;
+  // When no cursor/since anchor, fetch the most recent events (DESC) and reverse
+  // so the result is still in chronological order. With an anchor, fetch forward (ASC).
+  const hasAnchor = !!(options.cursor || options.since);
+  const order = hasAnchor ? 'ASC' : 'DESC';
+
+  const sql = `SELECT * FROM events WHERE ${conditions.join(' AND ')} ORDER BY id ${order} LIMIT ?`;
   bindings.push(limit + 1);
 
   const stmt = db.prepare(sql);
@@ -257,13 +268,16 @@ export async function pollEvents(
   const rows = result.results;
 
   const hasMore = rows.length > limit;
-  const events = hasMore ? rows.slice(0, limit) : rows;
+  const trimmed = hasMore ? rows.slice(0, limit) : rows;
+
+  // DESC results need reversing to restore chronological order
+  const events = hasAnchor ? trimmed : trimmed.reverse();
   const cursor = events.length > 0 ? events[events.length - 1].id : null;
 
   return {
     events,
-    cursor: hasMore ? cursor : null,
-    has_more: hasMore,
+    cursor: hasAnchor && hasMore ? cursor : null,
+    has_more: hasAnchor ? hasMore : false,
   };
 }
 
@@ -315,9 +329,7 @@ export async function createWebhook(
 
   // Fetch back — could be the new row or the updated existing one
   const row = await db
-    .prepare(
-      `SELECT * FROM webhooks WHERE channel_id = ? AND url = ?`,
-    )
+    .prepare(`SELECT * FROM webhooks WHERE channel_id = ? AND url = ?`)
     .bind(webhook.channelId, webhook.url)
     .first<Webhook>();
 

package/src/index.ts

@@ -2,7 +2,11 @@ import { Hono } from 'hono';
 import { fromHono } from 'chanfana';
 import type { Bindings, Variables } from './types';
 import { wellKnown } from './routes/well-known';
-import { requireAuth, requireScope, requireSubscribeIfPrivate } from './middleware/auth';
+import {
+  requireAuth,
+  requireScope,
+  requireSubscribeIfPrivate,
+} from './middleware/auth';
 import { ListChannels, CreateChannel, AddPublisher } from './routes/channels';
 import { PublishEvents, PollEvents } from './routes/events';
 import { RegisterWebhook, DeleteWebhook } from './routes/webhooks';

package/src/lib/schema-validator.test.ts

@@ -20,7 +20,10 @@ const schema = {
 
 describe('validateEvent', () => {
   it('accepts a valid alert event', () => {
-    const result = validateEvent(schema, 'alert', { level: 'info', message: 'hello' });
+    const result = validateEvent(schema, 'alert', {
+      level: 'info',
+      message: 'hello',
+    });
     expect(result.valid).toBe(true);
   });
 
@@ -30,15 +33,22 @@ describe('validateEvent', () => {
   });
 
   it('rejects event with no type', () => {
-    const result = validateEvent(schema, null, { level: 'info', message: 'hello' });
+    const result = validateEvent(schema, null, {
+      level: 'info',
+      message: 'hello',
+    });
     expect(result.valid).toBe(false);
-    expect(result.valid === false && result.error).toContain('must have a type');
+    expect(result.valid === false && result.error).toContain(
+      'must have a type',
+    );
   });
 
   it('rejects event with undefined type', () => {
     const result = validateEvent(schema, undefined, {});
     expect(result.valid).toBe(false);
-    expect(result.valid === false && result.error).toContain('must have a type');
+    expect(result.valid === false && result.error).toContain(
+      'must have a type',
+    );
   });
 
   it('rejects unknown event type', () => {
@@ -60,7 +70,10 @@ describe('validateEvent', () => {
   });
 
   it('rejects wrong type for a field', () => {
-    const result = validateEvent(schema, 'metric', { name: 'cpu', value: 'not-a-number' });
+    const result = validateEvent(schema, 'metric', {
+      name: 'cpu',
+      value: 'not-a-number',
+    });
     expect(result.valid).toBe(false);
     if (!result.valid) {
       expect(result.error).toContain('value');
@@ -68,7 +81,10 @@ describe('validateEvent', () => {
   });
 
   it('rejects invalid enum value', () => {
-    const result = validateEvent(schema, 'alert', { level: 'critical', message: 'oops' });
+    const result = validateEvent(schema, 'alert', {
+      level: 'critical',
+      message: 'oops',
+    });
     expect(result.valid).toBe(false);
     if (!result.valid) {
       expect(result.error).toContain('level');
@@ -76,7 +92,11 @@ describe('validateEvent', () => {
   });
 
   it('accepts data with extra fields (no additionalProperties restriction)', () => {
-    const result = validateEvent(schema, 'alert', { level: 'info', message: 'hi', extra: true });
+    const result = validateEvent(schema, 'alert', {
+      level: 'info',
+      message: 'hi',
+      extra: true,
+    });
     expect(result.valid).toBe(true);
   });
 
@@ -95,7 +115,11 @@ describe('validateEvent', () => {
         properties: { enabled: { type: 'boolean' } },
       },
     };
-    expect(validateEvent(boolSchema, 'toggle', { enabled: true }).valid).toBe(true);
-    expect(validateEvent(boolSchema, 'toggle', { enabled: 'yes' }).valid).toBe(false);
+    expect(validateEvent(boolSchema, 'toggle', { enabled: true }).valid).toBe(
+      true,
+    );
+    expect(validateEvent(boolSchema, 'toggle', { enabled: 'yes' }).valid).toBe(
+      false,
+    );
   });
 });

package/src/lib/schema-validator.ts

@@ -1,11 +1,13 @@
 import { Validator } from '@cfworker/json-schema';
 
-export type ValidationResult = {
-  valid: true;
-} | {
-  valid: false;
-  error: string;
-};
+export type ValidationResult =
+  | {
+      valid: true;
+    }
+  | {
+      valid: false;
+      error: string;
+    };
 
 /**
  * Validate an event against a channel's schema.
@@ -24,18 +26,27 @@ export type ValidationResult = {
  * using @cfworker/json-schema (Cloudflare Workers compatible).
  */
 export function validateEvent(
-  schema: Record<string, { required?: string[]; properties?: Record<string, unknown> }>,
+  schema: Record<
+    string,
+    { required?: string[]; properties?: Record<string, unknown> }
+  >,
   type: string | null | undefined,
   data: unknown,
 ): ValidationResult {
   if (!type) {
-    return { valid: false, error: 'Event must have a type when publishing to a strict channel' };
+    return {
+      valid: false,
+      error: 'Event must have a type when publishing to a strict channel',
+    };
   }
 
   const typeSchema = schema[type];
   if (!typeSchema) {
     const allowed = Object.keys(schema).join(', ');
-    return { valid: false, error: `Unknown event type "${type}". Allowed types: ${allowed}` };
+    return {
+      valid: false,
+      error: `Unknown event type "${type}". Allowed types: ${allowed}`,
+    };
   }
 
   // Build a JSON Schema object from the type definition
@@ -53,11 +64,17 @@ export function validateEvent(
   if (!result.valid) {
     const errors = result.errors
       .map((e) => {
-        const loc = e.instanceLocation === '#' ? 'data' : e.instanceLocation.replace('#/', 'data.');
+        const loc =
+          e.instanceLocation === '#'
+            ? 'data'
+            : e.instanceLocation.replace('#/', 'data.');
         return `${loc}: ${e.error}`;
       })
       .join('; ');
-    return { valid: false, error: `Validation failed for type "${type}": ${errors}` };
+    return {
+      valid: false,
+      error: `Validation failed for type "${type}": ${errors}`,
+    };
   }
 
   return { valid: true };

package/src/middleware/auth.test.ts

@@ -37,7 +37,11 @@ describe('Auth middleware', () => {
   const app = createTestApp();
 
   it('allows unauthenticated access to public routes', async () => {
-    const res = await app.request('/public', {}, { ZOOID_JWT_SECRET: JWT_SECRET });
+    const res = await app.request(
+      '/public',
+      {},
+      { ZOOID_JWT_SECRET: JWT_SECRET },
+    );
     expect(res.status).toBe(200);
   });
 

package/src/middleware/auth.ts

@@ -75,7 +75,9 @@ export function requireSubscribeIfPrivate(channelParam: string) {
 
     const authHeader = c.req.header('Authorization');
     const queryToken = c.req.query('token');
-    const rawToken = authHeader?.startsWith('Bearer ') ? authHeader.slice(7) : queryToken ?? null;
+    const rawToken = authHeader?.startsWith('Bearer ')
+      ? authHeader.slice(7)
+      : (queryToken ?? null);
 
     if (!rawToken) {
       return c.json(

package/src/routes/channels.ts

@@ -92,6 +92,22 @@ export class CreateChannel extends OpenAPIRoute {
           },
         },
       },
+      401: {
+        description: 'Missing or invalid authentication',
+        content: {
+          'application/json': {
+            schema: z.object({ error: z.string() }),
+          },
+        },
+      },
+      403: {
+        description: 'Insufficient permissions',
+        content: {
+          'application/json': {
+            schema: z.object({ error: z.string() }),
+          },
+        },
+      },
       409: {
         description: 'Channel already exists',
         content: {
@@ -180,6 +196,22 @@ export class AddPublisher extends OpenAPIRoute {
           },
         },
       },
+      401: {
+        description: 'Missing or invalid authentication',
+        content: {
+          'application/json': {
+            schema: z.object({ error: z.string() }),
+          },
+        },
+      },
+      403: {
+        description: 'Insufficient permissions',
+        content: {
+          'application/json': {
+            schema: z.object({ error: z.string() }),
+          },
+        },
+      },
       404: {
         description: 'Channel not found',
         content: {

package/src/routes/directory.test.ts

@@ -3,7 +3,11 @@ import { env } from 'cloudflare:test';
 import app from '../index';
 import { setupTestDb, cleanTestDb } from '../test-utils';
 import { createToken } from '../lib/jwt';
-import { generateKeyPair, exportPublicKey, importPublicKey } from '../lib/signing';
+import {
+  generateKeyPair,
+  exportPublicKey,
+  importPublicKey,
+} from '../lib/signing';
 
 const JWT_SECRET = 'test-jwt-secret';
 
@@ -124,7 +128,12 @@ describe('Directory claim route', () => {
       const sigBytes = base64UrlToBytes(body.signature);
 
       // Verify with the public key
-      const valid = await crypto.subtle.verify('Ed25519', PUBLIC_KEY, sigBytes, claimBytes);
+      const valid = await crypto.subtle.verify(
+        'Ed25519',
+        PUBLIC_KEY,
+        sigBytes,
+        claimBytes,
+      );
       expect(valid).toBe(true);
     });
 

package/src/routes/directory.ts

@@ -13,7 +13,10 @@ function arrayBufferToBase64Url(buffer: ArrayBuffer): string {
   for (const byte of bytes) {
     binary += String.fromCharCode(byte);
   }
-  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+  return btoa(binary)
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
 }
 
 function toBase64Url(str: string): string {
@@ -57,6 +60,22 @@ export class DirectoryClaim extends OpenAPIRoute {
           },
         },
       },
+      401: {
+        description: 'Missing or invalid authentication',
+        content: {
+          'application/json': {
+            schema: z.object({ error: z.string() }),
+          },
+        },
+      },
+      403: {
+        description: 'Insufficient permissions',
+        content: {
+          'application/json': {
+            schema: z.object({ error: z.string() }),
+          },
+        },
+      },
       500: {
         description: 'Server error',
         content: {
@@ -83,7 +102,10 @@ export class DirectoryClaim extends OpenAPIRoute {
       if (!ch) missing.push(id);
     }
     if (missing.length > 0) {
-      return c.json({ error: `Channels not found: ${missing.join(', ')}` }, 400);
+      return c.json(
+        { error: `Channels not found: ${missing.join(', ')}` },
+        400,
+      );
     }
 
     const serverUrl = new URL(c.req.url).origin;
@@ -99,7 +121,11 @@ export class DirectoryClaim extends OpenAPIRoute {
     const claimJson = JSON.stringify(claim);
     const claimBytes = new TextEncoder().encode(claimJson);
     const privateKey = await importPrivateKey(c.env.ZOOID_SIGNING_KEY);
-    const signatureBuffer = await crypto.subtle.sign('Ed25519', privateKey, claimBytes);
+    const signatureBuffer = await crypto.subtle.sign(
+      'Ed25519',
+      privateKey,
+      claimBytes,
+    );
 
     return c.json({
       claim: toBase64Url(claimJson),

package/src/routes/events.test.ts

@@ -1,8 +1,10 @@
-import { describe, it, expect, beforeAll, beforeEach } from 'vitest';
+import { describe, it, expect, beforeAll, beforeEach, vi } from 'vitest';
 import { env } from 'cloudflare:test';
 import app from '../index';
 import { setupTestDb, cleanTestDb } from '../test-utils';
 import { createToken } from '../lib/jwt';
+import { deliverToWebhooks } from './events';
+import { createWebhook } from '../db/queries';
 
 const JWT_SECRET = 'test-jwt-secret';
 
@@ -373,7 +375,7 @@ describe('Event routes', () => {
       expect(res.status).toBe(200);
     });
 
-    it('supports limit query param', async () => {
+    it('supports limit query param (returns most recent events)', async () => {
       for (let i = 0; i < 5; i++) {
         await publishRequest(
           '/api/v1/channels/pub-channel/events',
@@ -391,16 +393,18 @@ describe('Event routes', () => {
         { ...env, ZOOID_JWT_SECRET: JWT_SECRET },
       );
       const body = (await res.json()) as {
-        events: unknown[];
+        events: { data: string }[];
         has_more: boolean;
-        cursor: string;
+        cursor: string | null;
       };
       expect(body.events).toHaveLength(2);
-      expect(body.has_more).toBe(true);
-      expect(body.cursor).toBeTruthy();
+      // Should return the 2 most recent events in chronological order
+      expect(JSON.parse(body.events[0].data).i).toBe(3);
+      expect(JSON.parse(body.events[1].data).i).toBe(4);
+      expect(body.has_more).toBe(false);
     });
 
-    it('supports cursor pagination', async () => {
+    it('supports cursor pagination (forward from anchor)', async () => {
       for (let i = 0; i < 3; i++) {
         await publishRequest(
           '/api/v1/channels/pub-channel/events',
@@ -412,15 +416,20 @@ describe('Event routes', () => {
         );
       }
 
+      // Use since to anchor pagination forward
       const page1 = await app.request(
-        '/api/v1/channels/pub-channel/events?limit=2',
+        '/api/v1/channels/pub-channel/events?limit=2&since=2000-01-01T00:00:00Z',
         {},
         { ...env, ZOOID_JWT_SECRET: JWT_SECRET },
       );
       const body1 = (await page1.json()) as {
         cursor: string;
         events: unknown[];
+        has_more: boolean;
       };
+      expect(body1.events).toHaveLength(2);
+      expect(body1.has_more).toBe(true);
+      expect(body1.cursor).toBeTruthy();
 
       const page2 = await app.request(
         `/api/v1/channels/pub-channel/events?limit=2&cursor=${body1.cursor}`,
@@ -474,4 +483,104 @@ describe('Event routes', () => {
       expect(res.status).toBe(404);
     });
   });
+
+  describe('webhook delivery headers', () => {
+    it('includes X-Zooid-Server header in webhook deliveries', async () => {
+      // Register a webhook for the channel
+      await createWebhook(env.DB, {
+        channelId: 'pub-channel',
+        url: 'https://consumer.example.com/hook',
+      });
+
+      const captured: { url: string; headers: Record<string, string> }[] = [];
+      const mockFetch = vi.fn(
+        async (url: string | URL | Request, init?: RequestInit) => {
+          const headers: Record<string, string> = {};
+          if (init?.headers) {
+            for (const [k, v] of Object.entries(
+              init.headers as Record<string, string>,
+            )) {
+              headers[k] = v;
+            }
+          }
+          captured.push({ url: url.toString(), headers });
+          return new Response('ok', { status: 200 });
+        },
+      ) as unknown as typeof fetch;
+
+      await deliverToWebhooks(
+        { ...env, ZOOID_JWT_SECRET: JWT_SECRET } as never,
+        'pub-channel',
+        { id: '01TEST000000000000000000AA', type: 'signal' },
+        'https://my-server.zooid.dev',
+        mockFetch,
+      );
+
+      expect(captured).toHaveLength(1);
+      expect(captured[0].headers['X-Zooid-Server']).toBe(
+        'https://my-server.zooid.dev',
+      );
+      expect(captured[0].headers['X-Zooid-Channel']).toBe('pub-channel');
+      expect(captured[0].headers['X-Zooid-Event-Id']).toBe(
+        '01TEST000000000000000000AA',
+      );
+      expect(captured[0].headers['X-Zooid-Timestamp']).toBeTruthy();
+      expect(captured[0].url).toBe('https://consumer.example.com/hook');
+    });
+
+    it('includes X-Zooid-Signature when signing key is configured', async () => {
+      await createWebhook(env.DB, {
+        channelId: 'pub-channel',
+        url: 'https://consumer.example.com/hook',
+      });
+
+      // Generate a test signing key
+      const keyPair = await crypto.subtle.generateKey('Ed25519', true, [
+        'sign',
+        'verify',
+      ]);
+      const exported = await crypto.subtle.exportKey(
+        'pkcs8',
+        keyPair.privateKey,
+      );
+      const bytes = new Uint8Array(exported);
+      let binary = '';
+      for (const byte of bytes) binary += String.fromCharCode(byte);
+      const signingKeyBase64 = btoa(binary);
+
+      const captured: { headers: Record<string, string> }[] = [];
+      const mockFetch = vi.fn(
+        async (_url: string | URL | Request, init?: RequestInit) => {
+          const headers: Record<string, string> = {};
+          if (init?.headers) {
+            for (const [k, v] of Object.entries(
+              init.headers as Record<string, string>,
+            )) {
+              headers[k] = v;
+            }
+          }
+          captured.push({ headers });
+          return new Response('ok', { status: 200 });
+        },
+      ) as unknown as typeof fetch;
+
+      await deliverToWebhooks(
+        {
+          ...env,
+          ZOOID_JWT_SECRET: JWT_SECRET,
+          ZOOID_SIGNING_KEY: signingKeyBase64,
+        } as never,
+        'pub-channel',
+        { id: '01TEST000000000000000000BB', type: 'alert' },
+        'https://my-server.zooid.dev',
+        mockFetch,
+      );
+
+      expect(captured).toHaveLength(1);
+      expect(captured[0].headers['X-Zooid-Server']).toBe(
+        'https://my-server.zooid.dev',
+      );
+      expect(captured[0].headers['X-Zooid-Signature']).toBeTruthy();
+    });
+  });
 });

package/src/routes/events.ts

@@ -81,6 +81,22 @@ export class PublishEvents extends OpenAPIRoute {
           },
         },
       },
+      401: {
+        description: 'Missing or invalid authentication',
+        content: {
+          'application/json': {
+            schema: z.object({ error: z.string() }),
+          },
+        },
+      },
+      403: {
+        description: 'Insufficient permissions',
+        content: {
+          'application/json': {
+            schema: z.object({ error: z.string() }),
+          },
+        },
+      },
       404: {
         description: 'Channel not found',
         content: {
@@ -117,14 +133,13 @@ export class PublishEvents extends OpenAPIRoute {
           >)
         : null;
 
+    const serverUrl = new URL(c.req.url).origin;
+
     // Batch publish
     if ('events' in body && Array.isArray(body.events)) {
       for (const evt of body.events) {
         if (evt.data === undefined) {
-          return c.json(
-            { error: 'Each event must include a data field' },
-            400,
-          );
+          return c.json({ error: 'Each event must include a data field' }, 400);
         }
       }
 
@@ -155,7 +170,7 @@ export class PublishEvents extends OpenAPIRoute {
           // CHANNEL_DO binding may not exist in tests
         }
         for (const event of created) {
-          await deliverToWebhooks(c.env, channelId, event);
+          await deliverToWebhooks(c.env, channelId, event, serverUrl);
         }
       };
       try {
@@ -194,7 +209,7 @@ export class PublishEvents extends OpenAPIRoute {
       } catch {
         // CHANNEL_DO binding may not exist in tests
       }
-      await deliverToWebhooks(c.env, channelId, event);
+      await deliverToWebhooks(c.env, channelId, event, serverUrl);
     };
     try {
       c.executionCtx.waitUntil(afterPublish());
@@ -271,10 +286,12 @@ export class PollEvents extends OpenAPIRoute {
   }
 }
 
-async function deliverToWebhooks(
+export async function deliverToWebhooks(
   env: Bindings,
   channelId: string,
   event: { id: string; type: string | null },
+  serverUrl: string,
+  fetchFn: typeof fetch = fetch,
 ) {
   const webhooks = await getWebhooksForChannel(
     env.DB,
@@ -299,6 +316,7 @@ async function deliverToWebhooks(
     webhooks.map((webhook) => {
       const headers: Record<string, string> = {
         'Content-Type': 'application/json',
+        'X-Zooid-Server': serverUrl,
         'X-Zooid-Timestamp': timestamp,
         'X-Zooid-Channel': channelId,
         'X-Zooid-Event-Id': event.id,
@@ -309,7 +327,7 @@ async function deliverToWebhooks(
         headers['X-Zooid-Signature'] = signature;
       }
 
-      return fetch(webhook.url, { method: 'POST', headers, body });
+      return fetchFn(webhook.url, { method: 'POST', headers, body });
     }),
   );
 }

package/src/routes/feed.test.ts

@@ -99,14 +99,17 @@ describe('JSON Feed routes', () => {
       expect(res.status).toBe(200);
       expect(res.headers.get('Content-Type')).toBe('application/feed+json');
 
-      const body = await res.json() as FeedBody;
+      const body = (await res.json()) as FeedBody;
       expect(body.version).toBe('https://jsonfeed.org/version/1.1');
       expect(body.title).toBe('Feed Channel');
       expect(body.description).toBe('Test JSON feed');
       expect(body.items).toHaveLength(1);
       expect(body.items[0].id).toBeDefined();
       expect(body.items[0]._zooid).toBeDefined();
-      expect(body.items[0]._zooid.data).toEqual({ market: 'test', shift: 0.05 });
+      expect(body.items[0]._zooid.data).toEqual({
+        market: 'test',
+        shift: 0.05,
+      });
     });
 
     it('formats data as YAML by default', async () => {
@@ -128,7 +131,7 @@ describe('JSON Feed routes', () => {
         { ...env, ZOOID_JWT_SECRET: JWT_SECRET },
       );
 
-      const body = await res.json() as FeedBody;
+      const body = (await res.json()) as FeedBody;
       // YAML-style: key: value
       expect(body.items[0].content_text).toContain('market: election');
       expect(body.items[0].content_text).toContain('shift: 0.07');
@@ -153,7 +156,7 @@ describe('JSON Feed routes', () => {
         { ...env, ZOOID_JWT_SECRET: JWT_SECRET },
       );
 
-      const body = await res.json() as FeedBody;
+      const body = (await res.json()) as FeedBody;
       expect(body.items[0].content_text).toContain('"market"');
     });
 
@@ -176,7 +179,7 @@ describe('JSON Feed routes', () => {
         { ...env, ZOOID_JWT_SECRET: JWT_SECRET },
       );
 
-      const body = await res.json() as FeedBody;
+      const body = (await res.json()) as FeedBody;
       expect(body.items[0].title).toContain('[odds_shift]');
       expect(body.items[0].title).toContain('test-publisher');
       expect(body.items[0].tags).toEqual(['odds_shift']);
@@ -190,7 +193,7 @@ describe('JSON Feed routes', () => {
       );
 
       expect(res.status).toBe(200);
-      const body = await res.json() as FeedBody;
+      const body = (await res.json()) as FeedBody;
       expect(body.version).toBe('https://jsonfeed.org/version/1.1');
       expect(body.items).toEqual([]);
     });

package/src/routes/feed.ts

@@ -46,7 +46,9 @@ feed.get('/channels/:channelId/feed.json', async (c) => {
   const result = await pollEvents(db, channelId, { limit: 50 });
   const format = c.req.query('format') || 'yaml';
 
-  const items = result.events.map((event) => formatItem(event, channelId, format));
+  const items = result.events.map((event) =>
+    formatItem(event, channelId, format),
+  );
 
   const jsonFeed = {
     version: 'https://jsonfeed.org/version/1.1',

package/src/routes/server-meta.ts

@@ -87,6 +87,22 @@ export class UpdateServerMeta extends OpenAPIRoute {
           },
         },
       },
+      401: {
+        description: 'Missing or invalid authentication',
+        content: {
+          'application/json': {
+            schema: z.object({ error: z.string() }),
+          },
+        },
+      },
+      403: {
+        description: 'Insufficient permissions',
+        content: {
+          'application/json': {
+            schema: z.object({ error: z.string() }),
+          },
+        },
+      },
     },
   };
 

package/src/routes/webhooks.ts

@@ -85,6 +85,22 @@ export class DeleteWebhook extends OpenAPIRoute {
       204: {
         description: 'Webhook deleted',
       },
+      401: {
+        description: 'Missing or invalid authentication',
+        content: {
+          'application/json': {
+            schema: z.object({ error: z.string() }),
+          },
+        },
+      },
+      403: {
+        description: 'Insufficient permissions',
+        content: {
+          'application/json': {
+            schema: z.object({ error: z.string() }),
+          },
+        },
+      },
       404: {
         description: 'Webhook not found',
         content: {

package/src/routes/well-known.ts

@@ -44,7 +44,9 @@ wellKnown.get('/.well-known/zooid.json', async (c) => {
 
   return c.json({
     version: '0.1',
-    public_key: c.env.ZOOID_PUBLIC_KEY ? rawKeyToSpkiBase64Url(c.env.ZOOID_PUBLIC_KEY) : '',
+    public_key: c.env.ZOOID_PUBLIC_KEY
+      ? rawKeyToSpkiBase64Url(c.env.ZOOID_PUBLIC_KEY)
+      : '',
     public_key_format: 'spki',
     algorithm: 'Ed25519',
     server_id: c.env.ZOOID_SERVER_ID || 'zooid-local',

package/src/routes/ws.test.ts

@@ -231,8 +231,12 @@ describe('WebSocket routes', () => {
 
       const messages1: string[] = [];
       const messages2: string[] = [];
-      ws1.addEventListener('message', (e: MessageEvent) => messages1.push(e.data as string));
-      ws2.addEventListener('message', (e: MessageEvent) => messages2.push(e.data as string));
+      ws1.addEventListener('message', (e: MessageEvent) =>
+        messages1.push(e.data as string),
+      );
+      ws2.addEventListener('message', (e: MessageEvent) =>
+        messages2.push(e.data as string),
+      );
 
       // Publish an event
       const publishToken = await createToken(
@@ -303,8 +307,12 @@ describe('WebSocket routes', () => {
 
       const messages1: string[] = [];
       const messages2: string[] = [];
-      ws1.addEventListener('message', (e: MessageEvent) => messages1.push(e.data as string));
-      ws2.addEventListener('message', (e: MessageEvent) => messages2.push(e.data as string));
+      ws1.addEventListener('message', (e: MessageEvent) =>
+        messages1.push(e.data as string),
+      );
+      ws2.addEventListener('message', (e: MessageEvent) =>
+        messages2.push(e.data as string),
+      );
 
       const publishToken = await createToken(
         { scope: 'publish', channel: 'ws-channel', sub: 'test-pub' },
@@ -312,17 +320,14 @@ describe('WebSocket routes', () => {
       );
 
       // Publish a "signal" event — should only reach client 2
-      await SELF.fetch(
-        'http://localhost/api/v1/channels/ws-channel/events',
-        {
-          method: 'POST',
-          headers: {
-            Authorization: `Bearer ${publishToken}`,
-            'Content-Type': 'application/json',
-          },
-          body: JSON.stringify({ type: 'signal', data: { v: 1 } }),
+      await SELF.fetch('http://localhost/api/v1/channels/ws-channel/events', {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${publishToken}`,
+          'Content-Type': 'application/json',
         },
-      );
+        body: JSON.stringify({ type: 'signal', data: { v: 1 } }),
+      });
 
       await new Promise((r) => setTimeout(r, 100));
 
@@ -330,17 +335,14 @@ describe('WebSocket routes', () => {
       expect(messages2.length).toBe(1);
 
       // Publish an "alert" event — should reach both clients
-      await SELF.fetch(
-        'http://localhost/api/v1/channels/ws-channel/events',
-        {
-          method: 'POST',
-          headers: {
-            Authorization: `Bearer ${publishToken}`,
-            'Content-Type': 'application/json',
-          },
-          body: JSON.stringify({ type: 'alert', data: { v: 2 } }),
+      await SELF.fetch('http://localhost/api/v1/channels/ws-channel/events', {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${publishToken}`,
+          'Content-Type': 'application/json',
         },
-      );
+        body: JSON.stringify({ type: 'alert', data: { v: 2 } }),
+      });
 
       await new Promise((r) => setTimeout(r, 100));
 
@@ -381,7 +383,9 @@ describe('WebSocket routes', () => {
       ws.accept();
 
       const messages: string[] = [];
-      ws.addEventListener('message', (e: MessageEvent) => messages.push(e.data as string));
+      ws.addEventListener('message', (e: MessageEvent) =>
+        messages.push(e.data as string),
+      );
 
       const publishToken = await createToken(
         { scope: 'publish', channel: 'ws-channel', sub: 'test-pub' },
@@ -389,43 +393,34 @@ describe('WebSocket routes', () => {
       );
 
       // Publish "info" — should not be received
-      await SELF.fetch(
-        'http://localhost/api/v1/channels/ws-channel/events',
-        {
-          method: 'POST',
-          headers: {
-            Authorization: `Bearer ${publishToken}`,
-            'Content-Type': 'application/json',
-          },
-          body: JSON.stringify({ type: 'info', data: { v: 1 } }),
+      await SELF.fetch('http://localhost/api/v1/channels/ws-channel/events', {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${publishToken}`,
+          'Content-Type': 'application/json',
         },
-      );
+        body: JSON.stringify({ type: 'info', data: { v: 1 } }),
+      });
 
       // Publish "alert" — should be received
-      await SELF.fetch(
-        'http://localhost/api/v1/channels/ws-channel/events',
-        {
-          method: 'POST',
-          headers: {
-            Authorization: `Bearer ${publishToken}`,
-            'Content-Type': 'application/json',
-          },
-          body: JSON.stringify({ type: 'alert', data: { v: 2 } }),
+      await SELF.fetch('http://localhost/api/v1/channels/ws-channel/events', {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${publishToken}`,
+          'Content-Type': 'application/json',
         },
-      );
+        body: JSON.stringify({ type: 'alert', data: { v: 2 } }),
+      });
 
       // Publish "signal" — should be received
-      await SELF.fetch(
-        'http://localhost/api/v1/channels/ws-channel/events',
-        {
-          method: 'POST',
-          headers: {
-            Authorization: `Bearer ${publishToken}`,
-            'Content-Type': 'application/json',
-          },
-          body: JSON.stringify({ type: 'signal', data: { v: 3 } }),
+      await SELF.fetch('http://localhost/api/v1/channels/ws-channel/events', {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${publishToken}`,
+          'Content-Type': 'application/json',
         },
-      );
+        body: JSON.stringify({ type: 'signal', data: { v: 3 } }),
+      });
 
       await new Promise((r) => setTimeout(r, 150));
 
@@ -469,7 +464,9 @@ describe('WebSocket routes', () => {
       ws.accept();
 
       const messages: string[] = [];
-      ws.addEventListener('message', (e: MessageEvent) => messages.push(e.data as string));
+      ws.addEventListener('message', (e: MessageEvent) =>
+        messages.push(e.data as string),
+      );
 
       // Publish an event via SELF
       const publishToken = await createToken(