@sixtyninecommerce/admin 0.10.0 → 0.12.0

package/dist/fulfillments/index.js

@@ -1,4 +1,9 @@
-import { errorFromErrorResult, isErrorResult, NotFoundError, ValidationError, } from '@sixtyninecommerce/core';
+import { errorForStatus, errorFromErrorResult, errorFromGraphQLErrors, isErrorResult, NotFoundError, ValidationError, } from '@sixtyninecommerce/core';
+import { customerAgreedVariable, statedCustomerAgreed } from '../payments/customer-consent.js';
+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`. */
@@ -6,6 +11,7 @@ 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
@@ -48,10 +54,39 @@ export const CANCEL_FULFILLMENT_MUTATION = /* GraphQL */ `
         amount
         currencyCode
         choice
+        book
       }
     }
   }
 `;
+/**
+ * The refusal member is selected for its facts: `message` is core's per-code template ("Cannot
+ * transition Fulfillment from X to Y"), and the refusing step's reason is `transitionError` alone.
+ */
+export const TRANSITION_FULFILLMENT_MUTATION = /* GraphQL */ `
+  mutation TransitionFulfillment($id: ID!, $state: String!) {
+    transitionFulfillmentToState(id: $id, state: $state) {
+      __typename
+      ... on Fulfillment {
+        id
+        state
+        nextStates
+      }
+      ... on FulfillmentStateTransitionError {
+        errorCode
+        message
+        fromState
+        toState
+        transitionError
+      }
+    }
+  }
+`;
+export const RESEND_FULFILLMENT_LABEL_HANDOFF_MUTATION = /* GraphQL */ `
+  mutation ResendFulfillmentLabelHandoff($fulfillmentId: ID!) {
+    resendFulfillmentLabelHandoff(fulfillmentId: $fulfillmentId)
+  }
+`;
 /** Every field of `OrderFulfillmentCoverageOverride`. */
 const COVERAGE_OVERRIDE_FIELDS = /* GraphQL */ `
   id
@@ -154,15 +189,27 @@ function assertCancelRequest(fulfillmentId, input) {
         if (!OVERPAYMENT_CHOICES.has(entry.choice)) {
             throw invalidCancel(`overpayment[${String(index)}].choice`, `The choice for order ${orderId} must be REFUND or ACCOUNT_CREDIT; got ${JSON.stringify(entry.choice)}.`);
         }
+        if (entry.customerAgreed != null &&
+            customerAgreedVariable(entry.customerAgreed) === undefined) {
+            throw invalidCancel(`overpayment[${String(index)}].customerAgreed`, `The customer's answer for order ${orderId} must be true or false; got ${JSON.stringify(entry.customerAgreed)}.`);
+        }
         if (seen.has(orderId)) {
             throw invalidCancel(`overpayment[${String(index)}].orderId`, `Order ${orderId} is named twice: give one choice per order.`);
         }
         seen.add(orderId);
     }
 }
-/** An option as the SDK types it: `code` and `message` are null when it is open. */
+/**
+ * An option as the SDK types it: `code` and `message` are null when it is open; `book` (the
+ * account credit's, incentives sprint 8) null on the refund and from an engine before it.
+ */
 function toOption(raw) {
-    return { available: raw.available, code: raw.code ?? null, message: raw.message ?? null };
+    return {
+        available: raw.available,
+        code: raw.code ?? null,
+        message: raw.message ?? null,
+        book: raw.book ?? null,
+    };
 }
 export const REPORT_APP_FULFILLMENT_MUTATION = /* GraphQL */ `
   mutation ReportAppFulfillment(
@@ -358,8 +405,55 @@ function assertLabelRequest(fulfillmentId, format) {
         throw invalidLabelRequest('format', `format must be 'A4' or 'A6', or left out to label every parcel still missing one; got ${JSON.stringify(format)}.`);
     }
 }
+function invalidTransition(field, message) {
+    return new ValidationError({
+        code: 'FULFILLMENT_TRANSITION_INVALID',
+        message,
+        status: 400,
+        service: 'vendure',
+        details: [{ field, code: 'FULFILLMENT_TRANSITION_INVALID', message }],
+    });
+}
+/** The `[CODE]` a step of the fulfillment process prefixes its refusal text with. */
+const STEP_CODE = /^\s*\[([A-Z][A-Z0-9_]*)\]\s*/;
+/**
+ * A refused move as the coded error it is. Core carries a step's refusal only as text, so the
+ * step's own code is read off its `[CODE]` prefix and classed through the GraphQL dialect, as the
+ * warehouse API's refusals of the same codes are (`warehouseRefusalError`): one code, one class,
+ * whichever door answered it.
+ */
+export function fulfillmentTransitionRefusal(result) {
+    const text = typeof result.transitionError === 'string' ? result.transitionError.trim() : '';
+    const facts = {
+        errorCode: result.errorCode,
+        fromState: result.fromState ?? '',
+        toState: result.toState ?? '',
+        transitionError: text,
+    };
+    const step = STEP_CODE.exec(text);
+    const sentence = step ? text.slice(step[0].length).trim() : text;
+    // Core's `message` is a per-code template, untranslated on some engines
+    // ("errorResult.FULFILLMENT_STATE_TRANSITION_ERROR"): said only when the move is unknown too.
+    const message = sentence ||
+        (facts.fromState && facts.toState
+            ? `The fulfillment cannot move from ${facts.fromState} to ${facts.toState}.`
+            : result.message);
+    if (step?.[1]) {
+        return errorFromGraphQLErrors([{ message, extensions: { ...facts, code: step[1] } }]);
+    }
+    const base = errorFromErrorResult({ errorCode: result.errorCode, message });
+    return errorForStatus(base.status, {
+        code: base.code,
+        message,
+        service: 'vendure',
+        extensions: { ...facts },
+    });
+}
 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)
@@ -442,7 +536,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,
@@ -459,14 +553,21 @@ 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.
                 variables: {
                     fulfillmentId,
                     ...(overpayment.length > 0
-                        ? { overpayment: overpayment.map(({ orderId, choice }) => ({ orderId, choice })) }
+                        ? {
+                            overpayment: overpayment.map(({ orderId, choice, customerAgreed }) => ({
+                                orderId,
+                                choice,
+                                // Named only when stated: an engine before the field takes the rest.
+                                ...statedCustomerAgreed(customerAgreed),
+                            })),
+                        }
                         : {}),
                     ...(options?.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
                 },
@@ -480,6 +581,7 @@ export function createFulfillmentsModule(transport) {
                     amount: entry.amount,
                     currencyCode: entry.currencyCode,
                     choice: entry.choice,
+                    book: entry.book ?? null,
                 })),
             };
         },
@@ -515,6 +617,33 @@ export function createFulfillmentsModule(transport) {
             }, options);
             return toCoverageOverride(data.allowUncoveredFulfillment);
         },
+        async transition(fulfillmentId, state, options) {
+            if (typeof fulfillmentId !== 'string' || fulfillmentId.trim() === '') {
+                throw invalidTransition('fulfillmentId', 'A fulfillment id is required.');
+            }
+            if (typeof state !== 'string' || state.trim() === '') {
+                throw invalidTransition('state', 'Name the state to move the fulfillment to.');
+            }
+            const data = await transport.graphql({
+                api: 'admin',
+                query: TRANSITION_FULFILLMENT_MUTATION,
+                variables: { id: fulfillmentId, state },
+            }, options);
+            const result = data.transitionFulfillmentToState;
+            if (isErrorResult(result))
+                throw fulfillmentTransitionRefusal(result);
+            const moved = result;
+            return { id: moved.id, state: moved.state, nextStates: [...(moved.nextStates ?? [])] };
+        },
+        async resendLabelHandoff(fulfillmentId, options) {
+            assertLabelRequest(fulfillmentId, undefined);
+            const data = await transport.graphql({
+                api: 'admin',
+                query: RESEND_FULFILLMENT_LABEL_HANDOFF_MUTATION,
+                variables: { fulfillmentId },
+            }, options);
+            return data.resendFulfillmentLabelHandoff;
+        },
         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);
+        },
+    };
+}