AI Prompt: Forma3D.Connect — Phase 1: Shopify Inbound ✅¶

apps/api/src/
├── shopify/
│   ├── shopify.module.ts
│   ├── shopify.controller.ts           # Webhook receiver
│   ├── shopify.service.ts              # Shopify business logic
│   ├── shopify-api.client.ts           # API client
│   ├── dto/
│   │   ├── shopify-order.dto.ts        # Shopify order DTOs
│   │   ├── shopify-webhook.dto.ts      # Webhook payload DTOs
│   │   └── create-fulfillment.dto.ts   # Fulfillment DTOs
│   ├── guards/
│   │   └── shopify-webhook.guard.ts    # HMAC verification
│   └── interfaces/
│       └── shopify-types.ts            # Shopify type definitions
│
├── orders/
│   ├── orders.module.ts
│   ├── orders.controller.ts            # Order REST endpoints
│   ├── orders.service.ts               # Order business logic
│   ├── orders.repository.ts            # Prisma order operations
│   ├── dto/
│   │   ├── order.dto.ts
│   │   ├── create-order.dto.ts
│   │   └── order-query.dto.ts
│   └── events/
│       └── order.events.ts             # Order event definitions
│
├── line-items/
│   ├── line-items.module.ts
│   ├── line-items.service.ts
│   └── line-items.repository.ts
│
└── product-mappings/
    ├── product-mappings.module.ts
    ├── product-mappings.controller.ts  # CRUD for mappings
    ├── product-mappings.service.ts
    ├── product-mappings.repository.ts
    └── dto/
        ├── product-mapping.dto.ts
        └── create-product-mapping.dto.ts

libs/domain/src/
├── shopify/
│   ├── index.ts
│   ├── shopify-order.entity.ts         # Shopify order types
│   ├── shopify-product.entity.ts       # Shopify product types
│   └── shopify-webhook.types.ts        # Webhook types
└── index.ts                            # Update exports

/**
 * Shopify Order representation
 * Based on Shopify Admin API 2024-01
 */
export interface ShopifyOrder {
  id: number;
  admin_graphql_api_id: string;
  order_number: number;
  name: string; // e.g., "#1001"
  email: string | null;
  created_at: string;
  updated_at: string;
  cancelled_at: string | null;
  closed_at: string | null;
  processed_at: string;
  financial_status: ShopifyFinancialStatus;
  fulfillment_status: ShopifyFulfillmentStatus | null;
  currency: string;
  total_price: string;
  subtotal_price: string;
  total_tax: string;
  total_discounts: string;
  total_shipping_price_set: ShopifyPriceSet;
  customer: ShopifyCustomer | null;
  billing_address: ShopifyAddress | null;
  shipping_address: ShopifyAddress | null;
  line_items: ShopifyLineItem[];
  fulfillments: ShopifyFulfillment[];
  note: string | null;
  tags: string;
  test: boolean;
}

export type ShopifyFinancialStatus =
  | 'pending'
  | 'authorized'
  | 'partially_paid'
  | 'paid'
  | 'partially_refunded'
  | 'refunded'
  | 'voided';

export type ShopifyFulfillmentStatus = 'fulfilled' | 'partial' | 'restocked' | null;

export interface ShopifyCustomer {
  id: number;
  email: string | null;
  first_name: string | null;
  last_name: string | null;
  phone: string | null;
}

export interface ShopifyAddress {
  first_name: string | null;
  last_name: string | null;
  address1: string | null;
  address2: string | null;
  city: string | null;
  province: string | null;
  province_code: string | null;
  country: string | null;
  country_code: string | null;
  zip: string | null;
  phone: string | null;
  company: string | null;
}

export interface ShopifyLineItem {
  id: number;
  admin_graphql_api_id: string;
  product_id: number | null;
  variant_id: number | null;
  title: string;
  variant_title: string | null;
  sku: string | null;
  quantity: number;
  price: string;
  fulfillable_quantity: number;
  fulfillment_status: string | null;
}

export interface ShopifyFulfillment {
  id: number;
  order_id: number;
  status: string;
  tracking_number: string | null;
  tracking_url: string | null;
  tracking_company: string | null;
}

export interface ShopifyPriceSet {
  shop_money: ShopifyMoney;
  presentment_money: ShopifyMoney;
}

export interface ShopifyMoney {
  amount: string;
  currency_code: string;
}

export interface ShopifyProduct {
  id: number;
  title: string;
  handle: string;
  status: 'active' | 'archived' | 'draft';
  variants: ShopifyVariant[];
}

export interface ShopifyVariant {
  id: number;
  product_id: number;
  title: string;
  sku: string | null;
  price: string;
  inventory_quantity: number;
}

export interface ShopifyWebhook {
  id: number;
  address: string;
  topic: string;
  created_at: string;
  updated_at: string;
  format: string;
  api_version: string;
}

import { Injectable, Logger } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { ShopifyOrder, ShopifyProduct, ShopifyVariant, ShopifyWebhook } from '@forma3d/domain';

interface FulfillmentInput {
  line_items: Array<{ id: number; quantity: number }>;
  tracking_info?: {
    number?: string;
    url?: string;
    company?: string;
  };
  notify_customer?: boolean;
}

interface FulfillmentResponse {
  fulfillment: {
    id: number;
    order_id: number;
    status: string;
    tracking_number: string | null;
    tracking_url: string | null;
  };
}

interface OrderQueryParams {
  status?: 'open' | 'closed' | 'cancelled' | 'any';
  financial_status?: string;
  fulfillment_status?: string;
  created_at_min?: string;
  created_at_max?: string;
  updated_at_min?: string;
  updated_at_max?: string;
  limit?: number;
  since_id?: number;
}

@Injectable()
export class ShopifyApiClient {
  private readonly logger = new Logger(ShopifyApiClient.name);
  private readonly baseUrl: string;
  private readonly accessToken: string;
  private readonly apiVersion: string;

  constructor(private readonly configService: ConfigService) {
    const shopDomain = this.configService.getOrThrow<string>('SHOPIFY_SHOP_DOMAIN');
    this.apiVersion = this.configService.getOrThrow<string>('SHOPIFY_API_VERSION');
    this.accessToken = this.configService.getOrThrow<string>('SHOPIFY_ACCESS_TOKEN');
    this.baseUrl = `https://${shopDomain}/admin/api/${this.apiVersion}`;
  }

  /**
   * Generic request handler with rate limiting and error handling
   */
  private async request<T>(
    method: 'GET' | 'POST' | 'PUT' | 'DELETE',
    endpoint: string,
    body?: unknown
  ): Promise<T> {
    const url = `${this.baseUrl}${endpoint}`;

    const headers: HeadersInit = {
      'Content-Type': 'application/json',
      'X-Shopify-Access-Token': this.accessToken,
    };

    const options: RequestInit = {
      method,
      headers,
      body: body ? JSON.stringify(body) : undefined,
    };

    this.logger.debug(`Shopify API ${method} ${endpoint}`);

    const response = await fetch(url, options);

    // Handle rate limiting
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || '2';
      const waitTime = parseInt(retryAfter, 10) * 1000;
      this.logger.warn(`Rate limited. Waiting ${waitTime}ms before retry.`);
      await this.delay(waitTime);
      return this.request<T>(method, endpoint, body);
    }

    if (!response.ok) {
      const errorBody = await response.text();
      this.logger.error(`Shopify API error: ${response.status} - ${errorBody}`);
      throw new Error(`Shopify API error: ${response.status} - ${errorBody}`);
    }

    return response.json() as Promise<T>;
  }

  private delay(ms: number): Promise<void> {
    return new Promise((resolve) => setTimeout(resolve, ms));
  }

  // =========================================================================
  // Orders
  // =========================================================================

  async getOrder(orderId: string | number): Promise<ShopifyOrder> {
    const response = await this.request<{ order: ShopifyOrder }>('GET', `/orders/${orderId}.json`);
    return response.order;
  }

  async getOrders(params: OrderQueryParams = {}): Promise<ShopifyOrder[]> {
    const queryParams = new URLSearchParams();

    Object.entries(params).forEach(([key, value]) => {
      if (value !== undefined) {
        queryParams.append(key, String(value));
      }
    });

    const queryString = queryParams.toString();
    const endpoint = `/orders.json${queryString ? `?${queryString}` : ''}`;

    const response = await this.request<{ orders: ShopifyOrder[] }>('GET', endpoint);
    return response.orders;
  }

  // =========================================================================
  // Fulfillment
  // =========================================================================

  async createFulfillment(
    orderId: string | number,
    data: FulfillmentInput
  ): Promise<FulfillmentResponse> {
    return this.request<FulfillmentResponse>('POST', `/orders/${orderId}/fulfillments.json`, {
      fulfillment: data,
    });
  }

  // =========================================================================
  // Products
  // =========================================================================

  async getProducts(limit = 50): Promise<ShopifyProduct[]> {
    const response = await this.request<{ products: ShopifyProduct[] }>(
      'GET',
      `/products.json?limit=${limit}`
    );
    return response.products;
  }

  async getProductVariants(productId: string | number): Promise<ShopifyVariant[]> {
    const response = await this.request<{ variants: ShopifyVariant[] }>(
      'GET',
      `/products/${productId}/variants.json`
    );
    return response.variants;
  }

  // =========================================================================
  // Webhooks
  // =========================================================================

  async registerWebhook(topic: string, address: string): Promise<ShopifyWebhook> {
    const response = await this.request<{ webhook: ShopifyWebhook }>('POST', '/webhooks.json', {
      webhook: {
        topic,
        address,
        format: 'json',
      },
    });
    return response.webhook;
  }

  async listWebhooks(): Promise<ShopifyWebhook[]> {
    const response = await this.request<{ webhooks: ShopifyWebhook[] }>('GET', '/webhooks.json');
    return response.webhooks;
  }

  async deleteWebhook(webhookId: number): Promise<void> {
    await this.request<void>('DELETE', `/webhooks/${webhookId}.json`);
  }

  /**
   * Verify HMAC signature from Shopify webhook
   */
  static verifyWebhookSignature(body: string, hmacHeader: string, secret: string): boolean {
    const crypto = require('crypto');
    const hash = crypto.createHmac('sha256', secret).update(body, 'utf8').digest('base64');
    return hash === hmacHeader;
  }
}

import {
  Injectable,
  CanActivate,
  ExecutionContext,
  UnauthorizedException,
  Logger,
} from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { Request } from 'express';
import * as crypto from 'crypto';

@Injectable()
export class ShopifyWebhookGuard implements CanActivate {
  private readonly logger = new Logger(ShopifyWebhookGuard.name);
  private readonly webhookSecret: string;

  constructor(private readonly configService: ConfigService) {
    this.webhookSecret = this.configService.getOrThrow<string>('SHOPIFY_WEBHOOK_SECRET');
  }

  canActivate(context: ExecutionContext): boolean {
    const request = context.switchToHttp().getRequest<Request>();

    const hmacHeader = request.headers['x-shopify-hmac-sha256'] as string;
    const shopDomain = request.headers['x-shopify-shop-domain'] as string;
    const topic = request.headers['x-shopify-topic'] as string;

    if (!hmacHeader) {
      this.logger.warn('Missing HMAC header in webhook request');
      throw new UnauthorizedException('Missing HMAC signature');
    }

    // Get raw body for HMAC verification
    const rawBody = (request as Request & { rawBody?: Buffer }).rawBody;

    if (!rawBody) {
      this.logger.error('Raw body not available for HMAC verification');
      throw new UnauthorizedException('Unable to verify signature');
    }

    const isValid = this.verifySignature(rawBody.toString('utf8'), hmacHeader);

    if (!isValid) {
      this.logger.warn(`Invalid HMAC signature from ${shopDomain} for topic ${topic}`);
      throw new UnauthorizedException('Invalid HMAC signature');
    }

    this.logger.debug(`Verified webhook from ${shopDomain}: ${topic}`);
    return true;
  }

  private verifySignature(body: string, hmacHeader: string): boolean {
    const hash = crypto
      .createHmac('sha256', this.webhookSecret)
      .update(body, 'utf8')
      .digest('base64');

    return crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(hmacHeader));
  }
}

import { ShopifyOrder } from '@forma3d/domain';

export type ShopifyWebhookTopic =
  | 'orders/create'
  | 'orders/updated'
  | 'orders/cancelled'
  | 'orders/fulfilled';

export interface WebhookHeaders {
  'x-shopify-topic': ShopifyWebhookTopic;
  'x-shopify-hmac-sha256': string;
  'x-shopify-shop-domain': string;
  'x-shopify-api-version': string;
  'x-shopify-webhook-id': string;
}

export interface OrderWebhookPayload extends ShopifyOrder {
  // Additional webhook-specific fields if any
}

import {
  Controller,
  Post,
  Body,
  Headers,
  UseGuards,
  Logger,
  HttpCode,
  HttpStatus,
} from '@nestjs/common';
import { ShopifyWebhookGuard } from './guards/shopify-webhook.guard';
import { ShopifyService } from './shopify.service';
import { OrderWebhookPayload, ShopifyWebhookTopic } from './dto/shopify-webhook.dto';

@Controller('api/v1/webhooks/shopify')
export class ShopifyController {
  private readonly logger = new Logger(ShopifyController.name);

  constructor(private readonly shopifyService: ShopifyService) {}

  @Post()
  @UseGuards(ShopifyWebhookGuard)
  @HttpCode(HttpStatus.OK)
  async handleWebhook(
    @Headers('x-shopify-topic') topic: ShopifyWebhookTopic,
    @Headers('x-shopify-webhook-id') webhookId: string,
    @Body() payload: OrderWebhookPayload
  ): Promise<{ received: boolean }> {
    this.logger.log(`Received webhook: ${topic} (ID: ${webhookId})`);

    try {
      switch (topic) {
        case 'orders/create':
          await this.shopifyService.handleOrderCreated(payload, webhookId);
          break;

        case 'orders/updated':
          await this.shopifyService.handleOrderUpdated(payload, webhookId);
          break;

        case 'orders/cancelled':
          await this.shopifyService.handleOrderCancelled(payload, webhookId);
          break;

        case 'orders/fulfilled':
          await this.shopifyService.handleOrderFulfilled(payload, webhookId);
          break;

        default:
          this.logger.warn(`Unhandled webhook topic: ${topic}`);
      }
    } catch (error) {
      // Log error but return 200 to prevent Shopify retries for processing errors
      this.logger.error(`Error processing webhook ${topic}: ${error}`);
      // Re-throw only for critical errors that should trigger retry
      if (this.isCriticalError(error)) {
        throw error;
      }
    }

    return { received: true };
  }

  private isCriticalError(error: unknown): boolean {
    // Database connection errors should trigger retry
    if (error instanceof Error) {
      return error.message.includes('database') || error.message.includes('connection');
    }
    return false;
  }
}

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app/app.module';
import { Logger, ValidationPipe } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import * as bodyParser from 'body-parser';

async function bootstrap() {
  const app = await NestFactory.create(AppModule, {
    // Enable raw body for webhook signature verification
    rawBody: true,
  });

  const configService = app.get(ConfigService);
  const port = configService.get<number>('APP_PORT', 3000);
  const frontendUrl = configService.get<string>('FRONTEND_URL', 'http://localhost:4200');

  // Enable CORS
  app.enableCors({
    origin: frontendUrl,
    credentials: true,
  });

  // Global validation pipe
  app.useGlobalPipes(
    new ValidationPipe({
      whitelist: true,
      forbidNonWhitelisted: true,
      transform: true,
    })
  );

  // Raw body parser for webhooks
  app.use(
    bodyParser.json({
      verify: (req: Request & { rawBody?: Buffer }, _res, buf) => {
        req.rawBody = buf;
      },
    })
  );

  await app.listen(port);
  Logger.log(`🚀 Application is running on: http://localhost:${port}`);
}

bootstrap();

import { Injectable, Logger } from '@nestjs/common';
import { PrismaService } from '../database/prisma.service';
import { Order, LineItem, OrderStatus, LineItemStatus, Prisma } from '@prisma/client';

export interface CreateOrderInput {
  shopifyOrderId: string;
  shopifyOrderNumber: string;
  customerName: string;
  customerEmail?: string;
  shippingAddress: Prisma.JsonValue;
  totalPrice: Prisma.Decimal;
  currency: string;
  lineItems: CreateLineItemInput[];
}

export interface CreateLineItemInput {
  shopifyLineItemId: string;
  productSku: string;
  productName: string;
  variantTitle?: string;
  quantity: number;
  unitPrice: Prisma.Decimal;
}

export type OrderWithLineItems = Order & { lineItems: LineItem[] };

@Injectable()
export class OrdersRepository {
  private readonly logger = new Logger(OrdersRepository.name);

  constructor(private readonly prisma: PrismaService) {}

  async create(input: CreateOrderInput): Promise<OrderWithLineItems> {
    return this.prisma.order.create({
      data: {
        shopifyOrderId: input.shopifyOrderId,
        shopifyOrderNumber: input.shopifyOrderNumber,
        customerName: input.customerName,
        customerEmail: input.customerEmail,
        shippingAddress: input.shippingAddress,
        totalPrice: input.totalPrice,
        currency: input.currency,
        lineItems: {
          create: input.lineItems.map((item) => ({
            shopifyLineItemId: item.shopifyLineItemId,
            productSku: item.productSku,
            productName: item.productName,
            variantTitle: item.variantTitle,
            quantity: item.quantity,
            unitPrice: item.unitPrice,
          })),
        },
      },
      include: { lineItems: true },
    });
  }

  async findByShopifyOrderId(shopifyOrderId: string): Promise<OrderWithLineItems | null> {
    return this.prisma.order.findUnique({
      where: { shopifyOrderId },
      include: { lineItems: true },
    });
  }

  async findById(id: string): Promise<OrderWithLineItems | null> {
    return this.prisma.order.findUnique({
      where: { id },
      include: { lineItems: true },
    });
  }

  async findAll(params: {
    status?: OrderStatus;
    skip?: number;
    take?: number;
    orderBy?: Prisma.OrderOrderByWithRelationInput;
  }): Promise<{ orders: OrderWithLineItems[]; total: number }> {
    const where: Prisma.OrderWhereInput = params.status ? { status: params.status } : {};

    const [orders, total] = await Promise.all([
      this.prisma.order.findMany({
        where,
        skip: params.skip,
        take: params.take,
        orderBy: params.orderBy || { createdAt: 'desc' },
        include: { lineItems: true },
      }),
      this.prisma.order.count({ where }),
    ]);

    return { orders, total };
  }

  async updateStatus(
    id: string,
    status: OrderStatus,
    additionalData?: Partial<Order>
  ): Promise<Order> {
    return this.prisma.order.update({
      where: { id },
      data: {
        status,
        ...additionalData,
        ...(status === OrderStatus.COMPLETED ? { completedAt: new Date() } : {}),
      },
    });
  }

  async updateFulfillment(
    id: string,
    fulfillmentData: {
      shopifyFulfillmentId: string;
      trackingNumber?: string;
      trackingUrl?: string;
    }
  ): Promise<Order> {
    return this.prisma.order.update({
      where: { id },
      data: {
        shopifyFulfillmentId: fulfillmentData.shopifyFulfillmentId,
        trackingNumber: fulfillmentData.trackingNumber,
        trackingUrl: fulfillmentData.trackingUrl,
        status: OrderStatus.COMPLETED,
        completedAt: new Date(),
      },
    });
  }

  async exists(shopifyOrderId: string): Promise<boolean> {
    const count = await this.prisma.order.count({
      where: { shopifyOrderId },
    });
    return count > 0;
  }
}

import { Injectable, Logger, NotFoundException, ConflictException } from '@nestjs/common';
import { OrdersRepository, CreateOrderInput, OrderWithLineItems } from './orders.repository';
import { OrderStatus, LineItemStatus } from '@prisma/client';
import { EventEmitter2 } from '@nestjs/event-emitter';
import { EventLogService } from '../event-log/event-log.service';

export interface OrderCreatedEvent {
  orderId: string;
  shopifyOrderId: string;
  lineItemCount: number;
}

export interface OrderStatusChangedEvent {
  orderId: string;
  previousStatus: OrderStatus;
  newStatus: OrderStatus;
}

@Injectable()
export class OrdersService {
  private readonly logger = new Logger(OrdersService.name);

  constructor(
    private readonly ordersRepository: OrdersRepository,
    private readonly eventEmitter: EventEmitter2,
    private readonly eventLogService: EventLogService
  ) {}

  /**
   * Create order from Shopify webhook data
   * Implements idempotency - returns existing order if already exists
   */
  async createFromShopify(input: CreateOrderInput, webhookId: string): Promise<OrderWithLineItems> {
    // Check for existing order (idempotency)
    const existing = await this.ordersRepository.findByShopifyOrderId(input.shopifyOrderId);

    if (existing) {
      this.logger.debug(`Order ${input.shopifyOrderId} already exists, skipping creation`);
      return existing;
    }

    // Create new order
    const order = await this.ordersRepository.create(input);

    this.logger.log(`Created order ${order.id} from Shopify order ${input.shopifyOrderId}`);

    // Log event
    await this.eventLogService.log({
      orderId: order.id,
      eventType: 'order.created',
      severity: 'INFO',
      message: `Order created from Shopify webhook`,
      metadata: {
        webhookId,
        shopifyOrderNumber: input.shopifyOrderNumber,
        lineItemCount: order.lineItems.length,
      },
    });

    // Emit event for downstream processing
    this.eventEmitter.emit('order.created', {
      orderId: order.id,
      shopifyOrderId: input.shopifyOrderId,
      lineItemCount: order.lineItems.length,
    } satisfies OrderCreatedEvent);

    return order;
  }

  async findById(id: string): Promise<OrderWithLineItems> {
    const order = await this.ordersRepository.findById(id);
    if (!order) {
      throw new NotFoundException(`Order ${id} not found`);
    }
    return order;
  }

  async findByShopifyOrderId(shopifyOrderId: string): Promise<OrderWithLineItems | null> {
    return this.ordersRepository.findByShopifyOrderId(shopifyOrderId);
  }

  async findAll(params: {
    status?: OrderStatus;
    page?: number;
    pageSize?: number;
  }): Promise<{ orders: OrderWithLineItems[]; total: number; page: number; pageSize: number }> {
    const page = params.page || 1;
    const pageSize = params.pageSize || 50;

    const { orders, total } = await this.ordersRepository.findAll({
      status: params.status,
      skip: (page - 1) * pageSize,
      take: pageSize,
    });

    return { orders, total, page, pageSize };
  }

  async updateStatus(id: string, newStatus: OrderStatus): Promise<OrderWithLineItems> {
    const order = await this.findById(id);
    const previousStatus = order.status;

    if (previousStatus === newStatus) {
      return order;
    }

    // Validate status transition
    this.validateStatusTransition(previousStatus, newStatus);

    await this.ordersRepository.updateStatus(id, newStatus);

    await this.eventLogService.log({
      orderId: id,
      eventType: 'order.status_changed',
      severity: 'INFO',
      message: `Order status changed from ${previousStatus} to ${newStatus}`,
      metadata: { previousStatus, newStatus },
    });

    this.eventEmitter.emit('order.status_changed', {
      orderId: id,
      previousStatus,
      newStatus,
    } satisfies OrderStatusChangedEvent);

    return this.findById(id);
  }

  async cancelOrder(id: string, reason?: string): Promise<OrderWithLineItems> {
    const order = await this.findById(id);

    if (order.status === OrderStatus.COMPLETED) {
      throw new ConflictException('Cannot cancel a completed order');
    }

    await this.ordersRepository.updateStatus(id, OrderStatus.CANCELLED);

    await this.eventLogService.log({
      orderId: id,
      eventType: 'order.cancelled',
      severity: 'WARNING',
      message: reason || 'Order cancelled',
      metadata: { previousStatus: order.status },
    });

    this.eventEmitter.emit('order.cancelled', { orderId: id, reason });

    return this.findById(id);
  }

  private validateStatusTransition(from: OrderStatus, to: OrderStatus): void {
    const validTransitions: Record<OrderStatus, OrderStatus[]> = {
      [OrderStatus.PENDING]: [OrderStatus.PROCESSING, OrderStatus.CANCELLED, OrderStatus.FAILED],
      [OrderStatus.PROCESSING]: [
        OrderStatus.PARTIALLY_COMPLETED,
        OrderStatus.COMPLETED,
        OrderStatus.FAILED,
        OrderStatus.CANCELLED,
      ],
      [OrderStatus.PARTIALLY_COMPLETED]: [
        OrderStatus.COMPLETED,
        OrderStatus.FAILED,
        OrderStatus.CANCELLED,
      ],
      [OrderStatus.COMPLETED]: [], // Terminal state
      [OrderStatus.FAILED]: [OrderStatus.PENDING], // Can retry
      [OrderStatus.CANCELLED]: [], // Terminal state
    };

    if (!validTransitions[from].includes(to)) {
      throw new ConflictException(`Invalid status transition from ${from} to ${to}`);
    }
  }
}

import { Injectable, Logger } from '@nestjs/common';
import { PrismaService } from '../database/prisma.service';
import { EventSeverity, Prisma } from '@prisma/client';

export interface LogEventInput {
  orderId?: string;
  printJobId?: string;
  eventType: string;
  severity: 'INFO' | 'WARNING' | 'ERROR';
  message: string;
  metadata?: Record<string, unknown>;
}

@Injectable()
export class EventLogService {
  private readonly logger = new Logger(EventLogService.name);

  constructor(private readonly prisma: PrismaService) {}

  async log(input: LogEventInput): Promise<void> {
    try {
      await this.prisma.eventLog.create({
        data: {
          orderId: input.orderId,
          printJobId: input.printJobId,
          eventType: input.eventType,
          severity: input.severity as EventSeverity,
          message: input.message,
          metadata: input.metadata as Prisma.JsonValue,
        },
      });

      // Also log to application logger
      const logMethod =
        input.severity === 'ERROR' ? 'error' : input.severity === 'WARNING' ? 'warn' : 'log';

      this.logger[logMethod](`[${input.eventType}] ${input.message}`, input.metadata);
    } catch (error) {
      // Don't fail the main operation if logging fails
      this.logger.error(`Failed to write event log: ${error}`);
    }
  }

  async findByOrderId(
    orderId: string,
    options?: { take?: number }
  ): Promise<
    Array<{
      id: string;
      eventType: string;
      severity: EventSeverity;
      message: string;
      metadata: Prisma.JsonValue;
      createdAt: Date;
    }>
  > {
    return this.prisma.eventLog.findMany({
      where: { orderId },
      orderBy: { createdAt: 'desc' },
      take: options?.take || 100,
      select: {
        id: true,
        eventType: true,
        severity: true,
        message: true,
        metadata: true,
        createdAt: true,
      },
    });
  }
}

import { Injectable, Logger } from '@nestjs/common';
import { PrismaService } from '../database/prisma.service';
import { ProductMapping, AssemblyPart, Prisma } from '@prisma/client';

export interface CreateProductMappingInput {
  shopifyProductId: string;
  shopifyVariantId?: string;
  sku: string;
  productName: string;
  description?: string;
  isAssembly?: boolean;
  defaultPrintProfile?: Prisma.JsonValue;
  assemblyParts?: CreateAssemblyPartInput[];
}

export interface CreateAssemblyPartInput {
  partName: string;
  partNumber: number;
  simplyPrintFileId: string;
  simplyPrintFileName?: string;
  printProfile?: Prisma.JsonValue;
  estimatedPrintTime?: number;
  quantityPerProduct?: number;
}

export type ProductMappingWithParts = ProductMapping & { assemblyParts: AssemblyPart[] };

@Injectable()
export class ProductMappingsRepository {
  private readonly logger = new Logger(ProductMappingsRepository.name);

  constructor(private readonly prisma: PrismaService) {}

  async create(input: CreateProductMappingInput): Promise<ProductMappingWithParts> {
    const { assemblyParts, ...mappingData } = input;

    return this.prisma.productMapping.create({
      data: {
        ...mappingData,
        assemblyParts: assemblyParts
          ? {
              create: assemblyParts.map((part) => ({
                partName: part.partName,
                partNumber: part.partNumber,
                simplyPrintFileId: part.simplyPrintFileId,
                simplyPrintFileName: part.simplyPrintFileName,
                printProfile: part.printProfile,
                estimatedPrintTime: part.estimatedPrintTime,
                quantityPerProduct: part.quantityPerProduct || 1,
              })),
            }
          : undefined,
      },
      include: { assemblyParts: true },
    });
  }

  async findBySku(sku: string): Promise<ProductMappingWithParts | null> {
    return this.prisma.productMapping.findUnique({
      where: { sku },
      include: { assemblyParts: { orderBy: { partNumber: 'asc' } } },
    });
  }

  async findById(id: string): Promise<ProductMappingWithParts | null> {
    return this.prisma.productMapping.findUnique({
      where: { id },
      include: { assemblyParts: { orderBy: { partNumber: 'asc' } } },
    });
  }

  async findAll(params?: {
    isActive?: boolean;
    skip?: number;
    take?: number;
  }): Promise<{ mappings: ProductMappingWithParts[]; total: number }> {
    const where: Prisma.ProductMappingWhereInput = {};

    if (params?.isActive !== undefined) {
      where.isActive = params.isActive;
    }

    const [mappings, total] = await Promise.all([
      this.prisma.productMapping.findMany({
        where,
        skip: params?.skip,
        take: params?.take,
        orderBy: { productName: 'asc' },
        include: { assemblyParts: { orderBy: { partNumber: 'asc' } } },
      }),
      this.prisma.productMapping.count({ where }),
    ]);

    return { mappings, total };
  }

  async update(
    id: string,
    input: Partial<Omit<CreateProductMappingInput, 'assemblyParts'>>
  ): Promise<ProductMapping> {
    return this.prisma.productMapping.update({
      where: { id },
      data: input,
    });
  }

  async setActive(id: string, isActive: boolean): Promise<ProductMapping> {
    return this.prisma.productMapping.update({
      where: { id },
      data: { isActive },
    });
  }

  async delete(id: string): Promise<void> {
    await this.prisma.productMapping.delete({ where: { id } });
  }

  async addAssemblyPart(mappingId: string, part: CreateAssemblyPartInput): Promise<AssemblyPart> {
    return this.prisma.assemblyPart.create({
      data: {
        productMappingId: mappingId,
        partName: part.partName,
        partNumber: part.partNumber,
        simplyPrintFileId: part.simplyPrintFileId,
        simplyPrintFileName: part.simplyPrintFileName,
        printProfile: part.printProfile,
        estimatedPrintTime: part.estimatedPrintTime,
        quantityPerProduct: part.quantityPerProduct || 1,
      },
    });
  }

  async updateAssemblyPart(
    partId: string,
    input: Partial<CreateAssemblyPartInput>
  ): Promise<AssemblyPart> {
    return this.prisma.assemblyPart.update({
      where: { id: partId },
      data: input,
    });
  }

  async deleteAssemblyPart(partId: string): Promise<void> {
    await this.prisma.assemblyPart.delete({ where: { id: partId } });
  }
}

import { Injectable, Logger, NotFoundException, ConflictException } from '@nestjs/common';
import {
  ProductMappingsRepository,
  CreateProductMappingInput,
  ProductMappingWithParts,
} from './product-mappings.repository';

@Injectable()
export class ProductMappingsService {
  private readonly logger = new Logger(ProductMappingsService.name);

  constructor(private readonly repository: ProductMappingsRepository) {}

  async create(input: CreateProductMappingInput): Promise<ProductMappingWithParts> {
    // Check for existing mapping with same SKU
    const existing = await this.repository.findBySku(input.sku);
    if (existing) {
      throw new ConflictException(`Product mapping with SKU ${input.sku} already exists`);
    }

    // If has assembly parts, mark as assembly
    const isAssembly = (input.assemblyParts?.length || 0) > 1;

    const mapping = await this.repository.create({
      ...input,
      isAssembly,
    });

    this.logger.log(`Created product mapping: ${mapping.sku} (${mapping.productName})`);
    return mapping;
  }

  async findBySku(sku: string): Promise<ProductMappingWithParts | null> {
    return this.repository.findBySku(sku);
  }

  async findById(id: string): Promise<ProductMappingWithParts> {
    const mapping = await this.repository.findById(id);
    if (!mapping) {
      throw new NotFoundException(`Product mapping ${id} not found`);
    }
    return mapping;
  }

  async findAll(params?: { isActive?: boolean; page?: number; pageSize?: number }): Promise<{
    mappings: ProductMappingWithParts[];
    total: number;
    page: number;
    pageSize: number;
  }> {
    const page = params?.page || 1;
    const pageSize = params?.pageSize || 50;

    const { mappings, total } = await this.repository.findAll({
      isActive: params?.isActive,
      skip: (page - 1) * pageSize,
      take: pageSize,
    });

    return { mappings, total, page, pageSize };
  }

  async update(
    id: string,
    input: Partial<Omit<CreateProductMappingInput, 'assemblyParts' | 'sku'>>
  ): Promise<ProductMappingWithParts> {
    await this.findById(id); // Ensure exists
    await this.repository.update(id, input);
    return this.findById(id);
  }

  async setActive(id: string, isActive: boolean): Promise<ProductMappingWithParts> {
    await this.findById(id); // Ensure exists
    await this.repository.setActive(id, isActive);
    this.logger.log(`Product mapping ${id} ${isActive ? 'activated' : 'deactivated'}`);
    return this.findById(id);
  }

  async delete(id: string): Promise<void> {
    await this.findById(id); // Ensure exists
    await this.repository.delete(id);
    this.logger.log(`Deleted product mapping ${id}`);
  }

  /**
   * Check if all SKUs in a list have active mappings
   * Returns list of unmapped SKUs
   */
  async findUnmappedSkus(skus: string[]): Promise<string[]> {
    const unmapped: string[] = [];

    for (const sku of skus) {
      const mapping = await this.repository.findBySku(sku);
      if (!mapping || !mapping.isActive) {
        unmapped.push(sku);
      }
    }

    return unmapped;
  }
}