@scell/sdk 1.0.0

package/src/utils/retry.ts

@@ -0,0 +1,167 @@
+/**
+ * Retry utility with exponential backoff and jitter
+ *
+ * @packageDocumentation
+ */
+
+import { ScellRateLimitError, ScellServerError } from '../errors.js';
+
+/**
+ * Retry configuration options
+ */
+export interface RetryOptions {
+  /** Maximum number of retry attempts (default: 3) */
+  maxRetries?: number | undefined;
+  /** Base delay in milliseconds (default: 1000) */
+  baseDelay?: number | undefined;
+  /** Maximum delay in milliseconds (default: 30000) */
+  maxDelay?: number | undefined;
+  /** Jitter factor (0-1, default: 0.1) */
+  jitterFactor?: number | undefined;
+  /** Custom function to determine if error is retryable */
+  isRetryable?: ((error: unknown) => boolean) | undefined;
+}
+
+/**
+ * Default retry options
+ */
+const DEFAULT_RETRY_OPTIONS: Required<Omit<RetryOptions, 'isRetryable'>> = {
+  maxRetries: 3,
+  baseDelay: 1000,
+  maxDelay: 30000,
+  jitterFactor: 0.1,
+};
+
+/**
+ * Check if an error is retryable (429 or 5xx)
+ */
+export function isRetryableError(error: unknown): boolean {
+  if (error instanceof ScellRateLimitError) {
+    return true;
+  }
+  if (error instanceof ScellServerError) {
+    return true;
+  }
+  // Network errors are also retryable
+  if (error instanceof Error && error.name === 'ScellNetworkError') {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Calculate delay with exponential backoff and jitter
+ *
+ * @param attempt - Current attempt number (0-indexed)
+ * @param baseDelay - Base delay in milliseconds
+ * @param maxDelay - Maximum delay in milliseconds
+ * @param jitterFactor - Jitter factor (0-1)
+ * @param retryAfter - Optional retry-after header value in seconds
+ * @returns Delay in milliseconds
+ */
+export function calculateDelay(
+  attempt: number,
+  baseDelay: number,
+  maxDelay: number,
+  jitterFactor: number,
+  retryAfter?: number
+): number {
+  // If we have a retry-after header, use it
+  if (retryAfter !== undefined && retryAfter > 0) {
+    return retryAfter * 1000;
+  }
+
+  // Exponential backoff: baseDelay * 2^attempt
+  const exponentialDelay = baseDelay * Math.pow(2, attempt);
+
+  // Cap at maxDelay
+  const cappedDelay = Math.min(exponentialDelay, maxDelay);
+
+  // Add jitter: delay * (1 +/- jitterFactor * random)
+  const jitter = cappedDelay * jitterFactor * (Math.random() * 2 - 1);
+
+  return Math.floor(cappedDelay + jitter);
+}
+
+/**
+ * Sleep for a specified duration
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Execute a function with retry logic
+ *
+ * @param fn - Async function to execute
+ * @param options - Retry options
+ * @returns Result of the function
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   () => client.invoices.create(data),
+ *   { maxRetries: 5 }
+ * );
+ * ```
+ */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions = {}
+): Promise<T> {
+  const maxRetries = options.maxRetries ?? DEFAULT_RETRY_OPTIONS.maxRetries;
+  const baseDelay = options.baseDelay ?? DEFAULT_RETRY_OPTIONS.baseDelay;
+  const maxDelay = options.maxDelay ?? DEFAULT_RETRY_OPTIONS.maxDelay;
+  const jitterFactor = options.jitterFactor ?? DEFAULT_RETRY_OPTIONS.jitterFactor;
+  const isRetryable = options.isRetryable ?? isRetryableError;
+
+  let lastError: unknown;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+
+      // Check if we should retry
+      if (attempt >= maxRetries || !isRetryable(error)) {
+        throw error;
+      }
+
+      // Get retry-after header if available
+      const retryAfter: number | undefined =
+        error instanceof ScellRateLimitError ? error.retryAfter : undefined;
+
+      // Calculate delay
+      const delay = calculateDelay(
+        attempt,
+        baseDelay,
+        maxDelay,
+        jitterFactor,
+        retryAfter
+      );
+
+      // Wait before retrying
+      await sleep(delay);
+    }
+  }
+
+  // This should never be reached, but TypeScript needs it
+  throw lastError;
+}
+
+/**
+ * Create a retry wrapper with pre-configured options
+ *
+ * @example
+ * ```typescript
+ * const retry = createRetryWrapper({ maxRetries: 5 });
+ * const result = await retry(() => client.invoices.create(data));
+ * ```
+ */
+export function createRetryWrapper(
+  defaultOptions: RetryOptions = {}
+): <T>(fn: () => Promise<T>, options?: RetryOptions) => Promise<T> {
+  return <T>(fn: () => Promise<T>, options: RetryOptions = {}) =>
+    withRetry(fn, { ...defaultOptions, ...options });
+}

package/src/utils/webhook-verify.ts

@@ -0,0 +1,290 @@
+/**
+ * Webhook signature verification utility
+ *
+ * @packageDocumentation
+ */
+
+import type { WebhookPayload } from '../types/webhooks.js';
+
+/**
+ * Signature verification options
+ */
+export interface VerifySignatureOptions {
+  /** Tolerance in seconds for timestamp validation (default: 300 = 5 minutes) */
+  tolerance?: number | undefined;
+}
+
+/**
+ * Parse the X-Scell-Signature header
+ *
+ * @param header - The signature header value (format: "t=timestamp,v1=signature")
+ * @returns Parsed timestamp and signature
+ */
+function parseSignatureHeader(header: string): {
+  timestamp: number;
+  signature: string;
+} | null {
+  const parts = header.split(',');
+  let timestamp: number | undefined;
+  let signature: string | undefined;
+
+  for (const part of parts) {
+    const splitIndex = part.indexOf('=');
+    if (splitIndex === -1) continue;
+
+    const key = part.substring(0, splitIndex);
+    const value = part.substring(splitIndex + 1);
+
+    if (key === 't') {
+      timestamp = parseInt(value, 10);
+    } else if (key === 'v1') {
+      signature = value;
+    }
+  }
+
+  if (timestamp === undefined || signature === undefined) {
+    return null;
+  }
+
+  return { timestamp, signature };
+}
+
+/**
+ * Compute HMAC-SHA256 signature
+ *
+ * @param payload - The payload string
+ * @param timestamp - The timestamp
+ * @param secret - The webhook secret
+ * @returns Hex-encoded signature
+ */
+async function computeSignature(
+  payload: string,
+  timestamp: number,
+  secret: string
+): Promise<string> {
+  const signedPayload = `${timestamp}.${payload}`;
+
+  // Use Web Crypto API (works in Node.js 18+ and browsers)
+  const encoder = new TextEncoder();
+  const keyData = encoder.encode(secret);
+  const messageData = encoder.encode(signedPayload);
+
+  const cryptoKey = await crypto.subtle.importKey(
+    'raw',
+    keyData,
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign']
+  );
+
+  const signatureBuffer = await crypto.subtle.sign(
+    'HMAC',
+    cryptoKey,
+    messageData
+  );
+
+  // Convert to hex string
+  return Array.from(new Uint8Array(signatureBuffer))
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+/**
+ * Constant-time string comparison to prevent timing attacks
+ */
+function secureCompare(a: string, b: string): boolean {
+  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;
+}
+
+/**
+ * Scell Webhook signature verification utilities
+ *
+ * @example
+ * ```typescript
+ * import { ScellWebhooks } from '@scell/sdk';
+ *
+ * // In your webhook endpoint
+ * app.post('/webhooks/scell', async (req, res) => {
+ *   const signature = req.headers['x-scell-signature'];
+ *   const payload = JSON.stringify(req.body);
+ *
+ *   const isValid = await ScellWebhooks.verifySignature(
+ *     payload,
+ *     signature,
+ *     process.env.WEBHOOK_SECRET
+ *   );
+ *
+ *   if (!isValid) {
+ *     return res.status(401).send('Invalid signature');
+ *   }
+ *
+ *   // Process the webhook
+ *   const event = ScellWebhooks.parsePayload(payload);
+ *   console.log('Received event:', event.event);
+ * });
+ * ```
+ */
+export const ScellWebhooks = {
+  /**
+   * Verify webhook signature
+   *
+   * @param payload - Raw request body as string
+   * @param signature - Value of X-Scell-Signature header
+   * @param secret - Your webhook secret (whsec_...)
+   * @param options - Verification options
+   * @returns True if signature is valid
+   *
+   * @example
+   * ```typescript
+   * const isValid = await ScellWebhooks.verifySignature(
+   *   rawBody,
+   *   req.headers['x-scell-signature'],
+   *   'whsec_abc123...'
+   * );
+   * ```
+   */
+  async verifySignature(
+    payload: string,
+    signature: string,
+    secret: string,
+    options: VerifySignatureOptions = {}
+  ): Promise<boolean> {
+    const { tolerance = 300 } = options;
+
+    // Parse the signature header
+    const parsed = parseSignatureHeader(signature);
+    if (!parsed) {
+      return false;
+    }
+
+    const { timestamp, signature: providedSignature } = parsed;
+
+    // Check timestamp tolerance
+    const now = Math.floor(Date.now() / 1000);
+    if (Math.abs(now - timestamp) > tolerance) {
+      return false;
+    }
+
+    // Compute expected signature
+    const expectedSignature = await computeSignature(payload, timestamp, secret);
+
+    // Constant-time comparison
+    return secureCompare(expectedSignature, providedSignature);
+  },
+
+  /**
+   * Verify webhook signature synchronously using Node.js crypto
+   * (Only works in Node.js environment)
+   *
+   * @param payload - Raw request body as string
+   * @param signature - Value of X-Scell-Signature header
+   * @param secret - Your webhook secret (whsec_...)
+   * @param options - Verification options
+   * @returns True if signature is valid
+   */
+  verifySignatureSync(
+    payload: string,
+    signature: string,
+    secret: string,
+    options: VerifySignatureOptions = {}
+  ): boolean {
+    const { tolerance = 300 } = options;
+
+    // Parse the signature header
+    const parsed = parseSignatureHeader(signature);
+    if (!parsed) {
+      return false;
+    }
+
+    const { timestamp, signature: providedSignature } = parsed;
+
+    // Check timestamp tolerance
+    const now = Math.floor(Date.now() / 1000);
+    if (Math.abs(now - timestamp) > tolerance) {
+      return false;
+    }
+
+    // Use Node.js crypto for sync operation
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const crypto = require('crypto') as typeof import('crypto');
+    const signedPayload = `${timestamp}.${payload}`;
+    const expectedSignature = crypto
+      .createHmac('sha256', secret)
+      .update(signedPayload)
+      .digest('hex');
+
+    // Use Node.js timingSafeEqual
+    try {
+      return crypto.timingSafeEqual(
+        Buffer.from(expectedSignature),
+        Buffer.from(providedSignature)
+      );
+    } catch {
+      return false;
+    }
+  },
+
+  /**
+   * Parse webhook payload
+   *
+   * @param payload - Raw request body as string
+   * @returns Parsed webhook payload
+   *
+   * @example
+   * ```typescript
+   * const event = ScellWebhooks.parsePayload<InvoiceWebhookData>(rawBody);
+   * if (event.event === 'invoice.validated') {
+   *   console.log('Invoice validated:', event.data.invoice_number);
+   * }
+   * ```
+   */
+  parsePayload<T = unknown>(payload: string): WebhookPayload<T> {
+    return JSON.parse(payload) as WebhookPayload<T>;
+  },
+
+  /**
+   * Construct a test webhook event for local testing
+   *
+   * @param event - Event type
+   * @param data - Event data
+   * @param secret - Webhook secret for signing
+   * @returns Object with payload and headers for testing
+   */
+  async constructTestEvent<T>(
+    event: string,
+    data: T,
+    secret: string
+  ): Promise<{
+    payload: string;
+    headers: Record<string, string>;
+  }> {
+    const timestamp = Math.floor(Date.now() / 1000);
+    const webhookPayload: WebhookPayload<T> = {
+      event: event as WebhookPayload<T>['event'],
+      timestamp: new Date().toISOString(),
+      data,
+    };
+
+    const payload = JSON.stringify(webhookPayload);
+    const signature = await computeSignature(payload, timestamp, secret);
+
+    return {
+      payload,
+      headers: {
+        'X-Scell-Signature': `t=${timestamp},v1=${signature}`,
+        'X-Scell-Event': event,
+        'X-Scell-Delivery': crypto.randomUUID(),
+        'Content-Type': 'application/json',
+      },
+    };
+  },
+};