@bates-solutions/squareup 0.1.0

package/dist/server/middleware/express.js

@@ -0,0 +1,123 @@
+import { verifySignature, parseWebhookEvent, processWebhookEvent, SIGNATURE_HEADER, } from '../webhook.js';
+/**
+ * Create Express middleware for handling Square webhooks
+ *
+ * This middleware:
+ * 1. Captures the raw body for signature verification
+ * 2. Verifies the webhook signature
+ * 3. Parses the event and attaches it to the request
+ * 4. Calls the appropriate handler
+ *
+ * @param config - Webhook configuration
+ * @returns Express middleware function
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { createExpressWebhookHandler } from '@bates-solutions/squareup/server';
+ *
+ * const app = express();
+ *
+ * // IMPORTANT: Use raw body parser for webhook route
+ * app.use('/webhook', express.raw({ type: 'application/json' }));
+ *
+ * app.post('/webhook', createExpressWebhookHandler({
+ *   signatureKey: process.env.SQUARE_WEBHOOK_KEY!,
+ *   handlers: {
+ *     'payment.created': async (event) => {
+ *       console.log('Payment created:', event.data.id);
+ *     },
+ *   },
+ * }));
+ * ```
+ */
+export function createExpressWebhookHandler(config) {
+    const { autoRespond = true, ...webhookConfig } = config;
+    return async (req, res, next) => {
+        try {
+            // Get raw body - Express with raw() parser stores it as Buffer
+            let rawBody;
+            if (Buffer.isBuffer(req.body)) {
+                rawBody = req.body.toString('utf8');
+            }
+            else if (typeof req.body === 'string') {
+                rawBody = req.body;
+            }
+            else if (req.rawBody) {
+                rawBody = req.rawBody;
+            }
+            else {
+                // Body might be parsed JSON, stringify it (not ideal for signature verification)
+                rawBody = JSON.stringify(req.body);
+            }
+            // Get signature from headers
+            const signature = req.headers[SIGNATURE_HEADER];
+            if (!signature || Array.isArray(signature)) {
+                if (autoRespond) {
+                    res.status(401).json({ error: 'Missing or invalid signature header' });
+                    return;
+                }
+                throw new Error('Missing or invalid signature header');
+            }
+            // Verify signature
+            const verification = verifySignature(rawBody, signature, webhookConfig.signatureKey, webhookConfig.notificationUrl);
+            if (!verification.valid) {
+                if (autoRespond) {
+                    res.status(401).json({ error: verification.error });
+                    return;
+                }
+                throw new Error(verification.error);
+            }
+            // Parse event
+            const event = parseWebhookEvent(rawBody);
+            // Attach to request for downstream middleware
+            req.rawBody = rawBody;
+            req.squareEvent = event;
+            // Process event with handlers
+            await processWebhookEvent(event, webhookConfig);
+            // Send success response
+            if (autoRespond) {
+                res.status(200).json({ received: true, eventId: event.event_id });
+                return;
+            }
+            next();
+        }
+        catch (error) {
+            if (autoRespond) {
+                res.status(500).json({
+                    error: error instanceof Error ? error.message : 'Webhook processing failed',
+                });
+                return;
+            }
+            next(error);
+        }
+    };
+}
+/**
+ * Raw body parser middleware for Express
+ *
+ * Captures the raw body before JSON parsing for signature verification.
+ * Use this if you need to parse JSON but also need the raw body.
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { rawBodyMiddleware } from '@bates-solutions/squareup/server';
+ *
+ * const app = express();
+ * app.use('/webhook', rawBodyMiddleware);
+ * app.use('/webhook', express.json());
+ * ```
+ */
+export const rawBodyMiddleware = (req, _res, next) => {
+    const chunks = [];
+    req.on('data', (chunk) => {
+        chunks.push(chunk);
+    });
+    req.on('end', () => {
+        req.rawBody = Buffer.concat(chunks).toString('utf8');
+        next();
+    });
+    req.on('error', next);
+};
+//# sourceMappingURL=express.js.map

package/dist/server/middleware/express.js.map

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

package/dist/server/middleware/nextjs.d.ts

@@ -0,0 +1,118 @@
+import type { WebhookConfig, WebhookEvent } from '../types.js';
+/**
+ * Response type for Next.js webhook handlers
+ */
+export interface WebhookResponse {
+    status: number;
+    body: Record<string, unknown>;
+}
+/**
+ * Node.js readable stream interface for raw body reading
+ */
+interface NodeReadable {
+    on(event: 'data', listener: (chunk: Buffer) => void): void;
+    on(event: 'end', listener: () => void): void;
+    on(event: 'error', listener: (err: Error) => void): void;
+}
+/**
+ * Next.js Pages Router request type
+ */
+interface NextPagesRequest extends NodeReadable {
+    method?: string;
+    headers: Record<string, string | string[] | undefined>;
+    body?: unknown;
+}
+/**
+ * Next.js Pages Router response type
+ */
+interface NextPagesResponse {
+    status: (code: number) => {
+        json: (body: unknown) => void;
+    };
+}
+/**
+ * Create a Next.js App Router webhook handler
+ *
+ * @param config - Webhook configuration
+ * @returns Route handler for POST requests
+ *
+ * @example
+ * ```typescript
+ * // app/api/webhook/route.ts
+ * import { createNextWebhookHandler } from '@bates-solutions/squareup/server';
+ *
+ * export const POST = createNextWebhookHandler({
+ *   signatureKey: process.env.SQUARE_WEBHOOK_KEY!,
+ *   handlers: {
+ *     'payment.created': async (event) => {
+ *       console.log('Payment created:', event.data.id);
+ *     },
+ *     'order.fulfillment.updated': async (event) => {
+ *       await notifyCustomer(event.data.object);
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare function createNextWebhookHandler(config: WebhookConfig): (request: Request) => Promise<Response>;
+/**
+ * Create a Next.js Pages Router API handler
+ *
+ * @param config - Webhook configuration
+ * @returns API route handler
+ *
+ * @example
+ * ```typescript
+ * // pages/api/webhook.ts
+ * import { createNextPagesWebhookHandler } from '@bates-solutions/squareup/server';
+ *
+ * export const config = {
+ *   api: { bodyParser: false }, // Required for raw body
+ * };
+ *
+ * export default createNextPagesWebhookHandler({
+ *   signatureKey: process.env.SQUARE_WEBHOOK_KEY!,
+ *   handlers: {
+ *     'payment.created': async (event) => {
+ *       console.log('Payment:', event.data.id);
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare function createNextPagesWebhookHandler(config: WebhookConfig): (req: NextPagesRequest, res: NextPagesResponse) => Promise<void>;
+/**
+ * Utility to parse webhook event from Next.js request
+ *
+ * Use this for custom handling when you don't want automatic processing
+ *
+ * @param request - The incoming request
+ * @param signatureKey - Your webhook signature key
+ * @param notificationUrl - Optional URL for signature verification
+ * @returns Parsed webhook event
+ * @throws Error if verification fails
+ *
+ * @example
+ * ```typescript
+ * // app/api/webhook/route.ts
+ * import { parseNextWebhook } from '@bates-solutions/squareup/server';
+ *
+ * export async function POST(request: Request) {
+ *   const event = await parseNextWebhook(
+ *     request,
+ *     process.env.SQUARE_WEBHOOK_KEY!
+ *   );
+ *
+ *   // Custom handling
+ *   switch (event.type) {
+ *     case 'payment.created':
+ *       // ...
+ *   }
+ *
+ *   return Response.json({ received: true });
+ * }
+ * ```
+ */
+export declare function parseNextWebhook(request: Request, signatureKey: string, notificationUrl?: string): Promise<WebhookEvent>;
+export {};
+//# sourceMappingURL=nextjs.d.ts.map

package/dist/server/middleware/nextjs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nextjs.d.ts","sourceRoot":"","sources":["../../../src/server/middleware/nextjs.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;GAEG;AACH,UAAU,YAAY;IACpB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IAC3D,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC7C,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC;CAC1D;AAED;;GAEG;AACH,UAAU,gBAAiB,SAAQ,YAAY;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IACvD,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;GAEG;AACH,UAAU,iBAAiB;IACzB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK;QAAE,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,CAAC;CAC7D;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,aAAa,IAC9C,SAAS,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC,CA4CnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,aAAa,IACnD,KAAK,gBAAgB,EAAE,KAAK,iBAAiB,KAAG,OAAO,CAAC,IAAI,CAAC,CA8C5E;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,MAAM,EACpB,eAAe,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC,YAAY,CAAC,CAoBvB"}

package/dist/server/middleware/nextjs.js

@@ -0,0 +1,172 @@
+import { verifySignature, parseWebhookEvent, processWebhookEvent, SIGNATURE_HEADER, } from '../webhook.js';
+/**
+ * Create a Next.js App Router webhook handler
+ *
+ * @param config - Webhook configuration
+ * @returns Route handler for POST requests
+ *
+ * @example
+ * ```typescript
+ * // app/api/webhook/route.ts
+ * import { createNextWebhookHandler } from '@bates-solutions/squareup/server';
+ *
+ * export const POST = createNextWebhookHandler({
+ *   signatureKey: process.env.SQUARE_WEBHOOK_KEY!,
+ *   handlers: {
+ *     'payment.created': async (event) => {
+ *       console.log('Payment created:', event.data.id);
+ *     },
+ *     'order.fulfillment.updated': async (event) => {
+ *       await notifyCustomer(event.data.object);
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export function createNextWebhookHandler(config) {
+    return async (request) => {
+        try {
+            // Get raw body
+            const rawBody = await request.text();
+            // Get signature from headers
+            const signature = request.headers.get(SIGNATURE_HEADER);
+            if (!signature) {
+                return Response.json({ error: 'Missing signature header' }, { status: 401 });
+            }
+            // Verify signature
+            const verification = verifySignature(rawBody, signature, config.signatureKey, config.notificationUrl);
+            if (!verification.valid) {
+                return Response.json({ error: verification.error }, { status: 401 });
+            }
+            // Parse and process event
+            const event = parseWebhookEvent(rawBody);
+            await processWebhookEvent(event, config);
+            return Response.json({ received: true, eventId: event.event_id }, { status: 200 });
+        }
+        catch (error) {
+            return Response.json({ error: error instanceof Error ? error.message : 'Webhook processing failed' }, { status: 500 });
+        }
+    };
+}
+/**
+ * Create a Next.js Pages Router API handler
+ *
+ * @param config - Webhook configuration
+ * @returns API route handler
+ *
+ * @example
+ * ```typescript
+ * // pages/api/webhook.ts
+ * import { createNextPagesWebhookHandler } from '@bates-solutions/squareup/server';
+ *
+ * export const config = {
+ *   api: { bodyParser: false }, // Required for raw body
+ * };
+ *
+ * export default createNextPagesWebhookHandler({
+ *   signatureKey: process.env.SQUARE_WEBHOOK_KEY!,
+ *   handlers: {
+ *     'payment.created': async (event) => {
+ *       console.log('Payment:', event.data.id);
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export function createNextPagesWebhookHandler(config) {
+    return async (req, res) => {
+        // Only allow POST
+        if (req.method !== 'POST') {
+            res.status(405).json({ error: 'Method not allowed' });
+            return;
+        }
+        try {
+            // Get raw body
+            const rawBody = await getRawBody(req);
+            // Get signature
+            const signatureHeader = req.headers[SIGNATURE_HEADER];
+            const signature = Array.isArray(signatureHeader)
+                ? signatureHeader[0]
+                : signatureHeader;
+            if (!signature) {
+                res.status(401).json({ error: 'Missing signature header' });
+                return;
+            }
+            // Verify signature
+            const verification = verifySignature(rawBody, signature, config.signatureKey, config.notificationUrl);
+            if (!verification.valid) {
+                res.status(401).json({ error: verification.error });
+                return;
+            }
+            // Parse and process event
+            const event = parseWebhookEvent(rawBody);
+            await processWebhookEvent(event, config);
+            res.status(200).json({ received: true, eventId: event.event_id });
+        }
+        catch (error) {
+            res.status(500).json({
+                error: error instanceof Error ? error.message : 'Webhook processing failed',
+            });
+        }
+    };
+}
+/**
+ * Read raw body from Node.js request stream
+ */
+function getRawBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on('data', (chunk) => {
+            chunks.push(chunk);
+        });
+        req.on('end', () => {
+            resolve(Buffer.concat(chunks).toString('utf8'));
+        });
+        req.on('error', reject);
+    });
+}
+/**
+ * Utility to parse webhook event from Next.js request
+ *
+ * Use this for custom handling when you don't want automatic processing
+ *
+ * @param request - The incoming request
+ * @param signatureKey - Your webhook signature key
+ * @param notificationUrl - Optional URL for signature verification
+ * @returns Parsed webhook event
+ * @throws Error if verification fails
+ *
+ * @example
+ * ```typescript
+ * // app/api/webhook/route.ts
+ * import { parseNextWebhook } from '@bates-solutions/squareup/server';
+ *
+ * export async function POST(request: Request) {
+ *   const event = await parseNextWebhook(
+ *     request,
+ *     process.env.SQUARE_WEBHOOK_KEY!
+ *   );
+ *
+ *   // Custom handling
+ *   switch (event.type) {
+ *     case 'payment.created':
+ *       // ...
+ *   }
+ *
+ *   return Response.json({ received: true });
+ * }
+ * ```
+ */
+export async function parseNextWebhook(request, signatureKey, notificationUrl) {
+    const rawBody = await request.text();
+    const signature = request.headers.get(SIGNATURE_HEADER);
+    if (!signature) {
+        throw new Error('Missing signature header');
+    }
+    const verification = verifySignature(rawBody, signature, signatureKey, notificationUrl);
+    if (!verification.valid) {
+        throw new Error(verification.error ?? 'Signature verification failed');
+    }
+    return parseWebhookEvent(rawBody);
+}
+//# sourceMappingURL=nextjs.js.map

package/dist/server/middleware/nextjs.js.map

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

package/dist/server/types.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Square Webhook Event Types
+ *
+ * @see https://developer.squareup.com/reference/square/webhooks
+ */
+export type PaymentEventType = 'payment.created' | 'payment.updated';
+export type RefundEventType = 'refund.created' | 'refund.updated';
+export type OrderEventType = 'order.created' | 'order.updated' | 'order.fulfillment.updated';
+export type CustomerEventType = 'customer.created' | 'customer.updated' | 'customer.deleted';
+export type SubscriptionEventType = 'subscription.created' | 'subscription.updated';
+export type InvoiceEventType = 'invoice.created' | 'invoice.updated' | 'invoice.published' | 'invoice.payment_made' | 'invoice.canceled';
+export type LoyaltyEventType = 'loyalty.account.created' | 'loyalty.account.updated' | 'loyalty.program.created' | 'loyalty.promotion.created';
+export type CatalogEventType = 'catalog.version.updated';
+export type InventoryEventType = 'inventory.count.updated';
+export type TeamEventType = 'team_member.created' | 'team_member.updated';
+export type LaborEventType = 'labor.timecard.created' | 'labor.timecard.updated';
+/**
+ * All Square webhook event types
+ */
+export type WebhookEventType = PaymentEventType | RefundEventType | OrderEventType | CustomerEventType | SubscriptionEventType | InvoiceEventType | LoyaltyEventType | CatalogEventType | InventoryEventType | TeamEventType | LaborEventType;
+/**
+ * Base webhook event structure
+ */
+export interface WebhookEvent<T = unknown> {
+    /** Unique ID for this event */
+    event_id: string;
+    /** Merchant ID that triggered the event */
+    merchant_id: string;
+    /** Type of event */
+    type: WebhookEventType;
+    /** When the event was created */
+    created_at: string;
+    /** Event data payload */
+    data: {
+        /** Type of object in the event */
+        type: string;
+        /** Unique ID of the object */
+        id: string;
+        /** The actual object data */
+        object: T;
+    };
+}
+/**
+ * Handler function for webhook events
+ */
+export type WebhookHandler<T = unknown> = (event: WebhookEvent<T>) => void | Promise<void>;
+/**
+ * Map of event types to their handlers
+ */
+export type WebhookHandlers = {
+    [K in WebhookEventType]?: WebhookHandler;
+};
+/**
+ * Configuration for webhook handling
+ */
+export interface WebhookConfig {
+    /** Square webhook signature key */
+    signatureKey: string;
+    /** Event handlers by type */
+    handlers: WebhookHandlers;
+    /** URL where webhooks are received (for signature verification) */
+    notificationUrl?: string;
+    /**
+     * Whether to throw on signature verification failure
+     * @default true
+     */
+    throwOnInvalidSignature?: boolean;
+}
+/**
+ * Result of webhook verification
+ */
+export interface WebhookVerificationResult {
+    /** Whether the signature is valid */
+    valid: boolean;
+    /** Error message if invalid */
+    error?: string;
+}
+/**
+ * Parsed webhook request
+ */
+export interface ParsedWebhookRequest {
+    /** The raw request body */
+    rawBody: string;
+    /** The signature from headers */
+    signature: string;
+    /** Parsed event data */
+    event: WebhookEvent;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/server/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,GAAG,iBAAiB,CAAC;AAGrE,MAAM,MAAM,eAAe,GAAG,gBAAgB,GAAG,gBAAgB,CAAC;AAGlE,MAAM,MAAM,cAAc,GACtB,eAAe,GACf,eAAe,GACf,2BAA2B,CAAC;AAGhC,MAAM,MAAM,iBAAiB,GACzB,kBAAkB,GAClB,kBAAkB,GAClB,kBAAkB,CAAC;AAGvB,MAAM,MAAM,qBAAqB,GAAG,sBAAsB,GAAG,sBAAsB,CAAC;AAGpF,MAAM,MAAM,gBAAgB,GACxB,iBAAiB,GACjB,iBAAiB,GACjB,mBAAmB,GACnB,sBAAsB,GACtB,kBAAkB,CAAC;AAGvB,MAAM,MAAM,gBAAgB,GACxB,yBAAyB,GACzB,yBAAyB,GACzB,yBAAyB,GACzB,2BAA2B,CAAC;AAGhC,MAAM,MAAM,gBAAgB,GAAG,yBAAyB,CAAC;AAGzD,MAAM,MAAM,kBAAkB,GAAG,yBAAyB,CAAC;AAG3D,MAAM,MAAM,aAAa,GAAG,qBAAqB,GAAG,qBAAqB,CAAC;AAG1E,MAAM,MAAM,cAAc,GAAG,wBAAwB,GAAG,wBAAwB,CAAC;AAEjF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB,gBAAgB,GAChB,eAAe,GACf,cAAc,GACd,iBAAiB,GACjB,qBAAqB,GACrB,gBAAgB,GAChB,gBAAgB,GAChB,gBAAgB,GAChB,kBAAkB,GAClB,aAAa,GACb,cAAc,CAAC;AAEnB;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO;IACvC,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,oBAAoB;IACpB,IAAI,EAAE,gBAAgB,CAAC;IACvB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,yBAAyB;IACzB,IAAI,EAAE;QACJ,kCAAkC;QAClC,IAAI,EAAE,MAAM,CAAC;QACb,8BAA8B;QAC9B,EAAE,EAAE,MAAM,CAAC;QACX,6BAA6B;QAC7B,MAAM,EAAE,CAAC,CAAC;KACX,CAAC;CACH;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,GAAG,OAAO,IAAI,CACxC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,KACnB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;KAC3B,CAAC,IAAI,gBAAgB,CAAC,CAAC,EAAE,cAAc;CACzC,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,mCAAmC;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,6BAA6B;IAC7B,QAAQ,EAAE,eAAe,CAAC;IAC1B,mEAAmE;IACnE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,qCAAqC;IACrC,KAAK,EAAE,OAAO,CAAC;IACf,+BAA+B;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,wBAAwB;IACxB,KAAK,EAAE,YAAY,CAAC;CACrB"}

package/dist/server/types.js

@@ -0,0 +1,7 @@
+/**
+ * Square Webhook Event Types
+ *
+ * @see https://developer.squareup.com/reference/square/webhooks
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/server/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/server/webhook.d.ts

@@ -0,0 +1,114 @@
+import type { WebhookConfig, WebhookEvent, WebhookVerificationResult, ParsedWebhookRequest } from './types.js';
+/**
+ * Header name for Square webhook signature
+ */
+export declare 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 declare function verifySignature(rawBody: string, signature: string, signatureKey: string, notificationUrl?: string): WebhookVerificationResult;
+/**
+ * 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 declare function parseWebhookEvent(rawBody: string): WebhookEvent;
+/**
+ * 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 declare function parseAndVerifyWebhook(rawBody: string, signature: string, signatureKey: string, notificationUrl?: string): ParsedWebhookRequest;
+/**
+ * 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 declare function processWebhookEvent(event: WebhookEvent, config: WebhookConfig): Promise<void>;
+/**
+ * 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 declare function createWebhookProcessor(config: WebhookConfig): (rawBody: string, signature: string) => Promise<{
+    success: boolean;
+    event?: WebhookEvent;
+    error?: string;
+}>;
+//# sourceMappingURL=webhook.d.ts.map

package/dist/server/webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../../src/server/webhook.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,yBAAyB,EACzB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,eAAO,MAAM,gBAAgB,kCAAkC,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,eAAe,CAAC,EAAE,MAAM,GACvB,yBAAyB,CA6C3B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAM/D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,eAAe,CAAC,EAAE,MAAM,GACvB,oBAAoB,CActB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,IAAI,CAAC,CAMf;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,aAAa,IAExD,SAAS,MAAM,EACf,WAAW,MAAM,KAChB,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,YAAY,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA0BvE"}