@sixtyninecommerce/admin 0.10.0 → 0.12.0

package/dist/pos/returns.js

@@ -0,0 +1,83 @@
+import { statedCustomerAgreed } from '../payments/customer-consent.js';
+import { isUnknownFieldRejection } from '../payments/store-credit-fields.js';
+/** A quote's fields up to its store-credit payout, which every engine with C6b reads. */
+const QUOTE_BASE_FIELDS = 'orderId kind currencyCode receiptNumber lines { orderLineId name sku customItem restockable soldQuantity returnedQuantity returnableQuantity quantity refundAmount } total legs { paymentId kind method amount } cashPaidOut returnWindowEndsAt outsideWindow refundedOutsideReturns restockLocationName blockedBy blockedReason';
+// Spliced as template constants, never built by a call: the repo's GraphQL cost scan
+// (`graphql-cost-fits-repo.spec.ts`) resolves `${CONSTANT}` statically and nothing computed.
+/** A quote's fields before the till's consent (owner ruling Q4): what every engine with C6b reads. */
+const QUOTE_FIELDS_BEFORE_CONSENT = `${QUOTE_BASE_FIELDS} storedValuePayout { available reason }`;
+const QUOTE_FIELDS = `${QUOTE_BASE_FIELDS} storedValuePayout { available reason asksConsent }`;
+/** The sprint-20 result: what a void answers (it never pays out to store credit). */
+const VOID_RESULT_FIELDS = 'orderId returnId returnCode kind total refunds { paymentId kind method amount refundId outcome } cashPaidOut complete';
+/** A return's result: the void's, and the store credit a STORED_VALUE payout made (C6b). */
+const RESULT_FIELDS = `${VOID_RESULT_FIELDS} storedValueCredit { accountId entryId amount }`;
+export const POS_RETURN_QUOTE_QUERY = `query PosReturnQuote($input: PosReturnQuoteInput!) { posReturnQuote(input: $input) { ${QUOTE_FIELDS} } }`;
+/** The quote for an engine before the till's consent (owner ruling Q4): no `asksConsent`. */
+export const POS_RETURN_QUOTE_QUERY_BEFORE_CONSENT = `query PosReturnQuote($input: PosReturnQuoteInput!) { posReturnQuote(input: $input) { ${QUOTE_FIELDS_BEFORE_CONSENT} } }`;
+export const POS_RETURN_MUTATION = `mutation PosReturn($input: PosReturnInput!) { posReturn(input: $input) { ${RESULT_FIELDS} } }`;
+export const POS_VOID_SALE_MUTATION = `mutation PosVoidSale($input: PosVoidSaleInput!) { posVoidSale(input: $input) { ${VOID_RESULT_FIELDS} } }`;
+// Engine C3/34: their own documents, so a call to an older engine fails alone.
+const ONLINE_ORDER_FIELDS = 'orderId orderCode placedAt state currencyCode totalWithTax customerName refundMethodName returnableUnits blockedBy blockedReason';
+export const POS_ONLINE_ORDER_QUERY = `query PosOnlineOrder($input: PosOnlineOrderRefInput!) { posOnlineOrder(input: $input) { ${ONLINE_ORDER_FIELDS} } }`;
+// Never store credit (D22), so it never asks consent: the selection before Q4, `asksConsent` false.
+export const POS_ONLINE_RETURN_QUOTE_QUERY = `query PosOnlineReturnQuote($input: PosOnlineReturnQuoteInput!) { posOnlineReturnQuote(input: $input) { ${QUOTE_FIELDS_BEFORE_CONSENT} shippingRefund source } }`;
+// A webshop order's return never pays out to store credit (C3 D22): the void's result fields.
+export const POS_ONLINE_RETURN_MUTATION = `mutation PosOnlineReturn($input: PosOnlineReturnInput!) { posOnlineReturn(input: $input) { ${VOID_RESULT_FIELDS} } }`;
+/** Such a quote as this SDK answers it: `asksConsent` false (that engine takes no answer). */
+function withoutConsent(quote) {
+    return {
+        ...quote,
+        storedValuePayout: { ...quote.storedValuePayout, asksConsent: false },
+    };
+}
+function keyOf(options, call) {
+    const key = options?.idempotencyKey;
+    if (typeof key !== 'string' || key.trim() === '') {
+        throw new TypeError(`pos.returns.${call} needs options.idempotencyKey (a fresh UUIDv7 per return; reuse it only to retry the same one).`);
+    }
+    return key;
+}
+export function createPosReturnsModule(transport) {
+    const gql = async (query, variables, options) => transport.graphql({ api: 'admin', query, variables }, options);
+    return {
+        async quote(input, options) {
+            try {
+                const data = await gql(POS_RETURN_QUOTE_QUERY, { input }, options);
+                return data.posReturnQuote;
+            }
+            catch (error) {
+                // An engine before the till's consent (Q4) refuses the whole document; the quote is still
+                // readable without it, and that engine takes no answer. Any other failure is the read's.
+                if (!isUnknownFieldRejection(error))
+                    throw error;
+                const data = await gql(POS_RETURN_QUOTE_QUERY_BEFORE_CONSENT, { input }, options);
+                return withoutConsent(data.posReturnQuote);
+            }
+        },
+        async create(input, options) {
+            const idempotencyKey = keyOf(options, 'create');
+            // The answer only when stated: left out or null, the request is what it always was.
+            const { customerAgreed, ...rest } = input;
+            const data = await gql(POS_RETURN_MUTATION, { input: { ...rest, ...statedCustomerAgreed(customerAgreed), idempotencyKey } }, options);
+            return data.posReturn;
+        },
+        async void(input, options) {
+            const idempotencyKey = keyOf(options, 'void');
+            const data = await gql(POS_VOID_SALE_MUTATION, { input: { ...input, idempotencyKey } }, options);
+            return data.posVoidSale;
+        },
+        async findOnlineOrder(ref, options) {
+            const data = await gql(POS_ONLINE_ORDER_QUERY, { input: ref }, options);
+            return data.posOnlineOrder;
+        },
+        async onlineQuote(input, options) {
+            const data = await gql(POS_ONLINE_RETURN_QUOTE_QUERY, { input }, options);
+            return withoutConsent(data.posOnlineReturnQuote);
+        },
+        async onlineReturn(input, options) {
+            const idempotencyKey = keyOf(options, 'onlineReturn');
+            const data = await gql(POS_ONLINE_RETURN_MUTATION, { input: { ...input, idempotencyKey } }, options);
+            return data.posOnlineReturn;
+        },
+    };
+}

package/dist/pricing/bulk-coupons.d.ts

@@ -0,0 +1,139 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Call, ListOptions } from '../types.js';
+/**
+ * `admin.pricing.coupons.bulk`: unique codes generated in bulk for a promotion of the store
+ * (`vendure-plugin-bulk-coupons`). A code stands in for its promotion's own coupon code, so a
+ * promotion WITHOUT a coupon code takes none: its codes would never be accepted. Each code keeps
+ * its group's usage limits on top of the promotion's.
+ *
+ * Every id names a record of THIS store: another store's promotion, group or code is
+ * `ENTITY_NOT_FOUND` (`NotFoundError`, 404), the same answer as one that does not exist.
+ */
+export interface PricingBulkCouponsModule {
+    /**
+     * The promotion's code groups, newest first, each with how many of its codes are active and
+     * how many uses its codes have had (orders holding a code that are not cancelled). A voucher
+     * template (`kind: 'voucher'`, `pricing.vouchers`) is a group too.
+     *
+     * @effect read
+     * @permission ReadPromotion
+     */
+    groups(promotionId: string, options?: Call): Promise<BulkCouponGroup[]>;
+    /**
+     * One page of a group's codes, oldest first and then by id, an order every page agrees on, so
+     * a walk with `for await` sees each code once (`limit` 1 to 1,000, default 25), each with its
+     * own use count. Refused before sending: `INVALID_PAGE_SIZE` (`ValidationError`, 400).
+     *
+     * @effect read
+     * @permission ReadPromotion
+     */
+    codes(groupId: string, options?: ListOptions): Promise<Page<BulkCouponCode>>;
+    /**
+     * Generate a group of `quantity` new codes, `PREFIX-RANDOM`, for the promotion, and answer
+     * the group. The prefix is trimmed; the random part is `codeLength` characters (8 when
+     * omitted).
+     *
+     * Refusals (`ValidationError`, 400): `BULK_COUPON_PREFIX_INVALID` (1 to 50 capital letters,
+     * digits or "-", starting with a letter or digit), `BULK_COUPON_CODE_LENGTH_INVALID` (8 to
+     * 32), `BULK_COUPON_QUANTITY_INVALID` (1 to 100,000);
+     * `BULK_COUPON_CODE_SPACE_EXHAUSTED` (`BusinessRuleError`, 422) when the prefix and length
+     * have too few free codes left (choose a longer length or another prefix). Nothing is saved
+     * on a refusal. A repeat generates another group: no `idempotencyKey` is read.
+     *
+     * @effect write
+     * @permission CreatePromotion
+     */
+    generate(input: GenerateBulkCouponsInput, options?: Call): Promise<BulkCouponGroup>;
+    /**
+     * Accept a switched-off code again, and answer it.
+     *
+     * @effect write
+     * @permission UpdatePromotion
+     */
+    activate(codeId: string, options?: Call): Promise<BulkCouponCode>;
+    /**
+     * Stop accepting one code from now on, and answer it.
+     *
+     * @effect write
+     * @permission UpdatePromotion
+     */
+    deactivate(codeId: string, options?: Call): Promise<BulkCouponCode>;
+    /**
+     * Stop accepting every code of a group (each can be switched on again with
+     * {@link activate}).
+     *
+     * @effect write
+     * @permission UpdatePromotion
+     */
+    deactivateGroup(groupId: string, options?: Call): Promise<void>;
+    /**
+     * Delete a group and every code in it: none is accepted again, and none can be switched back
+     * on.
+     *
+     * @effect destructive
+     * @permission DeletePromotion
+     */
+    deleteGroup(groupId: string, options?: Call): Promise<void>;
+    /**
+     * Every code of a group as CSV text, in the order of {@link codes}: a `code,active,created_at`
+     * header, then one line per code (`active` is `true`/`false`, `created_at` an ISO-8601 instant).
+     *
+     * @effect read
+     * @permission ReadPromotion
+     */
+    export(groupId: string, options?: Call): Promise<string>;
+}
+export interface BulkCouponGroup {
+    id: string;
+    promotionId: string;
+    prefix: string;
+    codeLength: number;
+    /** Codes generated up front; 0 for a voucher template, whose codes are issued one by one. */
+    quantity: number;
+    /** Uses each code allows; null for no limit of its own. */
+    perCodeUsageLimit: number | null;
+    /** Uses each code allows one customer; null for no limit of its own. */
+    perCodeCustomerUsageLimit: number | null;
+    /** `batch` (generated up front) or `voucher` (personal codes issued one by one). */
+    kind: 'batch' | 'voucher' | (string & {});
+    /** A voucher template's validity in days when an issue names none. */
+    defaultValidityDays: number | null;
+    activeCount: number;
+    usedCount: number;
+    createdAt: string;
+}
+export interface BulkCouponCode {
+    id: string;
+    code: string;
+    isActive: boolean;
+    usageCount: number;
+    createdAt: string;
+    /** A voucher's customer; null for a batch code (or a voucher whose customer was erased). */
+    customerId: string | null;
+    /** A voucher's own expiry; its promotion's end still applies. */
+    expiresAt: string | null;
+    /** The system that issued a voucher, as it named itself. */
+    sourceSystem: string | null;
+    /** The issuing journey's own reference, opaque. */
+    sourceRef: string | null;
+}
+export interface GenerateBulkCouponsInput {
+    promotionId: string;
+    prefix: string;
+    /** The random part's length, 8 to 32; 8 when omitted. */
+    codeLength?: number;
+    /** 1 to 100,000. */
+    quantity: number;
+    perCodeUsageLimit?: number | null;
+    perCodeCustomerUsageLimit?: number | null;
+}
+export declare const BULK_COUPON_GROUPS_QUERY = "\n  query BulkCouponGroups($promotionId: ID!) {\n    bulkCouponGroups(promotionId: $promotionId) { \n  id\n  promotionId\n  prefix\n  codeLength\n  quantity\n  perCodeUsageLimit\n  perCodeCustomerUsageLimit\n  kind\n  defaultValidityDays\n  activeCount\n  usedCount\n  createdAt\n }\n  }\n";
+export declare const BULK_COUPON_CODES_QUERY = "\n  query BulkCouponCodes($groupId: ID!, $options: BulkCouponCodeListOptions) {\n    bulkCouponCodes(groupId: $groupId, options: $options) {\n      items { \n  id\n  code\n  isActive\n  usageCount\n  createdAt\n  customerId\n  expiresAt\n  sourceSystem\n  sourceRef\n }\n      totalItems\n    }\n  }\n";
+export declare const GENERATE_BULK_COUPONS_MUTATION = "\n  mutation GenerateBulkCoupons($input: GenerateBulkCouponsInput!) {\n    generateBulkCoupons(input: $input) { \n  id\n  promotionId\n  prefix\n  codeLength\n  quantity\n  perCodeUsageLimit\n  perCodeCustomerUsageLimit\n  kind\n  defaultValidityDays\n  activeCount\n  usedCount\n  createdAt\n }\n  }\n";
+export declare const ACTIVATE_BULK_COUPON_CODE_MUTATION = "\n  mutation ActivateBulkCouponCode($id: ID!) {\n    activateBulkCouponCode(id: $id) { \n  id\n  code\n  isActive\n  usageCount\n  createdAt\n  customerId\n  expiresAt\n  sourceSystem\n  sourceRef\n }\n  }\n";
+export declare const DEACTIVATE_BULK_COUPON_CODE_MUTATION = "\n  mutation DeactivateBulkCouponCode($id: ID!) {\n    deactivateBulkCouponCode(id: $id) { \n  id\n  code\n  isActive\n  usageCount\n  createdAt\n  customerId\n  expiresAt\n  sourceSystem\n  sourceRef\n }\n  }\n";
+export declare const DEACTIVATE_BULK_COUPON_GROUP_MUTATION = "\n  mutation DeactivateBulkCouponGroup($groupId: ID!) {\n    deactivateBulkCouponGroup(groupId: $groupId)\n  }\n";
+export declare const DELETE_BULK_COUPON_GROUP_MUTATION = "\n  mutation DeleteBulkCouponGroup($groupId: ID!) {\n    deleteBulkCouponGroup(groupId: $groupId)\n  }\n";
+/** A mutation, though it writes nothing: the plugin declares it so (`ReadPromotion`). */
+export declare const EXPORT_BULK_COUPON_CODES_MUTATION = "\n  mutation ExportBulkCouponCodes($groupId: ID!) {\n    exportBulkCouponCodes(groupId: $groupId)\n  }\n";
+export declare function createPricingBulkCouponsModule(transport: Transport): PricingBulkCouponsModule;

package/dist/pricing/bulk-coupons.js

@@ -0,0 +1,112 @@
+import { UpstreamError } from '@sixtyninecommerce/core';
+import { fieldOf, vendureListPage } from '../catalog/types.js';
+const GROUP_FIELDS = /* GraphQL */ `
+  id
+  promotionId
+  prefix
+  codeLength
+  quantity
+  perCodeUsageLimit
+  perCodeCustomerUsageLimit
+  kind
+  defaultValidityDays
+  activeCount
+  usedCount
+  createdAt
+`;
+const CODE_FIELDS = /* GraphQL */ `
+  id
+  code
+  isActive
+  usageCount
+  createdAt
+  customerId
+  expiresAt
+  sourceSystem
+  sourceRef
+`;
+export const BULK_COUPON_GROUPS_QUERY = /* GraphQL */ `
+  query BulkCouponGroups($promotionId: ID!) {
+    bulkCouponGroups(promotionId: $promotionId) { ${GROUP_FIELDS} }
+  }
+`;
+export const BULK_COUPON_CODES_QUERY = /* GraphQL */ `
+  query BulkCouponCodes($groupId: ID!, $options: BulkCouponCodeListOptions) {
+    bulkCouponCodes(groupId: $groupId, options: $options) {
+      items { ${CODE_FIELDS} }
+      totalItems
+    }
+  }
+`;
+export const GENERATE_BULK_COUPONS_MUTATION = /* GraphQL */ `
+  mutation GenerateBulkCoupons($input: GenerateBulkCouponsInput!) {
+    generateBulkCoupons(input: $input) { ${GROUP_FIELDS} }
+  }
+`;
+export const ACTIVATE_BULK_COUPON_CODE_MUTATION = /* GraphQL */ `
+  mutation ActivateBulkCouponCode($id: ID!) {
+    activateBulkCouponCode(id: $id) { ${CODE_FIELDS} }
+  }
+`;
+export const DEACTIVATE_BULK_COUPON_CODE_MUTATION = /* GraphQL */ `
+  mutation DeactivateBulkCouponCode($id: ID!) {
+    deactivateBulkCouponCode(id: $id) { ${CODE_FIELDS} }
+  }
+`;
+export const DEACTIVATE_BULK_COUPON_GROUP_MUTATION = /* GraphQL */ `
+  mutation DeactivateBulkCouponGroup($groupId: ID!) {
+    deactivateBulkCouponGroup(groupId: $groupId)
+  }
+`;
+export const DELETE_BULK_COUPON_GROUP_MUTATION = /* GraphQL */ `
+  mutation DeleteBulkCouponGroup($groupId: ID!) {
+    deleteBulkCouponGroup(groupId: $groupId)
+  }
+`;
+/** A mutation, though it writes nothing: the plugin declares it so (`ReadPromotion`). */
+export const EXPORT_BULK_COUPON_CODES_MUTATION = /* GraphQL */ `
+  mutation ExportBulkCouponCodes($groupId: ID!) {
+    exportBulkCouponCodes(groupId: $groupId)
+  }
+`;
+/** A `Boolean!` door's answer: anything but `true` is refused, never taken as done. */
+function assertDone(field, answer) {
+    if (answer === true)
+        return;
+    throw new UpstreamError({
+        code: 'UNEXPECTED_RESPONSE',
+        message: `The engine answered "${field}" with ${JSON.stringify(answer)}, not true.`,
+        status: 502,
+        service: 'vendure',
+    });
+}
+export function createPricingBulkCouponsModule(transport) {
+    return {
+        groups(promotionId, options) {
+            return fieldOf(transport, BULK_COUPON_GROUPS_QUERY, 'bulkCouponGroups', { promotionId }, options);
+        },
+        codes(groupId, options) {
+            return vendureListPage(transport, BULK_COUPON_CODES_QUERY, 'bulkCouponCodes', (skip, take) => ({ groupId, options: { skip, take } }), options);
+        },
+        generate(input, options) {
+            return fieldOf(transport, GENERATE_BULK_COUPONS_MUTATION, 'generateBulkCoupons', { input }, options);
+        },
+        activate(codeId, options) {
+            return fieldOf(transport, ACTIVATE_BULK_COUPON_CODE_MUTATION, 'activateBulkCouponCode', { id: codeId }, options);
+        },
+        deactivate(codeId, options) {
+            return fieldOf(transport, DEACTIVATE_BULK_COUPON_CODE_MUTATION, 'deactivateBulkCouponCode', { id: codeId }, options);
+        },
+        async deactivateGroup(groupId, options) {
+            const field = 'deactivateBulkCouponGroup';
+            assertDone(field, await fieldOf(transport, DEACTIVATE_BULK_COUPON_GROUP_MUTATION, field, { groupId }, options));
+        },
+        async deleteGroup(groupId, options) {
+            const field = 'deleteBulkCouponGroup';
+            assertDone(field, await fieldOf(transport, DELETE_BULK_COUPON_GROUP_MUTATION, field, { groupId }, options));
+        },
+        export(groupId, options) {
+            return fieldOf(transport, EXPORT_BULK_COUPON_CODES_MUTATION, 'exportBulkCouponCodes', { groupId }, options);
+        },
+    };
+}

package/dist/pricing/index.d.ts

@@ -1,6 +1,8 @@
 import { type Page, type Transport } from '@sixtyninecommerce/core';
-import type { ConfigurableOperation, ConfigurableOperationInput, LanguageCode } from '../catalog/types.js';
-import type { Call } from '../types.js';
+import { type ConfigurableOperation, type ConfigurableOperationInput, type LanguageCode } from '../catalog/types.js';
+import type { Call, ConfigurableOperationDefinition, ListOptions } from '../types.js';
+import { type PricingBulkCouponsModule } from './bulk-coupons.js';
+import { type PricingPriceListsModule } from './price-lists.js';
 import { type PricingVouchersModule } from './vouchers.js';
 /**
  * Promotions at the register (headless spec §9.2 `pricing`; incentives spec §5,
@@ -36,6 +38,11 @@ export interface PricingModule {
     coupons: PricingCouponsModule;
     /** Personal vouchers: templates, issuing, a customer's vouchers (`./vouchers.ts`). */
     vouchers: PricingVouchersModule;
+    /**
+     * The store's B2B price lists: the lists, their entries, assignments and order rules, and
+     * bulk enable/disable/delete (`./price-lists.ts`).
+     */
+    priceLists: PricingPriceListsModule;
     /**
      * The order's discounts as they stand: its coupon codes, the order-level
      * discounts, and each line's discounts, every one naming the promotion it came
@@ -45,6 +52,80 @@ export interface PricingModule {
     discounts(orderId: string, options?: Call): Promise<OrderDiscounts>;
 }
 export interface PricingPromotionsModule {
+    /**
+     * One page of the store's promotions (`limit` 1 to 1,000, default 25), every state and date
+     * window: what a back office lists, unlike {@link active}. Walk them all with `for await`:
+     * every following page re-sends the same filters, sort and store.
+     *
+     * - `term` (trimmed; a blank one is ignored) matches a case-insensitive part of the name, in
+     *   ANY of its languages, or of the coupon code. A row found through another language's name
+     *   answers that language's `name`. EXCEPT while sorted by `name`: the engine then reads the
+     *   name in the request's language only (the store's default language where a promotion has
+     *   none in it), so a term matches no other language; sort by another key to search them all.
+     * - `enabled` keeps only the enabled (or disabled) ones; their date window is not judged.
+     * - `sort`: one key; the engine's own order when omitted.
+     *
+     * The store's auto-managed order-rule promotion is never listed (see {@link active}).
+     *
+     * Refused before sending: `INVALID_PAGE_SIZE` (`ValidationError`, 400) for a `limit` outside
+     * 1 to 1,000; `INVALID_PROMOTION_SORT` (`ValidationError`, 400) for a sort field or direction
+     * this method does not name; `INVALID_PROMOTION_FILTER` (`ValidationError`, 400) for a `term`
+     * that is not a string or an `enabled` that is not a boolean.
+     *
+     * @effect read
+     * @permission ReadPromotion
+     */
+    list(options?: PromotionListOptions): Promise<Page<PromotionListItem>>;
+    /**
+     * One promotion of this store with its translations, conditions and actions as stored (the
+     * stacking guard included), or `null` when the store has none by that id (another store's
+     * answers the same).
+     *
+     * The store's auto-managed order-rule promotion (the id an "Order discount" on an order names)
+     * is answered with `customFields.managedBy` set: it is read-only, every change and the delete
+     * are refused `MANAGED_PROMOTION_NOT_ALLOWED`; its rules are set on the price lists
+     * (`priceLists.orderRules`). A merchant's promotion answers `managedBy: null`.
+     *
+     * @effect read
+     * @permission ReadPromotion
+     */
+    get(id: string, options?: Call): Promise<PromotionDetail | null>;
+    /**
+     * Delete a promotion of this store. It stops applying: an order priced after the delete no
+     * longer gets its discount, and its coupon code (and every bulk code generated for it) is no
+     * longer accepted.
+     *
+     * Refusals: `ENTITY_NOT_FOUND` (`NotFoundError`, 404) for an id this store does not hold (one
+     * answer for another store's and an unknown one), `SHARED_PROMOTION_NOT_ALLOWED` (403) for a
+     * promotion other stores hold too, `MANAGED_PROMOTION_NOT_ALLOWED` (`PermissionDeniedError`,
+     * 403) for the store's auto-managed order-rule promotion, and `PROMOTION_NOT_DELETED`
+     * (`ConflictError`, 409) should the engine answer that it kept it.
+     *
+     * @effect destructive
+     * @permission DeletePromotion
+     */
+    delete(id: string, options?: Call): Promise<void>;
+    /**
+     * The conditions a promotion of this store can carry, each with its arguments, in the
+     * language of the request. Two the engine registers are left out because a caller never sets
+     * them: the stacking guard (`promotion_stacking_guard`, which {@link create} and
+     * {@link update} add themselves) and the price-list order-rule condition
+     * (`price_list_order_rules`, refused on every promotion but the store's auto-managed one).
+     *
+     * `args[].required` is NOT the enforced rule (see `ConfigArgDefinition.required`).
+     *
+     * @effect read
+     * @permission ReadPromotion
+     */
+    conditionDefinitions(options?: Call): Promise<ConfigurableOperationDefinition[]>;
+    /**
+     * The actions a promotion of this store can carry, as {@link conditionDefinitions} answers the
+     * conditions: the price-list order-rule action (`price_list_order_rules`) is left out.
+     *
+     * @effect read
+     * @permission ReadPromotion
+     */
+    actionDefinitions(options?: Call): Promise<ConfigurableOperationDefinition[]>;
     /**
      * The store's promotions that can apply right now: enabled, inside their date
      * window, not used up, and — with `customerId` — open to that customer (a
@@ -61,9 +142,17 @@ export interface PricingPromotionsModule {
      * location of this store that the credential may act at
      * (`LOCATION_NOT_IN_CHANNEL` / `LOCATION_NOT_ALLOWED`).
      *
+     * The store's auto-managed order-rule promotion is never listed: it applies
+     * the order rules of the store's price lists (`priceLists.orderRules`), is no
+     * offer, and is managed by the platform. Its discount still shows on an order
+     * ("Order discount", {@link PricingOrdersModule.discounts}), naming that
+     * promotion's id.
+     *
      * Needs `ReadPromotion`, `CreateOrder` or `OperatePos`. A `Page` because every
      * list in this SDK is one; the engine answers the whole list, so it is always
      * the last page.
+     *
+     * @effect read
      */
     active(filter?: ActivePromotionsFilter, options?: Call): Promise<Page<ActivePromotion>>;
     /**
@@ -85,12 +174,18 @@ export interface PricingPromotionsModule {
      * targeting or set argument the engine cannot read, a second set condition or
      * a set action without its condition (`argument: "conditions"`), or a set
      * condition without its action or a second copy of a set action
-     * (`argument: "actions"`), judged on `update` for the pair the update leaves; `extensions.details` names the condition and
+     * (`argument: "actions"`), judged on `update` for the pair the update leaves,
+     * or the price-list order-rule pair `price_list_order_rules`, which only the
+     * store's own auto-managed promotion carries (`argument: "conditions"` or
+     * `"actions"`: order rules are set on a price list); `extensions.details` names the condition and
      * argument), `LOCATION_NOT_IN_CHANNEL` (a location of another store, or not
      * an id), `LOCATION_NOT_ALLOWED` (outside the credential's location
      * restriction), `FACET_VALUE_NOT_FOUND` / `COLLECTION_NOT_FOUND`
      * (`NotFoundError`, 404: a set component names a facet value or collection
      * this store does not have; another store's answers the same).
+     *
+     * @effect write
+     * @permission CreatePromotion
      */
     create(input: CreatePromotionInput, options?: Call): Promise<PricingPromotion>;
     /**
@@ -98,7 +193,10 @@ export interface PricingPromotionsModule {
      * replace the whole list (the guard is kept as on create). Needs
      * `UpdatePromotion`.
      *
-     * Refusals: those of {@link PricingPromotionsModule.create}, and
+     * Refusals: those of {@link PricingPromotionsModule.create},
+     * `MANAGED_PROMOTION_NOT_ALLOWED` (`PermissionDeniedError`, 403) for the
+     * store's auto-managed order-rule promotion (the id an "Order discount" on an
+     * order names; change the price list's order rules instead), and
      * `MISSING_CONDITIONS_ERROR` (`BusinessRuleError`, 422) for one case: the input
      * does not name `conditions`, the STORED promotion has none (an imported
      * coupon, a seed: no guard was ever added), and the result would have no coupon
@@ -106,6 +204,9 @@ export interface PricingPromotionsModule {
      * conditions from the stored ones, and the guard is added only to conditions
      * the input sends: send `conditions` (even `[]`) to keep such a promotion
      * without a code.
+     *
+     * @effect write
+     * @permission UpdatePromotion
      */
     update(input: UpdatePromotionInput, options?: Call): Promise<PricingPromotion>;
 }
@@ -255,7 +356,71 @@ export interface PricingPromotion {
         priority: number | null;
     };
 }
+/** What {@link PricingPromotionsModule.list} can sort by. */
+export type PromotionSortField = 'name' | 'couponCode' | 'startsAt' | 'endsAt' | 'createdAt' | 'updatedAt';
+export declare const PROMOTION_SORT_FIELDS: readonly PromotionSortField[];
+export interface PromotionListOptions extends ListOptions {
+    /**
+     * A part of the name (any language, unless sorted by `name`: see `list`) or of the coupon code,
+     * capitals ignored; trimmed.
+     */
+    term?: string;
+    /** Only the enabled (`true`) or the disabled (`false`) ones. */
+    enabled?: boolean;
+    /** ONE sort key; the engine's own order when omitted. */
+    sort?: {
+        field: PromotionSortField;
+        direction: 'ASC' | 'DESC';
+    };
+}
+/** A promotion as {@link PricingPromotionsModule.list} answers it. */
+export interface PromotionListItem {
+    id: string;
+    /** In the request's language, or the language whose name a `term` matched. */
+    name: string;
+    description: string;
+    couponCode: string | null;
+    enabled: boolean;
+    /** ISO-8601 instants; null for an open start or end. */
+    startsAt: string | null;
+    endsAt: string | null;
+    usageLimit: number | null;
+    perCustomerUsageLimit: number | null;
+    createdAt: string;
+    updatedAt: string;
+    customFields: {
+        combineWithB2b: boolean | null;
+        combineWithOtherPromotions: boolean | null;
+        priority: number | null;
+    };
+}
+/** A promotion as {@link PricingPromotionsModule.get} answers it. */
+export interface PromotionDetail extends Omit<PromotionListItem, 'customFields'> {
+    translations: Array<{
+        id: string;
+        languageCode: LanguageCode;
+        name: string;
+        description: string;
+    }>;
+    /** As stored, the stacking guard (`promotion_stacking_guard`) included. */
+    conditions: ConfigurableOperation[];
+    actions: ConfigurableOperation[];
+    customFields: PromotionListItem['customFields'] & {
+        /**
+         * Set only on the store's auto-managed order-rule promotion (`price-list-order-rules`): a
+         * platform service owns it, and every change and the delete are refused. `null` for a
+         * merchant's promotion.
+         */
+        managedBy: string | null;
+    };
+}
 export interface PricingCouponsModule {
+    /**
+     * Unique codes generated in bulk for a promotion with a coupon code (`./bulk-coupons.ts`):
+     * the groups, their codes, generating, switching a code or a group off, deleting a group, and
+     * a group's codes as CSV.
+     */
+    bulk: PricingBulkCouponsModule;
     /**
      * Apply a coupon code — a promotion's own code or a unique code generated for
      * it — to a DRAFT order of this store: a back-office draft, or an order
@@ -400,6 +565,11 @@ export declare const ORDER_DISCOUNTS_FIELDS = "\n  id\n  code\n  state\n  curren
 export declare const ACTIVE_PROMOTIONS_QUERY = "\n  query ActivePromotions($locationId: ID, $customerId: ID) {\n    activePromotions(locationId: $locationId, customerId: $customerId) {\n      id\n      name\n      description\n      startsAt\n      endsAt\n      requiresCouponCode\n      usageLimit\n      perCustomerUsageLimit\n      conditions { code args { name value } summary }\n      actions { code args { name value } summary }\n      summary\n    }\n  }\n";
 export declare const CREATE_PROMOTION_MUTATION = "\n  mutation CreatePromotion($input: CreatePromotionInput!) {\n    createPromotion(input: $input) {\n      ... on Promotion { \n  id\n  name\n  description\n  enabled\n  couponCode\n  startsAt\n  endsAt\n  usageLimit\n  perCustomerUsageLimit\n  conditions { code args { name value } }\n  actions { code args { name value } }\n  customFields { combineWithB2b combineWithOtherPromotions priority }\n }\n      ... on ErrorResult { errorCode message }\n    }\n  }\n";
 export declare const UPDATE_PROMOTION_MUTATION = "\n  mutation UpdatePromotion($input: UpdatePromotionInput!) {\n    updatePromotion(input: $input) {\n      ... on Promotion { \n  id\n  name\n  description\n  enabled\n  couponCode\n  startsAt\n  endsAt\n  usageLimit\n  perCustomerUsageLimit\n  conditions { code args { name value } }\n  actions { code args { name value } }\n  customFields { combineWithB2b combineWithOtherPromotions priority }\n }\n      ... on ErrorResult { errorCode message }\n    }\n  }\n";
+export declare const PROMOTIONS_QUERY = "\n  query StorePromotions($options: PromotionListOptions) {\n    promotions(options: $options) {\n      items {\n        \n  id\n  name\n  description\n  couponCode\n  enabled\n  startsAt\n  endsAt\n  usageLimit\n  perCustomerUsageLimit\n  createdAt\n  updatedAt\n\n        customFields { combineWithB2b combineWithOtherPromotions priority }\n      }\n      totalItems\n    }\n  }\n";
+export declare const PROMOTION_QUERY = "\n  query StorePromotion($id: ID!) {\n    promotion(id: $id) {\n      \n  id\n  name\n  description\n  couponCode\n  enabled\n  startsAt\n  endsAt\n  usageLimit\n  perCustomerUsageLimit\n  createdAt\n  updatedAt\n\n      translations { id languageCode name description }\n      conditions { code args { name value } }\n      actions { code args { name value } }\n      customFields { combineWithB2b combineWithOtherPromotions priority managedBy }\n    }\n  }\n";
+export declare const DELETE_PROMOTION_MUTATION = "\n  mutation DeleteStorePromotion($id: ID!) {\n    deletePromotion(id: $id) {\n      result\n      message\n    }\n  }\n";
+export declare const PROMOTION_CONDITION_DEFINITIONS_QUERY = "\n  query PromotionConditionDefinitions {\n    promotionConditions { \n  code\n  description\n  args {\n    name\n    type\n    list\n    required\n    defaultValue\n    label\n    description\n    ui\n  }\n }\n  }\n";
+export declare const PROMOTION_ACTION_DEFINITIONS_QUERY = "\n  query PromotionActionDefinitions {\n    promotionActions { \n  code\n  description\n  args {\n    name\n    type\n    list\n    required\n    defaultValue\n    label\n    description\n    ui\n  }\n }\n  }\n";
 /** The condition the dashboard and the admin app put on every promotion they save. */
 export declare const STACKING_GUARD_CONDITION = "promotion_stacking_guard";
 export declare const APPLY_COUPON_CODE_TO_ORDER_MUTATION = "\n  mutation ApplyCouponCodeToOrder($orderId: ID!, $couponCode: String!, $idempotencyKey: String) {\n    applyCouponCodeToOrder(\n      orderId: $orderId\n      couponCode: $couponCode\n      idempotencyKey: $idempotencyKey\n    ) {\n      \n  id\n  code\n  state\n  currencyCode\n  couponCodes\n  subTotal\n  subTotalWithTax\n  shipping\n  shippingWithTax\n  total\n  totalWithTax\n  discounts { promotionId adjustmentSource type description amount amountWithTax }\n  promotions { id name }\n  lines {\n    id\n    quantity\n    productVariant { id sku name }\n    unitPrice\n    unitPriceWithTax\n    linePrice\n    linePriceWithTax\n    discountedLinePrice\n    discountedLinePriceWithTax\n    proratedLinePrice\n    proratedLinePriceWithTax\n    discounts { promotionId adjustmentSource type description amount amountWithTax }\n  }\n  surcharges { id description sku price priceWithTax }\n  packages { promotionId label price priceWithTax lineIds quantity }\n\n    }\n  }\n";