@squaredr/fieldcraft-webhook 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present SquaredR
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# @squaredr/fieldcraft-webhook
+
+Webhook delivery adapter for [FieldCraft](https://squaredr.tech/products/fieldcraft). POST form responses to any endpoint with HMAC-SHA256 signing and configurable retry with exponential backoff.
+
+## Install
+
+```bash
+npm install @squaredr/fieldcraft-webhook
+```
+
+**Peer dependency:** Requires `@squaredr/fieldcraft-core` v1.0.0+.
+
+## Quick Start
+
+```typescript
+import { createWebhookAdapter } from '@squaredr/fieldcraft-webhook'
+
+const adapter = createWebhookAdapter({
+  url: 'https://api.example.com/form-submissions',
+  secret: process.env.WEBHOOK_SECRET,
+})
+```
+
+Pass the adapter to your form engine's `onSubmit`:
+
+```tsx
+<FormEngineRenderer
+  schema={schema}
+  onSubmit={(response) => adapter.submit(response)}
+/>
+```
+
+## HMAC-SHA256 Signing
+
+Every request includes an `X-FormEngine-Signature` header with a SHA256 HMAC of the payload body. Verify it on your server:
+
+```typescript
+import { signPayload } from '@squaredr/fieldcraft-webhook'
+
+// On your server:
+const expected = signPayload(requestBody, secret)
+const received = req.headers['x-formengine-signature'].replace('sha256=', '')
+
+if (expected !== received) {
+  return res.status(401).json({ error: 'Invalid signature' })
+}
+```
+
+## Retries
+
+The adapter retries failed requests with configurable backoff:
+
+```typescript
+const adapter = createWebhookAdapter({
+  url: 'https://api.example.com/submissions',
+  secret: process.env.WEBHOOK_SECRET,
+  retries: 5,              // max retry attempts (default: 3)
+  retryDelayMs: 2000,      // base delay in ms (default: 1000)
+  retryBackoff: 'exponential', // 'linear' or 'exponential' (default: 'exponential')
+  timeoutMs: 15000,        // request timeout (default: 30000)
+  onRetry: (attempt, delay) => {
+    console.log(`Retry ${attempt}, waiting ${delay}ms`)
+  },
+})
+```
+
+## Payload Transform
+
+Customize the request body shape before sending:
+
+```typescript
+const adapter = createWebhookAdapter({
+  url: 'https://api.example.com/submissions',
+  secret: process.env.WEBHOOK_SECRET,
+  transform: (response) => ({
+    form_id: response.schemaId,
+    answers: response.values,
+    submitted: response.submittedAt,
+  }),
+})
+```
+
+## Custom Headers
+
+```typescript
+const adapter = createWebhookAdapter({
+  url: 'https://api.example.com/submissions',
+  secret: process.env.WEBHOOK_SECRET,
+  headers: {
+    'Authorization': `Bearer ${process.env.API_TOKEN}`,
+    'X-Custom-Header': 'value',
+  },
+})
+```
+
+## Configuration
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `url` | `string` | Yes | Webhook endpoint URL |
+| `secret` | `string` | Yes | HMAC-SHA256 signing secret |
+| `retries` | `number` | No | Max retry attempts (default: 3) |
+| `retryDelayMs` | `number` | No | Base delay in ms (default: 1000) |
+| `retryBackoff` | `'linear' \| 'exponential'` | No | Backoff strategy (default: `'exponential'`) |
+| `timeoutMs` | `number` | No | Request timeout in ms (default: 30000) |
+| `headers` | `Record<string, string>` | No | Custom HTTP headers |
+| `transform` | `(response) => any` | No | Payload transform function |
+| `onSuccess` | `(response, status) => void` | No | Callback after successful delivery |
+| `onError` | `(error, attempt) => void` | No | Callback on delivery failure |
+| `onRetry` | `(attempt, delay) => void` | No | Callback before each retry |
+
+## Request Headers
+
+Every webhook request includes:
+
+| Header | Value |
+|---|---|
+| `Content-Type` | `application/json` |
+| `X-FormEngine-Signature` | `sha256={hmac}` |
+| `X-FormEngine-Event` | `submit` |
+| `X-FormEngine-Timestamp` | ISO 8601 timestamp |
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,39 @@
+import { FormResponse, SubmitAdapter } from '@squaredr/fieldcraft-core';
+
+type WebhookAdapterConfig = {
+    /** Webhook endpoint URL (HTTPS recommended) */
+    url: string;
+    /** HMAC signing secret */
+    secret: string;
+    /** Max retries (default: 3) */
+    retries?: number;
+    /** Base retry delay in ms (default: 1000) */
+    retryDelayMs?: number;
+    /** Backoff strategy (default: "exponential") */
+    retryBackoff?: "linear" | "exponential";
+    /** Request timeout in ms (default: 30000) */
+    timeoutMs?: number;
+    /** Additional headers to send */
+    headers?: Record<string, string>;
+    /** Transform the response before sending */
+    transform?: (response: FormResponse) => unknown;
+    /** Called after successful delivery */
+    onSuccess?: (response: FormResponse, statusCode: number) => void;
+    /** Called on each error */
+    onError?: (error: Error, attempt: number) => void;
+    /** Called before each retry */
+    onRetry?: (attempt: number, delay: number) => void;
+};
+
+/** Create a webhook submit adapter with HMAC signing and retries. */
+declare function createWebhookAdapter(config: WebhookAdapterConfig): SubmitAdapter;
+
+/** Sign a JSON payload string with HMAC-SHA256. Returns hex digest. */
+declare function signPayload(payload: string, secret: string): string;
+
+/** Calculate delay for a retry attempt. */
+declare function calculateDelay(attempt: number, baseDelay: number, backoff: "linear" | "exponential"): number;
+/** Sleep for a given number of milliseconds. */
+declare function sleep(ms: number): Promise<void>;
+
+export { type WebhookAdapterConfig, calculateDelay, createWebhookAdapter, signPayload, sleep };

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import { FormResponse, SubmitAdapter } from '@squaredr/fieldcraft-core';
+
+type WebhookAdapterConfig = {
+    /** Webhook endpoint URL (HTTPS recommended) */
+    url: string;
+    /** HMAC signing secret */
+    secret: string;
+    /** Max retries (default: 3) */
+    retries?: number;
+    /** Base retry delay in ms (default: 1000) */
+    retryDelayMs?: number;
+    /** Backoff strategy (default: "exponential") */
+    retryBackoff?: "linear" | "exponential";
+    /** Request timeout in ms (default: 30000) */
+    timeoutMs?: number;
+    /** Additional headers to send */
+    headers?: Record<string, string>;
+    /** Transform the response before sending */
+    transform?: (response: FormResponse) => unknown;
+    /** Called after successful delivery */
+    onSuccess?: (response: FormResponse, statusCode: number) => void;
+    /** Called on each error */
+    onError?: (error: Error, attempt: number) => void;
+    /** Called before each retry */
+    onRetry?: (attempt: number, delay: number) => void;
+};
+
+/** Create a webhook submit adapter with HMAC signing and retries. */
+declare function createWebhookAdapter(config: WebhookAdapterConfig): SubmitAdapter;
+
+/** Sign a JSON payload string with HMAC-SHA256. Returns hex digest. */
+declare function signPayload(payload: string, secret: string): string;
+
+/** Calculate delay for a retry attempt. */
+declare function calculateDelay(attempt: number, baseDelay: number, backoff: "linear" | "exponential"): number;
+/** Sleep for a given number of milliseconds. */
+declare function sleep(ms: number): Promise<void>;
+
+export { type WebhookAdapterConfig, calculateDelay, createWebhookAdapter, signPayload, sleep };

package/dist/index.js

@@ -0,0 +1,117 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  calculateDelay: () => calculateDelay,
+  createWebhookAdapter: () => createWebhookAdapter,
+  signPayload: () => signPayload,
+  sleep: () => sleep
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/signer.ts
+var import_node_crypto = __toESM(require("crypto"));
+function signPayload(payload, secret) {
+  return import_node_crypto.default.createHmac("sha256", secret).update(payload).digest("hex");
+}
+
+// src/retry.ts
+function calculateDelay(attempt, baseDelay, backoff) {
+  if (backoff === "linear") return baseDelay * attempt;
+  const delay = baseDelay * Math.pow(2, attempt - 1);
+  const jitter = Math.random() * delay * 0.1;
+  return Math.floor(delay + jitter);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/webhook-adapter.ts
+function createWebhookAdapter(config) {
+  const maxRetries = config.retries ?? 3;
+  const baseDelay = config.retryDelayMs ?? 1e3;
+  const backoff = config.retryBackoff ?? "exponential";
+  const timeoutMs = config.timeoutMs ?? 3e4;
+  return {
+    name: "webhook",
+    async submit(response) {
+      const payload = config.transform ? config.transform(response) : response;
+      const body = JSON.stringify(payload);
+      const signature = signPayload(body, config.secret);
+      for (let attempt = 1; attempt <= maxRetries + 1; attempt++) {
+        try {
+          const controller = new AbortController();
+          const timeout = setTimeout(
+            () => controller.abort(),
+            timeoutMs
+          );
+          const res = await fetch(config.url, {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              "X-FormEngine-Signature": `sha256=${signature}`,
+              "X-FormEngine-Event": "submit",
+              "X-FormEngine-Timestamp": (/* @__PURE__ */ new Date()).toISOString(),
+              ...config.headers
+            },
+            body,
+            signal: controller.signal
+          });
+          clearTimeout(timeout);
+          if (res.ok) {
+            config.onSuccess?.(response, res.status);
+            return;
+          }
+          throw new Error(
+            `Webhook returned ${res.status}: ${res.statusText}`
+          );
+        } catch (error) {
+          config.onError?.(error, attempt);
+          if (attempt <= maxRetries) {
+            const delay = calculateDelay(attempt, baseDelay, backoff);
+            config.onRetry?.(attempt, delay);
+            await sleep(delay);
+          } else {
+            throw error;
+          }
+        }
+      }
+    },
+    onError: config.onError ? (err) => config.onError(err, 0) : void 0
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  calculateDelay,
+  createWebhookAdapter,
+  signPayload,
+  sleep
+});

package/dist/index.mjs

@@ -0,0 +1,77 @@
+// src/signer.ts
+import crypto from "crypto";
+function signPayload(payload, secret) {
+  return crypto.createHmac("sha256", secret).update(payload).digest("hex");
+}
+
+// src/retry.ts
+function calculateDelay(attempt, baseDelay, backoff) {
+  if (backoff === "linear") return baseDelay * attempt;
+  const delay = baseDelay * Math.pow(2, attempt - 1);
+  const jitter = Math.random() * delay * 0.1;
+  return Math.floor(delay + jitter);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/webhook-adapter.ts
+function createWebhookAdapter(config) {
+  const maxRetries = config.retries ?? 3;
+  const baseDelay = config.retryDelayMs ?? 1e3;
+  const backoff = config.retryBackoff ?? "exponential";
+  const timeoutMs = config.timeoutMs ?? 3e4;
+  return {
+    name: "webhook",
+    async submit(response) {
+      const payload = config.transform ? config.transform(response) : response;
+      const body = JSON.stringify(payload);
+      const signature = signPayload(body, config.secret);
+      for (let attempt = 1; attempt <= maxRetries + 1; attempt++) {
+        try {
+          const controller = new AbortController();
+          const timeout = setTimeout(
+            () => controller.abort(),
+            timeoutMs
+          );
+          const res = await fetch(config.url, {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              "X-FormEngine-Signature": `sha256=${signature}`,
+              "X-FormEngine-Event": "submit",
+              "X-FormEngine-Timestamp": (/* @__PURE__ */ new Date()).toISOString(),
+              ...config.headers
+            },
+            body,
+            signal: controller.signal
+          });
+          clearTimeout(timeout);
+          if (res.ok) {
+            config.onSuccess?.(response, res.status);
+            return;
+          }
+          throw new Error(
+            `Webhook returned ${res.status}: ${res.statusText}`
+          );
+        } catch (error) {
+          config.onError?.(error, attempt);
+          if (attempt <= maxRetries) {
+            const delay = calculateDelay(attempt, baseDelay, backoff);
+            config.onRetry?.(attempt, delay);
+            await sleep(delay);
+          } else {
+            throw error;
+          }
+        }
+      }
+    },
+    onError: config.onError ? (err) => config.onError(err, 0) : void 0
+  };
+}
+export {
+  calculateDelay,
+  createWebhookAdapter,
+  signPayload,
+  sleep
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@squaredr/fieldcraft-webhook",
+  "version": "1.0.0",
+  "description": "FieldCraft webhook delivery adapter with HMAC-SHA256 signing and exponential backoff retries",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "LICENSE"],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@squaredr/fieldcraft-core": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "^5.5",
+    "tsup": "^8.0",
+    "vitest": "^2.0"
+  },
+  "license": "MIT",
+  "author": "SquaredR",
+  "homepage": "https://squaredr.tech/products/fieldcraft",
+  "bugs": {
+    "url": "https://github.com/SquaredR98/fieldcraft/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SquaredR98/fieldcraft.git",
+    "directory": "packages/adapters/webhook"
+  },
+  "keywords": ["fieldcraft", "form-engine", "webhook", "hmac", "adapter", "retry"],
+  "engines": {
+    "node": ">=18"
+  }
+}