@open-mercato/core 0.4.7-develop-0a657b411f → 0.4.7-develop-e249d3e7d0

package/src/modules/sales/widgets/injection/payment-gateway-config-field/widget.ts

@@ -0,0 +1,28 @@
+import type { InjectionFieldWidget } from '@open-mercato/shared/modules/widgets/injection'
+
+const widget: InjectionFieldWidget = {
+  metadata: {
+    id: 'sales.injection.payment-gateway-config-field',
+    priority: 40,
+  },
+  fields: [
+    {
+      id: 'payment_gateways.captureMethod',
+      label: 'payment_gateways.field.captureMethod',
+      type: 'select',
+      group: 'details',
+      options: [
+        { value: 'automatic', label: 'payment_gateways.captureMethod.automatic' },
+        { value: 'manual', label: 'payment_gateways.captureMethod.manual' },
+      ],
+    },
+    {
+      id: 'payment_gateways.paymentTypes',
+      label: 'payment_gateways.field.paymentTypes',
+      type: 'text',
+      group: 'details',
+    },
+  ],
+}
+
+export default widget

package/src/modules/sales/widgets/injection/payment-gateway-status-column/widget.ts

@@ -0,0 +1,22 @@
+import type { InjectionColumnWidget } from '@open-mercato/shared/modules/widgets/injection'
+
+const widget: InjectionColumnWidget = {
+  metadata: {
+    id: 'sales.injection.payment-gateway-status-column',
+    priority: 50,
+  },
+  columns: [
+    {
+      id: 'gateway_status',
+      header: 'payment_gateways.column.gatewayStatus',
+      accessorKey: '_gateway.unifiedStatus',
+      sortable: false,
+      cell: ({ getValue }) => {
+        const value = getValue()
+        return typeof value === 'string' && value.trim().length > 0 ? value : 'pending'
+      },
+    },
+  ],
+}
+
+export default widget

package/src/modules/sales/widgets/injection-table.ts

@@ -17,6 +17,18 @@ export const injectionTable: ModuleInjectionTable = {
       priority: 50,
     },
   ],
+  'data-table:sales.payments:columns': {
+    widgetId: 'sales.injection.payment-gateway-status-column',
+    priority: 50,
+  },
+  'crud-form:sales.payment_method:fields': {
+    widgetId: 'sales.injection.payment-gateway-config-field',
+    priority: 40,
+  },
+  'crud-form:sales.sales_payment_method:fields': {
+    widgetId: 'sales.injection.payment-gateway-config-field',
+    priority: 40,
+  },
 }
 
 export default injectionTable

package/src/modules/shipping_carriers/acl.ts

@@ -0,0 +1,6 @@
+export const features = [
+  { id: 'shipping_carriers.view', title: 'View shipping carrier shipments', module: 'shipping_carriers' },
+  { id: 'shipping_carriers.manage', title: 'Manage shipping carrier operations', module: 'shipping_carriers' },
+]
+
+export default features

package/src/modules/shipping_carriers/api/cancel/route.ts

@@ -0,0 +1,53 @@
+import { NextResponse } from 'next/server'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import type { ShippingCarrierService } from '../../lib/shipping-service'
+import { cancelShipmentSchema } from '../../data/validators'
+import { shippingCarriersTag } from '../openapi'
+
+export const metadata = {
+  path: '/shipping-carriers/cancel',
+  POST: { requireAuth: true, requireFeatures: ['shipping_carriers.manage'] },
+}
+
+export async function POST(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.tenantId || !auth.orgId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+  const payload = await readJsonSafe<unknown>(req)
+  const parsed = cancelShipmentSchema.safeParse(payload)
+  if (!parsed.success) {
+    return NextResponse.json({ error: 'Invalid payload', details: parsed.error.flatten() }, { status: 422 })
+  }
+  const container = await createRequestContainer()
+  const service = container.resolve('shippingCarrierService') as ShippingCarrierService
+  try {
+    const result = await service.cancelShipment({
+      ...parsed.data,
+      organizationId: auth.orgId as string,
+      tenantId: auth.tenantId,
+    })
+    return NextResponse.json(result)
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : 'Failed to cancel shipment'
+    return NextResponse.json({ error: message }, { status: 502 })
+  }
+}
+
+export const openApi = {
+  tags: [shippingCarriersTag],
+  summary: 'Cancel shipment',
+  methods: {
+    POST: {
+      summary: 'Cancel shipment',
+      tags: [shippingCarriersTag],
+      responses: [
+        { status: 200, description: 'Shipment cancelled' },
+        { status: 422, description: 'Validation failed' },
+        { status: 502, description: 'Provider upstream error' },
+      ],
+    },
+  },
+}

package/src/modules/shipping_carriers/api/interceptors.ts

@@ -0,0 +1,19 @@
+import type { ApiInterceptor } from '@open-mercato/shared/lib/crud/api-interceptor'
+import { getShippingAdapter } from '../lib/adapter-registry'
+
+export const interceptors: ApiInterceptor[] = [
+  {
+    id: 'shipping_carriers.validate-provider',
+    targetRoute: 'shipping-carriers/*',
+    methods: ['POST', 'GET'],
+    priority: 100,
+    async before(request) {
+      const providerKey = (request.body?.providerKey ?? request.query?.providerKey) as string | undefined
+      if (!providerKey || providerKey.trim().length === 0) return { ok: true }
+      if (!getShippingAdapter(providerKey.trim())) {
+        return { ok: false, statusCode: 422, message: `Unknown shipping provider: ${providerKey}` }
+      }
+      return { ok: true }
+    },
+  },
+]

package/src/modules/shipping_carriers/api/openapi.ts

@@ -0,0 +1 @@
+export const shippingCarriersTag = 'ShippingCarriers'

package/src/modules/shipping_carriers/api/rates/route.ts

@@ -0,0 +1,53 @@
+import { NextResponse } from 'next/server'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import type { ShippingCarrierService } from '../../lib/shipping-service'
+import { calculateRatesSchema } from '../../data/validators'
+import { shippingCarriersTag } from '../openapi'
+
+export const metadata = {
+  path: '/shipping-carriers/rates',
+  POST: { requireAuth: true, requireFeatures: ['shipping_carriers.manage'] },
+}
+
+export async function POST(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.tenantId || !auth.orgId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+  const payload = await readJsonSafe<unknown>(req)
+  const parsed = calculateRatesSchema.safeParse(payload)
+  if (!parsed.success) {
+    return NextResponse.json({ error: 'Invalid payload', details: parsed.error.flatten() }, { status: 422 })
+  }
+  const container = await createRequestContainer()
+  const service = container.resolve('shippingCarrierService') as ShippingCarrierService
+  try {
+    const rates = await service.calculateRates({
+      ...parsed.data,
+      organizationId: auth.orgId as string,
+      tenantId: auth.tenantId,
+    })
+    return NextResponse.json({ rates })
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : 'Failed to calculate rates'
+    return NextResponse.json({ error: message }, { status: 502 })
+  }
+}
+
+export const openApi = {
+  tags: [shippingCarriersTag],
+  summary: 'Calculate shipping rates',
+  methods: {
+    POST: {
+      summary: 'Calculate shipping rates',
+      tags: [shippingCarriersTag],
+      responses: [
+        { status: 200, description: 'Rates calculated' },
+        { status: 422, description: 'Validation failed' },
+        { status: 502, description: 'Provider upstream error' },
+      ],
+    },
+  },
+}

package/src/modules/shipping_carriers/api/shipments/route.ts

@@ -0,0 +1,59 @@
+import { NextResponse } from 'next/server'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import type { ShippingCarrierService } from '../../lib/shipping-service'
+import { createShipmentSchema } from '../../data/validators'
+import { shippingCarriersTag } from '../openapi'
+
+export const metadata = {
+  path: '/shipping-carriers/shipments',
+  POST: { requireAuth: true, requireFeatures: ['shipping_carriers.manage'] },
+}
+
+export async function POST(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.tenantId || !auth.orgId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+  const payload = await readJsonSafe<unknown>(req)
+  const parsed = createShipmentSchema.safeParse(payload)
+  if (!parsed.success) {
+    return NextResponse.json({ error: 'Invalid payload', details: parsed.error.flatten() }, { status: 422 })
+  }
+  const container = await createRequestContainer()
+  const service = container.resolve('shippingCarrierService') as ShippingCarrierService
+  try {
+    const shipment = await service.createShipment({
+      ...parsed.data,
+      organizationId: auth.orgId as string,
+      tenantId: auth.tenantId,
+    })
+    return NextResponse.json({
+      shipmentId: shipment.id,
+      carrierShipmentId: shipment.carrierShipmentId,
+      trackingNumber: shipment.trackingNumber,
+      status: shipment.unifiedStatus,
+      labelUrl: shipment.labelUrl,
+    }, { status: 201 })
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : 'Failed to create shipment'
+    return NextResponse.json({ error: message }, { status: 502 })
+  }
+}
+
+export const openApi = {
+  tags: [shippingCarriersTag],
+  summary: 'Create shipment',
+  methods: {
+    POST: {
+      summary: 'Create shipment',
+      tags: [shippingCarriersTag],
+      responses: [
+        { status: 201, description: 'Shipment created' },
+        { status: 422, description: 'Validation failed' },
+        { status: 502, description: 'Provider upstream error' },
+      ],
+    },
+  },
+}

package/src/modules/shipping_carriers/api/tracking/route.ts

@@ -0,0 +1,56 @@
+import { NextResponse } from 'next/server'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import type { ShippingCarrierService } from '../../lib/shipping-service'
+import { trackingQuerySchema } from '../../data/validators'
+import { shippingCarriersTag } from '../openapi'
+
+export const metadata = {
+  path: '/shipping-carriers/tracking',
+  GET: { requireAuth: true, requireFeatures: ['shipping_carriers.view'] },
+}
+
+export async function GET(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.tenantId || !auth.orgId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+  const url = new URL(req.url)
+  const parsed = trackingQuerySchema.safeParse({
+    providerKey: url.searchParams.get('providerKey'),
+    shipmentId: url.searchParams.get('shipmentId') ?? undefined,
+    trackingNumber: url.searchParams.get('trackingNumber') ?? undefined,
+  })
+  if (!parsed.success) {
+    return NextResponse.json({ error: 'Invalid query', details: parsed.error.flatten() }, { status: 422 })
+  }
+  const container = await createRequestContainer()
+  const service = container.resolve('shippingCarrierService') as ShippingCarrierService
+  try {
+    const tracking = await service.getTracking({
+      ...parsed.data,
+      organizationId: auth.orgId as string,
+      tenantId: auth.tenantId,
+    })
+    return NextResponse.json(tracking)
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : 'Failed to fetch tracking'
+    return NextResponse.json({ error: message }, { status: 502 })
+  }
+}
+
+export const openApi = {
+  tags: [shippingCarriersTag],
+  summary: 'Get tracking',
+  methods: {
+    GET: {
+      summary: 'Get tracking',
+      tags: [shippingCarriersTag],
+      responses: [
+        { status: 200, description: 'Tracking returned' },
+        { status: 422, description: 'Validation failed' },
+        { status: 502, description: 'Provider upstream error' },
+      ],
+    },
+  },
+}

package/src/modules/shipping_carriers/api/webhook/[provider]/route.ts

@@ -0,0 +1,134 @@
+import { NextResponse } from 'next/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { CredentialsService } from '../../../../integrations/lib/credentials-service'
+import { CarrierShipment } from '../../../data/entities'
+import { getShippingAdapter } from '../../../lib/adapter-registry'
+import type { ShippingCarrierService } from '../../../lib/shipping-service'
+import { getShippingCarrierQueue } from '../../../lib/queue'
+import { shippingCarriersTag } from '../../openapi'
+
+export const metadata = {
+  path: '/shipping-carriers/webhook/[provider]',
+  POST: { requireAuth: false },
+}
+
+function readCarrierShipmentId(payload: Record<string, unknown> | null): string | null {
+  if (!payload) return null
+  const shipmentId = payload.shipmentId
+  if (typeof shipmentId === 'string' && shipmentId.trim().length > 0) return shipmentId.trim()
+  const data = payload.data
+  if (data && typeof data === 'object') {
+    const nested = (data as Record<string, unknown>).shipmentId
+    if (typeof nested === 'string' && nested.trim().length > 0) return nested.trim()
+  }
+  return null
+}
+
+export async function POST(req: Request, { params }: { params: Promise<{ provider: string }> | { provider: string } }) {
+  const resolvedParams = await params
+  const providerKey = resolvedParams.provider
+  const adapter = getShippingAdapter(providerKey)
+  if (!adapter) {
+    return NextResponse.json({ error: `No shipping adapter for provider: ${providerKey}` }, { status: 404 })
+  }
+
+  const rawBody = await req.text()
+  const headers: Record<string, string> = {}
+  req.headers.forEach((value, key) => {
+    headers[key] = value
+  })
+
+  const container = await createRequestContainer()
+  const service = container.resolve('shippingCarrierService') as ShippingCarrierService
+  const em = container.resolve('em') as EntityManager
+  const integrationCredentialsService = container.resolve('integrationCredentialsService') as CredentialsService
+  const queue = getShippingCarrierQueue('shipping-carriers-webhook')
+  const payload = await readJsonSafe<Record<string, unknown>>(rawBody)
+  const carrierShipmentId = readCarrierShipmentId(payload)
+
+  try {
+    const candidates = carrierShipmentId
+      ? await findWithDecryption(
+        em,
+        CarrierShipment,
+        {
+          providerKey,
+          carrierShipmentId,
+          deletedAt: null,
+        },
+        { limit: 10, orderBy: { createdAt: 'desc' } },
+      )
+      : []
+
+    let shipment = null as CarrierShipment | null
+    let matchedScope = null as { organizationId: string; tenantId: string } | null
+    let event = null as Awaited<ReturnType<typeof adapter.verifyWebhook>> | null
+    let lastVerificationError: unknown = null
+
+    for (const candidate of candidates) {
+      const candidateScope = { organizationId: candidate.organizationId, tenantId: candidate.tenantId }
+      const credentials = await integrationCredentialsService.resolve(`carrier_${providerKey}`, candidateScope) ?? {}
+      try {
+        event = await adapter.verifyWebhook({ rawBody, headers, credentials })
+        shipment = candidate
+        matchedScope = candidateScope
+        break
+      } catch (error: unknown) {
+        lastVerificationError = error
+      }
+    }
+
+    if (!event) {
+      try {
+        event = await adapter.verifyWebhook({ rawBody, headers, credentials: {} })
+      } catch (error: unknown) {
+        throw lastVerificationError ?? error
+      }
+    }
+    if (!event) {
+      throw new Error('Webhook verification failed')
+    }
+
+    if (!shipment && carrierShipmentId && matchedScope) {
+      shipment = await service.findShipmentByCarrierId(providerKey, carrierShipmentId, matchedScope)
+    }
+
+    const scope = shipment
+      ? { organizationId: shipment.organizationId, tenantId: shipment.tenantId }
+      : matchedScope
+
+    await queue.enqueue({
+      name: 'shipping-carrier-webhook',
+      payload: {
+        providerKey,
+        event,
+        shipmentId: shipment?.id ?? null,
+        scope,
+      },
+    })
+
+    return NextResponse.json({ received: true, queued: true }, { status: 202 })
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : 'Webhook verification failed'
+    return NextResponse.json({ error: message }, { status: 401 })
+  }
+}
+
+export const openApi = {
+  tags: [shippingCarriersTag],
+  summary: 'Receive shipping carrier webhook',
+  methods: {
+    POST: {
+      summary: 'Process inbound carrier webhook',
+      tags: [shippingCarriersTag],
+      responses: [
+        { status: 202, description: 'Webhook accepted for async processing' },
+        { status: 401, description: 'Signature verification failed' },
+        { status: 404, description: 'Unknown provider' },
+      ],
+    },
+  },
+}

package/src/modules/shipping_carriers/data/enrichers.ts

@@ -0,0 +1,89 @@
+import type { ResponseEnricher } from '@open-mercato/shared/lib/crud/response-enricher'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { CarrierShipment } from './entities'
+
+type SalesShipmentRecord = Record<string, unknown> & { id?: string; shipmentId?: string; orderId?: string }
+
+const salesShipmentCarrierEnricher: ResponseEnricher<SalesShipmentRecord, Record<string, unknown>> = {
+  id: 'shipping_carriers.sales-shipment-carrier',
+  targetEntity: 'sales.shipment',
+  priority: 40,
+  timeout: 2000,
+  async enrichOne(record, context) {
+    const orderId = typeof record.orderId === 'string' ? record.orderId : null
+    if (!orderId) return record
+    const em = context.em as EntityManager
+    const scope = { organizationId: context.organizationId, tenantId: context.tenantId }
+    const shipment = await findOneWithDecryption(
+      em,
+      CarrierShipment,
+      {
+        orderId,
+        organizationId: context.organizationId,
+        tenantId: context.tenantId,
+        deletedAt: null,
+      },
+      { orderBy: { createdAt: 'desc' } },
+      scope,
+    )
+    if (!shipment) return record
+    return {
+      ...record,
+      _carrier: {
+        shipmentId: shipment.id,
+        providerKey: shipment.providerKey,
+        trackingNumber: shipment.trackingNumber,
+        status: shipment.unifiedStatus,
+      },
+    }
+  },
+  async enrichMany(records, context) {
+    const orderIds = Array.from(new Set(
+      records
+        .map((record) => (typeof record.orderId === 'string' ? record.orderId : null))
+        .filter((value): value is string => Boolean(value)),
+    ))
+    if (!orderIds.length) return records
+
+    const em = context.em as EntityManager
+    const scope = { organizationId: context.organizationId, tenantId: context.tenantId }
+    const shipments = await findWithDecryption(
+      em,
+      CarrierShipment,
+      {
+        orderId: { $in: orderIds },
+        organizationId: context.organizationId,
+        tenantId: context.tenantId,
+        deletedAt: null,
+      },
+      { orderBy: { createdAt: 'desc' } },
+      scope,
+    )
+
+    const latestByOrderId = new Map<string, CarrierShipment>()
+    for (const shipment of shipments) {
+      if (!latestByOrderId.has(shipment.orderId)) {
+        latestByOrderId.set(shipment.orderId, shipment)
+      }
+    }
+
+    return records.map((record) => {
+      const orderId = typeof record.orderId === 'string' ? record.orderId : null
+      if (!orderId) return record
+      const shipment = latestByOrderId.get(orderId)
+      if (!shipment) return record
+      return {
+        ...record,
+        _carrier: {
+          shipmentId: shipment.id,
+          providerKey: shipment.providerKey,
+          trackingNumber: shipment.trackingNumber,
+          status: shipment.unifiedStatus,
+        },
+      }
+    })
+  },
+}
+
+export const enrichers: ResponseEnricher[] = [salesShipmentCarrierEnricher]

package/src/modules/shipping_carriers/data/entities.ts

@@ -0,0 +1,60 @@
+import { Entity, Index, OptionalProps, PrimaryKey, Property } from '@mikro-orm/core'
+
+@Entity({ tableName: 'carrier_shipments' })
+@Index({ properties: ['orderId', 'organizationId', 'tenantId'] })
+@Index({ properties: ['providerKey', 'carrierShipmentId', 'organizationId'] })
+@Index({ properties: ['organizationId', 'tenantId', 'unifiedStatus'] })
+export class CarrierShipment {
+  [OptionalProps]?: 'labelUrl' | 'labelData' | 'trackingEvents' | 'carrierStatus' | 'lastWebhookAt' | 'lastPolledAt' | 'createdAt' | 'updatedAt' | 'deletedAt'
+
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'order_id', type: 'uuid' })
+  orderId!: string
+
+  @Property({ name: 'provider_key', type: 'text' })
+  providerKey!: string
+
+  @Property({ name: 'carrier_shipment_id', type: 'text' })
+  carrierShipmentId!: string
+
+  @Property({ name: 'tracking_number', type: 'text' })
+  trackingNumber!: string
+
+  @Property({ name: 'unified_status', type: 'text' })
+  unifiedStatus: string = 'label_created'
+
+  @Property({ name: 'carrier_status', type: 'text', nullable: true })
+  carrierStatus?: string | null
+
+  @Property({ name: 'label_url', type: 'text', nullable: true })
+  labelUrl?: string | null
+
+  @Property({ name: 'label_data', type: 'text', nullable: true })
+  labelData?: string | null
+
+  @Property({ name: 'tracking_events', type: 'jsonb', nullable: true })
+  trackingEvents?: Array<{ status: string; occurredAt: string; location?: string }> | null
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @Property({ name: 'last_webhook_at', type: Date, nullable: true })
+  lastWebhookAt?: Date | null
+
+  @Property({ name: 'last_polled_at', type: Date, nullable: true })
+  lastPolledAt?: Date | null
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
+
+  @Property({ name: 'deleted_at', type: Date, nullable: true })
+  deletedAt?: Date | null
+}

package/src/modules/shipping_carriers/data/validators.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod'
+
+const addressSchema = z.object({
+  countryCode: z.string().min(2).max(3),
+  postalCode: z.string().min(1),
+  city: z.string().min(1),
+  line1: z.string().min(1),
+  line2: z.string().optional(),
+})
+
+const packageSchema = z.object({
+  weightKg: z.number().positive(),
+  lengthCm: z.number().positive(),
+  widthCm: z.number().positive(),
+  heightCm: z.number().positive(),
+})
+
+export const calculateRatesSchema = z.object({
+  providerKey: z.string().min(1),
+  origin: addressSchema,
+  destination: addressSchema,
+  packages: z.array(packageSchema).min(1),
+})
+
+export const createShipmentSchema = z.object({
+  providerKey: z.string().min(1),
+  orderId: z.string().uuid(),
+  origin: addressSchema,
+  destination: addressSchema,
+  packages: z.array(packageSchema).min(1),
+  serviceCode: z.string().min(1),
+  labelFormat: z.enum(['pdf', 'zpl', 'png']).optional(),
+})
+
+export const trackingQuerySchema = z.object({
+  providerKey: z.string().min(1),
+  shipmentId: z.string().uuid().optional(),
+  trackingNumber: z.string().min(1).optional(),
+}).refine((value) => Boolean(value.shipmentId || value.trackingNumber), {
+  message: 'shipmentId or trackingNumber is required',
+  path: ['shipmentId'],
+})
+
+export const cancelShipmentSchema = z.object({
+  providerKey: z.string().min(1),
+  shipmentId: z.string().uuid(),
+  reason: z.string().max(200).optional(),
+})

package/src/modules/shipping_carriers/di.ts

@@ -0,0 +1,20 @@
+import { asFunction, asValue } from 'awilix'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { AppContainer } from '@open-mercato/shared/lib/di/container'
+import type { CredentialsService } from '../integrations/lib/credentials-service'
+import { CarrierShipment } from './data/entities'
+import { createShippingCarrierService } from './lib/shipping-service'
+
+type Cradle = {
+  em: EntityManager
+  integrationCredentialsService: CredentialsService
+}
+
+export function register(container: AppContainer) {
+  container.register({
+    shippingCarrierService: asFunction(({ em, integrationCredentialsService }: Cradle) =>
+      createShippingCarrierService({ em, integrationCredentialsService }),
+    ).scoped().proxy(),
+    CarrierShipment: asValue(CarrierShipment),
+  })
+}