@withaevum/sdk 0.0.1

package/dist/webhooks.d.ts

@@ -0,0 +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: 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, 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

@@ -0,0 +1,153 @@
+// packages/sdk/src/webhooks.ts
+// Webhook verification utilities
+import crypto from 'crypto';
+export class WebhookVerificationError extends Error {
+    constructor(message) {
+        super(message);
+        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, previousSecret, previousSecretExpiresAt) {
+    if (!body || !signature || !secret) {
+        throw new WebhookVerificationError('Missing required parameters: body, signature, or secret');
+    }
+    // Extract signature from format: sha256=<hex>
+    const signatureMatch = signature.match(/^sha256=(.+)$/);
+    if (!signatureMatch) {
+        throw new WebhookVerificationError('Invalid signature format. Expected format: sha256=<hex>');
+    }
+    const providedSignature = signatureMatch[1];
+    // Compute signature with current secret
+    const computedSignature = crypto
+        .createHmac('sha256', secret)
+        .update(body)
+        .digest('hex');
+    // Compare signatures using constant-time comparison
+    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
+    let event;
+    try {
+        event = JSON.parse(body);
+    }
+    catch (error) {
+        throw new WebhookVerificationError(`Invalid JSON payload: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // Validate event structure
+    if (!event.type || !event.version || !event.id || !event.delivery_id) {
+        throw new WebhookVerificationError('Invalid event structure: missing required fields');
+    }
+    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

@@ -0,0 +1,52 @@
+{
+  "name": "@withaevum/sdk",
+  "version": "0.0.1",
+  "description": "TypeScript SDK for the Aevum API",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "module": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "lint": "echo \"No linting configured\""
+  },
+  "keywords": [
+    "aevum",
+    "scheduling",
+    "bookings",
+    "api",
+    "sdk",
+    "typescript",
+    "calendar",
+    "appointments"
+  ],
+  "author": "",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/getaevum/aevum.git",
+    "directory": "packages/sdk"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.1",
+    "typescript": "^5.6.3"
+  }
+}