@sixtyninecommerce/admin 0.8.0 → 0.10.0

package/dist/pricing/index.js

@@ -0,0 +1,353 @@
+import { createPage, errorFromErrorResult, isErrorResult, NotFoundError, ValidationError, } from '@sixtyninecommerce/core';
+import { createPricingVouchersModule } from './vouchers.js';
+/**
+ * The targeting conditions (incentives sprint 2), encoded as the engine stores
+ * them — every argument a string, lists JSON-encoded. Their argument names and
+ * shapes are a stored contract.
+ */
+export const promotionConditions = {
+    /**
+     * `selling_location`: the order is sold from one of these stock locations of
+     * the store — a till there, an order `orders.createOrRecover` recorded for it
+     * (`location`), or a register sending it as `x-location` on the Admin API. A
+     * web order has no location and never matches.
+     */
+    sellingLocation(locationIds) {
+        return {
+            code: 'selling_location',
+            arguments: [{ name: 'locationIds', value: JSON.stringify([...locationIds]) }],
+        };
+    },
+    /**
+     * `time_window`: on one of `days`, from `from` (included) to `until`
+     * (excluded), local time — the selling location's profile zone, else the
+     * store's. An `until` not after `from` runs into the next day and belongs to
+     * the day it opened (`fri 22:00–02:00`); equal times are 24 hours
+     * (`00:00`–`00:00`: all day). Judged on the wall clock, so a window in the
+     * hour clocks repeat in autumn is open twice, one in the hour they skip in
+     * spring never opens. A placed order keeps a window it was placed with.
+     */
+    timeWindow(window) {
+        return {
+            code: 'time_window',
+            arguments: [
+                { name: 'daysOfWeek', value: JSON.stringify([...window.days]) },
+                { name: 'startTime', value: window.from },
+                { name: 'endTime', value: window.until },
+            ],
+        };
+    },
+    /**
+     * `first_order`: the customer has no earlier placed order in this store. An
+     * order with no customer, or the till's walk-in, never matches.
+     */
+    firstOrder() {
+        return { code: 'first_order', arguments: [] };
+    },
+    /**
+     * `bundle_fixed_price` (incentives sprint 4): each complete set of
+     * `components` costs `price` — minor units of the store's DEFAULT currency, in
+     * the store's tax basis (as its catalogue prices are entered), converted into
+     * an order's currency at the checkout's rate. The discount is spread over the
+     * set's lines by value; a set worth `price` or less stays at list price. Pair
+     * it with {@link promotionActions}`.bundleFixedPrice()`.
+     *
+     * `price` is required and must be a whole amount above 0: anything else throws
+     * `ValidationError` (`PROMOTION_CONDITION_INVALID`) before a request is sent,
+     * as the engine would refuse it. To give sets away use
+     * {@link promotionConditions}`.nthSetPercentage` with `discount: 100`.
+     */
+    bundleFixedPrice(set) {
+        assertSetPrice('bundle_fixed_price', set.price);
+        return {
+            code: 'bundle_fixed_price',
+            arguments: [
+                { name: 'components', value: componentsValue(set.components) },
+                { name: 'price', value: String(set.price) },
+            ],
+        };
+    },
+    /**
+     * `nth_set_percentage`: of every `nth` complete sets, the cheapest is
+     * `discount`% off ("second pair at 50%" is `nth: 2, discount: 50`; `nth: 1`
+     * discounts every set). Pair it with {@link promotionActions}`.nthSetPercentage()`.
+     */
+    nthSetPercentage(set) {
+        return {
+            code: 'nth_set_percentage',
+            arguments: [
+                { name: 'components', value: componentsValue(set.components) },
+                { name: 'nth', value: String(set.nth) },
+                { name: 'discount', value: String(set.discount) },
+            ],
+        };
+    },
+    /**
+     * `mix_and_match`: any `quantity` units matching the selector (all of
+     * `facetValueIds`, any of `collectionIds`) for `price`, per complete group;
+     * leftover units stay at list price. `price` as in `bundleFixedPrice`
+     * (required, above 0, refused before sending otherwise). Pair it with
+     * {@link promotionActions}`.mixAndMatch()`.
+     */
+    mixAndMatch(group) {
+        assertSetPrice('mix_and_match', group.price);
+        return {
+            code: 'mix_and_match',
+            arguments: [
+                { name: 'facetValueIds', value: JSON.stringify([...(group.facetValueIds ?? [])]) },
+                { name: 'collectionIds', value: JSON.stringify([...(group.collectionIds ?? [])]) },
+                { name: 'quantity', value: String(group.quantity) },
+                { name: 'price', value: String(group.price) },
+            ],
+        };
+    },
+};
+/**
+ * A set or group price as the engine accepts it: a whole number of minor units above 0. A 0
+ * would make every set free (the engine refuses it on save and discounts nothing for one it
+ * finds stored), so it is refused here, before a request is sent, with the engine's own code.
+ */
+function assertSetPrice(condition, price) {
+    if (Number.isSafeInteger(price) && price >= 1 && price <= 2_147_483_647)
+        return;
+    const message = `The "${condition}" condition's price must be a whole amount in minor units above 0; got ${String(price)}. To give sets away, use promotionConditions.nthSetPercentage with discount: 100.`;
+    throw new ValidationError({
+        code: 'PROMOTION_CONDITION_INVALID',
+        message,
+        status: 400,
+        service: 'vendure',
+        details: [{ field: 'price', code: 'PROMOTION_CONDITION_INVALID', message }],
+    });
+}
+function componentsValue(components) {
+    return JSON.stringify(components.map((component) => ({
+        facetValueIds: [...(component.facetValueIds ?? [])],
+        collectionIds: [...(component.collectionIds ?? [])],
+        quantity: component.quantity,
+    })));
+}
+/**
+ * The set actions (incentives sprint 4). Each takes no arguments and applies
+ * what its same-code condition computed, so it goes on the promotion together
+ * with that condition: the engine refuses one without the other.
+ */
+export const promotionActions = {
+    bundleFixedPrice() {
+        return { code: 'bundle_fixed_price', arguments: [] };
+    },
+    nthSetPercentage() {
+        return { code: 'nth_set_percentage', arguments: [] };
+    },
+    mixAndMatch() {
+        return { code: 'mix_and_match', arguments: [] };
+    },
+};
+const DISCOUNT_FIELDS = 'promotionId adjustmentSource type description amount amountWithTax';
+/** An order's pricing readout; the manual pricing doors (`orders.setLinePrices`, …) answer it too. */
+export const ORDER_DISCOUNTS_FIELDS = /* GraphQL */ `
+  id
+  code
+  state
+  currencyCode
+  couponCodes
+  subTotal
+  subTotalWithTax
+  shipping
+  shippingWithTax
+  total
+  totalWithTax
+  discounts { ${DISCOUNT_FIELDS} }
+  promotions { id name }
+  lines {
+    id
+    quantity
+    productVariant { id sku name }
+    unitPrice
+    unitPriceWithTax
+    linePrice
+    linePriceWithTax
+    discountedLinePrice
+    discountedLinePriceWithTax
+    proratedLinePrice
+    proratedLinePriceWithTax
+    discounts { ${DISCOUNT_FIELDS} }
+  }
+  surcharges { id description sku price priceWithTax }
+  packages { promotionId label price priceWithTax lineIds quantity }
+`;
+const OPERATION_FIELDS = 'code args { name value } summary';
+export const ACTIVE_PROMOTIONS_QUERY = /* GraphQL */ `
+  query ActivePromotions($locationId: ID, $customerId: ID) {
+    activePromotions(locationId: $locationId, customerId: $customerId) {
+      id
+      name
+      description
+      startsAt
+      endsAt
+      requiresCouponCode
+      usageLimit
+      perCustomerUsageLimit
+      conditions { ${OPERATION_FIELDS} }
+      actions { ${OPERATION_FIELDS} }
+      summary
+    }
+  }
+`;
+const PROMOTION_FIELDS = /* GraphQL */ `
+  id
+  name
+  description
+  enabled
+  couponCode
+  startsAt
+  endsAt
+  usageLimit
+  perCustomerUsageLimit
+  conditions { code args { name value } }
+  actions { code args { name value } }
+  customFields { combineWithB2b combineWithOtherPromotions priority }
+`;
+export const CREATE_PROMOTION_MUTATION = /* GraphQL */ `
+  mutation CreatePromotion($input: CreatePromotionInput!) {
+    createPromotion(input: $input) {
+      ... on Promotion { ${PROMOTION_FIELDS} }
+      ... on ErrorResult { errorCode message }
+    }
+  }
+`;
+export const UPDATE_PROMOTION_MUTATION = /* GraphQL */ `
+  mutation UpdatePromotion($input: UpdatePromotionInput!) {
+    updatePromotion(input: $input) {
+      ... on Promotion { ${PROMOTION_FIELDS} }
+      ... on ErrorResult { errorCode message }
+    }
+  }
+`;
+/** The condition the dashboard and the admin app put on every promotion they save. */
+export const STACKING_GUARD_CONDITION = 'promotion_stacking_guard';
+function withStackingGuard(conditions) {
+    return conditions.some((condition) => condition.code === STACKING_GUARD_CONDITION)
+        ? conditions
+        : [{ code: STACKING_GUARD_CONDITION, arguments: [] }, ...conditions];
+}
+/** The SDK input as the engine's `Create`/`UpdatePromotionInput`. */
+function promotionInputOf(input) {
+    const { combineWithB2b, combineWithOtherPromotions, priority, conditions, ...rest } = input;
+    const customFields = {
+        ...(combineWithB2b === undefined ? {} : { combineWithB2b }),
+        ...(combineWithOtherPromotions === undefined ? {} : { combineWithOtherPromotions }),
+        ...(priority === undefined ? {} : { priority }),
+    };
+    return {
+        ...rest,
+        ...(conditions === undefined ? {} : { conditions: withStackingGuard(conditions) }),
+        ...(Object.keys(customFields).length === 0 ? {} : { customFields }),
+    };
+}
+export const APPLY_COUPON_CODE_TO_ORDER_MUTATION = /* GraphQL */ `
+  mutation ApplyCouponCodeToOrder($orderId: ID!, $couponCode: String!, $idempotencyKey: String) {
+    applyCouponCodeToOrder(
+      orderId: $orderId
+      couponCode: $couponCode
+      idempotencyKey: $idempotencyKey
+    ) {
+      ${ORDER_DISCOUNTS_FIELDS}
+    }
+  }
+`;
+export const REMOVE_COUPON_CODE_FROM_ORDER_MUTATION = /* GraphQL */ `
+  mutation RemoveCouponCodeFromOrder($orderId: ID!, $couponCode: String!, $idempotencyKey: String) {
+    removeCouponCodeFromOrder(
+      orderId: $orderId
+      couponCode: $couponCode
+      idempotencyKey: $idempotencyKey
+    ) {
+      ${ORDER_DISCOUNTS_FIELDS}
+    }
+  }
+`;
+export const ORDER_DISCOUNTS_QUERY = /* GraphQL */ `
+  query OrderDiscounts($id: ID!) {
+    order(id: $id) {
+      ${ORDER_DISCOUNTS_FIELDS}
+    }
+  }
+`;
+/** `undefined` for an absent or blank filter id: an explicit null is a value the engine reads. */
+function idVariable(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
+export function createPricingModule(transport) {
+    return {
+        promotions: {
+            async active(filter, options) {
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: ACTIVE_PROMOTIONS_QUERY,
+                    variables: {
+                        locationId: idVariable(filter?.locationId),
+                        customerId: idVariable(filter?.customerId),
+                    },
+                }, options);
+                const items = data.activePromotions;
+                return createPage(items, { nextCursor: null, hasNext: false, total: items.length }, () => {
+                    throw new Error('activePromotions returns a complete list; there is no next page');
+                });
+            },
+            async create(input, options) {
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: CREATE_PROMOTION_MUTATION,
+                    variables: { input: promotionInputOf(input) },
+                }, options);
+                // A union at HTTP 200 (`Promotion | MissingConditionsError`). With the guard
+                // always sent, core does not answer the error member for this input; should
+                // it ever, it is thrown, never handed back as a promotion.
+                if (isErrorResult(data.createPromotion))
+                    throw errorFromErrorResult(data.createPromotion);
+                return data.createPromotion;
+            },
+            async update(input, options) {
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: UPDATE_PROMOTION_MUTATION,
+                    variables: { input: promotionInputOf(input) },
+                }, options);
+                if (isErrorResult(data.updatePromotion))
+                    throw errorFromErrorResult(data.updatePromotion);
+                return data.updatePromotion;
+            },
+        },
+        vouchers: createPricingVouchersModule(transport),
+        coupons: {
+            async apply(orderId, couponCode, options) {
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: APPLY_COUPON_CODE_TO_ORDER_MUTATION,
+                    variables: { orderId, couponCode, idempotencyKey: options?.idempotencyKey },
+                }, options);
+                return data.applyCouponCodeToOrder;
+            },
+            async remove(orderId, couponCode, options) {
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: REMOVE_COUPON_CODE_FROM_ORDER_MUTATION,
+                    variables: { orderId, couponCode, idempotencyKey: options?.idempotencyKey },
+                }, options);
+                return data.removeCouponCodeFromOrder;
+            },
+        },
+        async discounts(orderId, options) {
+            const data = await transport.graphql({ api: 'admin', query: ORDER_DISCOUNTS_QUERY, variables: { id: orderId } }, options);
+            if (!data.order) {
+                throw new NotFoundError({
+                    code: 'ORDER_NOT_FOUND',
+                    message: `This store has no order ${orderId}.`,
+                    status: 404,
+                    service: 'vendure',
+                });
+            }
+            return data.order;
+        },
+    };
+}

package/dist/pricing/vouchers.d.ts

@@ -0,0 +1,103 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * Personal vouchers (incentives sprint 9): a voucher TEMPLATE under a promotion, codes issued one
+ * by one to a customer of the store, single use, with an optional expiry and the issuing journey
+ * recorded as an opaque `source`. Applied like any coupon (`pricing.coupons.apply`, the till's
+ * `pos.sale.applyCouponCode`), which refuse `VOUCHER_NOT_FOR_CUSTOMER`, `VOUCHER_EXPIRED` and
+ * `VOUCHER_ALREADY_REDEEMED`. Issuing needs `CreatePromotion`.
+ */
+/** A customer of this store: exactly one of its id or a master system's key (PR #1176). */
+export type VoucherCustomer = {
+    id: string;
+} | {
+    externalRef: {
+        system: string;
+        ref: string;
+    };
+};
+export interface IssueVoucherInput {
+    templateId: string;
+    customer: VoucherCustomer;
+    /** Usable through the end of the store's local day this many days after today (1 to 3650). */
+    validityDays?: number;
+    /** Or an explicit instant, ISO-8601. Neither: the template's default, else the promotion's window. */
+    expiresAt?: string;
+    /** The issuing journey; with a `ref`, an issue is exactly-once per template, customer and source. */
+    source: {
+        system: string;
+        ref?: string;
+    };
+}
+export interface IssueVouchersInput {
+    templateId: string;
+    sourceSystem: string;
+    /** At most 1,000. */
+    items: Array<{
+        customer: VoucherCustomer;
+        validityDays?: number;
+        expiresAt?: string;
+        sourceRef?: string;
+    }>;
+}
+export interface IssuedVoucher {
+    id: string;
+    code: string;
+    customerId: string;
+    /** The earlier of its own expiry and its promotion's end; null when neither ends. */
+    expiresAt: string | null;
+    /** False when this template, customer and source had issued it already: the same code. */
+    created: boolean;
+}
+export interface IssueVouchersItem {
+    index: number;
+    voucher: IssuedVoucher | null;
+    /** A `VOUCHER_*` code or `ENTITY_NOT_FOUND` for a refused item; the others were issued. */
+    errorCode: string | null;
+    message: string | null;
+}
+export type VoucherStatus = 'OPEN' | 'REDEEMED' | 'EXPIRED' | 'REVOKED';
+export interface Voucher {
+    id: string;
+    code: string;
+    templateId: string;
+    promotionId: string;
+    customerId: string | null;
+    status: VoucherStatus;
+    issuedAt: string;
+    expiresAt: string | null;
+    sourceSystem: string | null;
+    sourceRef: string | null;
+    /** The order that redeemed it. */
+    orderId: string | null;
+}
+export interface VoucherTemplate {
+    id: string;
+    promotionId: string;
+    prefix: string;
+    codeLength: number;
+    defaultValidityDays: number | null;
+}
+export interface PricingVouchersModule {
+    /** A voucher template under a promotion of this store (codes of 12 to 32 random characters). */
+    createTemplate(input: {
+        promotionId: string;
+        prefix: string;
+        codeLength?: number;
+        defaultValidityDays?: number;
+    }, options?: Call): Promise<VoucherTemplate>;
+    /**
+     * Issue one voucher. `options.idempotencyKey` replays the first answer; the same template,
+     * customer and `source.ref` answers the voucher already issued (`created: false`) under any key.
+     */
+    issue(input: IssueVoucherInput, options?: Call): Promise<IssuedVoucher>;
+    /** Issue up to 1,000 vouchers of one template; a refused item answers in its place. */
+    issueMany(input: IssueVouchersInput, options?: Call): Promise<IssueVouchersItem[]>;
+    /** A customer's vouchers in this store, newest first; every status when `status` is omitted. */
+    forCustomer(customer: VoucherCustomer, status?: VoucherStatus, options?: Call): Promise<Voucher[]>;
+}
+export declare const CREATE_VOUCHER_TEMPLATE_MUTATION = "\n  mutation CreateVoucherTemplate($input: CreateVoucherTemplateInput!) {\n    createVoucherTemplate(input: $input) {\n      id\n      promotionId\n      prefix\n      codeLength\n      defaultValidityDays\n    }\n  }\n";
+export declare const ISSUE_VOUCHER_MUTATION = "\n  mutation IssueVoucher($input: IssueVoucherInput!, $idempotencyKey: String) {\n    issueVoucher(input: $input, idempotencyKey: $idempotencyKey) { id code customerId expiresAt created }\n  }\n";
+export declare const ISSUE_VOUCHERS_MUTATION = "\n  mutation IssueVouchers($input: IssueVouchersInput!, $idempotencyKey: String) {\n    issueVouchers(input: $input, idempotencyKey: $idempotencyKey) {\n      items { index errorCode message voucher { id code customerId expiresAt created } }\n    }\n  }\n";
+export declare const VOUCHERS_FOR_CUSTOMER_QUERY = "\n  query VouchersForCustomer($customer: VoucherCustomerInput!, $status: VoucherStatus) {\n    vouchersForCustomer(customer: $customer, status: $status) {\n      id\n      code\n      templateId\n      promotionId\n      customerId\n      status\n      issuedAt\n      expiresAt\n      sourceSystem\n      sourceRef\n      orderId\n    }\n  }\n";
+export declare function createPricingVouchersModule(transport: Transport): PricingVouchersModule;

package/dist/pricing/vouchers.js

@@ -0,0 +1,69 @@
+const ISSUED_VOUCHER_FIELDS = `id code customerId expiresAt created`;
+export const CREATE_VOUCHER_TEMPLATE_MUTATION = /* GraphQL */ `
+  mutation CreateVoucherTemplate($input: CreateVoucherTemplateInput!) {
+    createVoucherTemplate(input: $input) {
+      id
+      promotionId
+      prefix
+      codeLength
+      defaultValidityDays
+    }
+  }
+`;
+export const ISSUE_VOUCHER_MUTATION = /* GraphQL */ `
+  mutation IssueVoucher($input: IssueVoucherInput!, $idempotencyKey: String) {
+    issueVoucher(input: $input, idempotencyKey: $idempotencyKey) { ${ISSUED_VOUCHER_FIELDS} }
+  }
+`;
+export const ISSUE_VOUCHERS_MUTATION = /* GraphQL */ `
+  mutation IssueVouchers($input: IssueVouchersInput!, $idempotencyKey: String) {
+    issueVouchers(input: $input, idempotencyKey: $idempotencyKey) {
+      items { index errorCode message voucher { ${ISSUED_VOUCHER_FIELDS} } }
+    }
+  }
+`;
+export const VOUCHERS_FOR_CUSTOMER_QUERY = /* GraphQL */ `
+  query VouchersForCustomer($customer: VoucherCustomerInput!, $status: VoucherStatus) {
+    vouchersForCustomer(customer: $customer, status: $status) {
+      id
+      code
+      templateId
+      promotionId
+      customerId
+      status
+      issuedAt
+      expiresAt
+      sourceSystem
+      sourceRef
+      orderId
+    }
+  }
+`;
+export function createPricingVouchersModule(transport) {
+    return {
+        async createTemplate(input, options) {
+            const data = await transport.graphql({ api: 'admin', query: CREATE_VOUCHER_TEMPLATE_MUTATION, variables: { input } }, options);
+            return data.createVoucherTemplate;
+        },
+        async issue(input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: ISSUE_VOUCHER_MUTATION,
+                variables: { input, idempotencyKey: options?.idempotencyKey },
+            }, options);
+            return data.issueVoucher;
+        },
+        async issueMany(input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: ISSUE_VOUCHERS_MUTATION,
+                variables: { input, idempotencyKey: options?.idempotencyKey },
+            }, options);
+            return data.issueVouchers.items;
+        },
+        async forCustomer(customer, status, options) {
+            const data = await transport.graphql({ api: 'admin', query: VOUCHERS_FOR_CUSTOMER_QUERY, variables: { customer, status } }, options);
+            return data.vouchersForCustomer;
+        },
+    };
+}

package/dist/provenance/index.d.ts

@@ -0,0 +1,93 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/** The records provenance is kept for. An address change is recorded on its customer. */
+export type ProvenanceEntityType = 'PRODUCT' | 'VARIANT' | 'CUSTOMER';
+/**
+ * The field groups a row can be about: the four groups an app can be granted (spec §8.10).
+ */
+export type ProvenanceFieldGroup = 'price' | 'stock' | 'product_details' | 'customer_details';
+/** Who made the last change of a field group. */
+export interface ProvenanceActor {
+    /**
+     * `user` (a staff member), `customer` (the shopper, on their own record), `api_token`,
+     * `app_installation`, `system` (a platform job), `service`, `anonymous` (a guest), or
+     * `unknown` when nothing could name the writer.
+     */
+    type: string;
+    /**
+     * A User id for `user` and `customer`, an API token or app installation id, or
+     * `system:<job>`. Null for a guest, an unknown writer, or a customer since erased.
+     */
+    id: string | null;
+    /**
+     * The app's name, the API token's name, the job (`system:<job>`), or a staff member's name for
+     * a caller holding `ReadAdministrator` who can see that staff member. Null otherwise, and never
+     * a customer's name.
+     */
+    label: string | null;
+}
+/** The app or API key whose change a field group last carries: the "Managed by" badge. */
+export interface ProvenanceManagedBy {
+    kind: 'app_installation' | 'api_token';
+    /** The app installation's or API token's id. */
+    id: string;
+    /** The app's name or the API token's name. */
+    label: string;
+}
+/** The last change of one field group of one record, in the store the client acts on. */
+export interface EntityProvenance {
+    entityType: ProvenanceEntityType;
+    entityId: string;
+    /** A {@link ProvenanceFieldGroup}; a group a newer engine adds reaches you as it is. */
+    fieldGroup: string;
+    actor: ProvenanceActor;
+    /** The platform job that carried a change made for someone else (a bulk import), or null. */
+    via: string | null;
+    /** When the change committed, ISO-8601 UTC. */
+    writtenAt: string;
+    /** The trace of the change: the key into `admin.audit.correlation` and the event log. */
+    traceId: string | null;
+    /**
+     * Non-null only when the last change of THIS group was made by an app or an API key of this
+     * store: the rule for showing "Managed by <name>". A staff, customer or job change clears it.
+     */
+    managedBy: ProvenanceManagedBy | null;
+}
+/** The most records one read may name; more is refused with `PROVENANCE_REQUEST_INVALID`. */
+export declare const PROVENANCE_MAX_IDS = 250;
+export declare const ENTITY_PROVENANCE_QUERY = "\n  query EntityProvenance($entityType: ProvenanceEntityType!, $ids: [ID!]!) {\n    entityProvenance(entityType: $entityType, ids: $ids) {\n      entityType\n      entityId\n      fieldGroup\n      actor {\n        type\n        id\n        label\n      }\n      via\n      writtenAt\n      traceId\n      managedBy {\n        kind\n        id\n        label\n      }\n    }\n  }\n";
+/**
+ * Who last changed each field group of a product, variant or customer (spec §8.10): the price, the
+ * stock, the product details, the customer's details. Recorded for every change, made by staff,
+ * an app, an API key, an import or the shopper, in the change's own transaction.
+ *
+ * - **Last writer only, per group.** One row per (record, group), replaced by the next write
+ *   that NAMES a field of that group, an unchanged value re-sent included (the engine sees no
+ *   prior value, as with `product_variant.price_changed`). What changed and when, in order, is the platform event log filtered by the
+ *   record (`GET /event-log?aggregate_type=&aggregate_id=` in the plugins service, which needs
+ *   `ReadPlatformEvents`); it is not here.
+ * - **`managedBy` is the badge rule.** Show "Managed by <label>" only when it is non-null.
+ * - **Only the store you act on.** A record the store does not hold, and one it holds with
+ *   nothing recorded since provenance began, answer the same way: no rows.
+ * - **Permissions:** products and variants need `ReadCatalog` or `ReadProduct`, customers
+ *   `ReadCustomer` (`FORBIDDEN` → `PermissionDeniedError`). Staff names need `ReadAdministrator`.
+ *
+ * Refusals: `PROVENANCE_REQUEST_INVALID` (`ValidationError`) for more than
+ * {@link PROVENANCE_MAX_IDS} ids; `ENTITY_NOT_FOUND` (`NotFoundError`) for an id that is not
+ * a record id at all, and from `get` for a record with nothing recorded.
+ */
+export interface ProvenanceModule {
+    /**
+     * Every recorded group of each named record, in the order the ids were given, then by group.
+     * A `Page` because every list in this SDK is one; it is always complete (one round trip, at
+     * most {@link PROVENANCE_MAX_IDS} ids).
+     */
+    list(entityType: ProvenanceEntityType, ids: readonly string[], options?: Call): Promise<Page<EntityProvenance>>;
+    /**
+     * The recorded groups of one record. Throws `NotFoundError` (`ENTITY_NOT_FOUND`) when the
+     * store holds none: the record is not this store's, or nothing has changed it since
+     * provenance began. The two are deliberately indistinguishable.
+     */
+    get(entityType: ProvenanceEntityType, id: string, options?: Call): Promise<EntityProvenance[]>;
+}
+export declare function createProvenanceModule(transport: Transport): ProvenanceModule;

package/dist/provenance/index.js

@@ -0,0 +1,53 @@
+import { createPage, NotFoundError } from '@sixtyninecommerce/core';
+/** The most records one read may name; more is refused with `PROVENANCE_REQUEST_INVALID`. */
+export const PROVENANCE_MAX_IDS = 250;
+export const ENTITY_PROVENANCE_QUERY = /* GraphQL */ `
+  query EntityProvenance($entityType: ProvenanceEntityType!, $ids: [ID!]!) {
+    entityProvenance(entityType: $entityType, ids: $ids) {
+      entityType
+      entityId
+      fieldGroup
+      actor {
+        type
+        id
+        label
+      }
+      via
+      writtenAt
+      traceId
+      managedBy {
+        kind
+        id
+        label
+      }
+    }
+  }
+`;
+export function createProvenanceModule(transport) {
+    async function read(entityType, ids, options) {
+        const data = await transport.graphql({ api: 'admin', query: ENTITY_PROVENANCE_QUERY, variables: { entityType, ids: [...ids] } }, options);
+        return data.entityProvenance;
+    }
+    return {
+        async list(entityType, ids, options) {
+            const items = await read(entityType, ids, options);
+            return createPage(items, { nextCursor: null, hasNext: false, total: items.length }, () => {
+                // Unreachable while `hasNext` is false — `Page.next()` short-circuits — and a rejection
+                // rather than a silent re-fetch if that changes.
+                throw new Error('entityProvenance returns a complete list; there is no next page');
+            });
+        },
+        async get(entityType, id, options) {
+            const rows = await read(entityType, [id], options);
+            if (rows.length === 0) {
+                throw new NotFoundError({
+                    code: 'ENTITY_NOT_FOUND',
+                    message: `This store has no recorded change of ${entityType.toLowerCase()} ${id}.`,
+                    status: 404,
+                    service: 'vendure',
+                });
+            }
+            return rows;
+        },
+    };
+}