@sixtyninecommerce/admin 0.9.0 → 0.11.0

package/dist/fulfillments/index.js

@@ -1,9 +1,16 @@
 import { errorFromErrorResult, isErrorResult, NotFoundError, ValidationError, } from '@sixtyninecommerce/core';
+import { storeCreditAware } from '../payments/store-credit-fields.js';
+import { createFulfillmentCreateMethods } from './create.js';
+import { createFulfillmentPaymentPolicyModule, } from './payment-policy.js';
+import { createWarehouseFulfillmentsModule, } from './warehouse.js';
+/** The longest override reason the engine stores. */
+export const FULFILLMENT_COVERAGE_REASON_MAX_LENGTH = 500;
 /** Every field of `OrderOverpaymentOption`. */
 const OVERPAYMENT_OPTION_FIELDS = /* GraphQL */ `
   available
   code
   message
+  book
 `;
 /**
  * Its own document, like every call here: on an engine without the query this call alone fails
@@ -46,10 +53,86 @@ export const CANCEL_FULFILLMENT_MUTATION = /* GraphQL */ `
         amount
         currencyCode
         choice
+        book
       }
     }
   }
 `;
+/** Every field of `OrderFulfillmentCoverageOverride`. */
+const COVERAGE_OVERRIDE_FIELDS = /* GraphQL */ `
+  id
+  orderId
+  reason
+  actorKind
+  actorId
+  outstandingAtGrant
+  currencyCode
+  createdAt
+  active
+`;
+/** Its own document: on an engine without the query this call alone fails validation. */
+export const ORDER_FULFILLMENT_COVERAGE_QUERY = /* GraphQL */ `
+  query OrderFulfillmentCoverage($orderId: ID!) {
+    orderFulfillmentCoverage(orderId: $orderId) {
+      orderId
+      orderCode
+      currencyCode
+      policyActive
+      covered
+      outstanding
+      exempt
+      exemptReason
+      allowed
+      override { ${COVERAGE_OVERRIDE_FIELDS} }
+    }
+  }
+`;
+/** `$idempotencyKey` is optional and left out of the variables when not given. */
+export const ALLOW_UNCOVERED_FULFILLMENT_MUTATION = /* GraphQL */ `
+  mutation AllowUncoveredFulfillment($orderId: ID!, $reason: String!, $idempotencyKey: String) {
+    allowUncoveredFulfillment(orderId: $orderId, reason: $reason, idempotencyKey: $idempotencyKey) {
+      ${COVERAGE_OVERRIDE_FIELDS}
+    }
+  }
+`;
+function invalidCoverage(field, message) {
+    return new ValidationError({
+        code: 'FULFILLMENT_COVERAGE_OVERRIDE_INVALID',
+        message,
+        status: 400,
+        service: 'vendure',
+        details: [{ field, code: 'FULFILLMENT_COVERAGE_OVERRIDE_INVALID', message }],
+    });
+}
+function assertOrderId(orderId) {
+    if (typeof orderId !== 'string' || orderId.trim() === '') {
+        throw invalidCoverage('orderId', 'An order id is required.');
+    }
+}
+/** Refused before any request: the engine would refuse it the same way. */
+function assertOverrideReason(reason) {
+    const text = typeof reason === 'string' ? reason.trim() : '';
+    if (text === '') {
+        throw invalidCoverage('reason', 'Say why this order may be handed over before it is paid: a reason is required.');
+    }
+    if (text.length > FULFILLMENT_COVERAGE_REASON_MAX_LENGTH) {
+        throw invalidCoverage('reason', `The reason is at most ${FULFILLMENT_COVERAGE_REASON_MAX_LENGTH} characters.`);
+    }
+    return text;
+}
+function toCoverageOverride(raw) {
+    return {
+        id: raw.id,
+        orderId: raw.orderId,
+        reason: raw.reason,
+        actorKind: raw.actorKind,
+        actorId: raw.actorId,
+        outstandingAtGrant: raw.outstandingAtGrant,
+        currencyCode: raw.currencyCode,
+        createdAt: raw.createdAt,
+        active: raw.active,
+    };
+}
 const OVERPAYMENT_CHOICES = new Set([
     'REFUND',
     'ACCOUNT_CREDIT',
@@ -283,6 +366,9 @@ function assertLabelRequest(fulfillmentId, format) {
 }
 export function createFulfillmentsModule(transport) {
     return {
+        ...createFulfillmentCreateMethods(transport),
+        paymentPolicy: createFulfillmentPaymentPolicyModule(transport),
+        warehouse: createWarehouseFulfillmentsModule(transport),
         async parcelsOfOrder(orderId, options) {
             const data = await transport.graphql({ api: 'admin', query: ORDER_FULFILLMENT_PARCELS_QUERY, variables: { id: orderId } }, options);
             if (!data.order)
@@ -365,7 +451,7 @@ export function createFulfillmentsModule(transport) {
             if (typeof fulfillmentId !== 'string' || fulfillmentId.trim() === '') {
                 throw invalidCancel('fulfillmentId', 'A fulfillment id is required.');
             }
-            const data = await transport.graphql({ api: 'admin', query: FULFILLMENT_CANCEL_PREVIEW_QUERY, variables: { fulfillmentId } }, options);
+            const data = await storeCreditAware(transport).graphql({ api: 'admin', query: FULFILLMENT_CANCEL_PREVIEW_QUERY, variables: { fulfillmentId } }, options);
             const preview = data.fulfillmentCancelPreview;
             return {
                 fulfillmentId: preview.fulfillmentId,
@@ -382,7 +468,7 @@ export function createFulfillmentsModule(transport) {
         async cancel(fulfillmentId, input = {}, options) {
             assertCancelRequest(fulfillmentId, input);
             const overpayment = input.overpayment ?? [];
-            const data = await transport.graphql({
+            const data = await storeCreditAware(transport).graphql({
                 api: 'admin',
                 query: CANCEL_FULFILLMENT_MUTATION,
                 // A variable, not a header: the Admin API takes the key as an argument.
@@ -406,6 +492,38 @@ export function createFulfillmentsModule(transport) {
                 })),
             };
         },
+        async coverage(orderId, options) {
+            assertOrderId(orderId);
+            const data = await transport.graphql({ api: 'admin', query: ORDER_FULFILLMENT_COVERAGE_QUERY, variables: { orderId } }, options);
+            const coverage = data.orderFulfillmentCoverage;
+            return {
+                orderId: coverage.orderId,
+                orderCode: coverage.orderCode,
+                currencyCode: coverage.currencyCode,
+                policyActive: coverage.policyActive,
+                covered: coverage.covered,
+                outstanding: coverage.outstanding,
+                exempt: coverage.exempt,
+                exemptReason: coverage.exemptReason ?? null,
+                allowed: coverage.allowed,
+                override: coverage.override ? toCoverageOverride(coverage.override) : null,
+            };
+        },
+        async allowUncovered(orderId, reason, options) {
+            assertOrderId(orderId);
+            const text = assertOverrideReason(reason);
+            const data = await transport.graphql({
+                api: 'admin',
+                query: ALLOW_UNCOVERED_FULFILLMENT_MUTATION,
+                // A variable, not a header: the Admin API takes the key as an argument.
+                variables: {
+                    orderId,
+                    reason: text,
+                    ...(options?.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+                },
+            }, options);
+            return toCoverageOverride(data.allowUncoveredFulfillment);
+        },
         async reportAppFulfillment(fulfillmentId, input, options) {
             const data = await transport.graphql({
                 api: 'admin',

package/dist/fulfillments/payment-policy.d.ts

@@ -0,0 +1,64 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/** The most payment method codes `exemptMethodCodes` may name. */
+export declare const FULFILLMENT_PAYMENT_POLICY_EXEMPT_METHODS_MAX = 50;
+/** The longest payment method code the list accepts (`PaymentMethod.code` is a varchar(255)). */
+export declare const FULFILLMENT_PAYMENT_POLICY_METHOD_CODE_MAX_LENGTH = 255;
+/**
+ * The store's fulfilment payment policy (`Channel.customFields.fulfillmentPaymentPolicy`):
+ * whether goods are handed over before an order is paid in full. Every field present: this is
+ * what the engine APPLIES, absent and malformed fields read as their defaults (OFF).
+ */
+export interface FulfillmentPaymentPolicy {
+    /**
+     * On: a fulfilment is created, extended or shipped only once the money COLLECTED for the
+     * order (settled, or held by a payment provider) covers what it bills, unless the order is
+     * exempt or an override was recorded (`fulfillments.allowUncovered`). Otherwise refused
+     * `ORDER_NOT_COVERED`.
+     */
+    requireFullPayment: boolean;
+    /**
+     * Payment method CODES whose orders are handed over unpaid as a matter of course (cash on
+     * delivery, a bank transfer the store ships against), judged on the order's latest live
+     * payment. Read as the engine compares them: trimmed, lower-cased, once each.
+     */
+    exemptMethodCodes: string[];
+}
+/** The policy of a store that never set one, and of a column that cannot be read: off. */
+export declare const DEFAULT_FULFILLMENT_PAYMENT_POLICY: Readonly<FulfillmentPaymentPolicy>;
+/**
+ * The ACTIVE store's fulfilment payment policy (`admin.fulfillments.paymentPolicy`), stored as a
+ * Channel custom field and written through core `updateChannel`.
+ *
+ * Reading needs an authenticated administrator on the store; writing needs `UpdateChannel`.
+ */
+export interface FulfillmentPaymentPolicyModule {
+    /**
+     * The policy the engine applies, read as tolerantly as the engine reads it
+     * (`resolveFulfillmentPaymentPolicy`): a store that never set one, a malformed column and a
+     * field of the wrong type all answer OFF ({@link DEFAULT_FULFILLMENT_PAYMENT_POLICY}); the
+     * exempt codes are the non-blank ones, trimmed, lower-cased and once each.
+     */
+    get(options?: Call): Promise<FulfillmentPaymentPolicy>;
+    /**
+     * Replace the whole policy, and answer it as the engine now applies it.
+     *
+     * Both fields are required: read it with {@link get}, change what you mean to, and send it
+     * back. Only the schema's fields are stored, the codes trimmed.
+     *
+     * Refused before any request with `FULFILLMENT_PAYMENT_POLICY_INVALID` ({@link ValidationError},
+     * one `details[]` entry per failing field): a non-boolean switch, an exempt list that is not a
+     * list, holds a blank or over-long code, names one code twice in any case, or more than 50.
+     * The engine's own write validator refuses the same values (a `ValidationError` too, carrying
+     * its sentence), so a value that slips past this check is still never stored.
+     *
+     * Absent and "set to the defaults" mean the same thing to the engine, and a store's column is
+     * never backfilled: write the policy when a merchant changed it.
+     */
+    set(policy: FulfillmentPaymentPolicy, options?: Call): Promise<FulfillmentPaymentPolicy>;
+}
+export declare const FULFILLMENT_PAYMENT_POLICY_QUERY = "\n  query FulfillmentPaymentPolicy {\n    activeChannel { \n  id\n  customFields {\n    fulfillmentPaymentPolicy\n  }\n }\n  }\n";
+export declare const SET_FULFILLMENT_PAYMENT_POLICY_MUTATION = "\n  mutation SetFulfillmentPaymentPolicy($input: UpdateChannelInput!) {\n    updateChannel(input: $input) {\n      ... on Channel { \n  id\n  customFields {\n    fulfillmentPaymentPolicy\n  }\n }\n      ... on ErrorResult { errorCode message }\n    }\n  }\n";
+/** A payment method code as the engine compares it (`normalizeMethodCode`). */
+export declare function normalizeFulfillmentPolicyMethodCode(code: string): string;
+export declare function createFulfillmentPaymentPolicyModule(transport: Transport): FulfillmentPaymentPolicyModule;

package/dist/fulfillments/payment-policy.js

@@ -0,0 +1,140 @@
+import { errorFromErrorResult, isErrorResult, ValidationError, } from '@sixtyninecommerce/core';
+// The bounds of the meta catalog's `fulfillment_payment_policy` schema
+// (`packages/shared/src/meta-catalog/settings-schemas.ts`), which the spec reads
+// back from that schema, and of the engine's write validator
+// (`validateFulfillmentPaymentPolicyValue`), which refuses the same values.
+/** The most payment method codes `exemptMethodCodes` may name. */
+export const FULFILLMENT_PAYMENT_POLICY_EXEMPT_METHODS_MAX = 50;
+/** The longest payment method code the list accepts (`PaymentMethod.code` is a varchar(255)). */
+export const FULFILLMENT_PAYMENT_POLICY_METHOD_CODE_MAX_LENGTH = 255;
+/** The policy of a store that never set one, and of a column that cannot be read: off. */
+export const DEFAULT_FULFILLMENT_PAYMENT_POLICY = Object.freeze({
+    requireFullPayment: false,
+    exemptMethodCodes: [],
+});
+const POLICY_FIELDS = /* GraphQL */ `
+  id
+  customFields {
+    fulfillmentPaymentPolicy
+  }
+`;
+export const FULFILLMENT_PAYMENT_POLICY_QUERY = /* GraphQL */ `
+  query FulfillmentPaymentPolicy {
+    activeChannel { ${POLICY_FIELDS} }
+  }
+`;
+export const SET_FULFILLMENT_PAYMENT_POLICY_MUTATION = /* GraphQL */ `
+  mutation SetFulfillmentPaymentPolicy($input: UpdateChannelInput!) {
+    updateChannel(input: $input) {
+      ... on Channel { ${POLICY_FIELDS} }
+      ... on ErrorResult { errorCode message }
+    }
+  }
+`;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** A payment method code as the engine compares it (`normalizeMethodCode`). */
+export function normalizeFulfillmentPolicyMethodCode(code) {
+    return code.trim().toLowerCase();
+}
+/** The column, read as the engine reads it: anything unreadable is OFF. */
+function readFulfillmentPaymentPolicy(raw) {
+    let parsed = raw;
+    if (typeof raw === 'string') {
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            parsed = null;
+        }
+    }
+    if (!isRecord(parsed))
+        return { requireFullPayment: false, exemptMethodCodes: [] };
+    const codes = Array.isArray(parsed.exemptMethodCodes)
+        ? [
+            ...new Set(parsed.exemptMethodCodes
+                .filter((code) => typeof code === 'string' && code.trim() !== '')
+                .map(normalizeFulfillmentPolicyMethodCode)),
+        ].slice(0, FULFILLMENT_PAYMENT_POLICY_EXEMPT_METHODS_MAX)
+        : [];
+    return { requireFullPayment: parsed.requireFullPayment === true, exemptMethodCodes: codes };
+}
+/** Every way `policy` breaks the schema, one entry per field. */
+function problemsOf(policy) {
+    const problems = [];
+    const add = (field, message) => problems.push({ field, code: 'FULFILLMENT_PAYMENT_POLICY_INVALID', message });
+    if (!isRecord(policy)) {
+        add('policy', 'Pass the whole policy as an object: read it with get(), change it, send it back.');
+        return problems;
+    }
+    if (typeof policy.requireFullPayment !== 'boolean') {
+        add('requireFullPayment', 'requireFullPayment must be true or false.');
+    }
+    const codes = policy.exemptMethodCodes;
+    if (!Array.isArray(codes)) {
+        add('exemptMethodCodes', 'exemptMethodCodes must be a list of payment method codes.');
+    }
+    else if (codes.some((code) => typeof code !== 'string' || code.trim() === '')) {
+        add('exemptMethodCodes', 'exemptMethodCodes may hold only non-blank payment method codes.');
+    }
+    else if (codes.some((code) => code.trim().length > FULFILLMENT_PAYMENT_POLICY_METHOD_CODE_MAX_LENGTH)) {
+        add('exemptMethodCodes', `A payment method code is at most ${String(FULFILLMENT_PAYMENT_POLICY_METHOD_CODE_MAX_LENGTH)} characters.`);
+    }
+    else if (new Set(codes.map((code) => normalizeFulfillmentPolicyMethodCode(code))).size !==
+        codes.length) {
+        add('exemptMethodCodes', 'exemptMethodCodes names a payment method code more than once (codes are compared ignoring case).');
+    }
+    else if (codes.length > FULFILLMENT_PAYMENT_POLICY_EXEMPT_METHODS_MAX) {
+        add('exemptMethodCodes', `exemptMethodCodes may name at most ${String(FULFILLMENT_PAYMENT_POLICY_EXEMPT_METHODS_MAX)} payment methods.`);
+    }
+    return problems;
+}
+/** Exactly the schema's fields, in its order, codes trimmed: what the column stores. */
+function storedOf(policy) {
+    return {
+        requireFullPayment: policy.requireFullPayment,
+        exemptMethodCodes: policy.exemptMethodCodes.map((code) => code.trim()),
+    };
+}
+export function createFulfillmentPaymentPolicyModule(transport) {
+    const read = async (options) => {
+        const data = await transport.graphql({ api: 'admin', query: FULFILLMENT_PAYMENT_POLICY_QUERY }, options);
+        return data.activeChannel;
+    };
+    return {
+        async get(options) {
+            const channel = await read(options);
+            return readFulfillmentPaymentPolicy(channel.customFields?.fulfillmentPaymentPolicy ?? null);
+        },
+        async set(policy, options) {
+            const problems = problemsOf(policy);
+            if (problems.length > 0) {
+                throw new ValidationError({
+                    code: 'FULFILLMENT_PAYMENT_POLICY_INVALID',
+                    message: problems.map((problem) => problem.message).join(' '),
+                    status: 400,
+                    service: 'vendure',
+                    details: problems,
+                });
+            }
+            // `updateChannel` needs the id, and the active channel is the one the client is scoped
+            // to: read it with the SAME call options, so a per-call tenant writes its own channel.
+            const { id } = await read(options);
+            const data = await transport.graphql({
+                api: 'admin',
+                query: SET_FULFILLMENT_PAYMENT_POLICY_MUTATION,
+                variables: {
+                    // The column is `text` holding JSON, so it is sent as a string.
+                    input: {
+                        id,
+                        customFields: { fulfillmentPaymentPolicy: JSON.stringify(storedOf(policy)) },
+                    },
+                },
+            }, options);
+            if (isErrorResult(data.updateChannel))
+                throw errorFromErrorResult(data.updateChannel);
+            return readFulfillmentPaymentPolicy(data.updateChannel.customFields?.fulfillmentPaymentPolicy ?? null);
+        },
+    };
+}