@exayard/sdk 0.3.0

package/dist/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,6GAA6G;AAC7G,eAAO,MAAM,mBAAmB,YAC9B,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,sBAAsB,EACtB,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,eAAe,EACf,SAAS,EACT,UAAU,EACV,cAAc,EACd,cAAc,EACd,UAAU,EACV,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,sBAAsB,EACtB,gCAAgC,EAChC,qBAAqB,EACrB,eAAe,EACf,iBAAiB,EACjB,oBAAoB,EACpB,yBAAyB,EACzB,uBAAuB,EACvB,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,CACR,CAAA;AAEV,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAA;AAEnE,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO;IACvC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,gBAAgB,CAAA;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,yFAAyF;IACzF,cAAc,EAAE,MAAM,CAAA;IACtB,IAAI,EAAE,CAAC,CAAA;IACP,yFAAyF;IACzF,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED,6CAA6C;AAC7C,eAAO,MAAM,wBAAwB,sBAAsB,CAAA;AAE3D,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,EAAE,mBAAmB,GAAG,wBAAwB,GAAG,kBAAkB,CAAA;IAElF,YAAY,IAAI,EAAE,qBAAqB,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,EAI/D;CACF;AAED,uGAAuG;AACvG,eAAO,MAAM,iCAAiC,QAAS,CAAA;AA8CvD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,YACpB,MAAM,GAAG,UAAU,UACpB,MAAM,YACL;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,KAC9B,OAAO,CAAC,MAAM,CAIhB,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,GAAU,CAAC,GAAG,OAAO,WAC5C,MAAM,GAAG,UAAU,mBACX,MAAM,GAAG,IAAI,GAAG,SAAS,UAClC,MAAM,YACL;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAE,KACnD,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAmBzB,CAAA"}

package/dist/webhooks.js

@@ -0,0 +1,149 @@
+"use strict";
+/**
+ * Webhook signature verification — Stripe-compatible pattern.
+ *
+ * Exayard signs every delivery (and `exayard listen` signs every forwarded event the same way) with:
+ *   Exayard-Signature: t=<unix seconds>,v1=<base64 HMAC-SHA256>
+ *
+ * where the signed payload is `${t}.${rawBody}` and the HMAC key is the UTF-8 bytes of the whole whsec_... secret,
+ * returned once when the endpoint (or listener) was created (server: packages/backend/convex/webhooks.ts deliver).
+ *
+ *   import { Exayard } from '@exayard/sdk'
+ *   const event = await exa.webhooks.constructEvent(rawBody, request.headers.get('Exayard-Signature')!, process.env.EXAYARD_WEBHOOK_SECRET!)
+ *   switch (event.type) {
+ *     case 'assessment.completed': ...
+ *     case 'bid.won':              ...
+ *   }
+ *
+ * Verify the raw body exactly as received: re-serializing parsed JSON changes the bytes and the signature fails.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.constructWebhookEvent = exports.signWebhookPayload = exports.DEFAULT_WEBHOOK_TOLERANCE_SECONDS = exports.WebhookSignatureError = exports.WEBHOOK_SIGNATURE_HEADER = exports.WEBHOOK_EVENT_TYPES = void 0;
+/** Every event type a webhook endpoint or `exayard listen` receives (the server's webhook event catalog). */
+exports.WEBHOOK_EVENT_TYPES = [
+    'project.created',
+    'project.updated',
+    'project.archived',
+    'assessment.started',
+    'assessment.completed',
+    'assessment.cancelled',
+    'assessment.failed',
+    'estimate.generated',
+    'bid.generated',
+    'bid.submitted',
+    'bid.won',
+    'bid.lost',
+    'bid.accepted',
+    'bid.declined',
+    'bid.sent',
+    'bid.viewed',
+    'bid.commented',
+    'file.processed',
+    'addendum.uploaded',
+    'quote.requested',
+    'quote.received',
+    'quote.accepted',
+    'quote.rejected',
+    'quote.expired',
+    'conversation.started',
+    'conversation.handoff_requested',
+    'conversation.closed',
+    'lead.captured',
+    'contact.created',
+    'appointment.booked',
+    'appointment.rescheduled',
+    'appointment.cancelled',
+    'call.completed',
+    'call.missed',
+    'review.requested',
+    'job.written_back',
+    'payment.captured',
+    'payment.failed'
+];
+/** The header that carries the signature. */
+exports.WEBHOOK_SIGNATURE_HEADER = 'Exayard-Signature';
+class WebhookSignatureError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'WebhookSignatureError';
+        this.code = code;
+    }
+}
+exports.WebhookSignatureError = WebhookSignatureError;
+/** Default tolerance between the signature's timestamp and now: 5 minutes, as the server documents. */
+exports.DEFAULT_WEBHOOK_TOLERANCE_SECONDS = 5 * 60;
+const parseSignatureHeader = (header) => {
+    let t;
+    const v1 = [];
+    for (const part of header.split(',').map(s => s.trim())) {
+        const eq = part.indexOf('=');
+        if (eq === -1)
+            continue;
+        const k = part.slice(0, eq);
+        const v = part.slice(eq + 1);
+        if (k === 't' && /^\d+$/.test(v))
+            t = Number(v);
+        if (k === 'v1' && v)
+            v1.push(v);
+    }
+    if (t === undefined || v1.length === 0) {
+        throw new WebhookSignatureError('malformed_header', 'Exayard-Signature must be "t=<unix seconds>,v1=<digest>".');
+    }
+    return { t, v1 };
+};
+const toText = (payload) => typeof payload === 'string' ? payload : new TextDecoder().decode(payload);
+const hmacSha256Base64 = async (secret, payload) => {
+    const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const digest = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(payload));
+    const bytes = new Uint8Array(digest);
+    let str = '';
+    for (let i = 0; i < bytes.length; i++)
+        str += String.fromCharCode(bytes[i]);
+    return btoa(str);
+};
+// Constant-time base64 compare. Short-circuit on length mismatch is fine —
+// attacker already knows the digest length (SHA-256 = 44 base64 chars).
+const safeCompare = (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;
+};
+/**
+ * The Exayard-Signature header value for a payload: what the server sends with each delivery, and what
+ * `exayard listen` sends with each forwarded event. Also useful to sign fixtures in your own tests.
+ */
+const signWebhookPayload = async (payload, secret, options = {}) => {
+    const t = options.timestamp ?? Math.floor(Date.now() / 1000);
+    const v1 = await hmacSha256Base64(secret, `${t}.${toText(payload)}`);
+    return `t=${t},v1=${v1}`;
+};
+exports.signWebhookPayload = signWebhookPayload;
+/**
+ * Verify a webhook delivery and parse its payload as a typed WebhookEvent.
+ *
+ * Throws WebhookSignatureError with a stable `code` on failure; answer it with a 400 so the delivery is retried:
+ *   - malformed_header: Exayard-Signature isn't in t=…,v1=… form
+ *   - replay_window_exceeded: the timestamp is more than `toleranceSeconds` (default 300) from now
+ *   - invalid_signature: no v1 digest matches
+ */
+const constructWebhookEvent = async (payload, signatureHeader, secret, options = {}) => {
+    if (!signatureHeader)
+        throw new WebhookSignatureError('malformed_header', 'The Exayard-Signature header is missing.');
+    const { t, v1 } = parseSignatureHeader(signatureHeader);
+    const tolerance = options.toleranceSeconds ?? exports.DEFAULT_WEBHOOK_TOLERANCE_SECONDS;
+    const nowSec = Math.floor((options.now ?? Date.now()) / 1000);
+    if (Math.abs(nowSec - t) > tolerance) {
+        throw new WebhookSignatureError('replay_window_exceeded', `Signature timestamp ${t} is outside the ${tolerance}-second window (now=${nowSec}).`);
+    }
+    const text = toText(payload);
+    const expected = await hmacSha256Base64(secret, `${t}.${text}`);
+    if (!v1.some(candidate => safeCompare(expected, candidate))) {
+        throw new WebhookSignatureError('invalid_signature', 'HMAC digest mismatch. Check the endpoint secret.');
+    }
+    return JSON.parse(text);
+};
+exports.constructWebhookEvent = constructWebhookEvent;

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@exayard/sdk",
+  "version": "0.3.0",
+  "description": "Official TypeScript SDK for the Exayard API",
+  "license": "MIT",
+  "homepage": "https://developers.exayard.com",
+  "keywords": [
+    "exayard",
+    "construction",
+    "takeoff",
+    "estimating",
+    "api",
+    "sdk"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "generate": "node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON scripts/generate.mts",
+    "regen": "cd ../../apps/api && npx tsx scripts/emit-openapi.ts",
+    "build": "node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON scripts/generate.mts --check && rm -rf dist && tsc -p tsconfig.json",
+    "prepublishOnly": "yarn build",
+    "test": "vitest run",
+    "typecheck": "node ../../node_modules/@typescript/native/lib/tsc.js --noEmit"
+  },
+  "devDependencies": {
+    "@exayard/config-typescript": "*",
+    "@types/node": "24.13.6",
+    "@typescript/native": "npm:typescript@7.0.2",
+    "typescript": "npm:@typescript/typescript6@6.0.2"
+  }
+}