@openlup/platform 0.17.0 → 0.18.0

package/dist/catalog/contracts/bundleAdmin.d.ts

@@ -0,0 +1,143 @@
+/** Plain bundle transport DTOs. The host owns parsing, defaults and wire-version values. */
+export type CreateBundleDraftRequest = {
+    bundle: {
+        code: string;
+        title: string;
+        fulfillmentMode: "virtual" | "kitted";
+        compositionConstraint?: {
+            kind: string;
+            version: number;
+            data: Record<string, unknown>;
+        } | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    };
+    mode: "commit" | "dry_run";
+    idempotencyKey?: string | undefined;
+};
+export type CreateBundleDraftResponse = {
+    code: string;
+    bundleId: string;
+    contractVersion: "commerce.v0";
+    dryRun: boolean;
+    idempotent: boolean;
+};
+export type UpdateBundleDraftRequest = {
+    code: string;
+    updates: {
+        title?: string | undefined;
+        fulfillmentMode?: "virtual" | "kitted" | undefined;
+        compositionConstraint?: {
+            kind: string;
+            version: number;
+            data: Record<string, unknown>;
+        } | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    };
+    mode: "commit" | "dry_run";
+    idempotencyKey?: string | undefined;
+};
+export type UpdateBundleDraftResponse = {
+    code: string;
+    contractVersion: "commerce.v0";
+    dryRun: boolean;
+    idempotent: boolean;
+};
+export type BundleComponent = {
+    sku: string;
+    quantity: number;
+    isAddon: boolean;
+    sortOrder: number;
+};
+export type SetBundleCompositionRequest = {
+    code: string;
+    components: {
+        sku: string;
+        quantity: number;
+        isAddon: boolean;
+        sortOrder: number;
+    }[];
+    mode: "commit" | "dry_run";
+    idempotencyKey?: string | undefined;
+};
+export type SetBundleCompositionResponse = {
+    code: string;
+    componentCount: number;
+    contractVersion: "commerce.v0";
+    dryRun: boolean;
+    idempotent: boolean;
+};
+export type SetBundleTargetPriceRequest = {
+    code: string;
+    price: {
+        mode: "any" | "one_time" | "subscription";
+        targetPriceMinor: number;
+        currency: string;
+        amountKind: "gross" | "net";
+    };
+    mode: "commit" | "dry_run";
+    idempotencyKey?: string | undefined;
+};
+export type SetBundleTargetPriceResponse = {
+    code: string;
+    contractVersion: "commerce.v0";
+    dryRun: boolean;
+    idempotent: boolean;
+};
+export type ArchiveBundleRequest = {
+    code: string;
+    mode: "commit" | "dry_run";
+    idempotencyKey?: string | undefined;
+};
+export type ArchiveBundleResponse = {
+    code: string;
+    contractVersion: "commerce.v0";
+    dryRun: boolean;
+    idempotent: boolean;
+};
+export type RestoreBundleRequest = {
+    code: string;
+    mode: "commit" | "dry_run";
+    idempotencyKey?: string | undefined;
+};
+export type RestoreBundleResponse = {
+    code: string;
+    contractVersion: "commerce.v0";
+    dryRun: boolean;
+    idempotent: boolean;
+};
+export type CloneBundleDraftRequest = {
+    sourceCode: string;
+    code: string;
+    mode: "commit" | "dry_run";
+    title?: string | undefined;
+    idempotencyKey?: string | undefined;
+};
+export type CloneBundleDraftResponse = {
+    code: string;
+    bundleId: string;
+    contractVersion: "commerce.v0";
+    dryRun: boolean;
+    idempotent: boolean;
+};
+export type ActivateBundleRequest = {
+    code: string;
+    mode: "commit" | "dry_run";
+    idempotencyKey?: string | undefined;
+};
+export type ActivateBundleResponse = {
+    code: string;
+    contractVersion: "commerce.v0";
+    dryRun: boolean;
+    idempotent: boolean;
+};
+export type DeactivateBundleRequest = {
+    code: string;
+    mode: "commit" | "dry_run";
+    idempotencyKey?: string | undefined;
+};
+export type DeactivateBundleResponse = {
+    code: string;
+    contractVersion: "commerce.v0";
+    dryRun: boolean;
+    idempotent: boolean;
+};

package/dist/catalog/contracts/bundleAdmin.js

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

package/dist/catalog/contracts/bundleAvailability.d.ts

@@ -0,0 +1,61 @@
+/** Plain bundle transport DTOs. The host owns parsing, defaults and wire-version values. */
+export type SellableBundle = {
+    code: string;
+    title: string;
+    fulfillmentMode: string;
+    price: {
+        amountMinor: number;
+        currency: string;
+    };
+    components: {
+        sku: string;
+        quantity: number;
+        effectiveUnitPriceMinor: number;
+        lineSubtotalMinor: number;
+        discountBps: number;
+    }[];
+    availability: {
+        status: "unknown" | "available" | "low_stock" | "out_of_stock";
+        sellableNow: number | null;
+        limitingSku: string | null;
+        reasonCode: string;
+    };
+};
+export type SellableBundleComponent = {
+    sku: string;
+    quantity: number;
+    effectiveUnitPriceMinor: number;
+    lineSubtotalMinor: number;
+    discountBps: number;
+};
+export type SellableBundleAvailability = {
+    status: "unknown" | "available" | "low_stock" | "out_of_stock";
+    sellableNow: number | null;
+    limitingSku: string | null;
+    reasonCode: string;
+};
+export type SellableBundleListResponse = {
+    contractVersion: "catalog.sellable-bundle.v1";
+    bundles: {
+        code: string;
+        title: string;
+        fulfillmentMode: string;
+        price: {
+            amountMinor: number;
+            currency: string;
+        };
+        components: {
+            sku: string;
+            quantity: number;
+            effectiveUnitPriceMinor: number;
+            lineSubtotalMinor: number;
+            discountBps: number;
+        }[];
+        availability: {
+            status: "unknown" | "available" | "low_stock" | "out_of_stock";
+            sellableNow: number | null;
+            limitingSku: string | null;
+            reasonCode: string;
+        };
+    }[];
+};

package/dist/catalog/contracts/bundleAvailability.js

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

package/dist/catalog/contracts/bundleRead.d.ts

@@ -0,0 +1,223 @@
+/** Plain bundle transport DTOs. The host owns parsing, defaults and wire-version values. */
+export type ListBundlesRequest = {
+    limit: number;
+    offset: number;
+    status: "draft" | "active" | "archived" | "all";
+    query?: string | undefined;
+};
+export type ListBundlesResponse = {
+    bundles: {
+        code: string;
+        title: string;
+        status: string;
+        fulfillmentMode: string;
+        componentCount: number;
+        hasActiveTargetPrice: boolean;
+        updatedAt: string;
+    }[];
+    total: number;
+    contractVersion: "commerce.v0";
+};
+export type BundleSummaryView = {
+    code: string;
+    title: string;
+    status: string;
+    fulfillmentMode: string;
+    componentCount: number;
+    hasActiveTargetPrice: boolean;
+    updatedAt: string;
+};
+export type GetBundleRequest = {
+    code: string;
+    currency?: string | undefined;
+    mode?: "any" | "one_time" | "subscription" | undefined;
+};
+export type GetBundleResponse = {
+    bundle: {
+        code: string;
+        title: string;
+        status: string;
+        fulfillmentMode: string;
+        componentCount: number;
+        hasActiveTargetPrice: boolean;
+        updatedAt: string;
+        compositionConstraint: {
+            kind: string;
+            version: number;
+            data: Record<string, unknown>;
+        } | null;
+        metadata: Record<string, unknown>;
+        components: {
+            sku: string;
+            title: string | null;
+            productSlug: string;
+            quantity: number;
+            isAddon: boolean;
+            sortOrder: number;
+            referenceUnitPriceMinor: number | null;
+        }[];
+        prices: {
+            mode: string;
+            targetPriceMinor: number;
+            currency: string;
+            amountKind: string;
+            active: boolean;
+            validFrom: string;
+            validTo: string | null;
+        }[];
+        resolvedCurrency: string | null;
+        availability: {
+            sellableNow: number | null;
+            status: string;
+            reasonCode: string;
+            limitingSku: string | null;
+            components: {
+                sku: string;
+                quantity: number;
+                isAddon: boolean;
+                sellableNow: number | null;
+            }[];
+        } | null;
+    };
+    contractVersion: "commerce.v0";
+};
+export type BundleDetailView = {
+    code: string;
+    title: string;
+    status: string;
+    fulfillmentMode: string;
+    componentCount: number;
+    hasActiveTargetPrice: boolean;
+    updatedAt: string;
+    compositionConstraint: {
+        kind: string;
+        version: number;
+        data: Record<string, unknown>;
+    } | null;
+    metadata: Record<string, unknown>;
+    components: {
+        sku: string;
+        title: string | null;
+        productSlug: string;
+        quantity: number;
+        isAddon: boolean;
+        sortOrder: number;
+        referenceUnitPriceMinor: number | null;
+    }[];
+    prices: {
+        mode: string;
+        targetPriceMinor: number;
+        currency: string;
+        amountKind: string;
+        active: boolean;
+        validFrom: string;
+        validTo: string | null;
+    }[];
+    resolvedCurrency: string | null;
+    availability: {
+        sellableNow: number | null;
+        status: string;
+        reasonCode: string;
+        limitingSku: string | null;
+        components: {
+            sku: string;
+            quantity: number;
+            isAddon: boolean;
+            sellableNow: number | null;
+        }[];
+    } | null;
+};
+export type BundleAvailabilityView = {
+    sellableNow: number | null;
+    status: string;
+    reasonCode: string;
+    limitingSku: string | null;
+    components: {
+        sku: string;
+        quantity: number;
+        isAddon: boolean;
+        sellableNow: number | null;
+    }[];
+};
+export type BundleHistoryRequest = {
+    limit: number;
+    offset: number;
+    code: string;
+};
+export type BundleHistoryResponse = {
+    events: {
+        id: string;
+        action: string;
+        actorKind: string | null;
+        actorEmail: string | null;
+        entityId: string | null;
+        oldValue: unknown;
+        newValue: unknown;
+        occurredAt: string;
+    }[];
+    total: number;
+    contractVersion: "commerce.v0";
+};
+export type PreviewBundlePriceRequest = {
+    code: string;
+    currency?: string | undefined;
+    mode?: "any" | "one_time" | "subscription" | undefined;
+    targetPriceMinor?: number | undefined;
+};
+export type PreviewBundlePriceResponse = {
+    preview: {
+        bundleCode: string;
+        priceListId: string;
+        mode: string;
+        currency: string;
+        referenceTotalMinor: number;
+        targetPriceMinor: number;
+        discountTotalMinor: number;
+        discountBps: number;
+        floorApplied: boolean;
+        componentTargets: {
+            sku: string;
+            quantity: number;
+            referenceUnitPriceMinor: number;
+            referenceSubtotalMinor: number;
+            targetSubtotalMinor: number;
+            discountAllocatedMinor: number;
+            discountBps: number;
+            hasSplitPricing: boolean;
+        }[];
+        allocatedLines: {
+            sku: string;
+            quantity: number;
+            effectiveUnitPriceMinor: number;
+            lineSubtotalMinor: number;
+        }[];
+    };
+    contractVersion: "commerce.v0";
+};
+export type BundlePricePreview = {
+    bundleCode: string;
+    priceListId: string;
+    mode: string;
+    currency: string;
+    referenceTotalMinor: number;
+    targetPriceMinor: number;
+    discountTotalMinor: number;
+    discountBps: number;
+    floorApplied: boolean;
+    componentTargets: {
+        sku: string;
+        quantity: number;
+        referenceUnitPriceMinor: number;
+        referenceSubtotalMinor: number;
+        targetSubtotalMinor: number;
+        discountAllocatedMinor: number;
+        discountBps: number;
+        hasSplitPricing: boolean;
+    }[];
+    allocatedLines: {
+        sku: string;
+        quantity: number;
+        effectiveUnitPriceMinor: number;
+        lineSubtotalMinor: number;
+    }[];
+};

package/dist/catalog/contracts/bundleRead.js

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

package/dist/catalog/contracts/draft.d.ts

@@ -0,0 +1,79 @@
+import type { CatalogDocumentRevisionRef } from "./foundation.js";
+import type { CatalogProductTypeRef, CatalogOptionValue, CatalogQuantity } from "./productTypes.js";
+export declare const CATALOG_DRAFT_MAX_BYTES = 1048576;
+export declare const CATALOG_DRAFT_MAX_PAGE = 100;
+export interface CatalogDraftPayload {
+    schemaVersion: 1;
+    product: {
+        id: string;
+        type: CatalogProductTypeRef;
+        slug?: string;
+        primarySkuId?: string;
+        dimensions: string[];
+        sharedContent?: unknown;
+        documentRevision?: CatalogDocumentRevisionRef;
+    };
+    skus: {
+        id: string;
+        productId: string;
+        code?: string;
+        options: Record<string, CatalogOptionValue>;
+        netContent?: CatalogQuantity;
+        identifiers?: {
+            scheme: string;
+            issuer: string;
+            value: string;
+            packagingLevel: "unit" | "case";
+            quantity?: number;
+        }[];
+        assetRefs?: string[];
+        grossMass?: CatalogQuantity;
+        priceRef?: string;
+        logisticsRef?: string;
+    }[];
+}
+export interface CatalogDraftCommand {
+    schemaVersion: 1;
+    action: "create" | "revise" | "abandon";
+    draftId: string;
+    commandKey: string;
+    expectedRevision: number;
+    payload?: CatalogDraftPayload;
+}
+export interface CatalogDraftSummary {
+    draftId: string;
+    productId: string;
+    revision: number;
+    status: "open" | "abandoned";
+    commandKey: string;
+    fingerprint: string;
+    actorId: string;
+    createdAt: string;
+}
+export interface CatalogDraftRecord extends CatalogDraftSummary {
+    payload: CatalogDraftPayload;
+}
+export interface CatalogDraftPage {
+    items: CatalogDraftSummary[];
+    nextCursor: string | null;
+}
+export interface CatalogDraftRefusal {
+    outcome: "conflict" | "validation_issue" | "unauthorized" | "dependency_unavailable";
+    reason: string;
+    currentRevision?: number;
+}
+export type CatalogDraftApplyResult = {
+    outcome: "committed" | "replayed";
+    record: CatalogDraftRecord;
+} | CatalogDraftRefusal;
+export interface CatalogDraftGetQuery {
+    draftId: string;
+    revision?: number;
+    commandKey?: string;
+}
+export interface CatalogDraftListQuery {
+    afterDraftId?: string;
+    limit: number;
+}
+/** Reject lossy JSON inputs, prototype keys and excessive recursion before validation or hashing. */
+export declare function canonicalCatalogDraftJson(input: unknown): string;

package/dist/catalog/contracts/draft.js

@@ -0,0 +1,47 @@
+export const CATALOG_DRAFT_MAX_BYTES = 1_048_576;
+export const CATALOG_DRAFT_MAX_PAGE = 100;
+/** Reject lossy JSON inputs, prototype keys and excessive recursion before validation or hashing. */
+export function canonicalCatalogDraftJson(input) {
+    const ancestors = new Set();
+    function visit(value, depth) {
+        if (depth > 48)
+            throw new Error("draft_json_depth");
+        if (typeof value === "string") {
+            if (value.includes("\u0000") || /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(value))
+                throw new Error("draft_json_invalid");
+            return value;
+        }
+        if (value === null || typeof value === "boolean")
+            return value;
+        if (typeof value === "number" && Number.isFinite(value) && !Object.is(value, -0))
+            return value;
+        if (typeof value !== "object" || ancestors.has(value))
+            throw new Error("draft_json_invalid");
+        if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)
+            throw new Error("draft_json_invalid");
+        ancestors.add(value);
+        const keys = Reflect.ownKeys(value);
+        if (keys.some((key) => typeof key !== "string" || ["__proto__", "constructor", "prototype"].includes(key)))
+            throw new Error("draft_json_invalid");
+        for (const key of keys) {
+            visit(key, depth + 1);
+            if (Object.getOwnPropertyDescriptor(value, key)?.get || Object.getOwnPropertyDescriptor(value, key)?.set)
+                throw new Error("draft_json_invalid");
+        }
+        let result;
+        if (Array.isArray(value)) {
+            if (keys.length !== value.length + 1)
+                throw new Error("draft_json_invalid");
+            result = Array.from(value, (item) => visit(item, depth + 1));
+        }
+        else {
+            result = Object.fromEntries(keys.sort().map((key) => [key, visit(value[key], depth + 1)]));
+        }
+        ancestors.delete(value);
+        return result;
+    }
+    const text = JSON.stringify(visit(input, 0));
+    if (new TextEncoder().encode(text).byteLength > CATALOG_DRAFT_MAX_BYTES)
+        throw new Error("draft_payload_too_large");
+    return text;
+}

package/dist/catalog/contracts/foundation.d.ts

@@ -0,0 +1,78 @@
+/** Portable, payload-free catalog references and identifier authority. */
+export declare const CATALOG_FOUNDATION_CONTRACT_VERSION = "catalog.foundation.v1";
+export interface CatalogDocumentRevisionRef {
+    id: string;
+    productId: string;
+    revisionNo: number;
+    schemaId: string;
+    documentRef: string;
+    sourceRef: string;
+    digest: string;
+}
+export interface CatalogSkuIdentifier {
+    issuer: string;
+    normalizedValue: string;
+    kind: "gtin" | "other";
+    packKind: "unit" | "collective";
+    packQuantity: number;
+    isPrimary: boolean;
+}
+export type CatalogSkuEnvelopeSelector = {
+    kind: "sku_code";
+    skuCode: string;
+} | {
+    kind: "primary_product_slug";
+    productSlug: string;
+};
+export interface NeutralSkuEnvelopeV1 {
+    contractVersion: typeof CATALOG_FOUNDATION_CONTRACT_VERSION;
+    product: {
+        id: string;
+        slug: string;
+        primarySkuId: string;
+    };
+    sku: {
+        id: string;
+        productId: string;
+        code: string;
+        netContent: {
+            unscaled: number;
+            scale: number;
+            unit: string;
+        };
+        sellability: {
+            status: "draft" | "active" | "archived";
+            oneTime: boolean;
+            subscription: boolean;
+        };
+        isAddon: boolean;
+        assetRef: string | null;
+    };
+    documentRevision: CatalogDocumentRevisionRef;
+    identifiers: CatalogSkuIdentifier[];
+}
+export interface CatalogPriceContext {
+    priceListId: string;
+    regionCode: string;
+    currency: string;
+    channel: string;
+    atTime: string;
+}
+/** Refusal vocabulary shared by managed and portable catalog readers. */
+export type CatalogSkuAuthorityRefusal = "catalog_sku_authority_sku_absent" | "catalog_sku_authority_product_absent" | "catalog_sku_authority_primary_sku_invalid" | "catalog_sku_authority_selector_ambiguous" | "catalog_sku_authority_current_document_absent" | "catalog_sku_authority_current_document_invalid" | "catalog_sku_identifier_authority_absent" | "catalog_sku_identifier_authority_ambiguous" | "catalog_sku_identifier_authority_invalid";
+export declare class CatalogSkuAuthorityError extends Error {
+    readonly code: CatalogSkuAuthorityRefusal;
+    constructor(code: CatalogSkuAuthorityRefusal);
+}
+/** Accepts only GS1 GTIN-8/12/13/14 values with a valid modulo-10 check digit. */
+export declare function isValidGtin(value: string): boolean;
+/**
+ * Makes a read adapter fail closed when source rows cannot state one valid,
+ * primary unit GTIN. The neutral envelope itself remains payload and DB agnostic.
+ */
+export declare function assertPrimaryUnitGtinAuthority(identifiers: readonly CatalogSkuIdentifier[]): void;
+/** Returns the product-scoped revision only when the declared current authority is sound. */
+export declare function requireCurrentCatalogDocumentAuthority<T extends {
+    id: string;
+    productId: string;
+}>(productId: string, currentDocumentRevisionId: string | null, revision: T | null | undefined): T;

package/dist/catalog/contracts/foundation.js

@@ -0,0 +1,53 @@
+/** Portable, payload-free catalog references and identifier authority. */
+export const CATALOG_FOUNDATION_CONTRACT_VERSION = "catalog.foundation.v1";
+export class CatalogSkuAuthorityError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = "CatalogSkuAuthorityError";
+    }
+}
+/** Accepts only GS1 GTIN-8/12/13/14 values with a valid modulo-10 check digit. */
+export function isValidGtin(value) {
+    if (!/^\d{8}$|^\d{12}$|^\d{13}$|^\d{14}$/u.test(value))
+        return false;
+    const digits = [...value].map(Number);
+    const checkDigit = digits.pop();
+    if (checkDigit === undefined)
+        return false;
+    const weighted = digits.reverse().reduce((sum, digit, index) => sum + digit * (index % 2 === 0 ? 3 : 1), 0);
+    return (weighted + checkDigit) % 10 === 0;
+}
+/**
+ * Makes a read adapter fail closed when source rows cannot state one valid,
+ * primary unit GTIN. The neutral envelope itself remains payload and DB agnostic.
+ */
+export function assertPrimaryUnitGtinAuthority(identifiers) {
+    const primary = identifiers.filter((identifier) => identifier.isPrimary);
+    if (primary.length === 0) {
+        throw new CatalogSkuAuthorityError("catalog_sku_identifier_authority_absent");
+    }
+    if (primary.length !== 1) {
+        throw new CatalogSkuAuthorityError("catalog_sku_identifier_authority_ambiguous");
+    }
+    const [identifier] = primary;
+    if (identifier.kind !== "gtin"
+        || identifier.packKind !== "unit"
+        || identifier.packQuantity !== 1
+        || !isValidGtin(identifier.normalizedValue)) {
+        throw new CatalogSkuAuthorityError("catalog_sku_identifier_authority_invalid");
+    }
+}
+/** Returns the product-scoped revision only when the declared current authority is sound. */
+export function requireCurrentCatalogDocumentAuthority(productId, currentDocumentRevisionId, revision) {
+    if (currentDocumentRevisionId === null) {
+        throw new CatalogSkuAuthorityError("catalog_sku_authority_current_document_absent");
+    }
+    if (!revision
+        || revision.id !== currentDocumentRevisionId
+        || revision.productId !== productId) {
+        throw new CatalogSkuAuthorityError("catalog_sku_authority_current_document_invalid");
+    }
+    return revision;
+}