@sixtyninecommerce/admin 0.8.0 → 0.10.0

package/dist/orders/get.js

@@ -0,0 +1,530 @@
+/**
+ * `admin.orders.get(orderId)`: one order, typed (headless spec §9.2 `orders`
+ * "read", plan W9-9).
+ *
+ * The read has two layers. The CORE is what the engine itself serves for an
+ * order, and it is all a call without `include` asks for. Around it sit the
+ * blocks a plugin adds to an order (payment terms, delivery terms, the order's
+ * own price list, the ERP and carrier references). Each is asked for by name
+ * in `include`, so a caller reads only what it uses, and the core document
+ * names no field an engine without that plugin lacks.
+ *
+ * Money is an integer in minor units of the order's currency, with three
+ * exceptions that are NOT converted to it: a line's `productVariant.price` and
+ * `priceWithTax` (the catalogue price in the currency of the request, which is
+ * the store's default unless the call names another), and a line's
+ * `customFields.cost` (the store's default currency). An instant is an ISO-8601
+ * string with its offset.
+ */
+import { ValidationError } from '@sixtyninecommerce/core';
+import { redactionWatcher } from '../customer-data-redaction.js';
+/**
+ * The blocks a plugin adds to an order, in the order the document lists them.
+ *
+ * - `paymentTerms`: the payment terms the order was placed under, and the
+ *   order's own override of them (the B2B credit plugin).
+ * - `deliveryTerms`: the delivery terms accepted at placement (the shipping
+ *   calculator plugin).
+ * - `priceList`: the order's own price list, which is its one-time pricing
+ *   (the price-list plugin).
+ * - `lineAllocations`: each line's raw allocation rows (the stock-transfer
+ *   plugin). They never decrement: `OrderLine.outstandingAllocations` is what a
+ *   line reserves now, and needs no include.
+ * - `fulfillmentDetails`: each fulfillment's handler (code, name, its detail
+ *   rows) and packing slips (the order-documents plugin).
+ * - `vatValidation`: the customer's VAT number and its validation status (the
+ *   VAT-validation plugin).
+ * - `afas`, `parasut`: the references those ERP plugins keep on the order, its
+ *   customer and the customer's addresses.
+ * - `myparcel`: the MyParcel shipment and label state on each fulfillment.
+ */
+export const ORDER_INCLUDES = [
+    'paymentTerms',
+    'deliveryTerms',
+    'priceList',
+    'lineAllocations',
+    'fulfillmentDetails',
+    'vatValidation',
+    'afas',
+    'parasut',
+    'myparcel',
+];
+/**
+ * The order document with EVERY block, written out whole.
+ *
+ * One static literal on purpose. The repository's GraphQL cost guard
+ * (`services/vendure/src/rate-limit/__tests__/graphql-cost-fits-repo.spec.ts`)
+ * measures every document this package holds against the engine's caps, and it
+ * can only read a literal. This is the largest operation the dashboard sends,
+ * so it has to be the one that is measured: do not assemble it at run time.
+ *
+ * A block's fields sit between a `#[name` line and its `#]` line. Both are
+ * GraphQL comments, so the literal parses as it stands. `orderQuery` keeps a
+ * marked part when the call included the block, drops it otherwise, and drops
+ * the marker lines either way. `#[a|b` marks a part that is kept when ANY of
+ * the named blocks is included: an object whose every field belongs to a block
+ * (an empty selection is not valid GraphQL).
+ */
+export const ORDER_QUERY_EVERY_BLOCK = /* GraphQL */ `
+  query Order($id: ID!) {
+    order(id: $id) {
+      id
+      code
+      state
+      active
+      total
+      totalWithTax
+      subTotal
+      subTotalWithTax
+      shipping
+      shippingWithTax
+      currencyCode
+      orderPlacedAt
+      #[paymentTerms
+      paymentTerms {
+        source
+        managedExternally
+        status
+        conditionCode
+        conditionDescription
+        summary
+        classification
+        paymentDays
+        paymentEndOfMonths
+        paymentMethod
+        percentage
+        discountPaymentDays
+        discountPercentage
+        paymentDiscountType
+        stale
+        syncedAt
+        error
+        resolvedAt
+        remoteConditionCode
+        remoteConfirmedAt
+        remoteMismatch
+      }
+      #]
+      #[deliveryTerms
+      deliveryTerms {
+        source
+        sourceScope
+        governingCustomerId
+        sourceCustomerId
+        managedExternally
+        status
+        shippingMethodStatus
+        policyStatus
+        summary
+        selectionSource
+        selectedShippingMethodId
+        selectedShippingMethodCode
+        selectedShippingMethodName
+        platformShippingMethodCode
+        platformShippingMethodName
+        platformShippingMethodDescription
+        platformShippingPrice
+        platformShippingPriceWithTax
+        preferredShippingMethodId
+        incotermStatus
+        incotermCode
+        incotermVersion
+        incotermAddress
+        incotermDescription
+        shippingLeadDays
+        deliveryAdvice
+        stale
+        syncedAt
+        warning
+        resolvedAt
+        remoteShippingMethodCode
+        remoteShippingMethodName
+        remoteIncotermCode
+        remoteIncotermVersion
+        remoteIncotermAddress
+        remoteDeliveryDate
+        remoteConfirmedAt
+        remoteMismatch
+      }
+      #]
+      couponCodes
+      customer {
+        id
+        firstName
+        lastName
+        emailAddress
+        phoneNumber
+        #[vatValidation|afas|parasut
+        customFields {
+          #[vatValidation
+          vatNumber
+          vatValidationStatus
+          #]
+          #[afas
+          afasVrId
+          afasOrgId
+          afasContactId
+          afasPersId
+          #]
+          #[parasut
+          parasutContactId
+          #]
+        }
+        #]
+        addresses {
+          id
+          fullName
+          company
+          streetLine1
+          streetLine2
+          city
+          postalCode
+          country {
+            code
+          }
+          defaultShippingAddress
+          defaultBillingAddress
+          #[afas
+          customFields {
+            afasAddressId
+          }
+          #]
+        }
+      }
+      lines {
+        id
+        quantity
+        unitPrice
+        unitPriceWithTax
+        listPriceIncludesTax
+        discountedUnitPrice
+        discountedUnitPriceWithTax
+        linePrice
+        linePriceWithTax
+        discountedLinePrice
+        discountedLinePriceWithTax
+        proratedLinePrice
+        proratedLinePriceWithTax
+        taxRate
+        productVariant {
+          id
+          name
+          sku
+          price
+          priceWithTax
+          stockOnHand
+          stockAllocated
+          trackInventory
+          outOfStockThreshold
+          useGlobalOutOfStockThreshold
+          stockLevels {
+            stockLocationId
+            stockOnHand
+            stockAllocated
+            stockLocation {
+              id
+              name
+            }
+          }
+          product {
+            id
+            name
+            featuredAsset {
+              id
+              preview
+            }
+          }
+        }
+        featuredAsset {
+          id
+          preview
+        }
+        #[lineAllocations
+        allocations {
+          id
+          stockLocation {
+            id
+            name
+          }
+          quantity
+        }
+        #]
+        outstandingAllocatedQuantity
+        outstandingAllocations {
+          stockLocationId
+          stockLocationName
+          quantity
+        }
+        customFields {
+          unitPriceOverride
+          priceOverrideReason
+          unitPriceImported
+          priceListId
+          priceListName
+          retailPrice
+          priceListPrice
+          priceListDiscountType
+          priceListDiscountValue
+          priceListDiscountChain
+          cost
+          preferredStockLocationId
+          backorderedQuantity
+        }
+      }
+      surcharges {
+        id
+        description
+        sku
+        price
+        priceWithTax
+        taxRate
+      }
+      discounts {
+        description
+        amount
+        amountWithTax
+      }
+      shippingLines {
+        shippingMethod {
+          id
+          name
+        }
+      }
+      payments {
+        id
+        state
+        method
+        amount
+        transactionId
+        createdAt
+        refunds {
+          id
+          state
+          total
+          reason
+        }
+      }
+      fulfillments {
+        id
+        state
+        nextStates
+        method
+        trackingCode
+        lines {
+          orderLineId
+          quantity
+        }
+        #[fulfillmentDetails
+        handlerCode
+        handlerName
+        handlerDetails {
+          label
+          value
+        }
+        packingSlips {
+          id
+          packingSlipNumber
+          fulfillmentId
+          languageCode
+          storageKey
+          createdAt
+        }
+        #]
+        stockLocationName
+        linkedOrders {
+          id
+          code
+        }
+        customFields {
+          #[myparcel
+          myparcelShipmentId
+          myparcelLabelStatus
+          myparcelLabelFormat
+          myparcelLabelUrlA4
+          myparcelLabelUrlA6
+          myparcelLabelLastError
+          myparcelLabelHandoff
+          #]
+          bookingStatus
+        }
+        createdAt
+      }
+      shippingAddress {
+        fullName
+        company
+        streetLine1
+        streetLine2
+        city
+        province
+        postalCode
+        country
+        countryCode
+        phoneNumber
+      }
+      billingAddress {
+        fullName
+        company
+        streetLine1
+        streetLine2
+        city
+        province
+        postalCode
+        country
+        countryCode
+        phoneNumber
+      }
+      history(options: { take: 50, sort: { createdAt: DESC } }) {
+        items {
+          id
+          type
+          data
+          createdAt
+          isPublic
+          administrator {
+            id
+            firstName
+            lastName
+          }
+        }
+      }
+      taxSummary {
+        description
+        taxRate
+        taxBase
+        taxTotal
+      }
+      nextStates
+      createdAt
+      updatedAt
+      customFields {
+        isLocked
+        externalOrderId
+        externalPlatform
+        sourceFulfillmentHandedOff
+        originalPlacedAt
+        sourceWarehouse
+        pickupLocation
+        allocationExpiresAt
+        goodwillRoundingMinor
+        removeTax
+        isGift
+        giftNote
+        hidePricesOnPackingSlip
+        poNumber
+        requestedDeliveryDate
+        orderNotes
+        customerShippingAddressId
+        customerBillingAddressId
+        shippingAddressIsTemporary
+        billingAddressIsTemporary
+        paymentStatus
+        fulfillmentStatus
+        returnStatus
+        lifecycleStatus
+        #[paymentTerms
+        paymentTermsDays
+        paymentConditionCode
+        #]
+        #[afas
+        afasSalesOrderId
+        afasDirectInvoiceOrNu
+        afasInvoiceNumber
+        afasInvoiceDate
+        afasLocked
+        afasLockReason
+        afasLastSyncAt
+        #]
+        #[parasut
+        parasutInvoiceId
+        parasutEInvoiceStatus
+        parasutEInvoiceUuid
+        parasutLastError
+        #]
+      }
+      fulfillmentHold {
+        reason
+        note
+        heldAt
+        heldByUserId
+        heldBy
+      }
+      #[priceList
+      priceList {
+        id
+        name
+        description
+        defaultDiscountBps
+        defaultDiscountAmount
+        entries {
+          id
+          variantId
+          discountType
+          discountValue
+        }
+      }
+      #]
+    }
+  }
+`;
+const BLOCK_OPEN = '#[';
+const BLOCK_CLOSE = '#]';
+/**
+ * The document `get` sends for a set of blocks: {@link ORDER_QUERY_EVERY_BLOCK}
+ * without the blocks the call did not include, and without the marker lines.
+ * It depends on the SET only, never on the order the caller listed them in, so
+ * one set is one document.
+ */
+export function orderQuery(include = []) {
+    const asked = new Set(include);
+    const kept = [];
+    // One entry per marked part that is open: whether its lines are kept. A part
+    // inside a dropped part is dropped whatever it names.
+    const open = [];
+    for (const line of ORDER_QUERY_EVERY_BLOCK.split('\n')) {
+        const text = line.trim();
+        const outerKept = open.at(-1) ?? true;
+        if (text.startsWith(BLOCK_OPEN)) {
+            const names = text.slice(BLOCK_OPEN.length).split('|');
+            open.push(outerKept && names.some((name) => asked.has(name)));
+        }
+        else if (text === BLOCK_CLOSE) {
+            open.pop();
+        }
+        else if (outerKept) {
+            kept.push(line);
+        }
+    }
+    return kept.join('\n');
+}
+export function createOrderGetModule(transport) {
+    async function get(orderId, options) {
+        // Typed callers cannot get here wrong. A JavaScript caller can, and an
+        // unknown name would otherwise be dropped in silence: the read would
+        // answer an order without the block the caller believes it asked for.
+        const include = options?.include ?? [];
+        const known = (name) => ORDER_INCLUDES.includes(name);
+        if (!Array.isArray(include) || !include.every(known)) {
+            const given = Array.isArray(include)
+                ? include.filter((name) => !known(name)).map((name) => `"${String(name)}"`)
+                : [String(include)];
+            throw new ValidationError({
+                code: 'INVALID_ORDER_INCLUDE',
+                message: `\`include\` takes a list of an order's blocks, and ${given.join(', ')} is not one. The blocks are: ${ORDER_INCLUDES.join(', ')}.`,
+                status: 400,
+                service: 'vendure',
+            });
+        }
+        const redaction = redactionWatcher();
+        const data = await transport.graphql({
+            api: 'admin',
+            query: orderQuery(include),
+            variables: { id: orderId },
+            onExtensions: redaction.onExtensions,
+        }, options);
+        return redaction.mark(data.order);
+    }
+    // The answer holds exactly the blocks asked for; `OrderGetAnswer` decides how
+    // many of them the caller's type of the options may rely on. The overloads
+    // narrow this one implementation, which TypeScript cannot check for them.
+    return { get: get };
+}