@fundedfast/sdk 1.3.0

package/dist/esm/webhooks.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @fundedfast/sdk/webhooks - Webhook Signature Verification
+ *
+ * Helpers for verifying FAST webhook deliveries in your backend.
+ * FAST signs all webhook payloads with HMAC-SHA256 using your webhook secret.
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhookSignature, parseWebhookEvent } from '@fundedfast/sdk/webhooks';
+ *
+ * app.post('/webhooks/fast', express.raw({ type: 'application/json' }), async (req, res) => {
+ *   const signature = req.headers['x-webhook-signature'] as string;
+ *   const rawBody = req.body.toString('utf-8'); // the raw bytes, not parsed JSON
+ *
+ *   // It is async: without `await` the check is a Promise, always truthy, and
+ *   // every request passes.
+ *   if (!await verifyWebhookSignature(rawBody, signature, process.env.FAST_WEBHOOK_SECRET!)) {
+ *     return res.status(401).send('Invalid signature');
+ *   }
+ *
+ *   const event = parseWebhookEvent(rawBody);
+ *   switch (event.eventType) {
+ *     case 'challenge.completed':
+ *       handleChallengeCompleted(event.userId, event.data);
+ *       break;
+ *     case 'funded_account.revoked':
+ *       handleRevocation(event.userId, event.data);
+ *       break;
+ *   }
+ *
+ *   res.status(200).send({ received: true });
+ * });
+ * ```
+ *
+ * @module webhooks
+ */
+import type { WebhookPayload, WebhookEventType } from './types.js';
+/**
+ * Verify the HMAC-SHA256 signature of a webhook payload.
+ *
+ * Uses timing-safe comparison to prevent timing attacks.
+ * Works in Node.js (crypto module) and edge runtimes (Web Crypto API).
+ *
+ * @param rawBody - The raw request body as a string (NOT parsed JSON)
+ * @param signature - The X-Webhook-Signature header value
+ * @param secret - Your webhook secret (from tenant setup)
+ * @returns true if signature is valid
+ *
+ * @example
+ * ```typescript
+ * // Express with raw body parser
+ * app.use('/webhooks', express.raw({ type: 'application/json' }));
+ *
+ * app.post('/webhooks/fast', async (req, res) => {
+ *   const rawBody = req.body.toString('utf-8');
+ *   const sig = req.headers['x-webhook-signature'] as string;
+ *
+ *   if (!await verifyWebhookSignature(rawBody, sig, WEBHOOK_SECRET)) {
+ *     return res.status(401).json({ error: 'invalid_signature' });
+ *   }
+ *   // ... handle event
+ * });
+ * ```
+ */
+export declare function verifyWebhookSignature(rawBody: string, signature: string, secret: string): Promise<boolean>;
+/**
+ * Synchronous signature verification using Web Crypto (browser/edge compatible).
+ *
+ * NOTE: This is async because Web Crypto API is async.
+ * If you need sync verification in Node.js, import crypto directly:
+ *
+ * ```typescript
+ * import { createHmac, timingSafeEqual } from 'node:crypto';
+ * const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
+ * const valid = timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(signature, 'hex'));
+ * ```
+ */
+/**
+ * Parse a webhook event payload.
+ *
+ * @param rawBody - The raw request body as a string or parsed object
+ * @returns Typed webhook payload with eventId, eventType, userId, timestamp, and data
+ *
+ * @example
+ * ```typescript
+ * const event = parseWebhookEvent(rawBody);
+ * console.log(event.eventType); // 'challenge.completed'
+ * console.log(event.data);      // { challengeId: '...', balance: 105.50, ... }
+ * ```
+ */
+export declare function parseWebhookEvent<T = Record<string, unknown>>(rawBody: string | Record<string, unknown>): WebhookPayload<T>;
+/**
+ * Check if an event type is one of the challenge lifecycle events.
+ */
+export declare function isChallengeEvent(eventType: WebhookEventType): boolean;
+/**
+ * Check if an event type is one of the funded account lifecycle events.
+ */
+export declare function isFundedAccountEvent(eventType: WebhookEventType): boolean;
+/**
+ * Check if an event type is one of the user lifecycle events.
+ */
+export declare function isUserEvent(eventType: WebhookEventType): boolean;
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/esm/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../../src/webhooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,CAAC,CAuClB;AAED;;;;;;;;;;;GAWG;AAIH;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAG3H;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAErE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAEzE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAEhE"}

package/dist/esm/webhooks.js

@@ -0,0 +1,159 @@
+/**
+ * @fundedfast/sdk/webhooks - Webhook Signature Verification
+ *
+ * Helpers for verifying FAST webhook deliveries in your backend.
+ * FAST signs all webhook payloads with HMAC-SHA256 using your webhook secret.
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhookSignature, parseWebhookEvent } from '@fundedfast/sdk/webhooks';
+ *
+ * app.post('/webhooks/fast', express.raw({ type: 'application/json' }), async (req, res) => {
+ *   const signature = req.headers['x-webhook-signature'] as string;
+ *   const rawBody = req.body.toString('utf-8'); // the raw bytes, not parsed JSON
+ *
+ *   // It is async: without `await` the check is a Promise, always truthy, and
+ *   // every request passes.
+ *   if (!await verifyWebhookSignature(rawBody, signature, process.env.FAST_WEBHOOK_SECRET!)) {
+ *     return res.status(401).send('Invalid signature');
+ *   }
+ *
+ *   const event = parseWebhookEvent(rawBody);
+ *   switch (event.eventType) {
+ *     case 'challenge.completed':
+ *       handleChallengeCompleted(event.userId, event.data);
+ *       break;
+ *     case 'funded_account.revoked':
+ *       handleRevocation(event.userId, event.data);
+ *       break;
+ *   }
+ *
+ *   res.status(200).send({ received: true });
+ * });
+ * ```
+ *
+ * @module webhooks
+ */
+/**
+ * Verify the HMAC-SHA256 signature of a webhook payload.
+ *
+ * Uses timing-safe comparison to prevent timing attacks.
+ * Works in Node.js (crypto module) and edge runtimes (Web Crypto API).
+ *
+ * @param rawBody - The raw request body as a string (NOT parsed JSON)
+ * @param signature - The X-Webhook-Signature header value
+ * @param secret - Your webhook secret (from tenant setup)
+ * @returns true if signature is valid
+ *
+ * @example
+ * ```typescript
+ * // Express with raw body parser
+ * app.use('/webhooks', express.raw({ type: 'application/json' }));
+ *
+ * app.post('/webhooks/fast', async (req, res) => {
+ *   const rawBody = req.body.toString('utf-8');
+ *   const sig = req.headers['x-webhook-signature'] as string;
+ *
+ *   if (!await verifyWebhookSignature(rawBody, sig, WEBHOOK_SECRET)) {
+ *     return res.status(401).json({ error: 'invalid_signature' });
+ *   }
+ *   // ... handle event
+ * });
+ * ```
+ */
+export async function verifyWebhookSignature(rawBody, signature, secret) {
+    if (!rawBody || !signature || !secret)
+        return false;
+    // SHA-256 hex is exactly 64 hex characters. Anything else is not a signature
+    // FAST produced; refuse it before parsing rather than let parseInt guess.
+    if (typeof signature !== 'string' || !/^[0-9a-f]{64}$/i.test(signature))
+        return false;
+    signature = signature.toLowerCase();
+    // Try Node.js crypto first (fastest path)
+    try {
+        const crypto = await import('node:crypto');
+        const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
+        if (expected.length !== signature.length)
+            return false;
+        const a = new Uint8Array(expected.length / 2);
+        const b = new Uint8Array(signature.length / 2);
+        for (let i = 0; i < a.length; i++) {
+            a[i] = parseInt(expected.slice(i * 2, i * 2 + 2), 16);
+            b[i] = parseInt(signature.slice(i * 2, i * 2 + 2), 16);
+        }
+        return crypto.timingSafeEqual(a, b);
+    }
+    catch {
+        // Not in Node.js - fall through to Web Crypto
+    }
+    // Web Crypto API (edge runtimes, Deno, Bun, Cloudflare Workers)
+    try {
+        const encoder = new TextEncoder();
+        const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+        const sig = await crypto.subtle.sign('HMAC', key, encoder.encode(rawBody));
+        const expected = Array.from(new Uint8Array(sig)).map(b => b.toString(16).padStart(2, '0')).join('');
+        return timingSafeCompare(expected, signature);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Synchronous signature verification using Web Crypto (browser/edge compatible).
+ *
+ * NOTE: This is async because Web Crypto API is async.
+ * If you need sync verification in Node.js, import crypto directly:
+ *
+ * ```typescript
+ * import { createHmac, timingSafeEqual } from 'node:crypto';
+ * const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
+ * const valid = timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(signature, 'hex'));
+ * ```
+ */
+// Re-export verifyWebhookSignature as the primary API - it works everywhere.
+/**
+ * Parse a webhook event payload.
+ *
+ * @param rawBody - The raw request body as a string or parsed object
+ * @returns Typed webhook payload with eventId, eventType, userId, timestamp, and data
+ *
+ * @example
+ * ```typescript
+ * const event = parseWebhookEvent(rawBody);
+ * console.log(event.eventType); // 'challenge.completed'
+ * console.log(event.data);      // { challengeId: '...', balance: 105.50, ... }
+ * ```
+ */
+export function parseWebhookEvent(rawBody) {
+    const parsed = typeof rawBody === 'string' ? JSON.parse(rawBody) : rawBody;
+    return parsed;
+}
+/**
+ * Check if an event type is one of the challenge lifecycle events.
+ */
+export function isChallengeEvent(eventType) {
+    return eventType.startsWith('challenge.');
+}
+/**
+ * Check if an event type is one of the funded account lifecycle events.
+ */
+export function isFundedAccountEvent(eventType) {
+    return eventType.startsWith('funded_account.');
+}
+/**
+ * Check if an event type is one of the user lifecycle events.
+ */
+export function isUserEvent(eventType) {
+    return eventType.startsWith('user.');
+}
+// ---- Internals ----
+function timingSafeCompare(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let result = 0;
+    for (let i = 0; i < a.length; i++) {
+        result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return result === 0;
+}
+//# sourceMappingURL=webhooks.js.map

package/dist/esm/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../../src/webhooks.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@fundedfast/sdk",
+  "version": "1.3.0",
+  "description": "Official TypeScript SDK for the FAST platform - Skill Challenge engine for sportsbook operators",
+  "type": "module",
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./webhooks": {
+      "import": {
+        "types": "./dist/esm/webhooks.d.ts",
+        "default": "./dist/esm/webhooks.js"
+      },
+      "require": {
+        "types": "./dist/cjs/webhooks.d.ts",
+        "default": "./dist/cjs/webhooks.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "npm run build:esm && npm run build:cjs && npm run build:cjs:package",
+    "build:esm": "tsc -p tsconfig.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:cjs:package": "echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "clean": "rm -rf dist",
+    "test": "vitest --run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run clean && npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "fast",
+    "fundedfast",
+    "sportsbook",
+    "funded-accounts",
+    "skill-challenge",
+    "betting-api",
+    "bet-validation",
+    "prop-trading",
+    "typescript",
+    "sdk"
+  ],
+  "author": "BLACKLINE CONSULTING d.o.o. <support@fundedfast.eu>",
+  "license": "MIT",
+  "homepage": "https://fundedfast.eu",
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "devDependencies": {
+    "@types/node": "^26.5.0",
+    "typescript": "^5.5.0",
+    "vitest": "^5.0.0"
+  }
+}