@withaevum/sdk 1.3.9 → 1.3.11

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export { CalendarAPI } from './calendar';
 export { AnalyticsAPI } from './analytics';
 export { AvailabilityAPI } from './availability';
 export { PaymentsAPI } from './payments';
-export { verifyWebhook, WebhookVerificationError } from './webhooks';
-export type { WebhookEvent } from './webhooks';
+export { verifyWebhook, WebhookVerificationError, extractWebhookSignature, isBookingEvent, isPaymentEvent, isBookingCreatedEvent, isBookingUpdatedEvent, isBookingCancelledEvent, isBookingConfirmedEvent, isPaymentSucceededEvent, isPaymentFailedEvent, isPaymentRefundedEvent, isWebhookTestEvent, } from './webhooks';
+export type { WebhookEvent, WebhookEventType, BookingCreatedEvent, BookingUpdatedEvent, BookingCancelledEvent, BookingConfirmedEvent, PaymentSucceededEvent, PaymentFailedEvent, PaymentRefundedEvent, WebhookTestEvent, } from './webhooks';
 export * from './types';
 export * from './errors';

package/dist/index.js

@@ -9,6 +9,6 @@ export { CalendarAPI } from './calendar';
 export { AnalyticsAPI } from './analytics';
 export { AvailabilityAPI } from './availability';
 export { PaymentsAPI } from './payments';
-export { verifyWebhook, WebhookVerificationError } from './webhooks';
+export { verifyWebhook, WebhookVerificationError, extractWebhookSignature, isBookingEvent, isPaymentEvent, isBookingCreatedEvent, isBookingUpdatedEvent, isBookingCancelledEvent, isBookingConfirmedEvent, isPaymentSucceededEvent, isPaymentFailedEvent, isPaymentRefundedEvent, isWebhookTestEvent, } from './webhooks';
 export * from './types';
 export * from './errors';

package/dist/webhooks.d.ts

@@ -1,20 +1,176 @@
+export type WebhookEventType = 'booking.created' | 'booking.updated' | 'booking.cancelled' | 'booking.confirmed' | 'payment.succeeded' | 'payment.failed' | 'payment.refunded' | 'offering.created' | 'offering.updated' | 'offering.deleted' | 'availability.updated' | 'webhook.test';
 export interface WebhookEvent {
-    type: string;
+    type: WebhookEventType;
     version: string;
     id: string;
     delivery_id: string;
     timestamp: string;
     data: Record<string, unknown>;
 }
+export interface BookingCreatedEvent extends WebhookEvent {
+    type: 'booking.created';
+    data: {
+        id: string;
+        organization_id: string;
+        customer_id: string | null;
+        status: string;
+        start_time: string;
+        end_time: string;
+        price_cents: number | null;
+        notes: string | null;
+        provider_ids: string[];
+        offering_ids: string[];
+        customer?: {
+            id: string;
+            name: string | null;
+            email: string | null;
+            phone: string | null;
+        };
+    };
+}
+export interface BookingUpdatedEvent extends WebhookEvent {
+    type: 'booking.updated';
+    data: {
+        id: string;
+        organization_id: string;
+        customer_id: string | null;
+        status: string;
+        start_time: string;
+        end_time: string;
+        price_cents: number | null;
+        notes: string | null;
+        provider_ids: string[];
+        offering_ids: string[];
+        previous_status?: string;
+        customer?: {
+            id: string;
+            name: string | null;
+            email: string | null;
+            phone: string | null;
+        };
+    };
+}
+export interface BookingCancelledEvent extends WebhookEvent {
+    type: 'booking.cancelled';
+    data: {
+        id: string;
+        organization_id: string;
+        cancelled_at: string;
+        cancellation_reason?: string;
+        [key: string]: unknown;
+    };
+}
+export interface BookingConfirmedEvent extends WebhookEvent {
+    type: 'booking.confirmed';
+    data: {
+        id: string;
+        organization_id: string;
+        confirmed_at: string;
+        [key: string]: unknown;
+    };
+}
+export interface PaymentSucceededEvent extends WebhookEvent {
+    type: 'payment.succeeded';
+    data: {
+        id: string;
+        booking_id: string;
+        organization_id: string;
+        amount_cents: number;
+        currency: string;
+        payment_intent_id: string;
+        charged_at: string;
+        customer_id: string | null;
+    };
+}
+export interface PaymentFailedEvent extends WebhookEvent {
+    type: 'payment.failed';
+    data: {
+        id: string;
+        booking_id: string;
+        organization_id: string;
+        amount_cents: number;
+        payment_intent_id: string;
+        failure_reason?: string;
+        customer_id: string | null;
+    };
+}
+export interface PaymentRefundedEvent extends WebhookEvent {
+    type: 'payment.refunded';
+    data: {
+        id: string;
+        booking_id: string;
+        organization_id: string;
+        refund_amount_cents: number;
+        refunded_at: string;
+        customer_id: string | null;
+    };
+}
+export interface WebhookTestEvent extends WebhookEvent {
+    type: 'webhook.test';
+    data: {
+        message: string;
+        test: boolean;
+        organization_id: string;
+    };
+}
 export declare class WebhookVerificationError extends Error {
     constructor(message: string);
 }
+/**
+ * Extract webhook signature from request headers
+ * @param headers - Request headers (Headers object or Record<string, string>)
+ * @returns Signature string or null if not found
+ */
+export declare function extractWebhookSignature(headers: Headers | Record<string, string | string[] | null | undefined>): string | null;
 /**
  * Verify webhook signature and parse event
+ * Supports secret rotation by checking previous secret if provided and not expired
  * @param body - Raw request body as string
  * @param signature - Signature from X-Aevum-Signature header
  * @param secret - Webhook secret
+ * @param previousSecret - Previous secret (optional, for secret rotation grace period)
+ * @param previousSecretExpiresAt - When previous secret expires (optional, ISO 8601 string or Date)
  * @returns Parsed webhook event
  * @throws WebhookVerificationError if signature verification fails
  */
-export declare function verifyWebhook(body: string, signature: string, secret: string): WebhookEvent;
+export declare function verifyWebhook(body: string, signature: string, secret: string, previousSecret?: string | null, previousSecretExpiresAt?: string | Date | null): WebhookEvent;
+/**
+ * Type guard: Check if event is a booking event
+ */
+export declare function isBookingEvent(event: WebhookEvent): event is BookingCreatedEvent | BookingUpdatedEvent | BookingCancelledEvent | BookingConfirmedEvent;
+/**
+ * Type guard: Check if event is a payment event
+ */
+export declare function isPaymentEvent(event: WebhookEvent): event is PaymentSucceededEvent | PaymentFailedEvent | PaymentRefundedEvent;
+/**
+ * Type guard: Check if event is booking.created
+ */
+export declare function isBookingCreatedEvent(event: WebhookEvent): event is BookingCreatedEvent;
+/**
+ * Type guard: Check if event is booking.updated
+ */
+export declare function isBookingUpdatedEvent(event: WebhookEvent): event is BookingUpdatedEvent;
+/**
+ * Type guard: Check if event is booking.cancelled
+ */
+export declare function isBookingCancelledEvent(event: WebhookEvent): event is BookingCancelledEvent;
+/**
+ * Type guard: Check if event is booking.confirmed
+ */
+export declare function isBookingConfirmedEvent(event: WebhookEvent): event is BookingConfirmedEvent;
+/**
+ * Type guard: Check if event is payment.succeeded
+ */
+export declare function isPaymentSucceededEvent(event: WebhookEvent): event is PaymentSucceededEvent;
+/**
+ * Type guard: Check if event is payment.failed
+ */
+export declare function isPaymentFailedEvent(event: WebhookEvent): event is PaymentFailedEvent;
+/**
+ * Type guard: Check if event is payment.refunded
+ */
+export declare function isPaymentRefundedEvent(event: WebhookEvent): event is PaymentRefundedEvent;
+/**
+ * Type guard: Check if event is webhook.test
+ */
+export declare function isWebhookTestEvent(event: WebhookEvent): event is WebhookTestEvent;

package/dist/webhooks.js

@@ -7,15 +7,36 @@ export class WebhookVerificationError extends Error {
         this.name = 'WebhookVerificationError';
     }
 }
+/**
+ * Extract webhook signature from request headers
+ * @param headers - Request headers (Headers object or Record<string, string>)
+ * @returns Signature string or null if not found
+ */
+export function extractWebhookSignature(headers) {
+    if (headers instanceof Headers) {
+        return headers.get('x-aevum-signature');
+    }
+    const signature = headers['x-aevum-signature'];
+    if (typeof signature === 'string') {
+        return signature;
+    }
+    if (Array.isArray(signature) && signature.length > 0) {
+        return signature[0];
+    }
+    return null;
+}
 /**
  * Verify webhook signature and parse event
+ * Supports secret rotation by checking previous secret if provided and not expired
  * @param body - Raw request body as string
  * @param signature - Signature from X-Aevum-Signature header
  * @param secret - Webhook secret
+ * @param previousSecret - Previous secret (optional, for secret rotation grace period)
+ * @param previousSecretExpiresAt - When previous secret expires (optional, ISO 8601 string or Date)
  * @returns Parsed webhook event
  * @throws WebhookVerificationError if signature verification fails
  */
-export function verifyWebhook(body, signature, secret) {
+export function verifyWebhook(body, signature, secret, previousSecret, previousSecretExpiresAt) {
     if (!body || !signature || !secret) {
         throw new WebhookVerificationError('Missing required parameters: body, signature, or secret');
     }
@@ -25,13 +46,30 @@ export function verifyWebhook(body, signature, secret) {
         throw new WebhookVerificationError('Invalid signature format. Expected format: sha256=<hex>');
     }
     const providedSignature = signatureMatch[1];
-    // Compute signature with secret
+    // Compute signature with current secret
     const computedSignature = crypto
         .createHmac('sha256', secret)
         .update(body)
         .digest('hex');
     // Compare signatures using constant-time comparison
-    if (!crypto.timingSafeEqual(Buffer.from(providedSignature, 'hex'), Buffer.from(computedSignature, 'hex'))) {
+    let isValid = crypto.timingSafeEqual(Buffer.from(providedSignature, 'hex'), Buffer.from(computedSignature, 'hex'));
+    // If current secret doesn't match and previous secret is provided, check it
+    if (!isValid &&
+        previousSecret &&
+        previousSecretExpiresAt) {
+        const expiresAt = typeof previousSecretExpiresAt === 'string'
+            ? new Date(previousSecretExpiresAt)
+            : previousSecretExpiresAt;
+        // Check if previous secret is still valid (within grace period)
+        if (new Date() < expiresAt) {
+            const previousComputedSignature = crypto
+                .createHmac('sha256', previousSecret)
+                .update(body)
+                .digest('hex');
+            isValid = crypto.timingSafeEqual(Buffer.from(providedSignature, 'hex'), Buffer.from(previousComputedSignature, 'hex'));
+        }
+    }
+    if (!isValid) {
         throw new WebhookVerificationError('Invalid webhook signature');
     }
     // Parse and validate event
@@ -48,3 +86,68 @@ export function verifyWebhook(body, signature, secret) {
     }
     return event;
 }
+/**
+ * Type guard: Check if event is a booking event
+ */
+export function isBookingEvent(event) {
+    return (event.type === 'booking.created' ||
+        event.type === 'booking.updated' ||
+        event.type === 'booking.cancelled' ||
+        event.type === 'booking.confirmed');
+}
+/**
+ * Type guard: Check if event is a payment event
+ */
+export function isPaymentEvent(event) {
+    return (event.type === 'payment.succeeded' ||
+        event.type === 'payment.failed' ||
+        event.type === 'payment.refunded');
+}
+/**
+ * Type guard: Check if event is booking.created
+ */
+export function isBookingCreatedEvent(event) {
+    return event.type === 'booking.created';
+}
+/**
+ * Type guard: Check if event is booking.updated
+ */
+export function isBookingUpdatedEvent(event) {
+    return event.type === 'booking.updated';
+}
+/**
+ * Type guard: Check if event is booking.cancelled
+ */
+export function isBookingCancelledEvent(event) {
+    return event.type === 'booking.cancelled';
+}
+/**
+ * Type guard: Check if event is booking.confirmed
+ */
+export function isBookingConfirmedEvent(event) {
+    return event.type === 'booking.confirmed';
+}
+/**
+ * Type guard: Check if event is payment.succeeded
+ */
+export function isPaymentSucceededEvent(event) {
+    return event.type === 'payment.succeeded';
+}
+/**
+ * Type guard: Check if event is payment.failed
+ */
+export function isPaymentFailedEvent(event) {
+    return event.type === 'payment.failed';
+}
+/**
+ * Type guard: Check if event is payment.refunded
+ */
+export function isPaymentRefundedEvent(event) {
+    return event.type === 'payment.refunded';
+}
+/**
+ * Type guard: Check if event is webhook.test
+ */
+export function isWebhookTestEvent(event) {
+    return event.type === 'webhook.test';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withaevum/sdk",
-  "version": "1.3.9",
+  "version": "1.3.11",
   "description": "TypeScript SDK for the Aevum API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",