@openlup/platform 0.16.0 → 0.18.0

package/dist/inventory/contracts/newPurchaseStock.d.ts

@@ -0,0 +1,20 @@
+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/dist/inventory/contracts/newPurchaseStock.js

@@ -0,0 +1 @@
+export {};

package/dist/inventory/contracts/reservation.d.ts

@@ -0,0 +1,18 @@
+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/dist/inventory/contracts/reservation.js

@@ -0,0 +1 @@
+export {};

package/dist/inventory/forecast.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import { type InventoryStockLine } from "@openlup/core/inventory";
+import type { InventoryForecastDemandLine, InventoryForecastResponse, InventoryForecastSupplyLine, InventorySubscriptionForecastResponse } from "./contracts/index.js";
+import type { InventoryProviderStockLine, InventoryHardReservationLine } from "./contracts/forecast.js";
+export declare function forecastSubscriptionInventoryShortages(input: {
+    demand: InventoryForecastDemandLine[];
+    supply: InventoryForecastSupplyLine[];
+    stock: InventoryStockLine[];
+}): InventoryForecastResponse;
+export declare 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;

package/dist/inventory/forecast.js

@@ -0,0 +1,200 @@
+import { z } from "zod";
+import { INVENTORY_CONTRACT_VERSION, availableNow } from "@openlup/core/inventory";
+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) {
+    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((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();
+    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, config) {
+    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([
+        ...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) {
+    let available = input.sellableNow;
+    let shortageDate = null;
+    let horizonMissingQty = 0;
+    let protectionMissingQty = 0;
+    const events = [
+        ...input.supply.map((line) => ({
+            type: "supply",
+            at: line.expectedAt,
+            quantity: line.quantity,
+        })),
+        ...input.demand.map((line) => ({
+            type: "demand",
+            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, dueAtOrBeforeMs) {
+    return sum(lines
+        .filter((line) => Date.parse(line.dueAt) <= dueAtOrBeforeMs)
+        .map((line) => line.quantity));
+}
+function sum(values) {
+    return values.reduce((total, value) => total + value, 0);
+}

package/dist/inventory/index.d.ts

@@ -0,0 +1,13 @@
+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/dist/inventory/index.js

@@ -0,0 +1,10 @@
+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 { 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 } from "./renewalReservation.js";
+export { forecastSubscriptionInventoryShortages, buildSubscriptionInventoryForecast } from "./forecast.js";
+export { calculateSubscriptionForecastSkus, calculateSubscriptionForecastTotals } from "./subscriptionForecastCalculation.js";
+export { INVENTORY_MIGRATIONS } from "./sql.js";

package/dist/inventory/inventoryHandlers.d.ts

@@ -0,0 +1,53 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { z } from "zod";
+import { type InventoryMutationPort, type InventoryReadPort } from "./ports.js";
+import type { InventorySubscriptionForecastResponse } from "./contracts/index.js";
+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 declare function createAdminInventoryStockHandler({ authorizeAdmin, sendBffError, sendBffSuccess, sendMethodNotAllowed, inventoryPort, }: BaseDeps & {
+    inventoryPort: Pick<InventoryReadPort, "listStock">;
+}): (req: HttpRequest, res: HttpResponse) => Promise<void>;
+export declare function createAdminInventoryReservationsHandler({ authorizeAdmin, sendBffError, sendBffSuccess, sendMethodNotAllowed, inventoryPort, }: BaseDeps & {
+    inventoryPort: Pick<InventoryReadPort, "listReservations">;
+}): (req: HttpRequest, res: HttpResponse) => Promise<void>;
+export declare function createAdminInventoryAtpCheckHandler({ authorizeAdmin, sendBffError, sendBffSuccess, sendMethodNotAllowed, inventoryPort, configuredRegion, }: BaseDeps & {
+    inventoryPort: Pick<InventoryReadPort, "checkAtp">;
+    configuredRegion?: string;
+}): (req: HttpRequest, res: HttpResponse) => Promise<void>;
+export declare function createAdminInventorySubscriptionForecastHandler({ inventorySubscriptionForecastResponseSchema, authorizeAdmin, sendBffError, sendBffSuccess, sendMethodNotAllowed, inventoryPort, }: BaseDeps & {
+    inventoryPort: Pick<InventoryReadPort, "forecastSubscriptions">;
+    inventorySubscriptionForecastResponseSchema: z.ZodType<InventorySubscriptionForecastResponse>;
+}): (req: HttpRequest, res: HttpResponse) => Promise<void>;
+export declare function createAdminInventoryStockAdjustmentHandler({ authorizeAdmin, sendBffError, sendBffSuccess, sendMethodNotAllowed, inventoryPort, mutationsEnabled, }: BaseDeps & {
+    inventoryPort: Pick<InventoryMutationPort, "adjustStock">;
+    mutationsEnabled: () => boolean;
+}): (req: HttpRequest, res: HttpResponse) => Promise<void>;
+export {};

package/dist/inventory/inventoryHandlers.js

@@ -0,0 +1,151 @@
+import { inventoryAtpRequestSchema, inventoryAtpResultSchema } from "@openlup/core/inventory";
+import { adminInventoryReservationsRequestSchema, adminInventoryStockAdjustmentRequestSchema, adminInventoryStockRequestSchema, adminInventorySubscriptionForecastRequestSchema, inventoryReservationsListResponseSchema, inventoryStockListResponseSchema, } from "./schemas.js";
+import { InventoryConflictError } from "./ports.js";
+export function createAdminInventoryStockHandler({ authorizeAdmin, sendBffError, sendBffSuccess, sendMethodNotAllowed, inventoryPort, }) {
+    return async function handler(req, res) {
+        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, }) {
+    return async function handler(req, res) {
+        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, }) {
+    return async function handler(req, res) {
+        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, }) {
+    return async function handler(req, res) {
+        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, }) {
+    return async function handler(req, res) {
+        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, res, authorizeAdmin, sendBffError) {
+    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;
+    }
+}

package/dist/inventory/newPurchaseStockAvailability.d.ts

@@ -0,0 +1,47 @@
+import type { NewPurchaseStockRow, NewPurchaseStockAvailabilityOptions } from "./contracts/newPurchaseStock.js";
+type BundleStockStatus = "available" | "low_stock" | "out_of_stock" | "unknown";
+interface BundleStockRequestItem {
+    sku: string;
+    productSlug: string;
+    variantId: string;
+    requestedQuantity: number;
+    checkoutMode: "one_time" | "subscription";
+}
+interface BundleStockAvailability {
+    sku: string;
+    productSlug: string;
+    variantId: string;
+    status: BundleStockStatus;
+    visibleInConfigurator: boolean;
+    sellableNow: number | null;
+    reasonCode: string;
+    source: string;
+}
+interface BundleStockPort {
+    getAvailability(input: {
+        items: readonly BundleStockRequestItem[];
+    }): Promise<BundleStockAvailability[]>;
+}
+/** Normalized host read. Transport, missing-function recognition and fallback stay with the host. */
+export interface NewPurchaseStockReadPort {
+    read(input: {
+        skus: readonly string[];
+        horizonDays: number;
+        excludeOrderId: string | null;
+    }): Promise<Map<string, NewPurchaseStockRow>>;
+}
+interface StockBindings {
+    readPort: NewPurchaseStockReadPort;
+    functionMissingFallback: (() => BundleStockPort) | null;
+    functionMissingError: string;
+    defaultLowStockThreshold: number;
+    defaultHorizonDays: number;
+    deriveOfferAvailability(input: BundleStockRequestItem & {
+        sellableNow: number | null;
+        lowStockThreshold: number;
+        source: string;
+    }): BundleStockAvailability;
+    observe: Pick<Console, "warn">;
+}
+export declare function createNewPurchaseStockAvailabilityPort({ readPort, functionMissingFallback, functionMissingError, defaultLowStockThreshold, defaultHorizonDays, deriveOfferAvailability, observe }: StockBindings, options: NewPurchaseStockAvailabilityOptions): BundleStockPort;
+export {};

package/dist/inventory/newPurchaseStockAvailability.js

@@ -0,0 +1,75 @@
+export function createNewPurchaseStockAvailabilityPort({ readPort, functionMissingFallback, functionMissingError, defaultLowStockThreshold, defaultHorizonDays, deriveOfferAvailability, observe }, options) {
+    const lowStockThreshold = options.lowStockThreshold ?? defaultLowStockThreshold;
+    const horizonDays = options.horizonDays ?? defaultHorizonDays;
+    return {
+        async getAvailability({ items }) {
+            if (items.length === 0)
+                return [];
+            let rows;
+            try {
+                rows = await readPort.read({
+                    skus: items.map((item) => item.sku),
+                    horizonDays,
+                    excludeOrderId: null,
+                });
+            }
+            catch (error) {
+                if (functionMissingFallback
+                    && error instanceof Error
+                    && error.message === functionMissingError) {
+                    observe.warn("[new-purchase-stock] function missing; falling back to the core availability read");
+                    return functionMissingFallback().getAvailability({ items });
+                }
+                observe.warn("[new-purchase-stock] availability read failed", {
+                    reason: error instanceof Error ? error.message : String(error),
+                });
+                return items.map((item) => unknownAvailability(item, "inventory_read_failed"));
+            }
+            // Same branch rule as the core adapter: once any requested SKU is
+            // provider-backed, every SKU must be, and a SKU without a provider row is
+            // not sellable rather than silently falling back to local stock.
+            const providerBacked = [...rows.values()].some((row) => row.source === "provider");
+            return items.map((item) => {
+                const row = rows.get(item.sku);
+                if (providerBacked) {
+                    if (row?.source !== "provider")
+                        return unavailable(item, "provider_stock_missing");
+                    if (row.stale)
+                        return unavailable(item, "provider_stock_stale");
+                    return deriveOfferAvailability({
+                        ...item,
+                        sellableNow: sellableFor(row, options.mode),
+                        lowStockThreshold,
+                        source: "inventory_provider",
+                    });
+                }
+                return deriveOfferAvailability({
+                    ...item,
+                    sellableNow: row?.source === "local" ? sellableFor(row, options.mode) : null,
+                    lowStockThreshold,
+                    source: "inventory",
+                });
+            });
+        },
+    };
+}
+function sellableFor(row, mode) {
+    const value = mode === "new_purchase" ? row.availableForNewPurchases : row.available;
+    return value == null ? null : Math.max(0, value);
+}
+/** The core adapter's provider-missing / provider-stale answer shape. */
+function unavailable(item, reasonCode) {
+    const { sku, productSlug, variantId } = item;
+    return {
+        sku, productSlug, variantId, status: "out_of_stock", visibleInConfigurator: false, sellableNow: 0,
+        reasonCode, source: "inventory_provider",
+    };
+}
+/** The core adapter's read-failure answer shape. */
+function unknownAvailability(item, reasonCode) {
+    const { sku, productSlug, variantId } = item;
+    return {
+        sku, productSlug, variantId, status: "unknown", visibleInConfigurator: true, sellableNow: null,
+        reasonCode, source: "inventory",
+    };
+}

package/dist/inventory/ports.d.ts

@@ -0,0 +1,21 @@
+import type { InventoryAtpRequest, InventoryAtpResult } from "@openlup/core/inventory";
+import type { AdminInventoryReservationsRequest, AdminInventoryStockAdjustmentRequest, AdminInventoryStockRequest, AdminInventorySubscriptionForecastRequest, InventoryReservationsListResponse, InventoryStockAdjustmentResponse, InventoryStockListResponse, InventorySubscriptionForecastResponse } from "./contracts/index.js";
+export interface InventoryReadPort {
+    listStock(request: AdminInventoryStockRequest): Promise<InventoryStockListResponse>;
+    listReservations(request: AdminInventoryReservationsRequest): Promise<InventoryReservationsListResponse>;
+    checkAtp(request: InventoryAtpRequest): Promise<InventoryAtpResult>;
+    forecastSubscriptions(request: AdminInventorySubscriptionForecastRequest): Promise<InventorySubscriptionForecastResponse>;
+}
+export interface InventoryMutationPort {
+    adjustStock(request: AdminInventoryStockAdjustmentRequest & {
+        actorUserId: string;
+    }): Promise<InventoryStockAdjustmentResponse>;
+}
+export declare class InventoryPersistenceError extends Error {
+    readonly details: Record<string, unknown>;
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+export declare class InventoryConflictError extends Error {
+    readonly details: Record<string, unknown>;
+    constructor(message?: string, details?: Record<string, unknown>);
+}