shraga 0.1.3 → 0.1.5

package/src/server/events/bus.ts

@@ -4,24 +4,48 @@
 // call emitEvent(); the dispatcher subscribes and routes matching events to the
 // scheduler's execution path. Deliberately minimal: no plugin registry, no
 // lifecycle — just emit + subscribe. Adding a source = one emitEvent() call.
-import type { ShragaEvent } from './types.ts';
+//
+// TYPING: `ShragaEventMap` (types.ts) maps a source → its payload type. A source
+// listed there gets a checked payload; anything else falls back to `unknown`, so
+// ad-hoc emitters keep compiling. Add-ons register their source via declaration
+// merging (see types.ts).
+import type { ShragaEvent, PayloadOf } from './types.ts';
 
 type Listener = (evt: ShragaEvent) => void;
 
 const listeners = new Set<Listener>();
 
-/** Subscribe to all events. Returns an unsubscribe fn. */
+/** Clear all subscribers. For tests: `listeners` is a process-global, so a test file that boots a
+ *  server (or its on() subscribers) leaks listeners into a later file's emit. Reset between files
+ *  that share bus state to stay hermetic — bun's cross-file order is not stable across platforms.
+ *  Mirrors clearTurnContext()/`__resetExtensionsForTest()`. Test-only. */
+export function __resetEventBusForTest(): void {
+  listeners.clear();
+}
+
+/** Subscribe to ALL events. Returns an unsubscribe fn. The dispatcher uses this. */
 export function subscribeEvents(fn: Listener): () => void {
   listeners.add(fn);
   return () => listeners.delete(fn);
 }
 
+/** Subscribe to a SINGLE source with a typed payload. Thin filter over
+ *  subscribeEvents — convenience + typing for the common "I only care about X" case. */
+export function subscribeEvent<K extends string>(
+  source: K,
+  handler: (payload: PayloadOf<K>, evt: ShragaEvent<K>) => void,
+): () => void {
+  return subscribeEvents((evt) => {
+    if (evt.source === source) handler(evt.payload as PayloadOf<K>, evt as ShragaEvent<K>);
+  });
+}
+
 /** Publish an event. Listeners are invoked synchronously; a throwing listener is
  *  logged and skipped so one bad subscriber can't sink the emit. */
-export function emitEvent(source: string, payload: unknown, opts?: { id?: string }): ShragaEvent {
-  const evt: ShragaEvent = { source, payload, id: opts?.id, at: Date.now() };
+export function emitEvent<K extends string>(source: K, payload: PayloadOf<K>, opts?: { id?: string }): ShragaEvent<K> {
+  const evt: ShragaEvent<K> = { source, payload, id: opts?.id, at: Date.now() };
   for (const fn of listeners) {
-    try { fn(evt); } catch (err) {
+    try { fn(evt as ShragaEvent); } catch (err) {
       console.error(`[events] listener threw for source "${source}":`, err);
     }
   }

package/src/server/events/types.ts

@@ -1,9 +1,32 @@
 /** A single event flowing through the bus. `source` routes it to matching
  *  `event`-trigger schedules; `payload` is matched against their `match` filter and
  *  injected into the run. `id` (optional) dedupes retried webhook deliveries. */
-export interface ShragaEvent {
-  source: string;
-  payload: unknown;
+export interface ShragaEvent<K extends string = string> {
+  source: K;
+  payload: PayloadOf<K>;
   id?: string;
   at: number;
 }
+
+/** Extensible registry of source → payload types. Add-ons augment it via
+ *  declaration merging so a known source gets a typed payload, e.g.:
+ *
+ *    declare module '../events/types.ts' {
+ *      interface ShragaEventMap { stripe: Stripe.Event }
+ *    }
+ *
+ *  Sources NOT in the map still work — they fall back to `unknown` (see PayloadOf),
+ *  so untyped/ad-hoc emitters keep compiling. */
+export interface ShragaEventMap {
+  // Core sources shipped by shraga itself. Add-ons merge in their own.
+  'schedule.finished': {
+    scheduleId: string;
+    name?: string;
+    status?: string;
+    sessionId?: string;
+    error?: string;
+  };
+}
+
+/** Payload type for a source: the mapped type if registered, else `unknown`. */
+export type PayloadOf<K extends string> = K extends keyof ShragaEventMap ? ShragaEventMap[K] : unknown;

package/src/server/events/webhook.ts

@@ -0,0 +1,64 @@
+// Generic verified-webhook → event bridge.
+//
+// A vendor webhook can't present shraga auth (it carries the vendor's OWN
+// signature), so it can't hit the auth-gated POST /api/events/:source. Instead
+// declare it as data: registerWebhook(app, { source, verify }) mounts a PUBLIC
+// POST /api/webhooks/<source>, and on a passing `verify` calls emitEvent(source).
+//
+// The ONLY per-vendor piece is `verify` — dispatch, dedup, and typing are generic.
+// The raw request bytes (needed for HMAC) are read from req.rawBody, which the
+// global express.json({ verify }) in index.ts stashes for every request.
+import type { IRouter, Request, Response } from 'express';
+import { emitEvent } from './bus.ts';
+import type { PayloadOf } from './types.ts';
+
+export interface WebhookOptions<K extends string> {
+  /** Event source name → the bus source + `/api/webhooks/<source>` path. */
+  source: K;
+  /** Verify the vendor's signature over the RAW body. Return any FALSY value
+   *  (false/undefined/null/'') to reject (400). Return `true` to accept
+   *  (payload = normalize?.(req) ?? parsed body), or return the payload object
+   *  directly. Receives the raw bytes for HMAC. */
+  verify: (req: Request, raw: string) => boolean | PayloadOf<K>;
+  /** Optional payload shaper when `verify` returns `true` (defaults to req.body). */
+  normalize?: (req: Request) => PayloadOf<K>;
+  /** Optional dedup id extractor (retried deliveries). Defaults to body.id. */
+  eventId?: (payload: PayloadOf<K>, req: Request) => string | undefined;
+  /** Override the mount path (default `/api/webhooks/<source>`). */
+  path?: string;
+}
+
+function rawBodyOf(req: Request): string {
+  const buf = (req as unknown as { rawBody?: unknown }).rawBody;
+  return buf instanceof Buffer ? buf.toString('utf8') : '';
+}
+
+/** Mount a public webhook route that verifies the vendor's signature, then emits a
+ *  typed event. Returns the mounted path. */
+export function registerWebhook<K extends string>(router: IRouter, opts: WebhookOptions<K>): string {
+  const path = opts.path ?? `/api/webhooks/${opts.source}`;
+  router.post(path, (req: Request, res: Response) => {
+    const raw = rawBodyOf(req);
+    let result: boolean | PayloadOf<K>;
+    try {
+      result = opts.verify(req, raw);
+    } catch (err) {
+      console.error(`[webhook] verify threw for "${opts.source}":`, err);
+      return res.status(400).json({ error: 'verification failed' });
+    }
+    // Reject on ANY falsy result — a `verify` written as "return the payload, or
+    // nothing on failure" yields undefined/null/''/0 on a bad signature; those must
+    // NOT fall through and emit an unauthenticated event.
+    if (!result) return res.status(400).json({ error: 'bad signature' });
+
+    const payload: PayloadOf<K> = result === true ? (opts.normalize?.(req) ?? (req.body as PayloadOf<K>)) : result;
+    const id = opts.eventId
+      ? opts.eventId(payload, req)
+      : ((payload as { id?: unknown } | null)?.id != null ? String((payload as { id?: unknown }).id) : undefined);
+
+    emitEvent(opts.source, payload, { id });
+    res.json({ received: true });
+  });
+  console.log(`[webhook] mounted POST ${path} → emitEvent("${opts.source}")`);
+  return path;
+}

package/src/server/extensions.ts

@@ -22,6 +22,7 @@ import { pathToFileURL } from 'node:url';
 import { dataPath } from './paths.ts';
 import { requireAuth } from './auth.ts';
 import { emitEvent } from './events/bus.ts';
+import { registerWebhook, type WebhookOptions } from './events/webhook.ts';
 
 export interface ExtensionContext {
   /** Resolve a path inside the active data dir (e.g. ctx.dataPath('github-app.json')). */
@@ -35,11 +36,52 @@ export interface ExtensionContext {
   /** Publish an event onto the bus → fires matching `event`-trigger schedules.
    *  Use after verifying a vendor webhook's own signature. */
   emitEvent: (source: string, payload: unknown, opts?: { id?: string }) => void;
+  /** Declare a vendor webhook as data: mounts a PUBLIC POST /api/webhooks/<source>
+   *  that runs `verify` (the only per-vendor piece) → emitEvent. Returns the path. */
+  registerWebhook: <K extends string>(opts: WebhookOptions<K>) => string;
 }
 
+/** A programmatic extension: the same shape as a `*.ext.ts` file's default export. */
+export type ExtRegisterFn = (router: ExpressRouter, ctx: ExtensionContext) => void | Promise<void>;
+
 const loaded = new Set<string>();
 let extRouter: ExpressRouter | null = null;
 let ctx: ExtensionContext | null = null;
+const pendingProgrammatic: ExtRegisterFn[] = [];
+
+/** Reset the module-global router/ctx/registry. For tests: `extRouter`, `ctx` and `loaded` are
+ *  process-globals, so a test file that boots a second createShraga server in the same bun process
+ *  inherits the PRIOR file's router — and a pre-start `registerExtension`/`registerWebhook` (which
+ *  mounts immediately once `extRouter && ctx` are set, see registerExtension) then lands on the DEAD
+ *  router instead of queueing for the new one → the new server 404s. bun's cross-file order is not
+ *  stable across platforms (a Linux CI order that macOS never hits), so a test that boots a server
+ *  must reset first to be hermetic. Mirrors clearTurnContext() in turn-context.ts. Test-only. */
+export function __resetExtensionsForTest(): void {
+  extRouter = null;
+  ctx = null;
+  loaded.clear();
+  pendingProgrammatic.length = 0;
+}
+
+async function runProgrammatic(fn: ExtRegisterFn): Promise<void> {
+  try {
+    await fn(extRouter!, ctx!);
+    console.log('[extensions] mounted programmatic extension');
+  } catch (err) {
+    console.error('[extensions] programmatic register failed:', (err as Error)?.stack || err);
+  }
+}
+
+/**
+ * Programmatic equivalent of dropping a `data/extensions/*.ext.ts` file. Funnels through the SAME
+ * persistent Router + ExtensionContext (mounted before the SPA catch-all), so a webhook/callback
+ * registered this way is reachable exactly like a file-based one. If called before loadExtensions()
+ * (the usual case — createShraga queues these pre-boot), it runs when the router is ready.
+ */
+export async function registerExtension(fn: ExtRegisterFn): Promise<void> {
+  if (extRouter && ctx) return runProgrammatic(fn);
+  pendingProgrammatic.push(fn);
+}
 
 async function mountFile(dir: string, f: string): Promise<void> {
   if (loaded.has(f) || !extRouter || !ctx) return;
@@ -77,8 +119,14 @@ export async function loadExtensions(app: Express): Promise<void> {
     log: (...a) => console.log('[extensions]', ...a),
     app,
     emitEvent,
+    // Mount on the extension Router (before the SPA catch-all) so hot-loaded
+    // webhooks are reachable too — never on `app` directly.
+    registerWebhook: (opts) => registerWebhook(extRouter!, opts),
   };
 
+  // Flush programmatic extensions first (they mount ahead of file-based drop-ins, before the catch-all).
+  for (const fn of pendingProgrammatic.splice(0)) await runProgrammatic(fn);
+
   const dir = path.resolve(dataPath('extensions'));
   await scan(dir);