@open-mercato/core 0.6.7-develop.6669.1.40b669666b → 0.6.7-develop.6671.1.4b925c5096

package/src/modules/wms/api/inventory/import/apply/route.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { inventoryImportApplySchema } from '../../../../data/validators'
+import { executeWmsInventoryImportRoute } from '../helpers'
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['wms.import'] },
+}
+
+export async function POST(request: Request) {
+  return executeWmsInventoryImportRoute({
+    request,
+    routePath: 'wms/inventory/import/apply',
+    mode: 'apply',
+  })
+}
+
+const successSchema = z.object({
+  ok: z.boolean(),
+  importBatchId: z.string().uuid(),
+  summary: z.object({
+    applied: z.number(),
+    skipped: z.number(),
+    failed: z.number(),
+  }),
+})
+
+const errorSchema = z.object({ error: z.string() })
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'WMS',
+  summary: 'Apply inventory CSV import',
+  methods: {
+    POST: {
+      summary: 'Apply inventory CSV import',
+      description:
+        'Applies validated inventory import rows via wms.inventory.adjust commands (idempotent skip when delta is zero).',
+      requestBody: { contentType: 'application/json', schema: inventoryImportApplySchema },
+      responses: [{ status: 200, description: 'Import applied', schema: successSchema }],
+      errors: [
+        { status: 400, description: 'Validation failed', schema: errorSchema },
+        { status: 401, description: 'Unauthorized', schema: errorSchema },
+        { status: 409, description: 'Partial apply failure', schema: errorSchema },
+      ],
+    },
+  },
+}

package/src/modules/wms/api/inventory/import/helpers.ts

@@ -0,0 +1,223 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import type { CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import {
+  runCrudMutationGuardAfterSuccess,
+  validateCrudMutationGuard,
+} from '@open-mercato/shared/lib/crud/mutation-guard'
+import { runCustomRouteAfterInterceptors } from '@open-mercato/shared/lib/crud/custom-route-interceptor'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { parseInventoryImportCsv } from '../../../lib/inventoryImportCsv'
+import { applyInventoryImport, validateInventoryImport } from '../../../lib/inventoryImportService'
+import {
+  inventoryImportApplySchema,
+  inventoryImportValidateSchema,
+} from '../../../data/validators'
+
+const logger = createLogger('wms')
+
+type ImportRouteOptions = {
+  request: Request
+  routePath: string
+  mode: 'validate' | 'apply'
+}
+
+/**
+ * Fail-closed scope guard for inventory import payloads. Unlike the shared
+ * `ensureOrganizationScope` (which short-circuits for tenant-wide admins with
+ * `allowedIds === null`), this rejects payloads whose `organizationId`/`tenantId`
+ * fall outside the caller's actively selected scope so cross-organization imports
+ * cannot be smuggled through the request body.
+ */
+function assertImportScope(
+  ctx: CommandRuntimeContext,
+  input: { organizationId: string; tenantId: string },
+  translate: (key: string, fallback?: string) => string,
+): void {
+  const forbidden = () =>
+    new CrudHttpError(403, { error: translate('wms.errors.forbidden', 'Forbidden') })
+  if (ctx.auth?.isSuperAdmin === true) return
+
+  const actorTenantId = ctx.auth?.tenantId ?? null
+  if (!actorTenantId || actorTenantId !== input.tenantId) {
+    throw forbidden()
+  }
+
+  const allowedIds = ctx.organizationScope?.allowedIds ?? null
+  if (Array.isArray(allowedIds)) {
+    if (!allowedIds.includes(input.organizationId)) throw forbidden()
+    return
+  }
+
+  const selectedOrganizationId = ctx.selectedOrganizationId ?? ctx.auth?.orgId ?? null
+  if (!selectedOrganizationId || selectedOrganizationId !== input.organizationId) {
+    throw forbidden()
+  }
+}
+
+async function buildImportContext(request: Request): Promise<CommandRuntimeContext> {
+  const container = await createRequestContainer()
+  const auth = await getAuthFromRequest(request)
+  const { translate } = await resolveTranslations()
+  if (!auth || !auth.tenantId) {
+    throw new CrudHttpError(401, { error: translate('wms.errors.unauthorized', 'Unauthorized') })
+  }
+  const organizationScope = await resolveOrganizationScopeForRequest({
+    container,
+    auth,
+    request,
+  })
+  return {
+    container,
+    auth,
+    organizationScope,
+    selectedOrganizationId: organizationScope?.selectedId ?? auth.orgId ?? null,
+    organizationIds: organizationScope?.filterIds ?? (auth.orgId ? [auth.orgId] : null),
+    request,
+  }
+}
+
+async function parseValidatePayload(request: Request): Promise<z.infer<typeof inventoryImportValidateSchema>> {
+  const { translate } = await resolveTranslations()
+  const contentType = request.headers.get('content-type') ?? ''
+  if (contentType.includes('multipart/form-data')) {
+    const formData = await request.formData()
+    const organizationId = String(formData.get('organizationId') ?? '').trim()
+    const tenantId = String(formData.get('tenantId') ?? '').trim()
+    const importBatchIdRaw = String(formData.get('importBatchId') ?? '').trim()
+    const skipDuplicatesRaw = String(formData.get('skipDuplicates') ?? '').trim()
+    const modeRaw = String(formData.get('mode') ?? '').trim()
+    const file = formData.get('file')
+    if (!(file instanceof File)) {
+      throw new CrudHttpError(400, {
+        error: translate('wms.backend.inventory.import.errors.csvFileRequired', 'CSV file is required.'),
+      })
+    }
+    const csvText = await file.text()
+    const rows = parseInventoryImportCsv(csvText)
+    return inventoryImportValidateSchema.parse({
+      organizationId,
+      tenantId,
+      ...(importBatchIdRaw ? { importBatchId: importBatchIdRaw } : {}),
+      ...(skipDuplicatesRaw ? { skipDuplicates: skipDuplicatesRaw === 'true' } : {}),
+      ...(modeRaw ? { mode: modeRaw } : {}),
+      rows,
+    })
+  }
+
+  const body = (await readJsonSafe<Record<string, unknown>>(request, {})) ?? {}
+  if (typeof body.csv === 'string' && body.csv.trim().length > 0) {
+    const rows = parseInventoryImportCsv(body.csv)
+    return inventoryImportValidateSchema.parse({
+      ...body,
+      rows,
+    })
+  }
+  return inventoryImportValidateSchema.parse(body)
+}
+
+export async function executeWmsInventoryImportRoute(options: ImportRouteOptions) {
+  const { translate } = await resolveTranslations()
+  try {
+    const ctx = await buildImportContext(options.request)
+    const auth = ctx.auth
+    if (!auth?.tenantId || !auth.sub) {
+      throw new CrudHttpError(401, { error: translate('wms.errors.unauthorized', 'Unauthorized') })
+    }
+
+    if (options.mode === 'validate') {
+      const parsed = await parseValidatePayload(options.request)
+      assertImportScope(ctx, parsed, translate)
+      const result = await validateInventoryImport(ctx, parsed)
+      return NextResponse.json(result)
+    }
+
+    const parsed = inventoryImportApplySchema.parse(
+      (await readJsonSafe<Record<string, unknown>>(options.request, {})) ?? {},
+    )
+    assertImportScope(ctx, parsed, translate)
+    const guardResult = await validateCrudMutationGuard(ctx.container, {
+      tenantId: auth.tenantId,
+      organizationId: ctx.selectedOrganizationId,
+      userId: auth.sub,
+      resourceKind: 'wms.inventory',
+      resourceId: parsed.importBatchId,
+      operation: 'custom',
+      requestMethod: options.request.method,
+      requestHeaders: options.request.headers,
+      mutationPayload: parsed as Record<string, unknown>,
+    })
+    if (guardResult && !guardResult.ok) {
+      return NextResponse.json(guardResult.body, { status: guardResult.status })
+    }
+
+    const result = await applyInventoryImport(ctx, {
+      ...parsed,
+      performedBy: auth.sub,
+    })
+    if (guardResult?.ok && guardResult.shouldRunAfterSuccess) {
+      await runCrudMutationGuardAfterSuccess(ctx.container, {
+        tenantId: auth.tenantId,
+        organizationId: ctx.selectedOrganizationId,
+        userId: auth.sub,
+        resourceKind: 'wms.inventory',
+        resourceId: parsed.importBatchId,
+        operation: 'custom',
+        requestMethod: options.request.method,
+        requestHeaders: options.request.headers,
+        metadata: guardResult.metadata ?? null,
+      })
+    }
+
+    const intercepted = await runCustomRouteAfterInterceptors({
+      routePath: options.routePath,
+      method: 'POST',
+      request: {
+        method: 'POST',
+        url: options.request.url,
+        body: parsed as Record<string, unknown>,
+        headers: Object.fromEntries(options.request.headers.entries()),
+      },
+      response: {
+        statusCode: 200,
+        body: result as Record<string, unknown>,
+        headers: {},
+      },
+      context: {
+        em: ctx.container.resolve('em'),
+        container: ctx.container,
+        userId: auth.sub,
+        organizationId: ctx.selectedOrganizationId,
+        tenantId: auth.tenantId,
+      },
+    })
+    if (!intercepted.ok) {
+      return NextResponse.json(intercepted.body, { status: intercepted.statusCode })
+    }
+    return NextResponse.json(intercepted.body, { status: intercepted.statusCode })
+  } catch (error) {
+    if (error instanceof CrudHttpError) {
+      return NextResponse.json(error.body, { status: error.status })
+    }
+    if (error instanceof z.ZodError) {
+      return NextResponse.json(
+        {
+          error: translate('wms.backend.inventory.import.errors.validationFailed', 'Validation failed.'),
+          details: error.issues,
+        },
+        { status: 400 },
+      )
+    }
+    logger.error('inventory import route failed', { routePath: options.routePath, mode: options.mode, err: error })
+    return NextResponse.json(
+      { error: translate('wms.errors.internalServerError', 'Internal server error') },
+      { status: 500 },
+    )
+  }
+}

package/src/modules/wms/api/inventory/import/template/route.ts

@@ -0,0 +1,31 @@
+import { NextResponse } from 'next/server'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { buildInventoryImportTemplateCsv } from '../../../../lib/inventoryImportCsv'
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['wms.import'] },
+}
+
+export async function GET() {
+  const csv = buildInventoryImportTemplateCsv()
+  return new NextResponse(csv, {
+    status: 200,
+    headers: {
+      'content-type': 'text/csv; charset=utf-8',
+      'content-disposition': 'attachment; filename="wms-inventory-import-template.csv"',
+    },
+  })
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'WMS',
+  summary: 'Download inventory import CSV template',
+  methods: {
+    GET: {
+      summary: 'Download inventory import CSV template',
+      description:
+        'Returns a CSV template for WMS inventory imports. By default the quantity column is added to existing on-hand stock; the "Reconcile to exact balance" import option treats it as the absolute target balance instead.',
+      responses: [{ status: 200, description: 'CSV template file' }],
+    },
+  },
+}

package/src/modules/wms/api/inventory/import/validate/route.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { inventoryImportValidateSchema } from '../../../../data/validators'
+import { executeWmsInventoryImportRoute } from '../helpers'
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['wms.import'] },
+}
+
+export async function POST(request: Request) {
+  return executeWmsInventoryImportRoute({
+    request,
+    routePath: 'wms/inventory/import/validate',
+    mode: 'validate',
+  })
+}
+
+const rowResultSchema = z.object({
+  rowNumber: z.number(),
+  status: z.enum(['valid', 'error', 'warning', 'skip']),
+  errors: z.array(z.string()),
+  warnings: z.array(z.string()),
+})
+
+const successSchema = z.object({
+  ok: z.boolean(),
+  importBatchId: z.string().uuid(),
+  summary: z.object({
+    totalRows: z.number(),
+    validRows: z.number(),
+    errorRows: z.number(),
+    warningRows: z.number(),
+    skipRows: z.number(),
+  }),
+  rows: z.array(rowResultSchema),
+})
+
+const errorSchema = z.object({ error: z.string() })
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'WMS',
+  summary: 'Validate inventory CSV import',
+  methods: {
+    POST: {
+      summary: 'Validate inventory CSV import',
+      description:
+        'Dry-run validation for inventory import CSV rows. By default (mode "additive"), quantity is added to existing on-hand stock; opt into mode "reconcile" to instead treat quantity as the absolute target balance (overwrites existing stock, including reducing it). Accepts JSON rows, JSON csv text, or multipart file upload.',
+      requestBody: { contentType: 'application/json', schema: inventoryImportValidateSchema },
+      responses: [{ status: 200, description: 'Validation report', schema: successSchema }],
+      errors: [
+        { status: 400, description: 'Validation failed', schema: errorSchema },
+        { status: 401, description: 'Unauthorized', schema: errorSchema },
+      ],
+    },
+  },
+}

package/src/modules/wms/api/inventory/move/route.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { inventoryMoveSchema } from '../../../data/validators'
+import { executeWmsCustomPostRoute } from '../helpers'
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['wms.adjust_inventory'] },
+}
+
+export async function POST(request: Request) {
+  return executeWmsCustomPostRoute({
+    request,
+    routePath: 'wms/inventory/move',
+    inputSchema: inventoryMoveSchema,
+    commandId: 'wms.inventory.move',
+    describeResource: (input) => ({
+      resourceKind: 'wms.inventory',
+      resourceId: `${input.warehouseId}:${input.fromLocationId}:${input.catalogVariantId}`,
+    }),
+    mapSuccess: (result: { movementId: string }) => ({
+      ok: true,
+      movementId: result.movementId,
+    }),
+  })
+}
+
+const successSchema = z.object({
+  ok: z.literal(true),
+  movementId: z.string().uuid(),
+})
+const errorSchema = z.object({ error: z.string() })
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'WMS',
+  summary: 'Move inventory',
+  methods: {
+    POST: {
+      summary: 'Move inventory',
+      description: 'Moves stock from one location to another within a warehouse and appends a transfer movement.',
+      requestBody: { contentType: 'application/json', schema: inventoryMoveSchema },
+      responses: [{ status: 200, description: 'Inventory moved', schema: successSchema }],
+      errors: [
+        { status: 400, description: 'Validation failed', schema: errorSchema },
+        { status: 401, description: 'Unauthorized', schema: errorSchema },
+        { status: 409, description: 'Insufficient stock', schema: errorSchema },
+        { status: 422, description: 'Invalid location', schema: errorSchema },
+      ],
+    },
+  },
+}

package/src/modules/wms/api/inventory/movements/route.ts

@@ -0,0 +1,164 @@
+import { z } from 'zod'
+import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { escapeLikePattern } from '@open-mercato/shared/lib/db/escapeLikePattern'
+import { E } from '#generated/entities.ids.generated'
+import { InventoryMovement } from '../../../data/entities'
+import { inventoryMovementListQuerySchema } from '../../../data/validators'
+import { createPagedListResponseSchema } from '../../openapi'
+import {
+  attachLocationLabelsToListItems,
+  attachVariantLabelsToListItems,
+  attachWarehouseLabelsToListItems,
+} from '../../listEnrichers'
+import { buildInventoryListSearchOrFilters } from '../../listSearch'
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['wms.view'] },
+}
+
+const crud = makeCrudRoute({
+  metadata,
+  orm: {
+    entity: InventoryMovement,
+    idField: 'id',
+    orgField: 'organizationId',
+    tenantField: 'tenantId',
+    softDeleteField: 'deletedAt',
+  },
+  indexer: { entityType: E.wms.inventory_movement },
+  list: {
+    schema: inventoryMovementListQuerySchema,
+    entityId: E.wms.inventory_movement,
+    disableListCache: true,
+    fields: [
+      'id',
+      'organization_id',
+      'tenant_id',
+      'warehouse_id',
+      'location_from_id',
+      'location_to_id',
+      'catalog_variant_id',
+      'lot_id',
+      'serial_number',
+      'quantity',
+      'type',
+      'reference_type',
+      'reference_id',
+      'performed_by',
+      'performed_at',
+      'received_at',
+      'reason',
+      'reason_code',
+      'created_at',
+      'updated_at',
+    ],
+    sortFieldMap: {
+      catalogVariantId: 'catalog_variant_id',
+      warehouseId: 'warehouse_id',
+      quantity: 'quantity',
+      type: 'type',
+      performedAt: 'performed_at',
+      receivedAt: 'received_at',
+      createdAt: 'created_at',
+      updatedAt: 'updated_at',
+    },
+    buildFilters: async (query, ctx) => {
+      const filters: Record<string, unknown> = {}
+      if (query.warehouseId) filters.warehouse_id = { $eq: query.warehouseId }
+      if (query.catalogVariantId) filters.catalog_variant_id = { $eq: query.catalogVariantId }
+      if (query.lotId) filters.lot_id = { $eq: query.lotId }
+      if (query.referenceType) filters.reference_type = { $eq: query.referenceType }
+      if (query.referenceId) filters.reference_id = { $eq: query.referenceId }
+      if (query.type) filters.type = { $eq: query.type }
+      const andFilters: Record<string, unknown>[] = []
+      if (query.locationId) {
+        andFilters.push({
+          $or: [
+            { location_from_id: { $eq: query.locationId } },
+            { location_to_id: { $eq: query.locationId } },
+          ],
+        })
+      }
+      const term = query.search?.trim()
+      if (term) {
+        andFilters.push({
+          $or: await buildInventoryListSearchOrFilters(ctx, term, escapeLikePattern, {
+            extraFieldFilters: (like) => [
+              { reason: { $ilike: like } },
+              { reason_code: { $ilike: like } },
+            ],
+          }),
+        })
+      }
+      if (andFilters.length === 1) {
+        Object.assign(filters, andFilters[0])
+      } else if (andFilters.length > 1) {
+        filters.$and = andFilters
+      }
+      return filters
+    },
+  },
+  hooks: {
+    afterList: async (payload, ctx) => {
+      await Promise.all([
+        attachWarehouseLabelsToListItems(payload, ctx),
+        attachLocationLabelsToListItems(payload, ctx),
+        attachVariantLabelsToListItems(payload, ctx),
+      ])
+    },
+  },
+})
+
+export const GET = crud.GET
+
+const movementListItemSchema = z.object({
+  id: z.string().uuid().nullable().optional(),
+  organization_id: z.string().uuid().nullable().optional(),
+  tenant_id: z.string().uuid().nullable().optional(),
+  warehouse_id: z.string().uuid().nullable().optional(),
+  warehouse_name: z.string().nullable().optional(),
+  warehouse_code: z.string().nullable().optional(),
+  location_from_id: z.string().uuid().nullable().optional(),
+  location_from_code: z.string().nullable().optional(),
+  location_from_type: z.string().nullable().optional(),
+  location_to_id: z.string().uuid().nullable().optional(),
+  location_to_code: z.string().nullable().optional(),
+  location_to_type: z.string().nullable().optional(),
+  catalog_variant_id: z.string().uuid().nullable().optional(),
+  catalog_product_id: z.string().uuid().nullable().optional(),
+  variant_name: z.string().nullable().optional(),
+  variant_sku: z.string().nullable().optional(),
+  lot_id: z.string().uuid().nullable().optional(),
+  serial_number: z.string().nullable().optional(),
+  quantity: z.union([z.string(), z.number()]).nullable().optional(),
+  type: z.string().nullable().optional(),
+  reference_type: z.string().nullable().optional(),
+  reference_id: z.string().uuid().nullable().optional(),
+  performed_by: z.string().uuid().nullable().optional(),
+  performed_at: z.string().nullable().optional(),
+  received_at: z.string().nullable().optional(),
+  reason: z.string().nullable().optional(),
+  reason_code: z.string().nullable().optional(),
+  created_at: z.string().nullable().optional(),
+  updated_at: z.string().nullable().optional(),
+})
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'WMS',
+  summary: 'Inventory movements',
+  methods: {
+    GET: {
+      summary: 'List inventory movements',
+      description: 'Returns paginated inventory ledger entries for the authenticated organization.',
+      query: inventoryMovementListQuerySchema,
+      responses: [
+        {
+          status: 200,
+          description: 'Inventory movements collection',
+          schema: createPagedListResponseSchema(movementListItemSchema),
+        },
+      ],
+    },
+  },
+}

package/src/modules/wms/api/inventory/receive/route.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { inventoryReceiveSchema } from '../../../data/validators'
+import { executeWmsCustomPostRoute } from '../helpers'
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['wms.receive_inventory'] },
+}
+
+export async function POST(request: Request) {
+  return executeWmsCustomPostRoute({
+    request,
+    routePath: 'wms/inventory/receive',
+    inputSchema: inventoryReceiveSchema,
+    commandId: 'wms.inventory.receive',
+    describeResource: (input) => ({
+      resourceKind: 'wms.inventory',
+      resourceId: `${input.warehouseId}:${input.locationId}:${input.catalogVariantId}`,
+    }),
+    mapSuccess: (result: { movementId: string }) => ({
+      ok: true,
+      movementId: result.movementId,
+    }),
+  })
+}
+
+const successSchema = z.object({
+  ok: z.literal(true),
+  movementId: z.string().uuid(),
+})
+const errorSchema = z.object({ error: z.string() })
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'WMS',
+  summary: 'Receive inventory',
+  methods: {
+    POST: {
+      summary: 'Receive inventory',
+      description: 'Records inbound inventory receipt and appends a receipt movement ledger row.',
+      requestBody: { contentType: 'application/json', schema: inventoryReceiveSchema },
+      responses: [{ status: 200, description: 'Inventory received', schema: successSchema }],
+      errors: [
+        { status: 400, description: 'Validation failed', schema: errorSchema },
+        { status: 401, description: 'Unauthorized', schema: errorSchema },
+        { status: 422, description: 'Invalid location', schema: errorSchema },
+      ],
+    },
+  },
+}

package/src/modules/wms/api/inventory/release/route.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { inventoryReservationReleaseSchema } from '../../../data/validators'
+import { executeWmsCustomPostRoute } from '../helpers'
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['wms.manage_reservations'] },
+}
+
+export async function POST(request: Request) {
+  return executeWmsCustomPostRoute({
+    request,
+    routePath: 'wms/inventory/release',
+    inputSchema: inventoryReservationReleaseSchema,
+    commandId: 'wms.inventory.release',
+    describeResource: (input) => ({
+      resourceKind: 'wms.inventoryReservation',
+      resourceId: input.reservationId,
+    }),
+    mapSuccess: () => ({ ok: true }),
+  })
+}
+
+const successSchema = z.object({ ok: z.literal(true) })
+const errorSchema = z.object({ error: z.string() })
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'WMS',
+  summary: 'Release reservation',
+  methods: {
+    POST: {
+      summary: 'Release reservation',
+      description: 'Releases a previously reserved or allocated inventory reservation.',
+      requestBody: { contentType: 'application/json', schema: inventoryReservationReleaseSchema },
+      responses: [{ status: 200, description: 'Reservation released', schema: successSchema }],
+      errors: [
+        { status: 400, description: 'Validation failed', schema: errorSchema },
+        { status: 401, description: 'Unauthorized', schema: errorSchema },
+        { status: 404, description: 'Reservation not found', schema: errorSchema },
+      ],
+    },
+  },
+}