@legenki/print2medusa 0.8.2 → 0.9.2

package/.medusa/server/src/utils/bundle.js

@@ -0,0 +1,243 @@
+"use strict";
+/**
+ * Merch bundles: one Medusa product that stands for several Printful ones.
+ *
+ * Printful has no notion of a bundle — it fulfils individual items. So a
+ * bundle is a Medusa product whose variant records which member variants it
+ * contains, and order creation expands it back into those members.
+ *
+ * **Why expansion is mandatory rather than a nicety.** `create-printful-order`
+ * resolves one order line to one Printful item via `item.variant_id`. A bundle
+ * left unexpanded therefore ships a single thing where the customer bought
+ * three — or, if the bundle variant has no Printful link at all, the order is
+ * skipped as `no_printful_items` and nothing ships.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUNDLE_MEMBERS_KEY = void 0;
+exports.bundleMembersOf = bundleMembersOf;
+exports.isBundleLine = isBundleLine;
+exports.expandOrderLines = expandOrderLines;
+exports.medusaLineIdFor = medusaLineIdFor;
+exports.planBundlePass = planBundlePass;
+exports.planBundlePublication = planBundlePublication;
+exports.planBundleAvailability = planBundleAvailability;
+const stock_1 = require("./stock");
+/** Statuses meaning a variant cannot be ordered. Mirrors `stock.ts`. */
+const UNAVAILABLE = new Set([
+    "out_of_stock",
+    "temporary_out_of_stock",
+    "discontinued",
+]);
+/** Where a bundle's composition lives, on the variant and on the order line. */
+exports.BUNDLE_MEMBERS_KEY = "printful_bundle_members";
+/**
+ * The members recorded on a line, or nothing.
+ *
+ * Metadata is free-form JSON, so this validates rather than trusts: something
+ * else writing a string to this key must not crash order creation.
+ */
+function bundleMembersOf(line) {
+    const raw = (line?.metadata ?? {})[exports.BUNDLE_MEMBERS_KEY];
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    const members = [];
+    for (const entry of raw) {
+        if (!entry || typeof entry !== "object") {
+            continue;
+        }
+        const variantId = entry.variant_id;
+        if (typeof variantId !== "string" || !variantId.trim()) {
+            continue;
+        }
+        const quantity = Number(entry.quantity ?? 1);
+        members.push({
+            variant_id: variantId,
+            quantity: Number.isFinite(quantity) && quantity > 0 ? quantity : 1,
+        });
+    }
+    return members;
+}
+/**
+ * Whether a line stands for several products.
+ *
+ * A line whose member list is empty is *not* a bundle. Treating it as one
+ * would expand it to nothing, and an order of nothing looks identical to an
+ * order Printful was never asked about. Left alone, it flows through the
+ * ordinary unresolved-variant path, which reports it.
+ */
+function isBundleLine(line) {
+    return bundleMembersOf(line).length > 0;
+}
+/**
+ * Replace every bundle line with the lines it stands for.
+ *
+ * Composition is read from the line's own metadata, captured when the customer
+ * bought — never looked up live. A merchant who edits a bundle after a sale
+ * must not change what an already-placed order ships.
+ *
+ * Ordinary lines pass through untouched and keep their position, so a cart
+ * mixing bundles and singles reaches Printful in the order it was built.
+ */
+function expandOrderLines(lines) {
+    const out = [];
+    for (const line of lines) {
+        const members = bundleMembersOf(line);
+        if (members.length === 0) {
+            out.push(line);
+            continue;
+        }
+        for (const member of members) {
+            out.push({
+                // Synthesised, but stable and traceable: two bundles in one cart
+                // cannot collide, and the id says where the line came from.
+                id: `${line.id}::${member.variant_id}`,
+                variant_id: member.variant_id,
+                title: line.title,
+                // Two bundles each holding two stickers is four stickers. Dropping
+                // this multiplication ships a customer half their order.
+                quantity: (member.quantity ?? 1) * Number(line.quantity || 1),
+                metadata: {},
+                bundle_line_id: line.id,
+            });
+        }
+    }
+    return out;
+}
+/** Separates the bundle line id from the member variant id in a synthetic id. */
+const SYNTHETIC_SEPARATOR = "::";
+/**
+ * The Medusa line an `external_id` from Printful refers to.
+ *
+ * Expansion sends synthetic ids like `ordli_abc::variant_tee` as `external_id`,
+ * because Printful needs each item distinguishable and two members of one
+ * bundle would otherwise share the bundle line's id.
+ *
+ * Fulfillment reads those ids back to decide which Medusa line a parcel filled.
+ * Without this, a bundle's items resolve to an id no Medusa line has, every
+ * parcel clamps to zero open quantity, and the order is never marked shipped.
+ *
+ * A member id maps back to the *bundle* line, since that is the line the
+ * customer bought and the only one Medusa can fulfil.
+ */
+function medusaLineIdFor(externalId) {
+    const at = externalId.indexOf(SYNTHETIC_SEPARATOR);
+    return at === -1 ? externalId : externalId.slice(0, at);
+}
+/**
+ * Which bundle products the sync should rewrite, and to what.
+ *
+ * Bundles are invisible to the ordinary sync: they have no Printful product of
+ * their own, so no `sync_product` ever names them and the per-product loop
+ * never reaches them. Without this pass a bundle stays on sale after a member
+ * sells out, and every such order fails at Printful.
+ *
+ * Availability is read from the member variants passed in, not from the bundle
+ * — the bundle variant has no Printful status of its own to read.
+ *
+ * Returns only products that need writing, so a sync over a catalogue with no
+ * bundle changes issues no updates at all.
+ */
+function planBundlePass(input) {
+    const writes = [];
+    for (const bundle of input.bundles) {
+        const memberIds = (bundle.variants ?? []).flatMap((v) => bundleMembersOf({ id: v.id, quantity: 1, metadata: v.metadata }).map((m) => m.variant_id));
+        if (memberIds.length === 0) {
+            continue;
+        }
+        // A member variant the sync could not load is left out of the decision
+        // rather than counted as sold out: a failed lookup is not evidence that
+        // Printful ran out of anything, and drafting on it would hide a live
+        // bundle on a transient error.
+        const known = memberIds
+            .map((id) => input.variantsById.get(id))
+            .filter((v) => !!v);
+        // Knowing nothing about any member is not the same as knowing they are all
+        // in stock. Left to fall through, a bundle drafted for a sellout would be
+        // republished on the strength of a lookup that simply failed.
+        if (known.length === 0) {
+            continue;
+        }
+        const plan = planBundlePublication({
+            members: known,
+            currentStatus: bundle.status === "published" ? "published" : "draft",
+            currentMetadata: (bundle.metadata ?? {}),
+        });
+        if (!plan.changed) {
+            continue;
+        }
+        writes.push({
+            product_id: bundle.id,
+            status: plan.status,
+            metadata: plan.metadata,
+            missing: memberIds.filter((id) => {
+                const status = input.variantsById.get(id)?.metadata?.printful_availability_status;
+                return typeof status === "string" && UNAVAILABLE.has(status);
+            }),
+        });
+    }
+    return writes;
+}
+/**
+ * Whether a bundle should be published, from the stock of its members.
+ *
+ * Reuses `resolvePublication` so a bundle obeys the same ownership rule as
+ * every other product: the plugin undoes only unpublishes it performed, and a
+ * draft the merchant made themselves is left alone however available Printful
+ * says the members are.
+ *
+ * What differs is the threshold. `planStockActions` drafts a product only when
+ * *every* variant is gone, because any remaining variant is still sellable. A
+ * bundle is a promise to ship all of it, so one missing member already breaks
+ * the promise.
+ *
+ * A bundle with no members recorded is left untouched — that is a bundle the
+ * merchant has not finished configuring, not one that sold out.
+ */
+function planBundlePublication(input) {
+    const availability = planBundleAvailability(input.members.map((m) => m?.metadata ?? {}));
+    // One missing member is enough. A bundle with no members recorded has no
+    // unavailable ones either, so it falls through as available — an
+    // unconfigured bundle is not a sold-out one.
+    const allUnavailable = availability.unavailableCount > 0;
+    return (0, stock_1.resolvePublication)({
+        plan: {
+            allUnavailable,
+            status: allUnavailable ? "draft" : "published",
+            hasDiscontinued: false,
+            variantAvailability: {},
+        },
+        currentStatus: input.currentStatus,
+        currentMetadata: input.currentMetadata,
+    });
+}
+/**
+ * Whether a bundle can be sold, from the availability of its members.
+ *
+ * A bundle is a promise to ship all of it, so one sold-out member makes the
+ * promise unkeepable however available the rest are.
+ *
+ * Reads `printful_availability_status`, which the sync already writes — no new
+ * source of truth, and no second place to keep in step with Printful.
+ *
+ * An unknown status counts as available, matching `planStockActions`: the
+ * unavailable set is a closed list, and a bundle must not be stricter about a
+ * status than the member product itself is.
+ */
+function planBundleAvailability(members) {
+    let unavailable = 0;
+    for (const member of members) {
+        const status = member?.printful_availability_status;
+        if (typeof status === "string" && UNAVAILABLE.has(status)) {
+            unavailable += 1;
+        }
+    }
+    return {
+        // An empty bundle is unavailable rather than vacuously available: there is
+        // nothing to ship, which is not the same as everything being in stock.
+        available: members.length > 0 && unavailable === 0,
+        memberCount: members.length,
+        unavailableCount: unavailable,
+    };
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYnVuZGxlLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vLi4vc3JjL3V0aWxzL2J1bmRsZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiO0FBQUE7Ozs7Ozs7Ozs7OztHQVlHOzs7QUE4Q0gsMENBeUJDO0FBVUQsb0NBSUM7QUFZRCw0Q0E2QkM7QUFtQkQsMENBR0M7QUFtQ0Qsd0NBdURDO0FBd0JELHNEQXdCQztBQWVELHdEQW1CQztBQTlURCxtQ0FBb0U7QUFFcEUsd0VBQXdFO0FBQ3hFLE1BQU0sV0FBVyxHQUFHLElBQUksR0FBRyxDQUFDO0lBQzFCLGNBQWM7SUFDZCx3QkFBd0I7SUFDeEIsY0FBYztDQUNmLENBQUMsQ0FBQTtBQUVGLGdGQUFnRjtBQUNuRSxRQUFBLGtCQUFrQixHQUFHLHlCQUF5QixDQUFBO0FBNEIzRDs7Ozs7R0FLRztBQUNILFNBQWdCLGVBQWUsQ0FDN0IsSUFBNEM7SUFFNUMsTUFBTSxHQUFHLEdBQUcsQ0FBQyxJQUFJLEVBQUUsUUFBUSxJQUFJLEVBQUUsQ0FBQyxDQUFDLDBCQUFrQixDQUFDLENBQUE7SUFDdEQsSUFBSSxDQUFDLEtBQUssQ0FBQyxPQUFPLENBQUMsR0FBRyxDQUFDLEVBQUUsQ0FBQztRQUN4QixPQUFPLEVBQUUsQ0FBQTtJQUNYLENBQUM7SUFFRCxNQUFNLE9BQU8sR0FBbUIsRUFBRSxDQUFBO0lBQ2xDLEtBQUssTUFBTSxLQUFLLElBQUksR0FBRyxFQUFFLENBQUM7UUFDeEIsSUFBSSxDQUFDLEtBQUssSUFBSSxPQUFPLEtBQUssS0FBSyxRQUFRLEVBQUUsQ0FBQztZQUN4QyxTQUFRO1FBQ1YsQ0FBQztRQUNELE1BQU0sU0FBUyxHQUFJLEtBQXNCLENBQUMsVUFBVSxDQUFBO1FBQ3BELElBQUksT0FBTyxTQUFTLEtBQUssUUFBUSxJQUFJLENBQUMsU0FBUyxDQUFDLElBQUksRUFBRSxFQUFFLENBQUM7WUFDdkQsU0FBUTtRQUNWLENBQUM7UUFDRCxNQUFNLFFBQVEsR0FBRyxNQUFN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