@bates-solutions/squareup 0.1.0

package/dist/server/webhook.js

@@ -0,0 +1,190 @@
+import { createHmac, timingSafeEqual } from 'crypto';
+/**
+ * Header name for Square webhook signature
+ */
+export const SIGNATURE_HEADER = 'x-square-hmacsha256-signature';
+/**
+ * Verify a Square webhook signature using HMAC-SHA256
+ *
+ * @param rawBody - The raw request body as a string
+ * @param signature - The signature from the x-square-hmacsha256-signature header
+ * @param signatureKey - Your webhook signature key from Square
+ * @param notificationUrl - The URL where the webhook was sent (optional, for additional verification)
+ * @returns Verification result with valid flag and optional error
+ *
+ * @example
+ * ```typescript
+ * import { verifySignature } from '@bates-solutions/squareup/server';
+ *
+ * const result = verifySignature(
+ *   rawBody,
+ *   req.headers['x-square-hmacsha256-signature'],
+ *   process.env.SQUARE_WEBHOOK_KEY!
+ * );
+ *
+ * if (!result.valid) {
+ *   return res.status(401).json({ error: result.error });
+ * }
+ * ```
+ */
+export function verifySignature(rawBody, signature, signatureKey, notificationUrl) {
+    if (!rawBody) {
+        return { valid: false, error: 'Missing request body' };
+    }
+    if (!signature) {
+        return { valid: false, error: 'Missing signature header' };
+    }
+    if (!signatureKey) {
+        return { valid: false, error: 'Missing signature key' };
+    }
+    try {
+        // Build the string to sign
+        // Square uses: notificationUrl + rawBody (if URL provided) or just rawBody
+        const stringToSign = notificationUrl ? notificationUrl + rawBody : rawBody;
+        // Generate HMAC-SHA256 signature
+        const expectedSignature = createHmac('sha256', signatureKey)
+            .update(stringToSign)
+            .digest('base64');
+        // Use timing-safe comparison to prevent timing attacks
+        const signatureBuffer = Buffer.from(signature, 'base64');
+        const expectedBuffer = Buffer.from(expectedSignature, 'base64');
+        // Buffers must be same length for timingSafeEqual
+        if (signatureBuffer.length !== expectedBuffer.length) {
+            return { valid: false, error: 'Invalid signature' };
+        }
+        const isValid = timingSafeEqual(signatureBuffer, expectedBuffer);
+        if (!isValid) {
+            return { valid: false, error: 'Invalid signature' };
+        }
+        return { valid: true };
+    }
+    catch (error) {
+        return {
+            valid: false,
+            error: error instanceof Error ? error.message : 'Signature verification failed',
+        };
+    }
+}
+/**
+ * Parse a webhook request body into a typed event
+ *
+ * @param rawBody - The raw request body string
+ * @returns Parsed webhook event
+ * @throws Error if parsing fails
+ *
+ * @example
+ * ```typescript
+ * const event = parseWebhookEvent(rawBody);
+ * console.log(event.type); // 'payment.completed'
+ * ```
+ */
+export function parseWebhookEvent(rawBody) {
+    try {
+        return JSON.parse(rawBody);
+    }
+    catch {
+        throw new Error('Invalid webhook payload: failed to parse JSON');
+    }
+}
+/**
+ * Parse and verify a webhook request
+ *
+ * @param rawBody - The raw request body string
+ * @param signature - The signature from headers
+ * @param signatureKey - Your webhook signature key
+ * @param notificationUrl - Optional notification URL for verification
+ * @returns Parsed and verified webhook request
+ * @throws Error if verification or parsing fails
+ *
+ * @example
+ * ```typescript
+ * const { event } = parseAndVerifyWebhook(
+ *   rawBody,
+ *   signature,
+ *   process.env.SQUARE_WEBHOOK_KEY!
+ * );
+ * ```
+ */
+export function parseAndVerifyWebhook(rawBody, signature, signatureKey, notificationUrl) {
+    const verification = verifySignature(rawBody, signature, signatureKey, notificationUrl);
+    if (!verification.valid) {
+        throw new Error(verification.error ?? 'Signature verification failed');
+    }
+    const event = parseWebhookEvent(rawBody);
+    return {
+        rawBody,
+        signature,
+        event,
+    };
+}
+/**
+ * Process a webhook event by calling the appropriate handler
+ *
+ * @param event - The parsed webhook event
+ * @param config - Webhook configuration with handlers
+ * @returns Promise that resolves when handler completes
+ *
+ * @example
+ * ```typescript
+ * await processWebhookEvent(event, {
+ *   signatureKey: process.env.SQUARE_WEBHOOK_KEY!,
+ *   handlers: {
+ *     'payment.created': async (event) => {
+ *       console.log('Payment created:', event.data.id);
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export async function processWebhookEvent(event, config) {
+    const handler = config.handlers[event.type];
+    if (handler) {
+        await handler(event);
+    }
+}
+/**
+ * Create a webhook handler function that verifies and processes events
+ *
+ * @param config - Webhook configuration
+ * @returns Handler function that processes raw webhook requests
+ *
+ * @example
+ * ```typescript
+ * const handleWebhook = createWebhookProcessor({
+ *   signatureKey: process.env.SQUARE_WEBHOOK_KEY!,
+ *   handlers: {
+ *     'payment.created': async (event) => {
+ *       await sendReceipt(event.data.object.payment);
+ *     },
+ *     'order.updated': async (event) => {
+ *       await updateOrderStatus(event.data.object.order);
+ *     },
+ *   },
+ * });
+ *
+ * // Use in your route handler
+ * const result = await handleWebhook(rawBody, signature);
+ * ```
+ */
+export function createWebhookProcessor(config) {
+    return async (rawBody, signature) => {
+        try {
+            const verification = verifySignature(rawBody, signature, config.signatureKey, config.notificationUrl);
+            if (!verification.valid) {
+                if (config.throwOnInvalidSignature !== false) {
+                    return { success: false, error: verification.error };
+                }
+            }
+            const event = parseWebhookEvent(rawBody);
+            await processWebhookEvent(event, config);
+            return { success: true, event };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'Unknown error',
+            };
+        }
+    };
+}
+//# sourceMappingURL=webhook.js.map

package/dist/server/webhook.js.map

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

package/package.json

@@ -0,0 +1,118 @@
+{
+  "name": "@bates-solutions/squareup",
+  "version": "0.1.0",
+  "description": "TypeScript wrapper for Square API with React & Angular integrations",
+  "type": "module",
+  "main": "./dist/core/index.js",
+  "types": "./dist/core/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    },
+    "./angular": {
+      "types": "./dist/angular/index.d.ts",
+      "import": "./dist/angular/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:react": "vitest run --config vitest.react.config.ts",
+    "test:angular": "vitest run --config vitest.angular.config.ts",
+    "docs": "typedoc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "square",
+    "square-api",
+    "payments",
+    "payment-processing",
+    "react",
+    "react-hooks",
+    "angular",
+    "typescript",
+    "checkout",
+    "ecommerce",
+    "point-of-sale",
+    "pos",
+    "sdk",
+    "api"
+  ],
+  "author": "Bates Solutions",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mbates/squareup.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mbates/squareup/issues"
+  },
+  "homepage": "https://github.com/mbates/squareup#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "@angular/core": "^17.0.0 || ^18.0.0 || ^19.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "square": "^43.2.1"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "@angular/core": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@angular/common": "^21.0.6",
+    "@angular/core": "^21.0.6",
+    "@angular/platform-browser": "^21.0.6",
+    "@angular/platform-browser-dynamic": "^21.0.6",
+    "@eslint/js": "^9.39.2",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.1",
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.0.3",
+    "@types/react": "^19.2.7",
+    "@typescript-eslint/eslint-plugin": "^8.51.0",
+    "@typescript-eslint/parser": "^8.51.0",
+    "@vitest/coverage-v8": "^4.0.0",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.1.0",
+    "jsdom": "^27.4.0",
+    "prettier": "^3.2.0",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "rxjs": "^7.8.2",
+    "square": "^43.2.1",
+    "typedoc": "^0.28.15",
+    "typedoc-plugin-markdown": "^4.9.0",
+    "typescript": "^5.3.0",
+    "typescript-eslint": "^8.51.0",
+    "vitest": "^4.0.16",
+    "zone.js": "^0.16.0"
+  }
+}