@openlup/platform 0.17.0 → 0.18.0

package/src/inventory/contracts/forecast.ts

@@ -0,0 +1,96 @@
+export interface InventoryProviderStockLine {
+  skuId: string;
+  sku: string;
+  forSaleQuantity: number;
+  lastSyncedAt: string;
+  staleAfter: string;
+}
+
+export interface InventoryHardReservationLine {
+  skuId: string;
+  quantity: number;
+}
+
+/** Structural inputs for dated subscription stock coverage; validation belongs to the caller. */
+export interface SubscriptionForecastProviderStockLine {
+  skuId: string;
+  sku: string;
+  forSaleQuantity: number;
+  lastSyncedAt: string;
+  staleAfter: string;
+}
+
+export interface SubscriptionForecastHardReservationLine {
+  skuId: string;
+  quantity: number;
+}
+
+export interface SubscriptionForecastStockLine {
+  skuId: string;
+  sku: string;
+  fulfillable: boolean;
+  locationStatus: string;
+  safetyStock: number;
+}
+
+export interface SubscriptionForecastDemandLine {
+  skuId: string;
+  sku: string;
+  quantity: number;
+  dueAt: string;
+  status: string;
+}
+
+export interface SubscriptionForecastSupplyLine {
+  skuId: string;
+  quantity: number;
+  expectedAt: string;
+  status: string;
+}
+
+export interface SubscriptionForecastCalculationInput {
+  generatedAt: string;
+  horizonDays: number;
+  protectionDays: number;
+  providerCurrent: SubscriptionForecastProviderStockLine[];
+  openHardReservations: SubscriptionForecastHardReservationLine[];
+  stock: SubscriptionForecastStockLine[];
+  demand: SubscriptionForecastDemandLine[];
+  supply: SubscriptionForecastSupplyLine[];
+}
+
+export interface SubscriptionForecastCounts {
+  activeSubscriptionCount: number;
+  excludedSubscriptionCount: number;
+}
+
+export interface SubscriptionForecastSku {
+  skuId: string;
+  sku: string;
+  providerCurrentForSale: number | null;
+  providerStockLastSyncedAt: string | null;
+  providerStockStaleAfter: string | null;
+  stockStatus: "missing" | "stale" | "fresh";
+  openHardReservations: number;
+  safetyStock: number;
+  sellableNow: number;
+  activeSubscriptionDemand30: number;
+  activeSubscriptionDemand45: number;
+  activeSubscriptionDemand60: number;
+  plannedSupply: number;
+  coverageDays: number | null;
+  shortageDate: string | null;
+  horizonMissingQty: number;
+  protectionMissingQty: number;
+  missingQty: number;
+  recommendedProductionQty: number;
+}
+
+export interface SubscriptionForecastTotals extends SubscriptionForecastCounts {
+  missingProviderStockSkuCount: number;
+  staleProviderStockSkuCount: number;
+  horizonShortageSkuCount: number;
+  protectionShortageSkuCount: number;
+  shortageSkuCount: number;
+  recommendedProductionQty: number;
+}

package/src/inventory/contracts/index.ts

@@ -0,0 +1,18 @@
+export type {
+  InventoryReservationStatus,
+  AdminInventoryStockRequest,
+  AdminInventoryReservationsRequest,
+  AdminInventoryStockAdjustmentRequest,
+  AdminInventorySubscriptionForecastRequest,
+  InventoryStockListResponse,
+  InventoryReservationsListResponse,
+  InventoryStockAdjustmentResponse,
+  InventorySubscriptionForecastResponse,
+  InventorySubscriptionForecastSku,
+  InventoryForecastDemandLine,
+  InventoryForecastSupplyLine,
+  InventoryForecastResponse,
+} from "./inventory.js";
+export type { NewPurchaseStockRow, NewPurchaseStockMode, NewPurchaseStockAvailabilityOptions } from "./newPurchaseStock.js";
+export type { ReservationPolicyInput, ReservationPolicy, AutomaticRenewalReservationResult } from "./reservation.js";
+export type { InventoryProviderStockLine, InventoryHardReservationLine, SubscriptionForecastCalculationInput, SubscriptionForecastCounts, SubscriptionForecastSku, SubscriptionForecastTotals } from "./forecast.js";

package/src/inventory/contracts/inventory.ts

@@ -0,0 +1,14 @@
+/** Inventory wire DTOs. Runtime validation belongs to the server entry. */
+export type InventoryReservationStatus = "reserved" | "released" | "consumed" | "expired";
+export type AdminInventoryStockRequest = { page: number; pageSize: number; includeZero: boolean; skuId?: string | undefined; locationId?: string | undefined; };
+export type AdminInventoryReservationsRequest = { page: number; pageSize: number; status?: "reserved" | "released" | "consumed" | "expired" | undefined; orderId?: string | undefined; };
+export type AdminInventoryStockAdjustmentRequest = { idempotencyKey: string; skuId: string; locationId: string; quantityDelta: number; reason: string; lotId?: string | null | undefined; note?: string | undefined; };
+export type AdminInventorySubscriptionForecastRequest = { horizonDays: number; protectionDays: number; };
+export type InventoryStockListResponse = { contractVersion: "inventory.v0"; stock: { skuId: string; sku: string; locationId: string; locationCode: string; locationKind: "internal_warehouse" | "third_party_logistics" | "supplier" | "quarantine" | "virtual"; locationStatus: "active" | "inactive"; fulfillable: boolean; lotId: string | null; lotCode: string | null; lotStatus: "expired" | "available" | "quarantined" | "recalled" | null; expiresAt: string | null; onHand: number; reserved: number; unavailable: number; incoming: number; safetyStock: number; availableNow: number; }[]; totalCount: number; page: number; pageSize: number; };
+export type InventoryReservationsListResponse = { contractVersion: "inventory.v0"; reservations: { id: string; orderId: string; subscriptionCycleId: string | null; status: "reserved" | "released" | "consumed" | "expired"; kind: "checkout_payment_window" | "subscription_retry_window" | "manual_ops"; expiresAt: string | null; createdAt: string; }[]; totalCount: number; page: number; pageSize: number; };
+export type InventoryStockAdjustmentResponse = { contractVersion: "inventory.v0"; replayed: boolean; };
+export type InventorySubscriptionForecastResponse = { contractVersion: "inventory.v0"; generatedAt: string; stockMasterProvider: string; horizonDays: number; protectionDays: number; skus: { skuId: string; sku: string; providerCurrentForSale: number | null; providerStockLastSyncedAt: string | null; providerStockStaleAfter: string | null; stockStatus: "fresh" | "stale" | "missing"; openHardReservations: number; safetyStock: number; sellableNow: number; activeSubscriptionDemand30: number; activeSubscriptionDemand45: number; activeSubscriptionDemand60: number; plannedSupply: number; coverageDays: number | null; shortageDate: string | null; horizonMissingQty: number; protectionMissingQty: number; missingQty: number; recommendedProductionQty: number; }[]; totals: { activeSubscriptionCount: number; excludedSubscriptionCount: number; missingProviderStockSkuCount: number; staleProviderStockSkuCount: number; horizonShortageSkuCount: number; protectionShortageSkuCount: number; shortageSkuCount: number; recommendedProductionQty: number; }; };
+export type InventorySubscriptionForecastSku = { skuId: string; sku: string; providerCurrentForSale: number | null; providerStockLastSyncedAt: string | null; providerStockStaleAfter: string | null; stockStatus: "fresh" | "stale" | "missing"; openHardReservations: number; safetyStock: number; sellableNow: number; activeSubscriptionDemand30: number; activeSubscriptionDemand45: number; activeSubscriptionDemand60: number; plannedSupply: number; coverageDays: number | null; shortageDate: string | null; horizonMissingQty: number; protectionMissingQty: number; missingQty: number; recommendedProductionQty: number; };
+export type InventoryForecastDemandLine = { subscriptionId: string; subscriptionCycleId: string | null; skuId: string; sku: string; quantity: number; dueAt: string; status: "planned" | "payment_pending" | "paid" | "retry_scheduled" | "skipped" | "cancelled"; };
+export type InventoryForecastSupplyLine = { skuId: string; quantity: number; expectedAt: string; status: "planned" | "cancelled" | "received"; };
+export type InventoryForecastResponse = { contractVersion: "inventory.v0"; shortages: { skuId: string; sku: string; dueAt: string; demandQuantity: number; availableOrExpectedQuantity: number; missingQuantity: number; }[]; };

package/src/inventory/contracts/newPurchaseStock.ts

@@ -0,0 +1,23 @@
+export interface NewPurchaseStockRow {
+  sku: string;
+  catalogSkuId: string | null;
+  source: "provider" | "local" | "missing";
+  providerForSale: number | null;
+  activeHolds: number;
+  safetyStock: number;
+  available: number | null;
+  stale: boolean;
+  renewalDemand: number;
+  availableForNewPurchases: number | null;
+  /** Holds of the excluded order left out of `activeHolds`; 0 when no order is excluded. */
+  excludedOrderHolds: number;
+}
+
+export type NewPurchaseStockMode = "new_purchase" | "renewal";
+
+export interface NewPurchaseStockAvailabilityOptions {
+  mode: NewPurchaseStockMode;
+  lowStockThreshold?: number;
+  horizonDays?: number;
+}
+

package/src/inventory/contracts/reservation.ts

@@ -0,0 +1,20 @@
+export interface ReservationPolicyInput {
+  reservationKind: string;
+  paymentTargetKind: "one_time_order" | "subscription_cycle" | string;
+  orderMode: "one_time" | "subscription_cycle" | string;
+  now: Date;
+  checkoutTtlMinutes?: number | null;
+}
+
+export interface ReservationPolicy {
+  expiresAt: string | null;
+  ttlMinutes: number | null;
+}
+
+export interface AutomaticRenewalReservationResult {
+  reserved: boolean;
+  replayed: boolean;
+  reservationId: string | null;
+  status: "held" | "committed" | "consumed" | "released" | "expired" | "refused";
+  reason: string | null;
+}

package/src/inventory/forecast.ts

@@ -0,0 +1,239 @@
+import { z } from "zod";
+import { INVENTORY_CONTRACT_VERSION, availableNow, type InventoryStockLine } from "@openlup/core/inventory";
+import type { InventoryForecastDemandLine, InventoryForecastResponse, InventoryForecastSupplyLine, InventorySubscriptionForecastResponse } from "./contracts/index.js";
+import type { InventoryProviderStockLine, InventoryHardReservationLine } from "./contracts/forecast.js";
+import { createInventorySubscriptionForecastResponseSchema } from "./schemas.js";
+
+const uuidSchema = z.guid();
+const datetimeSchema = z.string().datetime({ offset: true });
+const quantitySchema = z.number().int().nonnegative();
+const positiveQuantitySchema = z.number().int().positive();
+
+const inventoryForecastShortageSchema = z.object({
+  skuId: uuidSchema,
+  sku: z.string().trim().min(1),
+  dueAt: datetimeSchema,
+  demandQuantity: positiveQuantitySchema,
+  availableOrExpectedQuantity: quantitySchema,
+  missingQuantity: positiveQuantitySchema,
+}).strict();
+
+const inventoryForecastResponseSchema = z.object({
+  contractVersion: z.literal(INVENTORY_CONTRACT_VERSION),
+  shortages: z.array(inventoryForecastShortageSchema),
+}).strict();
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+export function forecastSubscriptionInventoryShortages(input: {
+  demand: InventoryForecastDemandLine[];
+  supply: InventoryForecastSupplyLine[];
+  stock: InventoryStockLine[];
+}): InventoryForecastResponse {
+  const demand = input.demand
+    .filter((line) => !["skipped", "cancelled"].includes(line.status))
+    .sort((a, b) => Date.parse(a.dueAt) - Date.parse(b.dueAt));
+  const runningAvailable = input.stock.reduce<Record<string, number>>((available, line) => {
+    available[line.skuId] = (available[line.skuId] ?? 0) + availableNow(line);
+    return available;
+  }, {});
+  const plannedSupply = input.supply
+    .filter((line) => line.status === "planned")
+    .sort((a, b) => Date.parse(a.expectedAt) - Date.parse(b.expectedAt));
+  const usedSupplyIndexes = new Set<number>();
+
+  const shortages = demand.flatMap((line) => {
+    for (const [index, supply] of plannedSupply.entries()) {
+      if (usedSupplyIndexes.has(index)) continue;
+      if (supply.skuId !== line.skuId) continue;
+      if (Date.parse(supply.expectedAt) > Date.parse(line.dueAt)) continue;
+      runningAvailable[line.skuId] = (runningAvailable[line.skuId] ?? 0) + supply.quantity;
+      usedSupplyIndexes.add(index);
+    }
+
+    const available = runningAvailable[line.skuId] ?? 0;
+    if (available >= line.quantity) {
+      runningAvailable[line.skuId] = available - line.quantity;
+      return [];
+    }
+
+    runningAvailable[line.skuId] = 0;
+    return [{
+      skuId: line.skuId,
+      sku: line.sku,
+      dueAt: line.dueAt,
+      demandQuantity: line.quantity,
+      availableOrExpectedQuantity: available,
+      missingQuantity: line.quantity - available,
+    }];
+  });
+
+  return inventoryForecastResponseSchema.parse({
+    contractVersion: INVENTORY_CONTRACT_VERSION,
+    shortages,
+  });
+}
+
+export function buildSubscriptionInventoryForecast(input: {
+  generatedAt: string;
+  horizonDays: number;
+  protectionDays: number;
+  providerCurrent: InventoryProviderStockLine[];
+  openHardReservations: InventoryHardReservationLine[];
+  stock: InventoryStockLine[];
+  demand: InventoryForecastDemandLine[];
+  supply: InventoryForecastSupplyLine[];
+  activeSubscriptionCount: number;
+  excludedSubscriptionCount: number;
+}, config: { stockMasterProvider: string; providerSchema: z.ZodType<string> }): InventorySubscriptionForecastResponse {
+  const inventorySubscriptionForecastResponseSchema = createInventorySubscriptionForecastResponseSchema(config.providerSchema);
+  const generatedAtMs = Date.parse(input.generatedAt);
+  const horizonAtMs = generatedAtMs + input.horizonDays * DAY_MS;
+  const protectionAtMs = generatedAtMs + input.protectionDays * DAY_MS;
+  const demand = input.demand
+    .filter((line) => !["skipped", "cancelled"].includes(line.status))
+    .filter((line) => Date.parse(line.dueAt) <= horizonAtMs);
+  const plannedSupply = input.supply
+    .filter((line) => line.status === "planned")
+    .filter((line) => Date.parse(line.expectedAt) <= horizonAtMs);
+
+  const providerBySku = new Map(input.providerCurrent.map((line) => [line.skuId, line]));
+  const skuIds = new Set<string>([
+    ...input.providerCurrent.map((line) => line.skuId),
+    ...input.openHardReservations.map((line) => line.skuId),
+    ...input.stock.map((line) => line.skuId),
+    ...demand.map((line) => line.skuId),
+    ...plannedSupply.map((line) => line.skuId),
+  ]);
+
+  const skus = [...skuIds].map((skuId) => {
+    const provider = providerBySku.get(skuId) ?? null;
+    const stockLines = input.stock.filter((line) => line.skuId === skuId);
+    const demandLines = demand.filter((line) => line.skuId === skuId);
+    const supplyLines = plannedSupply.filter((line) => line.skuId === skuId);
+    const sku = provider?.sku ?? stockLines[0]?.sku ?? demandLines[0]?.sku ?? "unknown";
+    const stockStatus = provider === null
+      ? "missing"
+      : Date.parse(provider.staleAfter) <= generatedAtMs
+        ? "stale"
+        : "fresh";
+    const openHardReservations = sum(input.openHardReservations
+      .filter((line) => line.skuId === skuId)
+      .map((line) => line.quantity));
+    const safetyStock = sum(stockLines
+      .filter((line) => line.fulfillable && line.locationStatus === "active")
+      .map((line) => line.safetyStock));
+    const sellableNow = stockStatus === "fresh" && provider
+      ? Math.max(0, provider.forSaleQuantity - openHardReservations - safetyStock)
+      : 0;
+    const shortage = simulateSubscriptionCoverage({
+      generatedAtMs,
+      protectionAtMs,
+      sellableNow,
+      demand: demandLines,
+      supply: supplyLines,
+    });
+
+    return {
+      skuId,
+      sku,
+      providerCurrentForSale: provider?.forSaleQuantity ?? null,
+      providerStockLastSyncedAt: provider?.lastSyncedAt ?? null,
+      providerStockStaleAfter: provider?.staleAfter ?? null,
+      stockStatus,
+      openHardReservations,
+      safetyStock,
+      sellableNow,
+      activeSubscriptionDemand30: demandQuantityWithin(demandLines, generatedAtMs + 30 * DAY_MS),
+      activeSubscriptionDemand45: demandQuantityWithin(demandLines, generatedAtMs + 45 * DAY_MS),
+      activeSubscriptionDemand60: demandQuantityWithin(demandLines, generatedAtMs + 60 * DAY_MS),
+      plannedSupply: sum(supplyLines.map((line) => line.quantity)),
+      coverageDays: shortage.shortageDate
+        ? Math.max(0, Math.ceil((Date.parse(shortage.shortageDate) - generatedAtMs) / DAY_MS))
+        : null,
+      shortageDate: shortage.shortageDate,
+      horizonMissingQty: shortage.horizonMissingQty,
+      protectionMissingQty: shortage.protectionMissingQty,
+      missingQty: shortage.protectionMissingQty,
+      recommendedProductionQty: shortage.protectionMissingQty,
+    };
+  }).sort((a, b) => a.sku.localeCompare(b.sku));
+
+  return inventorySubscriptionForecastResponseSchema.parse({
+    contractVersion: INVENTORY_CONTRACT_VERSION,
+    generatedAt: input.generatedAt,
+    stockMasterProvider: config.stockMasterProvider,
+    horizonDays: input.horizonDays,
+    protectionDays: input.protectionDays,
+    skus,
+    totals: {
+      activeSubscriptionCount: input.activeSubscriptionCount,
+      excludedSubscriptionCount: input.excludedSubscriptionCount,
+      missingProviderStockSkuCount: skus.filter((line) => line.stockStatus === "missing").length,
+      staleProviderStockSkuCount: skus.filter((line) => line.stockStatus === "stale").length,
+      horizonShortageSkuCount: skus.filter((line) => line.shortageDate !== null).length,
+      protectionShortageSkuCount: skus.filter((line) => line.protectionMissingQty > 0).length,
+      shortageSkuCount: skus.filter((line) => line.shortageDate !== null).length,
+      recommendedProductionQty: sum(skus.map((line) => line.recommendedProductionQty)),
+    },
+  });
+}
+
+function simulateSubscriptionCoverage(input: {
+  generatedAtMs: number;
+  protectionAtMs: number;
+  sellableNow: number;
+  demand: InventoryForecastDemandLine[];
+  supply: InventoryForecastSupplyLine[];
+}): { shortageDate: string | null; horizonMissingQty: number; protectionMissingQty: number } {
+  let available = input.sellableNow;
+  let shortageDate: string | null = null;
+  let horizonMissingQty = 0;
+  let protectionMissingQty = 0;
+  const events = [
+    ...input.supply.map((line) => ({
+      type: "supply" as const,
+      at: line.expectedAt,
+      quantity: line.quantity,
+    })),
+    ...input.demand.map((line) => ({
+      type: "demand" as const,
+      at: line.dueAt,
+      quantity: line.quantity,
+    })),
+  ].sort((a, b) => {
+    const dateDelta = Date.parse(a.at) - Date.parse(b.at);
+    if (dateDelta !== 0) return dateDelta;
+    return a.type === "supply" && b.type === "demand" ? -1 : 1;
+  });
+
+  for (const event of events) {
+    if (event.type === "supply") {
+      available += event.quantity;
+      continue;
+    }
+
+    if (available >= event.quantity) {
+      available -= event.quantity;
+      continue;
+    }
+
+    const missing = event.quantity - available;
+    available = 0;
+    shortageDate ??= event.at;
+    horizonMissingQty += missing;
+    if (Date.parse(event.at) <= input.protectionAtMs) protectionMissingQty += missing;
+  }
+
+  return { shortageDate, horizonMissingQty, protectionMissingQty };
+}
+
+function demandQuantityWithin(lines: InventoryForecastDemandLine[], dueAtOrBeforeMs: number): number {
+  return sum(lines
+    .filter((line) => Date.parse(line.dueAt) <= dueAtOrBeforeMs)
+    .map((line) => line.quantity));
+}
+
+function sum(values: number[]): number {
+  return values.reduce((total, value) => total + value, 0);
+}

package/src/inventory/index.ts

@@ -0,0 +1,21 @@
+export type { InventoryReadPort, InventoryMutationPort } from "./ports.js";
+export { InventoryPersistenceError, InventoryConflictError } from "./ports.js";
+export {
+  adminInventoryStockRequestSchema,
+  adminInventoryReservationsRequestSchema,
+  adminInventoryStockAdjustmentRequestSchema,
+  adminInventorySubscriptionForecastRequestSchema,
+  inventoryStockListResponseSchema,
+  inventoryReservationsListResponseSchema,
+  createInventorySubscriptionForecastResponseSchema,
+} from "./schemas.js";
+export { createAdminInventoryStockHandler, createAdminInventoryReservationsHandler, createAdminInventoryAtpCheckHandler, createAdminInventorySubscriptionForecastHandler, createAdminInventoryStockAdjustmentHandler } from "./inventoryHandlers.js";
+export { createPostgresAdminInventoryPort } from "./adminInventory.js";
+export type { NewPurchaseStockRow, NewPurchaseStockMode, NewPurchaseStockAvailabilityOptions } from "./contracts/newPurchaseStock.js";
+export type { NewPurchaseStockReadPort } from "./newPurchaseStockAvailability.js";
+export { createNewPurchaseStockAvailabilityPort } from "./newPurchaseStockAvailability.js";
+export { MIN_CHECKOUT_RESERVATION_TTL_MINUTES, MAX_CHECKOUT_RESERVATION_TTL_MINUTES, DEFAULT_CHECKOUT_RESERVATION_TTL_MINUTES, reservationPolicyFor, normalizedTtlMinutes } from "./reservationPolicy.js";
+export { createPostgresRenewalReservationPort, type AutomaticRenewalInventoryPort } from "./renewalReservation.js";
+export { forecastSubscriptionInventoryShortages, buildSubscriptionInventoryForecast } from "./forecast.js";
+export { calculateSubscriptionForecastSkus, calculateSubscriptionForecastTotals } from "./subscriptionForecastCalculation.js";
+export { INVENTORY_MIGRATIONS } from "./sql.js";

package/src/inventory/inventoryHandlers.ts

@@ -0,0 +1,215 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { z } from "zod";
+import { inventoryAtpRequestSchema, inventoryAtpResultSchema } from "@openlup/core/inventory";
+import {
+  adminInventoryReservationsRequestSchema,
+  adminInventoryStockAdjustmentRequestSchema,
+  adminInventoryStockRequestSchema,
+  adminInventorySubscriptionForecastRequestSchema,
+  inventoryReservationsListResponseSchema,
+  inventoryStockListResponseSchema,
+} from "./schemas.js";
+import { InventoryConflictError, type InventoryMutationPort, type InventoryReadPort } from "./ports.js";
+import type { InventorySubscriptionForecastResponse } from "./contracts/index.js";
+
+// Structural host bindings keep response context and HTTP composition with the host.
+interface HttpRequest extends IncomingMessage {
+  query: Record<string, string | string[] | undefined>;
+  cookies?: Record<string, string>;
+  body?: unknown;
+}
+interface HttpResponse extends ServerResponse {
+  status(code: number): this;
+  json(body: unknown): this;
+  send(body: string | Buffer | object): this;
+  redirect(url: string): this;
+  redirect(status: number, url: string): this;
+}
+interface ResponseBindings {
+  sendBffSuccess(res: HttpResponse, data: unknown): void;
+  sendBffError(res: HttpResponse, code: "UNAUTHORIZED" | "FORBIDDEN" | "BAD_REQUEST" | "INVALID_RESPONSE" | "UPSTREAM_UNAVAILABLE" | "CONFLICT", message: string, options?: { details?: unknown }): void;
+  sendMethodNotAllowed(res: HttpResponse, methods: readonly string[]): void;
+}
+type AdminAuthResult =
+  | { ok: false; code: "UNAUTHORIZED" | "FORBIDDEN"; message: string }
+  | { ok: true; userId: string };
+
+interface BaseDeps extends ResponseBindings {
+  authorizeAdmin: (req: HttpRequest) => Promise<AdminAuthResult>;
+}
+
+export function createAdminInventoryStockHandler({
+  authorizeAdmin,
+  sendBffError, sendBffSuccess, sendMethodNotAllowed,
+  inventoryPort,
+}: BaseDeps & { inventoryPort: Pick<InventoryReadPort, "listStock"> }) {
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "GET") return sendMethodNotAllowed(res, ["GET"]);
+    if (!(await authorize(req, res, authorizeAdmin, sendBffError))) return;
+
+    const request = adminInventoryStockRequestSchema.safeParse(req.query);
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid admin inventory stock request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      const result = await inventoryPort.listStock(request.data);
+      const response = inventoryStockListResponseSchema.safeParse(result);
+      if (!response.success) return sendBffError(res, "INVALID_RESPONSE", "Inventory stock response invalid");
+      sendBffSuccess(res, response.data);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Inventory stock read failed");
+    }
+  };
+}
+
+export function createAdminInventoryReservationsHandler({
+  authorizeAdmin,
+  sendBffError, sendBffSuccess, sendMethodNotAllowed,
+  inventoryPort,
+}: BaseDeps & { inventoryPort: Pick<InventoryReadPort, "listReservations"> }) {
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "GET") return sendMethodNotAllowed(res, ["GET"]);
+    if (!(await authorize(req, res, authorizeAdmin, sendBffError))) return;
+
+    const request = adminInventoryReservationsRequestSchema.safeParse(req.query);
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid admin inventory reservations request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      const result = await inventoryPort.listReservations(request.data);
+      const response = inventoryReservationsListResponseSchema.safeParse(result);
+      if (!response.success) return sendBffError(res, "INVALID_RESPONSE", "Inventory reservations response invalid");
+      sendBffSuccess(res, response.data);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Inventory reservations read failed");
+    }
+  };
+}
+
+export function createAdminInventoryAtpCheckHandler({
+  authorizeAdmin,
+  sendBffError, sendBffSuccess, sendMethodNotAllowed,
+  inventoryPort,
+  configuredRegion,
+}: BaseDeps & { inventoryPort: Pick<InventoryReadPort, "checkAtp">; configuredRegion?: string }) {
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "POST") return sendMethodNotAllowed(res, ["POST"]);
+    if (!(await authorize(req, res, authorizeAdmin, sendBffError))) return;
+
+    const request = inventoryAtpRequestSchema.safeParse(req.body ?? {});
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid admin inventory ATP request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      const result = await inventoryPort.checkAtp({
+        ...request.data,
+        region: request.data.region ?? configuredRegion,
+      });
+      const response = inventoryAtpResultSchema.safeParse(result);
+      if (!response.success) return sendBffError(res, "INVALID_RESPONSE", "Inventory ATP response invalid");
+      sendBffSuccess(res, response.data);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Inventory ATP check failed");
+    }
+  };
+}
+
+export function createAdminInventorySubscriptionForecastHandler({
+  inventorySubscriptionForecastResponseSchema,
+  authorizeAdmin,
+  sendBffError, sendBffSuccess, sendMethodNotAllowed,
+  inventoryPort,
+}: BaseDeps & { inventoryPort: Pick<InventoryReadPort, "forecastSubscriptions">; inventorySubscriptionForecastResponseSchema: z.ZodType<InventorySubscriptionForecastResponse> }) {
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "GET") return sendMethodNotAllowed(res, ["GET"]);
+    if (!(await authorize(req, res, authorizeAdmin, sendBffError))) return;
+
+    const request = adminInventorySubscriptionForecastRequestSchema.safeParse(req.query);
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid admin inventory subscription forecast request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      const result = await inventoryPort.forecastSubscriptions(request.data);
+      const response = inventorySubscriptionForecastResponseSchema.safeParse(result);
+      if (!response.success) {
+        return sendBffError(res, "INVALID_RESPONSE", "Inventory subscription forecast response invalid");
+      }
+      sendBffSuccess(res, response.data);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Inventory subscription forecast read failed");
+    }
+  };
+}
+
+export function createAdminInventoryStockAdjustmentHandler({
+  authorizeAdmin,
+  sendBffError, sendBffSuccess, sendMethodNotAllowed,
+  inventoryPort,
+  mutationsEnabled,
+}: BaseDeps & {
+  inventoryPort: Pick<InventoryMutationPort, "adjustStock">;
+  mutationsEnabled: () => boolean;
+}) {
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "POST") return sendMethodNotAllowed(res, ["POST"]);
+    const auth = await authorize(req, res, authorizeAdmin, sendBffError);
+    if (!auth) return;
+    if (!mutationsEnabled()) {
+      sendBffError(res, "FORBIDDEN", "Inventory mutations are not enabled");
+      return;
+    }
+
+    const request = adminInventoryStockAdjustmentRequestSchema.safeParse(req.body ?? {});
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid admin inventory stock adjustment request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      sendBffSuccess(res, await inventoryPort.adjustStock({ ...request.data, actorUserId: auth.userId }));
+    } catch (error) {
+      if (error instanceof InventoryConflictError) {
+        sendBffError(res, "CONFLICT", error.message, { details: error.details });
+        return;
+      }
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Inventory stock adjustment failed");
+    }
+  };
+}
+
+async function authorize(
+  req: HttpRequest,
+  res: HttpResponse,
+  authorizeAdmin: (req: HttpRequest) => Promise<AdminAuthResult>,
+  sendBffError: ResponseBindings["sendBffError"],
+): Promise<{ userId: string } | null> {
+  try {
+    const authorization = await authorizeAdmin(req);
+    if (authorization.ok === false) {
+      sendBffError(res, authorization.code, authorization.message);
+      return null;
+    }
+    return { userId: authorization.userId };
+  } catch {
+    sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin authorization failed");
+    return null;
+  }
+}