Shared Definitions

interface User {
  // Frontend identifier (client-generated)
  clientUserId: string;          // Format: user_{timestamp}_{random}

  // Backend identifiers (system-generated)
  middlewareUserId: string;      // Format: usr_{alphanumeric}
  shopifyCustomerId: string;     // Format: gid://shopify/Customer/{id}
  googleAiUserId: string;        // Format: user_{id}

  // Core attributes
  email: string;
  firstName?: string;
  lastName?: string;
  displayName?: string;

  // Timestamps (ISO 8601)
  createdAt: string;
  updatedAt: string;
  lastSeenAt: string;
}

interface Session {
  // Session identifier
  sessionId: string;             // Format: session_{timestamp}_{random}

  // User association
  userId?: string;               // Linked after identification
  email?: string;                // Linked after identification

  // Session metadata
  deviceInfo: {
    type: 'mobile' | 'desktop' | 'tablet';
    browser: string;
    os: string;
    screenResolution?: string;
  };

  // Traffic source
  referrer?: string;
  landingPage: string;
  utmParams?: {
    source?: string;
    medium?: string;
    campaign?: string;
  };

  // Timestamps (ISO 8601)
  createdAt: string;
  lastActiveAt: string;
  expiresAt?: string;
}

interface ConsentStatus {
  [purpose: string]: ConsentRecord;
}

interface ConsentRecord {
  granted: boolean;              // true = opted in, false = opted out
  timestamp: string;             // ISO 8601 when consent was recorded
  version?: string;              // Consent policy version (e.g., "v2.1")
  method?: 'explicit' | 'implicit';
}

// Standard consent purposes
type ConsentPurpose =
  | 'functional'    // Essential (always true)
  | 'analytics'     // Performance tracking
  | 'marketing'     // Personalization
  | 'thirdParty';   // Third-party sharing

interface UCPEvent {
  eventId?: string;              // Format: evt_{timestamp}_{random}
  type: EventType;
  category?: EventCategory;
  sessionId: string;
  userId?: string;
  page: string;                  // URL path
  referrer?: string;
  data?: Record<string, any>;
  timestamp: string;             // ISO 8601
}

type EventType =
  | 'page_view'
  | 'click'
  | 'form_submit'
  | 'add_to_cart'
  | 'remove_from_cart'
  | 'checkout_start'
  | 'purchase'
  | 'search'
  | 'consent_updated'
  | 'user_identified'
  | 'session_start'
  | 'session_end';

type EventCategory =
  | 'navigation'
  | 'engagement'
  | 'conversion'
  | 'system';

interface Product {
  // Identifiers
  handle: string;                // URL-safe slug (frontend primary key)
  shopifyId: string;             // gid://shopify/Product/{id}
  middlewareId?: string;         // prod_{alphanumeric}

  // Core attributes
  title: string;
  description: string;
  descriptionHtml?: string;

  // Pricing
  priceRange: {
    min: Money;
    max: Money;
  };

  // Media
  images: ProductImage[];
  featuredImage?: ProductImage;

  // Variants & Options
  variants: ProductVariant[];
  options: ProductOption[];

  // Classification
  productType?: string;
  vendor?: string;
  tags: string[];
  collections: string[];

  // Availability
  available: boolean;
  totalInventory?: number;

  // Timestamps (ISO 8601)
  createdAt: string;
  updatedAt: string;
}

interface Money {
  amount: string;                // Decimal string (e.g., "99.99")
  currencyCode: string;          // ISO 4217 (e.g., "USD")
}

interface WebhookPayload {
  // Event metadata
  eventType: string;
  timestamp: string;             // ISO 8601

  // Idempotency
  idempotencyKey?: string;       // Format: {sessionId}_{eventType}_{timestamp}

  // Event data
  eventData: Record<string, any>;

  // Session context
  session: {
    sessionId: string;
    userId?: string;
    email?: string;
    consentStatus: ConsentStatus;
    userHistory: UCPEvent[];
  };

  // Security
  signature?: string;            // HMAC-SHA256 of payload
}

interface APIResponse<T> {
  success: boolean;
  data?: T;
  error?: {
    code: string;
    message: string;
    details?: Record<string, any>;
  };
  meta?: {
    timestamp: string;
    requestId?: string;
    idempotencyKey?: string;
  };
}

interface PaginatedResponse<T> extends APIResponse<T[]> {
  pagination: {
    page: number;
    limit: number;
    total: number;
    totalPages: number;
    hasNextPage: boolean;
    cursor?: string;
  };
}

// HMAC-SHA256 Webhook Signature
const signature = crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(JSON.stringify(payload))
  .digest('hex');

// Idempotency Key Format
const idempotencyKey = `${sessionId}_${eventType}_${Date.now()}`;