feat: add @relayfile/webhook-server package

Author: khaliqgant

README.md

@@ -10,7 +10,7 @@ Each adapter has exactly 3 jobs:
 ## Quick Start
 
 ```bash
-npm install @relayfile/sdk @relayfile/adapter-github @relayfile/provider-nango
+npm install @relayfile/sdk @relayfile/adapter-github @relayfile/provider-nango @relayfile/webhook-server
 ```
 
 ### Getting started
@@ -149,6 +149,7 @@ GitHub/GitLab/Slack/...
 | `@relayfile/adapter-slack` | Slack (channels, messages, reactions) |
 | `@relayfile/adapter-linear` | Linear (issues, projects, cycles) |
 | `@relayfile/adapter-notion` | Notion (pages, databases, blocks, comments) |
+| `@relayfile/webhook-server` | Hono webhook receiver for adapter-driven relayfile ingestion |
 
 ## Mapping YAML Specification
 

packages/webhook-server/README.md

@@ -0,0 +1,59 @@
+# @relayfile/webhook-server
+
+Thin [Hono](https://hono.dev) server for receiving provider webhooks, verifying signatures, and persisting normalized events into relayfile via `RelayFileClient`.
+
+## Install
+
+```bash
+npm install @relayfile/webhook-server hono
+```
+
+## Usage
+
+```ts
+import { GitHubAdapter } from "@relayfile/adapter-github";
+import { RelayFileClient } from "@relayfile/sdk";
+import { createWebhookServer } from "@relayfile/webhook-server";
+
+const client = new RelayFileClient({ token: process.env.RELAYFILE_TOKEN! });
+const provider = { name: "nango", proxy: async () => ({ status: 200, headers: {}, data: {} }), healthCheck: async () => true };
+const github = new GitHubAdapter(provider);
+const server = createWebhookServer({ client, port: 3456, secrets: { github: process.env.GITHUB_WEBHOOK_SECRET } });
+server.register("github", github);
+await server.start();
+```
+
+`POST /github/webhook` now verifies `x-hub-signature-256`, normalizes the event, computes a VFS path from the registered adapter, and calls `client.ingestWebhook(...)`.
+
+## Supported built-ins
+
+- `github`: HMAC-SHA256 verification via `x-hub-signature-256`
+- `slack`: signing secret verification via `x-slack-signature` and `x-slack-request-timestamp`
+
+Adapters can also provide their own `verifySignature` or `normalizeWebhook` hooks.
+
+## API
+
+### `createWebhookServer(options)`
+
+- `client`: `RelayFileClient` used to persist webhook events
+- `workspaceId`: relayfile workspace ID, defaults to `"default"`
+- `port`: default port for `server.start()`, defaults to `3456`
+- `hostname`: default hostname for `server.start()`, defaults to `"0.0.0.0"`
+- `adapters`: optional initial adapter map
+- `secrets`: provider-to-secret map for signature verification
+
+### `server.register(name, adapter)`
+
+Registers an adapter by provider name. The adapter may expose:
+
+- `computePath(objectType, objectId, payload?)`
+- `normalizeWebhook(payload, context)`
+- `verifySignature(context)`
+- `provider?: ConnectionProvider`
+
+### Route
+
+- `POST /:provider/webhook`
+
+The route returns `404` for unknown providers, `401` for signature failures, `400` for invalid payloads, and `200` with the queued relayfile operation IDs when the webhook is accepted.

packages/webhook-server/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@relayfile/webhook-server",
+  "version": "0.1.0",
+  "description": "Thin Hono webhook receiver for relayfile adapters",
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "peerDependencies": {
+    "@relayfile/sdk": "^0.1.3"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.19.4",
+    "hono": "^4.9.9"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT"
+}

packages/webhook-server/src/index.ts

@@ -0,0 +1,20 @@
+export { AdapterRegistry, createAdapterRegistry } from "./registry.js";
+export { createWebhookServer } from "./server.js";
+export { headersToRecord, verifyWebhookSignature } from "./verify.js";
+export type {
+  AdapterMap,
+  AdapterRegistryLike,
+  PersistedWebhook,
+  RegisteredWebhookAdapter,
+  StartedWebhookServer,
+  WebhookEvent,
+  WebhookNormalizationContext,
+  WebhookSecretMap,
+  WebhookServer,
+  WebhookServerOptions,
+  WebhookSignatureVerificationContext,
+  WebhookStartOptions,
+  WebhookVerificationFailure,
+  WebhookVerificationResult,
+  WebhookVerificationSuccess,
+} from "./types.js";

packages/webhook-server/src/registry.ts

@@ -0,0 +1,35 @@
+import type { AdapterMap, AdapterRegistryLike, RegisteredWebhookAdapter } from "./types.js";
+
+function normalizeProviderName(value: string): string {
+  const normalized = value.trim().toLowerCase();
+  if (!normalized) {
+    throw new Error("Provider name must be a non-empty string.");
+  }
+  return normalized;
+}
+
+export class AdapterRegistry implements AdapterRegistryLike {
+  private readonly adapters = new Map<string, RegisteredWebhookAdapter>();
+
+  constructor(initialAdapters: AdapterMap = {}) {
+    for (const [name, adapter] of Object.entries(initialAdapters)) {
+      this.register(name, adapter);
+    }
+  }
+
+  register(name: string, adapter: RegisteredWebhookAdapter): void {
+    this.adapters.set(normalizeProviderName(name), adapter);
+  }
+
+  get(name: string): RegisteredWebhookAdapter | undefined {
+    return this.adapters.get(normalizeProviderName(name));
+  }
+
+  list(): string[] {
+    return [...this.adapters.keys()].sort();
+  }
+}
+
+export function createAdapterRegistry(initialAdapters: AdapterMap = {}): AdapterRegistry {
+  return new AdapterRegistry(initialAdapters);
+}