@sixtyninecommerce/admin 0.8.0 → 0.10.0

package/dist/returns/index.js

@@ -0,0 +1,160 @@
+/** A return's state: the latest row of its status log. */
+export const RETURN_STATES = [
+    'requested',
+    'approved',
+    'rejected',
+    'cancelled',
+    'items_received',
+    'settlement_pending',
+    'settlement_failed',
+    'settled',
+];
+/**
+ * How a return is settled. `refund` gives money back to an original payment.
+ * `store_credit` issues a credit note: on a store with an accounts-receivable
+ * ledger it credits the customer's account, elsewhere it credits the order's
+ * invoice and moves no money.
+ */
+export const RETURN_SETTLEMENT_METHODS = ['refund', 'store_credit'];
+/** Why a return cannot be settled now, in the order the engine checks them. */
+export const RETURN_SETTLEMENT_BLOCKERS = [
+    'OUTCOME_UNKNOWN',
+    'ALREADY_SETTLED',
+    'IN_PROGRESS',
+    'RECEIPT_REQUIRED',
+    'STATE',
+];
+/** The fields of an `OrderReturn` every read selects (a selection, spliced into each document). */
+const RETURN_FIELDS = /* GraphQL */ `
+    id
+    code
+    channelId
+    orderId
+    orderCode
+    customerId
+    currencyCode
+    state
+    initiator
+    customerNote
+    adminNote
+    preferredSettlementMethod
+    settlementMethod
+    shippingRefundAmount
+    settledAmount
+    refundId
+    creditNoteId
+    creditNoteNumber
+    requestedAt
+    resolvedAt
+    createdAt
+    updatedAt
+    lines {
+      id
+      returnId
+      orderLineId
+      productVariantId
+      productVariantName
+      productVariantSku
+      requestedQty
+      approvedQty
+      receivedQty
+      restockQty
+      writeOffQty
+      restockLocationId
+      reasonCode
+      reasonNote
+      unitPriceWithTax
+      unitPriceWithTaxUnrounded
+      refundAmount
+      createdAt
+      updatedAt
+    }
+`;
+export const RETURN_QUERY = /* GraphQL */ `
+  query SdkOrderReturn($id: ID!) {
+    orderReturn(id: $id) {
+      ${RETURN_FIELDS}
+      history {
+        state
+        actor
+        actorUserId
+        reason
+        createdAt
+      }
+    }
+  }
+`;
+export const RETURNS_FOR_ORDER_QUERY = /* GraphQL */ `
+  query SdkReturnsForOrder($orderId: ID!) {
+    returnsForOrder(orderId: $orderId) {
+      ${RETURN_FIELDS}
+    }
+  }
+`;
+export const RETURN_ELIGIBILITY_QUERY = /* GraphQL */ `
+  query SdkReturnEligibility($orderId: ID!) {
+    returnEligibilityForOrder(orderId: $orderId) {
+      orderId
+      eligible
+      reason
+      returnWindowEndsAt
+      lines {
+        orderLineId
+        productVariantId
+        productVariantName
+        productVariantSku
+        fulfilledQty
+        returnableQty
+        unitPriceWithTax
+        unitPriceWithTaxUnrounded
+      }
+    }
+  }
+`;
+export const RETURN_SETTLEMENT_OPTIONS_QUERY = /* GraphQL */ `
+  query SdkReturnSettlementOptions($returnId: ID!) {
+    returnSettlementOptions(returnId: $returnId) {
+      returnId
+      currencyCode
+      settleable
+      blockedBy
+      refund {
+        available
+        reasonCode
+        payments {
+          paymentId
+          method
+          refundable
+        }
+      }
+      creditNote {
+        available
+        ledger
+        reasonCode
+        invoiceNumber
+      }
+      initialMethod
+      defaultAmount
+    }
+  }
+`;
+export function createReturnsModule(transport) {
+    return {
+        async get(id, options) {
+            const data = await transport.graphql({ api: 'admin', query: RETURN_QUERY, variables: { id } }, options);
+            return data.orderReturn;
+        },
+        async forOrder(orderId, options) {
+            const data = await transport.graphql({ api: 'admin', query: RETURNS_FOR_ORDER_QUERY, variables: { orderId } }, options);
+            return data.returnsForOrder;
+        },
+        async eligibility(orderId, options) {
+            const data = await transport.graphql({ api: 'admin', query: RETURN_ELIGIBILITY_QUERY, variables: { orderId } }, options);
+            return data.returnEligibilityForOrder;
+        },
+        async settlementOptions(returnId, options) {
+            const data = await transport.graphql({ api: 'admin', query: RETURN_SETTLEMENT_OPTIONS_QUERY, variables: { returnId } }, options);
+            return data.returnSettlementOptions;
+        },
+    };
+}

package/dist/search/index.d.ts

@@ -0,0 +1,99 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/** What `admin.search.entities` searches. */
+export type SearchEntityType = 'PRODUCTS' | 'ORDERS' | 'CUSTOMERS' | 'CONTENT';
+/**
+ * Why a type was not searched. A string on the wire: a newer engine may add a reason, so read an
+ * unknown one as "not searched".
+ *
+ * - `PERMISSION`: the credential holds none of the type's read permissions in the store
+ *   (`ReadCatalog` or `ReadProduct` for products, `ReadOrder` for orders, `ReadCustomer` for
+ *   customers).
+ * - `CUSTOMER_DATA_NOT_GRANTED`: the credential reads customer data below `full` (an app installed
+ *   at `none` or `identity`). Orders and customers are matched on customers' names, email
+ *   addresses and companies, so they are not searched for it.
+ * - `UNAVAILABLE`: the search service, or for content the content system, did not answer. Try
+ *   again shortly.
+ */
+export type SearchSkipReason = 'PERMISSION' | 'CUSTOMER_DATA_NOT_GRANTED' | 'UNAVAILABLE' | (string & {});
+export interface SearchProductHit {
+    id: string;
+    name: string;
+    slug: string;
+    /** The featured image's preview URL; null when the product has none. */
+    previewUrl: string | null;
+}
+export interface SearchOrderHit {
+    id: string;
+    code: string;
+    state: string;
+    /** ISO-8601; null for an order not placed yet. */
+    orderPlacedAt: string | null;
+    /** Minor units. */
+    totalWithTax: number;
+    currencyCode: string;
+    /** The order's lifecycle (`open`, `completed`, …); null until the engine sets it. */
+    lifecycleStatus: string | null;
+}
+export interface SearchCustomerHit {
+    id: string;
+    firstName: string;
+    lastName: string;
+    emailAddress: string;
+    /** The company of the default billing address, else the default shipping one, else any. */
+    company: string | null;
+}
+/** A content item of the store's content system. */
+export interface SearchContentHit {
+    id: string;
+    collectionId: string;
+    collectionSlug: string;
+    slug: string | null;
+    /** `draft`, `published` or `archived`. */
+    status: string;
+    title: string | null;
+}
+export interface SearchSkip {
+    type: SearchEntityType | (string & {});
+    reason: SearchSkipReason;
+}
+/** Each list holds the type's best matches, most relevant first. */
+export interface EntitySearchResult {
+    products: SearchProductHit[];
+    orders: SearchOrderHit[];
+    customers: SearchCustomerHit[];
+    content: SearchContentHit[];
+    /** The types that were not searched, and why; their lists are empty. */
+    skipped: SearchSkip[];
+}
+export interface SearchEntitiesOptions extends Call {
+    /** The types to search; all four when omitted. An empty list is refused. */
+    types?: readonly SearchEntityType[];
+    /** Results per type, from 1 to {@link SEARCH_ENTITIES_MAX_TAKE}; 5 when omitted. */
+    take?: number;
+}
+/** The engine's bounds, as `searchAcrossEntities` documents them. */
+export declare const SEARCH_ENTITIES_MIN_TERM_LENGTH = 2;
+export declare const SEARCH_ENTITIES_MAX_TAKE = 10;
+export declare const SEARCH_ACROSS_ENTITIES_QUERY = "\n  query SearchAcrossEntities($input: CommandSearchInput!) {\n    searchAcrossEntities(input: $input) {\n      products {\n        id\n        name\n        slug\n        previewUrl\n      }\n      orders {\n        id\n        code\n        state\n        orderPlacedAt\n        totalWithTax\n        currencyCode\n        lifecycleStatus\n      }\n      customers {\n        id\n        firstName\n        lastName\n        emailAddress\n        company\n      }\n      content {\n        id\n        collectionId\n        collectionSlug\n        slug\n        status\n        title\n      }\n      skipped {\n        type\n        reason\n      }\n    }\n  }\n";
+/**
+ * One search across the store (spec §7 `search.entities`): products, orders, customers and
+ * content items matching a term, in one call.
+ *
+ * - **Relevance order.** Each list is that type's best matches, most relevant first, every one
+ *   already loaded in the store you act on; a match the store no longer holds is left out, so a
+ *   list can be shorter than `take`.
+ * - **A type you may not read is skipped and named**, never a refusal: its list is empty and
+ *   `skipped` says why (see {@link SearchSkipReason}).
+ * - **Content may be missing when the content system is down**: the other types still answer,
+ *   and content is skipped `UNAVAILABLE`.
+ * - **Content** is published items, plus drafts and archived items for a `ReadCmsContent` holder.
+ *
+ * Refused before anything is searched: `SEARCH_INPUT_INVALID` (`ValidationError`, 400) for a term
+ * under {@link SEARCH_ENTITIES_MIN_TERM_LENGTH} or over 500 characters once trimmed, a `take`
+ * outside 1..{@link SEARCH_ENTITIES_MAX_TAKE}, or an empty `types` list.
+ */
+export interface SearchModule {
+    entities(term: string, options?: SearchEntitiesOptions): Promise<EntitySearchResult>;
+}
+export declare function createSearchModule(transport: Transport): SearchModule;

package/dist/search/index.js

@@ -0,0 +1,62 @@
+/** The engine's bounds, as `searchAcrossEntities` documents them. */
+export const SEARCH_ENTITIES_MIN_TERM_LENGTH = 2;
+export const SEARCH_ENTITIES_MAX_TAKE = 10;
+export const SEARCH_ACROSS_ENTITIES_QUERY = /* GraphQL */ `
+  query SearchAcrossEntities($input: CommandSearchInput!) {
+    searchAcrossEntities(input: $input) {
+      products {
+        id
+        name
+        slug
+        previewUrl
+      }
+      orders {
+        id
+        code
+        state
+        orderPlacedAt
+        totalWithTax
+        currencyCode
+        lifecycleStatus
+      }
+      customers {
+        id
+        firstName
+        lastName
+        emailAddress
+        company
+      }
+      content {
+        id
+        collectionId
+        collectionSlug
+        slug
+        status
+        title
+      }
+      skipped {
+        type
+        reason
+      }
+    }
+  }
+`;
+export function createSearchModule(transport) {
+    return {
+        async entities(term, options = {}) {
+            const { types, take, ...call } = options;
+            const data = await transport.graphql({
+                api: 'admin',
+                query: SEARCH_ACROSS_ENTITIES_QUERY,
+                variables: {
+                    input: {
+                        term,
+                        ...(types === undefined ? {} : { types: [...types] }),
+                        ...(take === undefined ? {} : { take }),
+                    },
+                },
+            }, call);
+            return data.searchAcrossEntities;
+        },
+    };
+}

package/dist/shipping/parcel-count-suggestion.d.ts

@@ -0,0 +1,52 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+export declare const PARCEL_SUGGESTION_MAX_ITEMS = 500;
+export declare const PARCEL_SUGGESTION_MAX_QUANTITY = 100000;
+export interface ParcelCountSuggestionItem {
+    productVariantId: string;
+    /** Whole units, 1..100,000. Items of one variant are summed by the engine. */
+    quantity: number;
+}
+export interface ParcelCountSuggestionInput {
+    /** 1..500 items, from any number of the active channel's orders. */
+    items: ParcelCountSuggestionItem[];
+    /** ISO 3166-1 alpha-2. Only sets `destinationRequiresCustoms`; the count ignores it. */
+    destinationCountryCode?: string | null;
+}
+/** The active channel's parcel-count rule applied to the items. */
+export interface ParcelCountSuggestion {
+    /** 1..50. */
+    count: number;
+    /** The unclamped count; 0 when nothing was counted. */
+    raw: number;
+    /** False only when no rule applied (then `count` is 1 and `reason` is `NO_PARCEL_RULE`). */
+    resolvable: boolean;
+    /** Every counted item had all the data the rule asks for. */
+    exact: boolean;
+    /** `raw` exceeded 50. */
+    capped: boolean;
+    /** The channel's items per parcel, when set. */
+    capacity: number | null;
+    /** The channel's maximum parcel weight in grams, when set. */
+    maxWeightGrams: number | null;
+    /** Variants counted without a capacity: `count` is a lower bound. */
+    unratedLines: number;
+    /** Variants counted without a package weight under a maximum: `count` is a lower bound. */
+    unweighedLines: number;
+    /** `NO_PARCEL_RULE`, or null. A code: the caller owns the wording, and may meet new codes. */
+    reason: string | null;
+    /** `UNIT_OVER_MAX_WEIGHT` and/or `CAPPED`; may gain codes. */
+    warnings: string[];
+    /** Whether a parcel there needs a customs declaration; null without a destination. */
+    destinationRequiresCustoms: boolean | null;
+}
+/**
+ * `admin.shipping.parcelCountSuggestion`: how many parcels the active
+ * channel's rule gives a set of variant + quantity items. Needs `ReadCatalog`
+ * or `ReadFulfillment`. A malformed input is refused before any request with
+ * `PARCEL_COUNT_INPUT_INVALID` ({@link ValidationError}); an unknown variant,
+ * or another store's, is `PARCEL_COUNT_VARIANT_NOT_FOUND` (`NotFoundError`).
+ */
+export type ParcelCountSuggestionMethod = (input: ParcelCountSuggestionInput, options?: Call) => Promise<ParcelCountSuggestion>;
+export declare const PARCEL_COUNT_SUGGESTION_QUERY = "\n  query ParcelCountSuggestion($input: ParcelCountSuggestionInput!) {\n    parcelCountSuggestion(input: $input) {\n      count\n      raw\n      resolvable\n      exact\n      capped\n      capacity\n      maxWeightGrams\n      unratedLines\n      unweighedLines\n      reason\n      warnings\n      destinationRequiresCustoms\n    }\n  }\n";
+export declare function createParcelCountSuggestion(transport: Transport): ParcelCountSuggestionMethod;

package/dist/shipping/parcel-count-suggestion.js

@@ -0,0 +1,73 @@
+import { ValidationError } from '@sixtyninecommerce/core';
+// Mirror the engine's bounds (`services/vendure/src/parcel-count/`), which are
+// the authority; these only refuse a bad input before it leaves the process.
+export const PARCEL_SUGGESTION_MAX_ITEMS = 500;
+export const PARCEL_SUGGESTION_MAX_QUANTITY = 100_000;
+export const PARCEL_COUNT_SUGGESTION_QUERY = /* GraphQL */ `
+  query ParcelCountSuggestion($input: ParcelCountSuggestionInput!) {
+    parcelCountSuggestion(input: $input) {
+      count
+      raw
+      resolvable
+      exact
+      capped
+      capacity
+      maxWeightGrams
+      unratedLines
+      unweighedLines
+      reason
+      warnings
+      destinationRequiresCustoms
+    }
+  }
+`;
+function invalid(field, message) {
+    return new ValidationError({
+        code: 'PARCEL_COUNT_INPUT_INVALID',
+        message,
+        status: 400,
+        service: 'vendure',
+        details: [{ field, code: 'PARCEL_COUNT_INPUT_INVALID', message }],
+    });
+}
+function assertInput(input) {
+    const items = input?.items;
+    if (!Array.isArray(items) || items.length < 1 || items.length > PARCEL_SUGGESTION_MAX_ITEMS) {
+        throw invalid('items', `Pass between 1 and ${PARCEL_SUGGESTION_MAX_ITEMS} items.`);
+    }
+    items.forEach((item, index) => {
+        if (typeof item?.productVariantId !== 'string' || item.productVariantId === '') {
+            throw invalid(`items[${index}].productVariantId`, 'productVariantId is required.');
+        }
+        const quantity = item.quantity;
+        if (typeof quantity !== 'number' ||
+            !Number.isInteger(quantity) ||
+            quantity < 1 ||
+            quantity > PARCEL_SUGGESTION_MAX_QUANTITY) {
+            throw invalid(`items[${index}].quantity`, `quantity must be a whole number from 1 to ${PARCEL_SUGGESTION_MAX_QUANTITY.toLocaleString('en')}; got ${JSON.stringify(quantity)}.`);
+        }
+    });
+    const country = input.destinationCountryCode;
+    if (country !== undefined && country !== null && !/^[A-Za-z]{2}$/.test(country.trim())) {
+        throw invalid('destinationCountryCode', 'destinationCountryCode must be an ISO 3166-1 alpha-2 code, such as NL.');
+    }
+}
+export function createParcelCountSuggestion(transport) {
+    return async (input, options) => {
+        assertInput(input);
+        const data = await transport.graphql({
+            api: 'admin',
+            query: PARCEL_COUNT_SUGGESTION_QUERY,
+            variables: {
+                input: {
+                    items: input.items.map(({ productVariantId, quantity }) => ({
+                        productVariantId,
+                        quantity,
+                    })),
+                    destinationCountryCode: input.destinationCountryCode ?? null,
+                },
+            },
+        }, options);
+        return data.parcelCountSuggestion;
+    };
+}

package/dist/shipping/parcel-rule.d.ts

@@ -0,0 +1,48 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+export declare const PARCEL_CAPACITY_MAX = 10000;
+export declare const PARCEL_WEIGHT_GRAMS_MAX = 70000;
+/** How the active channel counts parcels. `null` means "not set". */
+export interface ParcelRule {
+    channelId: string;
+    /**
+     * Units that fill one parcel unless a variant sets its own. `null` is no
+     * rule: every order counts as one parcel.
+     */
+    defaultParcelCapacity: number | null;
+    /** Extra lower bound from known package weights, in grams. `null` is no limit. */
+    maxParcelWeightGrams: number | null;
+}
+/**
+ * A PATCH: a key left out is unchanged, `null` clears it. At least one key is
+ * required.
+ */
+export interface SetParcelRuleInput {
+    /** Integer 1..10,000, or `null` to remove the rule. */
+    defaultParcelCapacity?: number | null;
+    /** Integer grams 1..70,000, or `null` to remove the limit. */
+    maxParcelWeightGrams?: number | null;
+}
+/**
+ * The ACTIVE channel's parcel-count rule (`admin.shipping.parcelRule`),
+ * stored as Channel custom fields and written through core `updateChannel`.
+ *
+ * Reading needs an authenticated administrator on the channel; writing needs
+ * `UpdateChannel`. A value out of range is refused here with
+ * `PARCEL_RULE_INVALID` ({@link ValidationError}) before any request, and by
+ * the engine's own custom-field validation for any other writer.
+ *
+ * The engine's storefront pricing reads the rule from its channel cache, so a
+ * change reaches another process after that cache refreshes.
+ */
+export interface ParcelRuleModule {
+    get(options?: Call): Promise<ParcelRule>;
+    set(input: SetParcelRuleInput, options?: Call): Promise<ParcelRule>;
+}
+/** `admin.shipping` (spec §9.2 `shipping`). */
+export interface ShippingModule {
+    parcelRule: ParcelRuleModule;
+}
+export declare const PARCEL_RULE_QUERY = "\n  query ParcelRule {\n    activeChannel { \n  id\n  customFields {\n    defaultParcelCapacity\n    maxParcelWeightGrams\n  }\n }\n  }\n";
+export declare const SET_PARCEL_RULE_MUTATION = "\n  mutation SetParcelRule($input: UpdateChannelInput!) {\n    updateChannel(input: $input) {\n      ... on Channel { \n  id\n  customFields {\n    defaultParcelCapacity\n    maxParcelWeightGrams\n  }\n }\n      ... on ErrorResult { errorCode message }\n    }\n  }\n";
+export declare function createShippingModule(transport: Transport): ShippingModule;

package/dist/shipping/parcel-rule.js

@@ -0,0 +1,91 @@
+import { errorFromErrorResult, isErrorResult, ValidationError, } from '@sixtyninecommerce/core';
+// Mirrors `MAX_PARCEL_CAPACITY` / `MAX_PARCEL_WEIGHT_GRAMS` in
+// `vendure-plugin-shipping-calculator/src/parcels/parcel-rule-fields.ts`. The
+// engine's custom-field `min`/`max` is the authority; these only refuse a bad
+// value before it leaves the process. Change both together.
+export const PARCEL_CAPACITY_MAX = 10_000;
+export const PARCEL_WEIGHT_GRAMS_MAX = 70_000;
+const RULE_FIELDS = /* GraphQL */ `
+  id
+  customFields {
+    defaultParcelCapacity
+    maxParcelWeightGrams
+  }
+`;
+export const PARCEL_RULE_QUERY = /* GraphQL */ `
+  query ParcelRule {
+    activeChannel { ${RULE_FIELDS} }
+  }
+`;
+export const SET_PARCEL_RULE_MUTATION = /* GraphQL */ `
+  mutation SetParcelRule($input: UpdateChannelInput!) {
+    updateChannel(input: $input) {
+      ... on Channel { ${RULE_FIELDS} }
+      ... on ErrorResult { errorCode message }
+    }
+  }
+`;
+function toRule(channel) {
+    return {
+        channelId: channel.id,
+        defaultParcelCapacity: channel.customFields?.defaultParcelCapacity ?? null,
+        maxParcelWeightGrams: channel.customFields?.maxParcelWeightGrams ?? null,
+    };
+}
+function invalid(field, message) {
+    return new ValidationError({
+        code: 'PARCEL_RULE_INVALID',
+        message,
+        status: 400,
+        service: 'vendure',
+        details: [{ field, code: 'PARCEL_RULE_INVALID', message }],
+    });
+}
+function assertBound(field, value, max, unit) {
+    if (value === undefined || value === null)
+        return;
+    if (typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= max)
+        return;
+    throw invalid(field, `${field} must be a whole number of ${unit} from 1 to ${max.toLocaleString('en')}, or null to clear it; got ${JSON.stringify(value)}.`);
+}
+function customFieldsOf(input) {
+    const fields = {};
+    if (input.defaultParcelCapacity !== undefined) {
+        fields.defaultParcelCapacity = input.defaultParcelCapacity;
+    }
+    if (input.maxParcelWeightGrams !== undefined) {
+        fields.maxParcelWeightGrams = input.maxParcelWeightGrams;
+    }
+    return fields;
+}
+export function createShippingModule(transport) {
+    const get = async (options) => {
+        const data = await transport.graphql({ api: 'admin', query: PARCEL_RULE_QUERY }, options);
+        return toRule(data.activeChannel);
+    };
+    return {
+        parcelRule: {
+            get,
+            async set(input, options) {
+                assertBound('defaultParcelCapacity', input?.defaultParcelCapacity, PARCEL_CAPACITY_MAX, 'items');
+                assertBound('maxParcelWeightGrams', input?.maxParcelWeightGrams, PARCEL_WEIGHT_GRAMS_MAX, 'grams');
+                const customFields = customFieldsOf(input ?? {});
+                if (Object.keys(customFields).length === 0) {
+                    throw invalid('input', 'Pass defaultParcelCapacity and/or maxParcelWeightGrams; an empty input changes nothing.');
+                }
+                // `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 rather than the client's.
+                const { channelId } = await get(options);
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: SET_PARCEL_RULE_MUTATION,
+                    variables: { input: { id: channelId, customFields } },
+                }, options);
+                if (isErrorResult(data.updateChannel))
+                    throw errorFromErrorResult(data.updateChannel);
+                return toRule(data.updateChannel);
+            },
+        },
+    };
+}