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

package/src/modules/shipping_carriers/events.ts

@@ -0,0 +1,16 @@
+import { createModuleEvents } from '@open-mercato/shared/modules/events'
+
+const events = [
+  { id: 'shipping_carriers.shipment.created', label: 'Shipment Created', category: 'lifecycle', entity: 'shipment' },
+  { id: 'shipping_carriers.shipment.status_changed', label: 'Shipment Status Changed', category: 'lifecycle', entity: 'shipment' },
+  { id: 'shipping_carriers.shipment.delivered', label: 'Shipment Delivered', category: 'lifecycle', entity: 'shipment' },
+  { id: 'shipping_carriers.shipment.returned', label: 'Shipment Returned', category: 'lifecycle', entity: 'shipment' },
+  { id: 'shipping_carriers.shipment.cancelled', label: 'Shipment Cancelled', category: 'lifecycle', entity: 'shipment' },
+  { id: 'shipping_carriers.webhook.received', label: 'Shipping Webhook Received', category: 'system', excludeFromTriggers: true },
+  { id: 'shipping_carriers.webhook.failed', label: 'Shipping Webhook Failed', category: 'system', excludeFromTriggers: true },
+] as const
+
+export const eventsConfig = createModuleEvents({ moduleId: 'shipping_carriers', events })
+export const emitShippingEvent = eventsConfig.emit
+export type ShippingEventId = typeof events[number]['id']
+export default eventsConfig

package/src/modules/shipping_carriers/i18n/de.json

@@ -0,0 +1,7 @@
+{
+  "shipping_carriers.action.createShipment": "Sendung erstellen",
+  "shipping_carriers.column.shippingStatus": "Versandstatus",
+  "shipping_carriers.column.trackingStatus": "Tracking-Status",
+  "shipping_carriers.feature.manage": "Versanddienstleister-Vorgaenge verwalten",
+  "shipping_carriers.feature.view": "Sendungen der Versanddienstleister anzeigen"
+}

package/src/modules/shipping_carriers/i18n/en.json

@@ -0,0 +1,7 @@
+{
+  "shipping_carriers.action.createShipment": "Create shipment",
+  "shipping_carriers.column.shippingStatus": "Shipping status",
+  "shipping_carriers.column.trackingStatus": "Tracking status",
+  "shipping_carriers.feature.manage": "Manage shipping carrier operations",
+  "shipping_carriers.feature.view": "View shipping carrier shipments"
+}

package/src/modules/shipping_carriers/i18n/en.ts

@@ -0,0 +1,7 @@
+export default {
+  'shipping_carriers.feature.view': 'View shipping carrier shipments',
+  'shipping_carriers.feature.manage': 'Manage shipping carrier operations',
+  'shipping_carriers.column.trackingStatus': 'Tracking status',
+  'shipping_carriers.column.shippingStatus': 'Shipping status',
+  'shipping_carriers.action.createShipment': 'Create shipment',
+}

package/src/modules/shipping_carriers/i18n/es.json

@@ -0,0 +1,7 @@
+{
+  "shipping_carriers.action.createShipment": "Crear envio",
+  "shipping_carriers.column.shippingStatus": "Estado del envio",
+  "shipping_carriers.column.trackingStatus": "Estado del seguimiento",
+  "shipping_carriers.feature.manage": "Gestionar operaciones de transportistas",
+  "shipping_carriers.feature.view": "Ver envios de transportistas"
+}

package/src/modules/shipping_carriers/i18n/pl.json

@@ -0,0 +1,7 @@
+{
+  "shipping_carriers.action.createShipment": "Utworz przesylke",
+  "shipping_carriers.column.shippingStatus": "Status wysylki",
+  "shipping_carriers.column.trackingStatus": "Status sledzenia",
+  "shipping_carriers.feature.manage": "Zarzadzanie operacjami przewoznikow",
+  "shipping_carriers.feature.view": "Podglad przesylek przewoznikow"
+}

package/src/modules/shipping_carriers/i18n/pl.ts

@@ -0,0 +1,7 @@
+export default {
+  'shipping_carriers.feature.view': 'Podgląd przesyłek przewoźników',
+  'shipping_carriers.feature.manage': 'Zarządzanie operacjami przewoźników',
+  'shipping_carriers.column.trackingStatus': 'Status śledzenia',
+  'shipping_carriers.column.shippingStatus': 'Status wysyłki',
+  'shipping_carriers.action.createShipment': 'Utwórz przesyłkę',
+}

package/src/modules/shipping_carriers/index.ts

@@ -0,0 +1,5 @@
+export const metadata = {
+  id: 'shipping_carriers',
+  title: 'Shipping Carriers',
+  description: 'Shipping carrier adapter hub with rates, shipment creation, tracking, and webhooks.',
+}

package/src/modules/shipping_carriers/lib/adapter-registry.ts

@@ -0,0 +1,33 @@
+import type { ShippingAdapter } from './adapter'
+
+const SHIPPING_ADAPTER_REGISTRY_KEY = Symbol.for('@open-mercato/shipping-carriers/adapter-registry')
+
+type GlobalWithShippingRegistry = typeof globalThis & {
+  [SHIPPING_ADAPTER_REGISTRY_KEY]?: Map<string, ShippingAdapter>
+}
+
+function getAdapterRegistry(): Map<string, ShippingAdapter> {
+  const globalScope = globalThis as GlobalWithShippingRegistry
+  if (!globalScope[SHIPPING_ADAPTER_REGISTRY_KEY]) {
+    globalScope[SHIPPING_ADAPTER_REGISTRY_KEY] = new Map<string, ShippingAdapter>()
+  }
+  return globalScope[SHIPPING_ADAPTER_REGISTRY_KEY]
+}
+
+export function registerShippingAdapter(adapter: ShippingAdapter): () => void {
+  const adapterRegistry = getAdapterRegistry()
+  adapterRegistry.set(adapter.providerKey, adapter)
+  return () => adapterRegistry.delete(adapter.providerKey)
+}
+
+export function getShippingAdapter(providerKey: string): ShippingAdapter | undefined {
+  return getAdapterRegistry().get(providerKey)
+}
+
+export function listShippingAdapters(): ShippingAdapter[] {
+  return Array.from(getAdapterRegistry().values())
+}
+
+export function clearShippingAdapters(): void {
+  getAdapterRegistry().clear()
+}

package/src/modules/shipping_carriers/lib/adapter.ts

@@ -0,0 +1,93 @@
+export type UnifiedShipmentStatus =
+  | 'label_created'
+  | 'picked_up'
+  | 'in_transit'
+  | 'out_for_delivery'
+  | 'delivered'
+  | 'failed_delivery'
+  | 'returned'
+  | 'cancelled'
+  | 'unknown'
+
+export type Address = {
+  countryCode: string
+  postalCode: string
+  city: string
+  line1: string
+  line2?: string
+}
+
+export type PackageInfo = {
+  weightKg: number
+  lengthCm: number
+  widthCm: number
+  heightCm: number
+}
+
+export type ShippingRate = {
+  serviceCode: string
+  serviceName: string
+  amount: number
+  currencyCode: string
+  estimatedDays?: number
+  guaranteedDelivery?: boolean
+}
+
+export type CreateShipmentInput = {
+  orderId: string
+  origin: Address
+  destination: Address
+  packages: PackageInfo[]
+  serviceCode: string
+  credentials: Record<string, unknown>
+  labelFormat?: 'pdf' | 'zpl' | 'png'
+}
+
+export type CreateShipmentResult = {
+  shipmentId: string
+  trackingNumber: string
+  labelUrl?: string
+  labelData?: string
+  estimatedDelivery?: Date
+}
+
+export type TrackingResult = {
+  trackingNumber: string
+  status: UnifiedShipmentStatus
+  events: Array<{ status: UnifiedShipmentStatus; occurredAt: string; location?: string }>
+}
+
+export type ShippingWebhookEvent = {
+  eventType: string
+  eventId: string
+  idempotencyKey: string
+  data: Record<string, unknown>
+  timestamp: Date
+}
+
+export interface ShippingAdapter {
+  readonly providerKey: string
+  calculateRates(input: {
+    origin: Address
+    destination: Address
+    packages: PackageInfo[]
+    credentials: Record<string, unknown>
+  }): Promise<ShippingRate[]>
+  createShipment(input: CreateShipmentInput): Promise<CreateShipmentResult>
+  getTracking(input: {
+    shipmentId?: string
+    trackingNumber?: string
+    credentials: Record<string, unknown>
+  }): Promise<TrackingResult>
+  cancelShipment(input: {
+    shipmentId: string
+    reason?: string
+    credentials: Record<string, unknown>
+  }): Promise<{ status: UnifiedShipmentStatus }>
+  verifyWebhook(input: {
+    rawBody: string | Buffer
+    headers: Record<string, string | string[] | undefined>
+    credentials: Record<string, unknown>
+  }): Promise<ShippingWebhookEvent>
+  mapStatus(carrierStatus: string): UnifiedShipmentStatus
+}

package/src/modules/shipping_carriers/lib/queue.ts

@@ -0,0 +1,19 @@
+import { createQueue, type Queue } from '@open-mercato/queue'
+import { getRedisUrl } from '@open-mercato/shared/lib/redis/connection'
+
+const queues = new Map<string, Queue<Record<string, unknown>>>()
+
+export function getShippingCarrierQueue(queueName: string): Queue<Record<string, unknown>> {
+  const existing = queues.get(queueName)
+  if (existing) return existing
+
+  const created = process.env.QUEUE_STRATEGY === 'async'
+    ? createQueue<Record<string, unknown>>(queueName, 'async', {
+      connection: { url: getRedisUrl('QUEUE') },
+      concurrency: Math.max(1, Number.parseInt(process.env.SHIPPING_CARRIER_QUEUE_CONCURRENCY ?? '5', 10) || 5),
+    })
+    : createQueue<Record<string, unknown>>(queueName, 'local')
+
+  queues.set(queueName, created)
+  return created
+}

package/src/modules/shipping_carriers/lib/shipping-service.ts

@@ -0,0 +1,204 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import type { CredentialsService } from '../../integrations/lib/credentials-service'
+import { CarrierShipment } from '../data/entities'
+import { emitShippingEvent } from '../events'
+import { getShippingAdapter } from './adapter-registry'
+
+export function createShippingCarrierService(deps: {
+  em: EntityManager
+  integrationCredentialsService: CredentialsService
+}) {
+  const { em, integrationCredentialsService } = deps
+
+  async function findShipmentOrThrow(
+    shipmentId: string,
+    scope: { organizationId: string; tenantId: string },
+  ): Promise<CarrierShipment> {
+    const shipment = await findOneWithDecryption(
+      em,
+      CarrierShipment,
+      {
+        id: shipmentId,
+        organizationId: scope.organizationId,
+        tenantId: scope.tenantId,
+        deletedAt: null,
+      },
+      undefined,
+      scope,
+    )
+    if (!shipment) {
+      throw new Error('Shipment not found')
+    }
+    return shipment
+  }
+
+  async function resolveAdapter(providerKey: string, scope: { organizationId: string; tenantId: string }) {
+    const adapter = getShippingAdapter(providerKey)
+    if (!adapter) throw new Error(`No shipping adapter registered for provider: ${providerKey}`)
+    const credentials = await integrationCredentialsService.resolve(`carrier_${providerKey}`, scope) ?? {}
+    return { adapter, credentials }
+  }
+
+  return {
+    async calculateRates(input: {
+      providerKey: string
+      origin: { countryCode: string; postalCode: string; city: string; line1: string; line2?: string }
+      destination: { countryCode: string; postalCode: string; city: string; line1: string; line2?: string }
+      packages: Array<{ weightKg: number; lengthCm: number; widthCm: number; heightCm: number }>
+      organizationId: string
+      tenantId: string
+    }) {
+      const { adapter, credentials } = await resolveAdapter(input.providerKey, {
+        organizationId: input.organizationId,
+        tenantId: input.tenantId,
+      })
+      return adapter.calculateRates({
+        origin: input.origin,
+        destination: input.destination,
+        packages: input.packages,
+        credentials,
+      })
+    },
+
+    async createShipment(input: {
+      providerKey: string
+      orderId: string
+      origin: { countryCode: string; postalCode: string; city: string; line1: string; line2?: string }
+      destination: { countryCode: string; postalCode: string; city: string; line1: string; line2?: string }
+      packages: Array<{ weightKg: number; lengthCm: number; widthCm: number; heightCm: number }>
+      serviceCode: string
+      labelFormat?: 'pdf' | 'zpl' | 'png'
+      organizationId: string
+      tenantId: string
+    }) {
+      const { adapter, credentials } = await resolveAdapter(input.providerKey, {
+        organizationId: input.organizationId,
+        tenantId: input.tenantId,
+      })
+      const created = await adapter.createShipment({
+        orderId: input.orderId,
+        origin: input.origin,
+        destination: input.destination,
+        packages: input.packages,
+        serviceCode: input.serviceCode,
+        credentials,
+        labelFormat: input.labelFormat,
+      })
+      const shipment = em.create(CarrierShipment, {
+        orderId: input.orderId,
+        providerKey: input.providerKey,
+        carrierShipmentId: created.shipmentId,
+        trackingNumber: created.trackingNumber,
+        unifiedStatus: 'label_created',
+        labelUrl: created.labelUrl ?? null,
+        labelData: created.labelData ?? null,
+        organizationId: input.organizationId,
+        tenantId: input.tenantId,
+      })
+      await em.persistAndFlush(shipment)
+      await emitShippingEvent('shipping_carriers.shipment.created', {
+        shipmentId: shipment.id,
+        orderId: input.orderId,
+        providerKey: input.providerKey,
+        trackingNumber: created.trackingNumber,
+        organizationId: input.organizationId,
+        tenantId: input.tenantId,
+      })
+      return shipment
+    },
+
+    async getTracking(input: {
+      providerKey: string
+      shipmentId?: string
+      trackingNumber?: string
+      organizationId: string
+      tenantId: string
+    }) {
+      const { adapter, credentials } = await resolveAdapter(input.providerKey, {
+        organizationId: input.organizationId,
+        tenantId: input.tenantId,
+      })
+      const shipment = input.shipmentId
+        ? await findOneWithDecryption(
+          em,
+          CarrierShipment,
+          {
+            id: input.shipmentId,
+            organizationId: input.organizationId,
+            tenantId: input.tenantId,
+            deletedAt: null,
+          },
+          undefined,
+          {
+            organizationId: input.organizationId,
+            tenantId: input.tenantId,
+          },
+        )
+        : null
+      const tracking = await adapter.getTracking({
+        shipmentId: shipment?.carrierShipmentId ?? input.shipmentId,
+        trackingNumber: input.trackingNumber,
+        credentials,
+      })
+      if (shipment) {
+        shipment.unifiedStatus = tracking.status
+        shipment.trackingEvents = tracking.events
+        shipment.lastPolledAt = new Date()
+        await em.flush()
+      }
+      return tracking
+    },
+
+    async cancelShipment(input: {
+      providerKey: string
+      shipmentId: string
+      reason?: string
+      organizationId: string
+      tenantId: string
+    }) {
+      const scope = { organizationId: input.organizationId, tenantId: input.tenantId }
+      const shipment = await findShipmentOrThrow(input.shipmentId, scope)
+      const { adapter, credentials } = await resolveAdapter(input.providerKey, {
+        organizationId: input.organizationId,
+        tenantId: input.tenantId,
+      })
+      const result = await adapter.cancelShipment({
+        shipmentId: shipment.carrierShipmentId,
+        reason: input.reason,
+        credentials,
+      })
+      shipment.unifiedStatus = result.status
+      await em.flush()
+      await emitShippingEvent('shipping_carriers.shipment.cancelled', {
+        shipmentId: shipment.id,
+        providerKey: input.providerKey,
+        organizationId: input.organizationId,
+        tenantId: input.tenantId,
+      })
+      return result
+    },
+
+    async findShipmentByCarrierId(
+      providerKey: string,
+      carrierShipmentId: string,
+      scope: { organizationId: string; tenantId: string },
+    ) {
+      return findOneWithDecryption(
+        em,
+        CarrierShipment,
+        {
+          providerKey,
+          carrierShipmentId,
+          organizationId: scope.organizationId,
+          tenantId: scope.tenantId,
+          deletedAt: null,
+        },
+        undefined,
+        scope,
+      )
+    },
+  }
+}
+
+export type ShippingCarrierService = ReturnType<typeof createShippingCarrierService>

package/src/modules/shipping_carriers/lib/status-sync.ts

@@ -0,0 +1,38 @@
+import type { UnifiedShipmentStatus } from './adapter'
+import type { CarrierShipment } from '../data/entities'
+import type { ShippingEventId } from '../events'
+
+const VALID_SHIPPING_TRANSITIONS: Record<string, UnifiedShipmentStatus[]> = {
+  label_created: ['picked_up', 'in_transit', 'cancelled'],
+  picked_up: ['in_transit', 'cancelled'],
+  in_transit: ['out_for_delivery', 'delivered', 'returned', 'failed_delivery'],
+  out_for_delivery: ['delivered', 'returned', 'failed_delivery'],
+  failed_delivery: ['in_transit', 'out_for_delivery', 'delivered', 'returned', 'cancelled'],
+}
+
+export const TERMINAL_SHIPPING_STATUSES: Set<UnifiedShipmentStatus> = new Set([
+  'delivered',
+  'returned',
+  'cancelled',
+])
+
+export function isValidShippingTransition(from: UnifiedShipmentStatus, to: UnifiedShipmentStatus): boolean {
+  if (from === to) return false
+  const allowed = VALID_SHIPPING_TRANSITIONS[from]
+  if (!allowed) return false
+  return allowed.includes(to)
+}
+
+export function syncShipmentStatus(shipment: CarrierShipment, newStatus: UnifiedShipmentStatus): boolean {
+  const currentStatus = shipment.unifiedStatus as UnifiedShipmentStatus
+  if (!isValidShippingTransition(currentStatus, newStatus)) return false
+  shipment.unifiedStatus = newStatus
+  return true
+}
+
+export function getTerminalShippingEvent(status: UnifiedShipmentStatus): ShippingEventId | null {
+  if (status === 'delivered') return 'shipping_carriers.shipment.delivered'
+  if (status === 'returned') return 'shipping_carriers.shipment.returned'
+  if (status === 'cancelled') return 'shipping_carriers.shipment.cancelled'
+  return null
+}

package/src/modules/shipping_carriers/migrations/Migration20260305170000.ts

@@ -0,0 +1,14 @@
+import { Migration } from '@mikro-orm/migrations'
+
+export class Migration20260305170000 extends Migration {
+  override async up(): Promise<void> {
+    this.addSql(`create table "carrier_shipments" ("id" uuid not null default gen_random_uuid(), "order_id" uuid not null, "provider_key" text not null, "carrier_shipment_id" text not null, "tracking_number" text not null, "unified_status" text not null default 'label_created', "carrier_status" text null, "label_url" text null, "label_data" text null, "tracking_events" jsonb null, "organization_id" uuid not null, "tenant_id" uuid not null, "last_webhook_at" timestamptz null, "last_polled_at" timestamptz null, "created_at" timestamptz not null, "updated_at" timestamptz not null, "deleted_at" timestamptz null, constraint "carrier_shipments_pkey" primary key ("id"));`)
+    this.addSql(`create index "carrier_shipments_organization_id_tenant_id_unif_b5ab4_index" on "carrier_shipments" ("organization_id", "tenant_id", "unified_status");`)
+    this.addSql(`create index "carrier_shipments_provider_key_carrier_shipment_i_f9f17_index" on "carrier_shipments" ("provider_key", "carrier_shipment_id", "organization_id");`)
+    this.addSql(`create index "carrier_shipments_order_id_organization_id_tenant_id_index" on "carrier_shipments" ("order_id", "organization_id", "tenant_id");`)
+  }
+
+  override async down(): Promise<void> {
+    this.addSql(`drop table if exists "carrier_shipments";`)
+  }
+}

package/src/modules/shipping_carriers/setup.ts

@@ -0,0 +1,11 @@
+import type { ModuleSetupConfig } from '@open-mercato/shared/modules/setup'
+
+export const setup: ModuleSetupConfig = {
+  defaultRoleFeatures: {
+    superadmin: ['shipping_carriers.view', 'shipping_carriers.manage'],
+    admin: ['shipping_carriers.view', 'shipping_carriers.manage'],
+    employee: ['shipping_carriers.view'],
+  },
+}
+
+export default setup

package/src/modules/shipping_carriers/widgets/injection/create-shipment-button/widget.ts

@@ -0,0 +1,24 @@
+import type { InjectionRowActionWidget } from '@open-mercato/shared/modules/widgets/injection'
+
+const widget: InjectionRowActionWidget = {
+  metadata: {
+    id: 'shipping_carriers.injection.create-shipment-button',
+    priority: 30,
+  },
+  rowActions: [
+    {
+      id: 'create_shipment',
+      label: 'shipping_carriers.action.createShipment',
+      icon: 'Truck',
+      onSelect: (row: unknown, context: unknown) => {
+        const ctx = context as { navigate?: (path: string) => void }
+        const order = row as { id?: string }
+        if (ctx.navigate && order.id) {
+          ctx.navigate(`/backend/shipping-carriers/create?orderId=${order.id}`)
+        }
+      },
+    },
+  ],
+}
+
+export default widget

package/src/modules/shipping_carriers/widgets/injection/tracking-column/widget.ts

@@ -0,0 +1,22 @@
+import type { InjectionColumnWidget } from '@open-mercato/shared/modules/widgets/injection'
+
+const widget: InjectionColumnWidget = {
+  metadata: {
+    id: 'shipping_carriers.injection.tracking-column',
+    priority: 40,
+  },
+  columns: [
+    {
+      id: 'carrier_tracking_status',
+      header: 'shipping_carriers.column.trackingStatus',
+      accessorKey: '_carrier.status',
+      sortable: false,
+      cell: ({ getValue }) => {
+        const value = getValue()
+        return typeof value === 'string' && value.length > 0 ? value : 'unknown'
+      },
+    },
+  ],
+}
+
+export default widget

package/src/modules/shipping_carriers/widgets/injection/tracking-status-badge/widget.tsx

@@ -0,0 +1,44 @@
+import type { InjectionColumnWidget } from '@open-mercato/shared/modules/widgets/injection'
+
+const SHIPPING_STATUS_COLORS: Record<string, string> = {
+  pending: 'bg-gray-100 text-gray-700',
+  label_created: 'bg-slate-100 text-slate-700',
+  picked_up: 'bg-sky-100 text-sky-700',
+  in_transit: 'bg-blue-100 text-blue-700',
+  out_for_delivery: 'bg-indigo-100 text-indigo-700',
+  delivered: 'bg-green-100 text-green-700',
+  returned: 'bg-amber-100 text-amber-700',
+  cancelled: 'bg-red-100 text-red-700',
+  failed_delivery: 'bg-orange-100 text-orange-700',
+}
+
+function formatShippingStatusLabel(value: string): string {
+  return value.replace(/_/g, ' ')
+}
+
+const widget: InjectionColumnWidget = {
+  metadata: {
+    id: 'shipping_carriers.injection.tracking-status-badge',
+    priority: 45,
+  },
+  columns: [
+    {
+      id: 'carrier_status_badge',
+      header: 'shipping_carriers.column.shippingStatus',
+      accessorKey: '_carrier.status',
+      sortable: false,
+      cell: ({ getValue }) => {
+        const value = getValue()
+        if (typeof value !== 'string' || value.length === 0) return null
+        const colors = SHIPPING_STATUS_COLORS[value] ?? 'bg-gray-100 text-gray-700'
+        return (
+          <span className={`inline-flex items-center rounded-full px-2 py-0.5 text-xs font-medium ${colors}`}>
+            {formatShippingStatusLabel(value)}
+          </span>
+        )
+      },
+    },
+  ],
+}
+
+export default widget

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

@@ -0,0 +1,22 @@
+import type { ModuleInjectionTable } from '@open-mercato/shared/modules/widgets/injection'
+
+export const injectionTable: ModuleInjectionTable = {
+  'data-table:sales.shipments:columns': [
+    {
+      widgetId: 'shipping_carriers.injection.tracking-column',
+      priority: 40,
+    },
+    {
+      widgetId: 'shipping_carriers.injection.tracking-status-badge',
+      priority: 45,
+    },
+  ],
+  'data-table:sales.orders:row-actions': [
+    {
+      widgetId: 'shipping_carriers.injection.create-shipment-button',
+      priority: 30,
+    },
+  ],
+}
+
+export default injectionTable

package/src/modules/shipping_carriers/workers/status-poller.ts

@@ -0,0 +1,33 @@
+import type { JobContext, QueuedJob, WorkerMeta } from '@open-mercato/queue'
+import type { ShippingCarrierService } from '../lib/shipping-service'
+
+type PollerJobPayload = {
+  providerKey: string
+  shipmentIds: string[]
+  scope: {
+    organizationId: string
+    tenantId: string
+  }
+}
+
+type HandlerContext = JobContext & {
+  resolve: <T = unknown>(name: string) => T
+}
+
+export const metadata: WorkerMeta = {
+  queue: 'shipping-carriers-status-poller',
+  id: 'shipping-carriers:status-poller',
+  concurrency: 2,
+}
+
+export default async function handle(job: QueuedJob<PollerJobPayload>, ctx: HandlerContext): Promise<void> {
+  const service = ctx.resolve<ShippingCarrierService>('shippingCarrierService')
+  for (const shipmentId of job.payload.shipmentIds) {
+    await service.getTracking({
+      providerKey: job.payload.providerKey,
+      shipmentId,
+      organizationId: job.payload.scope.organizationId,
+      tenantId: job.payload.scope.tenantId,
+    })
+  }
+}