@thebookingkit/server 0.1.1 → 0.1.3

package/src/adapters/payment-adapter.ts

@@ -1,118 +0,0 @@
-/**
- * Abstract interface for payment processing.
- *
- * Default implementation: Stripe via `stripe` npm package.
- * Alternatives: Square, PayPal, or mock for testing.
- */
-
-/** Result of creating a payment intent */
-export interface CreatePaymentIntentResult {
-  /** Stripe PaymentIntent ID (or equivalent) */
-  paymentIntentId: string;
-  /** Client secret for confirming payment on the frontend */
-  clientSecret: string;
-  /** Current status of the payment intent */
-  status: "requires_payment_method" | "requires_confirmation" | "requires_action" | "processing" | "succeeded" | "canceled";
-}
-
-/** Result of creating a setup intent for card authorization */
-export interface CreateSetupIntentResult {
-  /** Stripe SetupIntent ID (or equivalent) */
-  setupIntentId: string;
-  /** Client secret for confirming setup on the frontend */
-  clientSecret: string;
-}
-
-/** Result of capturing a held payment */
-export interface CaptureResult {
-  /** Whether the capture was successful */
-  captured: boolean;
-  /** The payment intent ID that was captured */
-  paymentIntentId: string;
-}
-
-/** Result of a refund operation */
-export interface RefundResult {
-  /** Refund ID from the payment provider */
-  refundId: string;
-  /** Amount refunded in cents */
-  amountCents: number;
-  /** Status of the refund */
-  status: "succeeded" | "pending" | "failed";
-}
-
-/** Options for creating a payment intent */
-export interface CreatePaymentIntentOptions {
-  /** Amount in smallest currency unit (e.g., cents for USD) */
-  amountCents: number;
-  /** ISO 4217 currency code */
-  currency: string;
-  /** Connected account ID (for Stripe Connect) */
-  connectedAccountId?: string;
-  /** Whether to use manual capture (for holds) */
-  captureMethod?: "automatic" | "manual";
-  /** Metadata to attach to the payment */
-  metadata?: Record<string, string>;
-  /** Customer email for receipt */
-  customerEmail?: string;
-}
-
-/** Options for creating a setup intent */
-export interface CreateSetupIntentOptions {
-  /** Connected account ID (for Stripe Connect) */
-  connectedAccountId?: string;
-  /** Customer email */
-  customerEmail?: string;
-  /** Metadata */
-  metadata?: Record<string, string>;
-}
-
-/**
- * Payment processing adapter interface.
- *
- * Implementations handle creating payment intents, capturing holds,
- * processing refunds, and managing Stripe Connect onboarding.
- */
-export interface PaymentAdapter {
-  /**
-   * Create a payment intent for collecting payment.
-   * Use `captureMethod: 'manual'` for no-show fee holds.
-   */
-  createPaymentIntent(options: CreatePaymentIntentOptions): Promise<CreatePaymentIntentResult>;
-
-  /**
-   * Create a setup intent for authorizing a card without charging.
-   */
-  createSetupIntent(options: CreateSetupIntentOptions): Promise<CreateSetupIntentResult>;
-
-  /**
-   * Capture a previously authorized (manual capture) payment intent.
-   * Used when marking a booking as no-show.
-   */
-  capturePaymentIntent(paymentIntentId: string, amountCents?: number): Promise<CaptureResult>;
-
-  /**
-   * Cancel a payment intent (release a hold).
-   * Used when a booking completes normally and the no-show hold should be released.
-   */
-  cancelPaymentIntent(paymentIntentId: string): Promise<void>;
-
-  /**
-   * Refund a payment intent (full or partial).
-   */
-  refund(paymentIntentId: string, amountCents?: number): Promise<RefundResult>;
-
-  /**
-   * Generate a Stripe Connect onboarding URL for a provider.
-   * Returns the URL the provider should be redirected to.
-   */
-  createConnectOnboardingUrl(options: {
-    returnUrl: string;
-    refreshUrl: string;
-  }): Promise<string>;
-
-  /**
-   * Disconnect a Stripe Connect account.
-   */
-  disconnectAccount(connectedAccountId: string): Promise<void>;
-}

package/src/adapters/sms-adapter.ts

@@ -1,35 +0,0 @@
-/**
- * Abstract interface for SMS delivery.
- *
- * Default implementation: Twilio.
- * Alternatives: AWS SNS, Vonage, or mock for testing.
- */
-
-/** Options for sending an SMS */
-export interface SendSmsOptions {
-  /** Recipient phone number (E.164 format) */
-  to: string;
-  /** SMS body text */
-  body: string;
-  /** Sender phone number or alphanumeric sender ID */
-  from?: string;
-}
-
-/** Result of an SMS send operation */
-export interface SmsResult {
-  /** Message ID from the SMS provider */
-  messageId: string;
-  /** Delivery status */
-  status: "queued" | "sent" | "delivered" | "failed";
-}
-
-/**
- * SMS delivery adapter interface.
- *
- * Implementations handle sending SMS messages via a provider
- * (e.g., Twilio, AWS SNS).
- */
-export interface SmsAdapter {
-  /** Send an SMS message */
-  send(options: SendSmsOptions): Promise<SmsResult>;
-}

package/src/adapters/storage-adapter.ts

@@ -1,11 +0,0 @@
-/**
- * Storage/encryption adapter interface.
- * Default implementation uses an environment variable encryption key.
- * Swap to AWS KMS, GCP KMS, or HashiCorp Vault by implementing this interface.
- */
-export interface StorageAdapter {
-  /** Encrypt a plaintext value */
-  encrypt(plaintext: string): Promise<string>;
-  /** Decrypt an encrypted value */
-  decrypt(ciphertext: string): Promise<string>;
-}

package/src/api.ts

@@ -1,446 +0,0 @@
-/**
- * REST API utilities for SlotKit.
- *
- * Provides standardized response formatting, API key management,
- * rate limiting, pagination, and request validation helpers
- * for Next.js API routes.
- */
-
-import { createHmac, randomBytes } from "node:crypto";
-
-// ---------------------------------------------------------------------------
-// Standard Response Types
-// ---------------------------------------------------------------------------
-
-/** Standard API error */
-export interface ApiError {
-  code: string;
-  message: string;
-  details?: Record<string, unknown>;
-}
-
-/** Standard error response envelope */
-export interface ApiErrorResponse {
-  error: ApiError;
-}
-
-/** Standard success response envelope */
-export interface ApiSuccessResponse<T> {
-  data: T;
-  meta?: ApiMeta;
-}
-
-/** Pagination metadata */
-export interface ApiMeta {
-  total?: number;
-  nextCursor?: string | null;
-  prevCursor?: string | null;
-  hasMore?: boolean;
-}
-
-/** Paginated list response */
-export interface PaginatedResponse<T> {
-  data: T[];
-  meta: {
-    nextCursor: string | null;
-    hasMore: boolean;
-    total?: number;
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Error Codes
-// ---------------------------------------------------------------------------
-
-/** Standard API error codes */
-export const API_ERROR_CODES = {
-  NOT_FOUND: "NOT_FOUND",
-  UNAUTHORIZED: "UNAUTHORIZED",
-  FORBIDDEN: "FORBIDDEN",
-  VALIDATION_ERROR: "VALIDATION_ERROR",
-  CONFLICT: "CONFLICT",
-  RATE_LIMITED: "RATE_LIMITED",
-  INTERNAL_ERROR: "INTERNAL_ERROR",
-  PAYMENT_REQUIRED: "PAYMENT_REQUIRED",
-} as const;
-
-export type ApiErrorCode = (typeof API_ERROR_CODES)[keyof typeof API_ERROR_CODES];
-
-// ---------------------------------------------------------------------------
-// Response Helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Create a standardized API error response.
- *
- * @param code - Error code from API_ERROR_CODES
- * @param message - Human-readable error message
- * @param details - Optional additional details
- * @returns Standardized error response object
- */
-export function createErrorResponse(
-  code: ApiErrorCode | string,
-  message: string,
-  details?: Record<string, unknown>,
-): ApiErrorResponse {
-  return {
-    error: {
-      code,
-      message,
-      ...(details ? { details } : {}),
-    },
-  };
-}
-
-/**
- * Create a standardized API success response.
- *
- * @param data - The response data
- * @param meta - Optional pagination metadata
- * @returns Standardized success response object
- */
-export function createSuccessResponse<T>(
-  data: T,
-  meta?: ApiMeta,
-): ApiSuccessResponse<T> {
-  return {
-    data,
-    ...(meta ? { meta } : {}),
-  };
-}
-
-/**
- * Create a paginated list response.
- *
- * @param items - The page of items
- * @param nextCursor - Cursor for the next page (null if last page)
- * @param total - Optional total count
- * @returns Paginated response
- */
-export function createPaginatedResponse<T>(
-  items: T[],
-  nextCursor: string | null,
-  total?: number,
-): PaginatedResponse<T> {
-  return {
-    data: items,
-    meta: {
-      nextCursor,
-      hasMore: nextCursor !== null,
-      ...(total !== undefined ? { total } : {}),
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// API Key Management
-// ---------------------------------------------------------------------------
-
-/** An API key record */
-export interface ApiKeyRecord {
-  id: string;
-  name: string;
-  keyHash: string;
-  keyPrefix: string;
-  providerId?: string;
-  teamId?: string;
-  scopes: ApiKeyScope[];
-  rateLimit: number;
-  createdAt: Date;
-  expiresAt?: Date;
-  lastUsedAt?: Date;
-}
-
-/** API key scope */
-export type ApiKeyScope =
-  | "read:bookings"
-  | "write:bookings"
-  | "read:availability"
-  | "write:availability"
-  | "read:event-types"
-  | "write:event-types"
-  | "read:webhooks"
-  | "write:webhooks"
-  | "read:analytics"
-  | "admin";
-
-/** Result of generating a new API key */
-export interface GeneratedApiKey {
-  /** The full key (only shown once) */
-  key: string;
-  /** The prefix for display (e.g., "sk_live_abc123...") */
-  prefix: string;
-  /** The hash stored in the database */
-  hash: string;
-}
-
-/**
- * Generate a new API key.
- *
- * The full key is only returned once and should be displayed to the user.
- * Only the hash is stored in the database.
- *
- * @param prefix - Key prefix (e.g., "sk_live_" or "sk_test_")
- * @returns Generated key with hash for storage
- */
-export function generateApiKey(prefix: string = "sk_live_"): GeneratedApiKey {
-  const rawKey = randomBytes(32).toString("hex");
-  const key = `${prefix}${rawKey}`;
-  const hash = hashApiKey(key);
-  const displayPrefix = key.slice(0, prefix.length + 8) + "...";
-
-  return { key, prefix: displayPrefix, hash };
-}
-
-/**
- * Hash an API key for secure storage.
- *
- * Uses HMAC-SHA256 with a secret from the SLOTKIT_API_KEY_SECRET
- * environment variable. Throws if the secret is not configured.
- *
- * @param key - The full API key
- * @param secret - Optional HMAC secret (defaults to SLOTKIT_API_KEY_SECRET env var)
- * @returns The hex-encoded hash
- */
-export function hashApiKey(key: string, secret?: string): string {
-  const hmacSecret =
-    secret ?? process.env.SLOTKIT_API_KEY_SECRET;
-  if (!hmacSecret) {
-    throw new Error(
-      "SLOTKIT_API_KEY_SECRET environment variable is required for API key hashing. " +
-        "Set it to a random 32+ character string.",
-    );
-  }
-  return createHmac("sha256", hmacSecret).update(key).digest("hex");
-}
-
-/**
- * Verify an API key against a stored hash.
- *
- * @param key - The key to verify
- * @param storedHash - The hash stored in the database
- * @returns Whether the key is valid
- */
-export function verifyApiKey(key: string, storedHash: string): boolean {
-  const hash = hashApiKey(key);
-  if (hash.length !== storedHash.length) return false;
-
-  // Constant-time comparison
-  const a = Buffer.from(hash, "hex");
-  const b = Buffer.from(storedHash, "hex");
-
-  if (a.length !== b.length) return false;
-
-  let mismatch = 0;
-  for (let i = 0; i < a.length; i++) {
-    mismatch |= a[i] ^ b[i];
-  }
-  return mismatch === 0;
-}
-
-/**
- * Check if an API key has a required scope.
- *
- * Admin scope grants all permissions.
- *
- * @param keyScopes - The scopes granted to the API key
- * @param requiredScope - The scope to check for
- * @returns Whether the key has the required scope
- */
-export function hasScope(
-  keyScopes: ApiKeyScope[],
-  requiredScope: ApiKeyScope,
-): boolean {
-  return keyScopes.includes("admin") || keyScopes.includes(requiredScope);
-}
-
-/**
- * Check if an API key has expired.
- *
- * @param expiresAt - Optional expiry timestamp
- * @returns Whether the key is expired
- */
-export function isKeyExpired(expiresAt: Date | undefined | null): boolean {
-  if (!expiresAt) return false;
-  return expiresAt.getTime() < Date.now();
-}
-
-// ---------------------------------------------------------------------------
-// Rate Limiting
-// ---------------------------------------------------------------------------
-
-/** Rate limit state for a key */
-export interface RateLimitState {
-  count: number;
-  windowStartMs: number;
-}
-
-/** Rate limit check result */
-export interface RateLimitResult {
-  allowed: boolean;
-  remaining: number;
-  resetMs: number;
-  limit: number;
-}
-
-/**
- * Check if a request should be allowed under rate limiting.
- *
- * Uses a fixed 1-minute window.
- *
- * @param state - Current rate limit state
- * @param limit - Maximum requests per minute
- * @param nowMs - Current timestamp in milliseconds
- * @returns Rate limit check result
- */
-export function checkRateLimit(
-  state: RateLimitState | null,
-  limit: number,
-  nowMs: number = Date.now(),
-): { result: RateLimitResult; newState: RateLimitState } {
-  const windowMs = 60 * 1000; // 1 minute
-  const windowStart = nowMs - (nowMs % windowMs);
-
-  // New window or no existing state
-  if (!state || state.windowStartMs !== windowStart) {
-    return {
-      result: {
-        allowed: true,
-        remaining: limit - 1,
-        resetMs: windowStart + windowMs,
-        limit,
-      },
-      newState: { count: 1, windowStartMs: windowStart },
-    };
-  }
-
-  const newCount = state.count + 1;
-  const allowed = newCount <= limit;
-
-  return {
-    result: {
-      allowed,
-      remaining: Math.max(0, limit - newCount),
-      resetMs: windowStart + windowMs,
-      limit,
-    },
-    newState: { count: newCount, windowStartMs: windowStart },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Pagination
-// ---------------------------------------------------------------------------
-
-/**
- * Encode a cursor for pagination (base64 JSON).
- *
- * @param data - The cursor data to encode
- * @returns Base64-encoded cursor string
- */
-export function encodeCursor(data: Record<string, unknown>): string {
-  return Buffer.from(JSON.stringify(data)).toString("base64url");
-}
-
-/**
- * Decode a pagination cursor.
- *
- * @param cursor - The base64-encoded cursor string
- * @returns The decoded cursor data, or null if invalid
- */
-export function decodeCursor(
-  cursor: string,
-): Record<string, unknown> | null {
-  try {
-    const json = Buffer.from(cursor, "base64url").toString("utf-8");
-    return JSON.parse(json);
-  } catch {
-    return null;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Request Validation
-// ---------------------------------------------------------------------------
-
-/** Validation error detail */
-export interface ValidationDetail {
-  field: string;
-  message: string;
-}
-
-/** Result of input validation */
-export interface ValidationResult {
-  valid: boolean;
-  errors: ValidationDetail[];
-}
-
-/**
- * Validate API request parameters for slot queries.
- *
- * @param params - Query parameters
- * @returns Validation result
- */
-export function validateSlotQueryParams(params: {
-  providerId?: string;
-  teamId?: string;
-  eventTypeId?: string;
-  start?: string;
-  end?: string;
-  timezone?: string;
-}): ValidationResult {
-  const errors: ValidationDetail[] = [];
-
-  if (!params.providerId && !params.teamId) {
-    errors.push({
-      field: "providerId",
-      message: "Either providerId or teamId is required",
-    });
-  }
-
-  if (!params.start) {
-    errors.push({ field: "start", message: "start date is required" });
-  } else if (isNaN(Date.parse(params.start))) {
-    errors.push({
-      field: "start",
-      message: `Invalid date: "${params.start}"`,
-    });
-  }
-
-  if (!params.end) {
-    errors.push({ field: "end", message: "end date is required" });
-  } else if (isNaN(Date.parse(params.end))) {
-    errors.push({ field: "end", message: `Invalid date: "${params.end}"` });
-  }
-
-  if (params.start && params.end) {
-    const start = new Date(params.start);
-    const end = new Date(params.end);
-    if (!isNaN(start.getTime()) && !isNaN(end.getTime()) && end <= start) {
-      errors.push({ field: "end", message: "end must be after start" });
-    }
-  }
-
-  return { valid: errors.length === 0, errors };
-}
-
-/**
- * Parse and validate a sort parameter.
- *
- * @param sortParam - Sort string (e.g., "-createdAt" or "startsAt")
- * @param allowedFields - Fields that can be sorted by
- * @returns Parsed sort field and direction
- */
-export function parseSortParam(
-  sortParam: string | undefined,
-  allowedFields: string[],
-): { field: string; direction: "asc" | "desc" } | null {
-  if (!sortParam) return null;
-
-  const descending = sortParam.startsWith("-");
-  const field = descending ? sortParam.slice(1) : sortParam;
-
-  if (!allowedFields.includes(field)) return null;
-
-  return { field, direction: descending ? "desc" : "asc" };
-}