@sixtyninecommerce/admin 0.11.0 → 0.12.0

package/dist/purchasing/returns.js

@@ -0,0 +1,229 @@
+import { pageFromVendureList, readOffsetCursor, } from '@sixtyninecommerce/core';
+export const SUPPLIER_RETURN_LINE_FIELDS = /* GraphQL */ `
+  id
+  supplierReturnId
+  position
+  goodsReceiptId
+  goodsReceiptCode
+  goodsReceiptLineId
+  purchaseOrderId
+  purchaseOrderCode
+  purchaseOrderLineId
+  productVariantId
+  sku
+  name
+  supplierSku
+  purchaseUnitLabel
+  purchaseUnitFactor
+  baseQuantity
+  reason
+  outcome
+  resolution
+  currencyCode
+  creditAmount
+  resolutionReference
+  unitCost
+  cancelledBaseQuantity
+  reopenedBaseQuantity
+  resolvedAt
+  resolvedByRef
+  stockMovementId
+  createdAt
+`;
+export const SUPPLIER_RETURN_FIELDS = /* GraphQL */ `
+  id
+  scopeId
+  legalEntityId
+  originChannelId
+  code
+  status
+  origin
+  supplierId
+  supplier { id code name status }
+  stockLocationId
+  stockLocation { id name }
+  supplierReference
+  notesToSupplier
+  carrier
+  trackingCode
+  shippedAt
+  resolvedAt
+  managedBy
+  externalId
+  createdByRef
+  documentIssuedAt
+  lines { ${SUPPLIER_RETURN_LINE_FIELDS} }
+  statusHistory { id fromStatus status actorRef reason metadata createdAt }
+  createdAt
+  updatedAt
+`;
+export const SUPPLIER_RETURNS_QUERY = /* GraphQL */ `
+  query SupplierReturns($options: SupplierReturnListOptions) {
+    supplierReturns(options: $options) {
+      items { ${SUPPLIER_RETURN_FIELDS} }
+      totalItems
+    }
+  }
+`;
+export const SUPPLIER_RETURN_QUERY = /* GraphQL */ `
+  query SupplierReturn($id: ID!) {
+    supplierReturn(id: $id) { ${SUPPLIER_RETURN_FIELDS} }
+  }
+`;
+export const CREATE_SUPPLIER_RETURN_MUTATION = /* GraphQL */ `
+  mutation CreateSupplierReturn($input: CreateSupplierReturnInput!, $idempotencyKey: String) {
+    createSupplierReturn(input: $input, idempotencyKey: $idempotencyKey) {
+      ${SUPPLIER_RETURN_FIELDS}
+    }
+  }
+`;
+export const UPDATE_SUPPLIER_RETURN_MUTATION = /* GraphQL */ `
+  mutation UpdateSupplierReturn($input: UpdateSupplierReturnInput!, $idempotencyKey: String) {
+    updateSupplierReturn(input: $input, idempotencyKey: $idempotencyKey) {
+      ${SUPPLIER_RETURN_FIELDS}
+    }
+  }
+`;
+export const SHIP_SUPPLIER_RETURN_MUTATION = /* GraphQL */ `
+  mutation ShipSupplierReturn($input: ShipSupplierReturnInput!, $idempotencyKey: String!) {
+    shipSupplierReturn(input: $input, idempotencyKey: $idempotencyKey) {
+      ${SUPPLIER_RETURN_FIELDS}
+    }
+  }
+`;
+export const RESOLVE_SUPPLIER_RETURN_LINE_MUTATION = /* GraphQL */ `
+  mutation ResolveSupplierReturnLine(
+    $input: ResolveSupplierReturnLineInput!
+    $idempotencyKey: String
+  ) {
+    resolveSupplierReturnLine(input: $input, idempotencyKey: $idempotencyKey) {
+      ${SUPPLIER_RETURN_FIELDS}
+    }
+  }
+`;
+export const CANCEL_SUPPLIER_RETURN_MUTATION = /* GraphQL */ `
+  mutation CancelSupplierReturn($id: ID!, $reason: String, $idempotencyKey: String) {
+    cancelSupplierReturn(id: $id, reason: $reason, idempotencyKey: $idempotencyKey) {
+      ${SUPPLIER_RETURN_FIELDS}
+    }
+  }
+`;
+export const CREATE_SUPPLIER_RETURN_DOCUMENT_URL_MUTATION = /* GraphQL */ `
+  mutation CreateSupplierReturnDocumentUrl($supplierReturnId: ID!) {
+    createSupplierReturnDocumentUrl(supplierReturnId: $supplierReturnId) {
+      url
+      expiresAt
+      filename
+    }
+  }
+`;
+const DEFAULT_PAGE_SIZE = 25;
+const LIST_FILTERS = [
+    'status',
+    'origin',
+    'supplierId',
+    'stockLocationId',
+    'purchaseOrderId',
+    'goodsReceiptId',
+    'term',
+];
+const LINE_INPUT_FIELDS = [
+    'goodsReceiptLineId',
+    'baseQuantity',
+    'reason',
+    'outcome',
+];
+const CREATE_INPUT_FIELDS = [
+    'origin',
+    'supplierId',
+    'stockLocationId',
+    'supplierReference',
+    'notesToSupplier',
+    'carrier',
+    'trackingCode',
+];
+const UPDATE_INPUT_FIELDS = [
+    'stockLocationId',
+    'supplierReference',
+    'notesToSupplier',
+    'carrier',
+    'trackingCode',
+];
+const SHIP_INPUT_FIELDS = [
+    'carrier',
+    'trackingCode',
+    'notifySupplier',
+];
+const RESOLVE_INPUT_FIELDS = [
+    'supplierReturnLineId',
+    'resolution',
+    'creditAmount',
+    'resolutionReference',
+];
+function picked(input, fields) {
+    const out = {};
+    for (const field of fields) {
+        const value = input[field];
+        if (value !== undefined)
+            out[field] = value;
+    }
+    return out;
+}
+export function createPurchasingReturnsModule(transport) {
+    const listPage = async (skip, take, options) => {
+        const filters = options ? picked(options, LIST_FILTERS) : {};
+        const data = await transport.graphql({
+            api: 'admin',
+            query: SUPPLIER_RETURNS_QUERY,
+            variables: { options: { skip, take, ...filters } },
+        }, options);
+        return pageFromVendureList(data.supplierReturns, skip, take, (cursor) => listPage(readOffsetCursor(cursor), take, options));
+    };
+    const mutate = async (field, query, variables, call) => {
+        const data = await transport.graphql({ api: 'admin', query, variables: { ...variables, idempotencyKey: call?.idempotencyKey } }, call);
+        return data[field];
+    };
+    return {
+        async list(options) {
+            const take = options?.limit ?? DEFAULT_PAGE_SIZE;
+            const skip = options?.after === undefined ? 0 : readOffsetCursor(options.after);
+            return listPage(skip, take, options);
+        },
+        async get(id, call) {
+            const data = await transport.graphql({ api: 'admin', query: SUPPLIER_RETURN_QUERY, variables: { id } }, call);
+            return data.supplierReturn;
+        },
+        create(input, call) {
+            return mutate('createSupplierReturn', CREATE_SUPPLIER_RETURN_MUTATION, {
+                input: {
+                    ...picked(input, CREATE_INPUT_FIELDS),
+                    lines: input.lines.map((line) => picked(line, LINE_INPUT_FIELDS)),
+                },
+            }, call);
+        },
+        update(id, input, call) {
+            const fields = { ...picked(input, UPDATE_INPUT_FIELDS), id };
+            if (input.lines !== undefined) {
+                fields.lines = input.lines.map((line) => picked(line, LINE_INPUT_FIELDS));
+            }
+            return mutate('updateSupplierReturn', UPDATE_SUPPLIER_RETURN_MUTATION, { input: fields }, call);
+        },
+        ship(id, input, call) {
+            return mutate('shipSupplierReturn', SHIP_SUPPLIER_RETURN_MUTATION, { input: { ...picked(input, SHIP_INPUT_FIELDS), id } }, call);
+        },
+        resolveLine(input, call) {
+            return mutate('resolveSupplierReturnLine', RESOLVE_SUPPLIER_RETURN_LINE_MUTATION, { input: picked(input, RESOLVE_INPUT_FIELDS) }, call);
+        },
+        cancel(id, options) {
+            return mutate('cancelSupplierReturn', CANCEL_SUPPLIER_RETURN_MUTATION, { id, ...(options?.reason === undefined ? {} : { reason: options.reason }) }, options);
+        },
+        async document(id, call) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: CREATE_SUPPLIER_RETURN_DOCUMENT_URL_MUTATION,
+                variables: { supplierReturnId: id },
+            }, call);
+            return data.createSupplierReturnDocumentUrl;
+        },
+    };
+}

package/dist/quotes/index.d.ts

@@ -65,16 +65,27 @@ export interface QuoteLine {
     discountValue: number;
     discountLabel: string | null;
     position: number;
-    /** The whole-line discount, in the store's primary tax mode. Null while unpriced. */
+    /**
+     * What the converted order takes off the line, in the store's primary tax mode: (`unitPrice` −
+     * `effectiveUnitPrice`) × quantity. It can differ from the typed discount by the per-unit
+     * rounding (€1.00 off 3 × €10.00 takes €0.99). Null while unpriced.
+     */
     discountAmount: number | null;
     /**
      * The per-unit price the converted order line gets: the discounted line total ÷ quantity,
      * rounded. The figure to show as the line's unit price. Null while unpriced.
      */
     effectiveUnitPrice: number | null;
-    /** Net line total after discount. Null while unpriced or when the variant is unavailable. */
+    /**
+     * Net total of the order line the quote converts into. Null while unpriced or when the variant
+     * is unavailable.
+     */
     lineTotal: number | null;
-    /** Gross line total after discount. Null while unpriced or when the variant is unavailable. */
+    /**
+     * Gross total of the order line the quote converts into, at `taxRate`: the order charges
+     * exactly this unless its customer is taxed in another zone or reverse-charged (conversion
+     * then records a `priceNotice`). Null while unpriced or when the variant is unavailable.
+     */
     lineTotalWithTax: number | null;
     /** `lineTotalWithTax − lineTotal`. Null as those are. */
     taxAmount: number | null;
@@ -95,6 +106,12 @@ export interface QuoteStatusLogEntry {
     status: QuoteStatus;
     createdAt: string;
     actorUserId: string | null;
+    /**
+     * What the change recorded. An `approved` row carries the offer the customer was sent
+     * (`offeredSubTotal`, `offeredTotalWithTax`); a `converted_to_order` row the order
+     * (`orderId`, `orderCode`), both totals, and `priceNotice`, a plain-words sentence, when the
+     * order does not total what the quote offered (the order's amount applies).
+     */
     metadata: Record<string, unknown> | null;
 }
 export interface QuoteSalesRepresentative {

package/dist/returns/index.d.ts

@@ -269,6 +269,26 @@ export interface SettleReturnInput {
     shippingRefundAmount?: number | null;
     /** Recorded on the refund and the return's history. */
     reason?: string | null;
+    /**
+     * `account` in a store whose book is store credit (`settlementOptions`' `account.book`
+     * `STORE_CREDIT`): whether the customer expressly agreed to store credit instead of a refund to
+     * their payment (EU consumer law, CRD art. 13(1)), as staff recorded it. The move records it on
+     * its ledger entries (`StoredValueEntry.customerAgreed`); never a condition, nothing is refused
+     * for it. Part of the request: a repeat under the same key sends the same answer. Sent only when
+     * given; an engine before the field (incentives sprint 8 PR 6a) refuses a call that gives it.
+     */
+    customerAgreed?: boolean | null;
+    /**
+     * The VAT rate, a percentage from 0 to 100, that the return's invoice credit note states: the
+     * note splits its lump sum at that rate (USER PD11). {@link ReturnSettlementOptions.creditNoteTaxRate}
+     * suggests one and lists the rates to pick. Used only where the settlement issues an invoice
+     * credit note (the methods `creditNoteTaxRate.methods` names). Left out, the note splits as the
+     * order allows. Outside 0 to 100:
+     * `RETURN_SETTLE_INPUT_INVALID` (`details[0].code` `NOT_A_RATE`) before anything moves. Part of
+     * the request: a repeat under the same key sends the same rate. Sent only when given; an engine
+     * before the field (whose plan has no `creditNoteTaxRate`) refuses a call that gives it.
+     */
+    taxRate?: number | null;
 }
 /** The store's RMA code format: `{prefix}{year}{number}{suffix}`, e.g. `RMA-000042`. */
 export interface ReturnNumberingConfig {
@@ -433,6 +453,34 @@ export interface ReturnSettlementAccountOption {
      */
     book?: 'AR' | 'STORE_CREDIT' | 'NONE' | (string & {}) | null;
 }
+/** Why the plan suggests the credit note's VAT rate it does. */
+export type ReturnCreditNoteTaxRateBasis = 'RETURNED_GOODS' | 'ORDER_MAIN_RATE';
+/** The VAT rate a return's invoice credit note states, which staff pick (USER PD11). */
+export interface ReturnCreditNoteTaxRateOption {
+    /** The rate to preselect, a percentage. */
+    suggested: number;
+    /**
+     * `RETURNED_GOODS`: every returned item carries this rate. `ORDER_MAIN_RATE`: the rate carrying
+     * most of the order's money, shipping included.
+     */
+    basis: ReturnCreditNoteTaxRateBasis | (string & {});
+    /** The rates to pick from, ascending, each once: the store's own, the order's and the suggestion. */
+    rates: number[];
+    /**
+     * The methods whose settlement issues the invoice credit note that takes the rate: ask for the
+     * rate on these only (a refund the accounts ledger documents, or an accounts store's own credit
+     * note, takes none).
+     */
+    methods: Array<ReturnSettlementMethod | (string & {})>;
+    /**
+     * The gross (minor units) of the invoice the note credits, when a settlement can still credit
+     * ALL of it; null once an earlier credit note took part of it, or when the engine does not
+     * know. A settlement reaching it credits the whole invoice: leave `taxRate` out and the note
+     * states the invoice's own VAT rows per rate, which no single rate can. Absent from an engine
+     * before it.
+     */
+    invoiceTotal?: number | null;
+}
 export interface ReturnSettlementOptions {
     returnId: string;
     currencyCode: string;
@@ -495,6 +543,14 @@ export interface ReturnSettlementOptions {
      * 2026-10-10 (the method does not exist there).
      */
     account?: ReturnSettlementAccountOption;
+    /**
+     * The VAT rate for the invoice credit note a settlement issues: the suggestion, the rates to
+     * pick and the methods that issue the note (send the pick as {@link SettleReturnInput.taxRate}).
+     * Null when no settlement of it issues an invoice credit note (the order has no invoice) or
+     * nothing can be suggested. Absent from an engine before it: that engine refuses
+     * `taxRate`, so leave it out.
+     */
+    creditNoteTaxRate?: ReturnCreditNoteTaxRateOption | null;
 }
 export declare const RETURN_QUERY = "\n  query SdkOrderReturn($id: ID!) {\n    orderReturn(id: $id) {\n      \n    id\n    code\n    channelId\n    orderId\n    orderCode\n    customerId\n    currencyCode\n    state\n    initiator\n    customerNote\n    adminNote\n    preferredSettlementMethod\n    settlementMethod\n    shippingRefundAmount\n    settledAmount\n    refundId\n    creditNoteId\n    creditNoteNumber\n    requestedAt\n    resolvedAt\n    createdAt\n    updatedAt\n    lines {\n      id\n      returnId\n      orderLineId\n      productVariantId\n      productVariantName\n      productVariantSku\n      requestedQty\n      approvedQty\n      receivedQty\n      restockQty\n      writeOffQty\n      restockLocationId\n      reasonCode\n      reasonNote\n      unitPriceWithTax\n      unitPriceWithTaxUnrounded\n      refundAmount\n      createdAt\n      updatedAt\n    }\n\n      alreadyCreditedBy {\n        \n        creditNoteId\n        creditNoteNumber\n        ledger\n\n      }\n      \n      history {\n        state\n        actor\n        actorUserId\n        reason\n        createdAt\n      }\n\n      \n    refundEstimate\n    customer {\n      id\n      firstName\n      lastName\n      emailAddress\n      addresses {\n        company\n        defaultBillingAddress\n        defaultShippingAddress\n      }\n    }\n    lines {\n      refundEstimate\n    }\n\n      allowedActions {\n        action\n        allowed\n        reasonCode\n      }\n    }\n  }\n";
 /**
@@ -530,7 +586,12 @@ export declare const RETURN_ELIGIBILITY_QUERY = "\n  query SdkReturnEligibility(
  * `creditedQty`/`correctionCredits`: GraphQL refuses a whole document over one unknown field.
  */
 export declare const RETURN_ELIGIBILITY_QUERY_LEGACY = "\n  query SdkReturnEligibilityLegacy($orderId: ID!) {\n    returnEligibilityForOrder(orderId: $orderId) {\n      orderId\n      eligible\n      reason\n      returnWindowEndsAt\n      lines {\n        orderLineId\n        productVariantId\n        productVariantName\n        productVariantSku\n        fulfilledQty\n        returnableQty\n        unitPriceWithTax\n        unitPriceWithTaxUnrounded\n      }\n    }\n  }\n";
-export declare const RETURN_SETTLEMENT_OPTIONS_QUERY = "\n  query SdkReturnSettlementOptions($returnId: ID!) {\n    returnSettlementOptions(returnId: $returnId) {\n      returnId\n      currencyCode\n      settleable\n      blockedBy\n      refund {\n        available\n        reasonCode\n        payments {\n          paymentId\n          method\n          refundable\n        }\n      }\n      creditNote {\n        available\n        ledger\n        reasonCode\n        invoiceNumber\n      }\n      account {\n        available\n        reasonCode\n        message\n        held\n        book\n      }\n      initialMethod\n      defaultAmount\n      amountCeiling\n      correctionCredits {\n        \n          orderLineId\n          creditNoteId\n          creditNoteNumber\n          ledger\n          quantity\n          amount\n\n      }\n      shippingCeiling\n      alreadyCredited {\n        available\n        reasonCode\n        creditNotes {\n          \n        creditNoteId\n        creditNoteNumber\n        ledger\n\n        }\n      }\n    }\n  }\n";
+export declare const RETURN_SETTLEMENT_OPTIONS_QUERY = "\n  query SdkReturnSettlementOptions($returnId: ID!) {\n    returnSettlementOptions(returnId: $returnId) {\n      returnId\n      currencyCode\n      settleable\n      blockedBy\n      refund {\n        available\n        reasonCode\n        payments {\n          paymentId\n          method\n          refundable\n        }\n      }\n      creditNote {\n        available\n        ledger\n        reasonCode\n        invoiceNumber\n      }\n      account {\n        available\n        reasonCode\n        message\n        held\n        book\n      }\n      initialMethod\n      defaultAmount\n      amountCeiling\n      correctionCredits {\n        \n          orderLineId\n          creditNoteId\n          creditNoteNumber\n          ledger\n          quantity\n          amount\n\n      }\n      shippingCeiling\n      alreadyCredited {\n        available\n        reasonCode\n        creditNotes {\n          \n        creditNoteId\n        creditNoteNumber\n        ledger\n\n        }\n      }\n      creditNoteTaxRate {\n        suggested\n        basis\n        rates\n        methods\n        invoiceTotal\n      }\n    }\n  }\n";
+/**
+ * {@link RETURN_SETTLEMENT_OPTIONS_QUERY} for an engine with the account's book but released before
+ * the credit note's VAT rate (USER PD11, B6b).
+ */
+export declare const RETURN_SETTLEMENT_OPTIONS_QUERY_BEFORE_TAX_RATE = "\n  query SdkReturnSettlementOptionsBeforeTaxRate($returnId: ID!) {\n    returnSettlementOptions(returnId: $returnId) {\n      returnId\n      currencyCode\n      settleable\n      blockedBy\n      refund {\n        available\n        reasonCode\n        payments {\n          paymentId\n          method\n          refundable\n        }\n      }\n      creditNote {\n        available\n        ledger\n        reasonCode\n        invoiceNumber\n      }\n      account {\n        available\n        reasonCode\n        message\n        held\n        book\n      }\n      initialMethod\n      defaultAmount\n      amountCeiling\n      correctionCredits {\n        \n          orderLineId\n          creditNoteId\n          creditNoteNumber\n          ledger\n          quantity\n          amount\n\n      }\n      shippingCeiling\n      alreadyCredited {\n        available\n        reasonCode\n        creditNotes {\n          \n        creditNoteId\n        creditNoteNumber\n        ledger\n\n        }\n      }\n    }\n  }\n";
 /**
  * {@link RETURN_SETTLEMENT_OPTIONS_QUERY} for an engine with `alreadyCredited` but released before
  * the account option named the store's book (incentives sprint 8 PR 4).

package/dist/returns/index.js

@@ -12,6 +12,7 @@
  * unknown value as "not available".
  */
 import { NotFoundError, ValidationError } from '@sixtyninecommerce/core';
+import { statedCustomerAgreed } from '../payments/customer-consent.js';
 /** A return's state: the latest row of its status log. */
 export const RETURN_STATES = [
     'requested',
@@ -392,6 +393,63 @@ export const RETURN_ELIGIBILITY_QUERY_LEGACY = /* GraphQL */ `
 `;
 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
+      }
+      account {
+        available
+        reasonCode
+        message
+        held
+        book
+      }
+      initialMethod
+      defaultAmount
+      amountCeiling
+      correctionCredits {
+        ${CORRECTION_CREDIT_FIELDS}
+      }
+      shippingCeiling
+      alreadyCredited {
+        available
+        reasonCode
+        creditNotes {
+          ${COVERING_CREDIT_NOTE_FIELDS}
+        }
+      }
+      creditNoteTaxRate {
+        suggested
+        basis
+        rates
+        methods
+        invoiceTotal
+      }
+    }
+  }
+`;
+/**
+ * {@link RETURN_SETTLEMENT_OPTIONS_QUERY} for an engine with the account's book but released before
+ * the credit note's VAT rate (USER PD11, B6b).
+ */
+export const RETURN_SETTLEMENT_OPTIONS_QUERY_BEFORE_TAX_RATE = /* GraphQL */ `
+  query SdkReturnSettlementOptionsBeforeTaxRate($returnId: ID!) {
     returnSettlementOptions(returnId: $returnId) {
       returnId
       currencyCode
@@ -646,6 +704,7 @@ function isUnknownFieldRejection(error) {
 /** The plan's documents, newest first: each drops the newest field the one before it asks. */
 const SETTLEMENT_OPTIONS_DOCUMENTS = [
     RETURN_SETTLEMENT_OPTIONS_QUERY,
+    RETURN_SETTLEMENT_OPTIONS_QUERY_BEFORE_TAX_RATE,
     RETURN_SETTLEMENT_OPTIONS_QUERY_BEFORE_BOOK,
     RETURN_SETTLEMENT_OPTIONS_QUERY_BEFORE_CLOSE,
     RETURN_SETTLEMENT_OPTIONS_QUERY_BEFORE_ACCOUNT,
@@ -788,6 +847,8 @@ export function createReturnsModule(transport) {
                             ? { shippingRefundAmount: input.shippingRefundAmount }
                             : {}),
                         ...(input.reason != null ? { reason: input.reason } : {}),
+                        ...statedCustomerAgreed(input.customerAgreed),
+                        ...(input.taxRate != null ? { taxRate: input.taxRate } : {}),
                     },
                     // A variable, not a header: the Admin API takes the key as an argument. `undefined`
                     // when omitted, never null: `JSON.stringify` drops it, so no key stays off the wire.

package/dist/seo/config.d.ts

@@ -0,0 +1,128 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import type { SettingsSourceKind } from '../tenant/settings-sources.js';
+import type { Call } from '../types.js';
+/**
+ * How often the SEO audit (the storefront crawl included) runs. Mirrors `@IsIn` on the plugins
+ * service's `UpdateSeoConfigDto` and the meta catalog's `SEO_CRAWL_SCHEDULES`, pinned by
+ * `__tests__/seo-config.spec.ts`.
+ */
+export declare const SEO_CRAWL_SCHEDULES: readonly ["off", "daily", "weekly"];
+export type SeoCrawlSchedule = (typeof SEO_CRAWL_SCHEDULES)[number];
+/**
+ * The ACTIVE store's SEO automation, as the plugins service applies it. The switches
+ * (`autoRedirectsEnabled`, `indexnowEnabled`, `cruxEnabled`, the crawl settings) are part of the
+ * `settings.seo` group: while the store takes the group from its organization they are the
+ * organization's, and `source` says so. The IndexNow key and the Search Console connection are
+ * always the store's own.
+ *
+ * The keys follow the service's wire names camelised (`indexnow_enabled` → `indexnowEnabled`), as
+ * the meta catalog's `seo` schema publishes them, so a head that renders that schema maps each
+ * property mechanically.
+ */
+export interface SeoConfig {
+    /** Changed URLs are submitted to IndexNow (needs {@link SeoConfig.indexnowKey} to send any). */
+    indexnowEnabled: boolean;
+    /** The store's IndexNow key, served at `/<key>.txt`; null until one is generated. */
+    indexnowKey: string | null;
+    /** The Search Console property the store connected; null when none. */
+    gscPropertyUrl: string | null;
+    /** The store holds a Search Console connection. The credential itself is never answered. */
+    gscConnected: boolean;
+    /** When the connection was made (ISO 8601, UTC); null when there is none. */
+    gscConnectedAt: string | null;
+    /** Core Web Vitals (CrUX). Stored and shown; nothing on the platform reads it yet. */
+    cruxEnabled: boolean;
+    /** A string on the wire: a newer service may answer a schedule this SDK does not name yet. */
+    crawlSchedule: SeoCrawlSchedule | (string & {});
+    /** The most storefront pages one audit crawls (10 to 5,000). */
+    crawlMaxPages: number;
+    /** How fast the audit crawls, in pages per second (1 to 10). */
+    crawlRatePerSec: number;
+    /** A renamed product, collection or page keeps its old URL alive with a redirect. */
+    autoRedirectsEnabled: boolean;
+    /** `organization` while the switches above are the organization's, else `channel`. */
+    source: SettingsSourceKind | (string & {});
+    /** The organization locks `settings.seo`: {@link SeoConfigModule.set} refuses any change. */
+    locked: boolean;
+    /** The store keeps its own switches although the organization shares the group. */
+    overridden: boolean;
+    /** The organization shares the group without locking it, so the store may override it. */
+    inheritable: boolean;
+    /** The store's organization; null for a store outside any organization. */
+    organizationName: string | null;
+}
+/** The switches {@link SeoConfigModule.set} changes; a key left out keeps its value. */
+export interface SeoConfigPatch {
+    indexnowEnabled?: boolean;
+    cruxEnabled?: boolean;
+    crawlSchedule?: SeoCrawlSchedule;
+    /** A whole number from 10 to 5,000. */
+    crawlMaxPages?: number;
+    /** A whole number from 1 to 10. */
+    crawlRatePerSec?: number;
+    autoRedirectsEnabled?: boolean;
+}
+/** What {@link SeoConfigModule.rotateIndexnowKey} answers. */
+export interface IndexnowKeyRotation {
+    /** The new key. The store's `/<key>.txt` serves it from now on; the old key is void. */
+    key: string;
+}
+/**
+ * `admin.seo.config` — the ACTIVE store's SEO automation on the plugins service (Settings → SEO):
+ * automatic redirects, IndexNow, Core Web Vitals and the audit schedule. Needs the store's `seo`
+ * plugin: without it every method is `PermissionDeniedError` (403) naming the plugin.
+ *
+ * The other half of the store's SEO settings, the channel defaults (storefront URL, share and AI
+ * crawler defaults), is `admin.seo.settings`.
+ */
+export interface SeoConfigModule {
+    /**
+     * The automation as the service applies it, and where its switches come from. Needs
+     * `ReadSettings`.
+     *
+     * @effect read
+     * @permission ReadSettings
+     */
+    get(options?: Call): Promise<SeoConfig>;
+    /**
+     * Change the switches `patch` names, and answer the whole configuration as it now applies.
+     * The next audit, URL change or IndexNow submission follows it.
+     *
+     * **Coded refusals:**
+     * - `SEO_CONFIG_INVALID` → `ValidationError` (400), before any request: an empty patch, a
+     *   key that is not a switch here (the IndexNow key and Search Console have doors of their
+     *   own), or a null (no switch can be cleared). One `details[]` entry per key, `field` naming
+     *   it.
+     * - `VALIDATION_FAILED` → `ValidationError` (400), from the service: a value of the wrong type,
+     *   a schedule outside {@link SEO_CRAWL_SCHEDULES}, or a number outside its range.
+     * - `MANAGED_BY_ORGANIZATION` → `BusinessRuleError` (422): a changed switch while the
+     *   organization locks `settings.seo`.
+     * - `ORGANIZATION_SETTINGS_INHERITED` → `BusinessRuleError` (422): a changed switch while the
+     *   store inherits the group; `tenant.settingsSources.override('settings.seo')` first. Sending
+     *   back the values `get` answered is not a change and passes.
+     * - `ORGANIZATION_SETTINGS_SWITCH_OFF_CONFLICT` → `ConflictError` (409): in an organization's
+     *   workspace, while the organization is switching its SEO defaults off and copying them into
+     *   its stores. Nothing changed; try again once that finishes.
+     * - `PermissionDeniedError` (403): the credential lacks `UpdateSettings`.
+     *
+     * @effect write
+     * @permission UpdateSettings
+     */
+    set(patch: SeoConfigPatch, options?: Call): Promise<SeoConfig>;
+    /**
+     * Generate a new IndexNow key for the store and answer it. The old key is void at once: the
+     * store's `/<key>.txt` serves only the new one, and submissions use it from now on. The key is
+     * the store's own, so it is never refused for a store taking `settings.seo` from its
+     * organization.
+     *
+     * **Coded refusals:**
+     * - `ORGANIZATION_WORKSPACE_NOT_A_STORE` → `BusinessRuleError` (422): the active store is an
+     *   organization's workspace, which has no storefront to prove.
+     * - `PermissionDeniedError` (403): the credential lacks `UpdateSettings`.
+     *
+     * @effect destructive
+     * @permission UpdateSettings
+     */
+    rotateIndexnowKey(options?: Call): Promise<IndexnowKeyRotation>;
+}
+export declare function createSeoConfigModule(transport: Transport): SeoConfigModule;

package/dist/seo/config.js

@@ -0,0 +1,95 @@
+import { ValidationError } from '@sixtyninecommerce/core';
+/**
+ * How often the SEO audit (the storefront crawl included) runs. Mirrors `@IsIn` on the plugins
+ * service's `UpdateSeoConfigDto` and the meta catalog's `SEO_CRAWL_SCHEDULES`, pinned by
+ * `__tests__/seo-config.spec.ts`.
+ */
+export const SEO_CRAWL_SCHEDULES = ['off', 'daily', 'weekly'];
+const INVALID = 'SEO_CONFIG_INVALID';
+const PATCH_KEYS = [
+    'indexnowEnabled',
+    'cruxEnabled',
+    'crawlSchedule',
+    'crawlMaxPages',
+    'crawlRatePerSec',
+    'autoRedirectsEnabled',
+];
+const KNOWN_KEYS = new Set(PATCH_KEYS);
+/** Not a switch: answered by `get`, written through a door of its own. */
+const OWN_DOORS = {
+    indexnowKey: 'indexnowKey is generated by rotateIndexnowKey(), never set.',
+    gscPropertyUrl: 'Search Console is connected through its OAuth flow, never set here.',
+    gscConnected: 'Search Console is connected through its OAuth flow, never set here.',
+    gscConnectedAt: 'Search Console is connected through its OAuth flow, never set here.',
+};
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+function problemsOf(patch) {
+    const problems = [];
+    const add = (field, message) => problems.push({ field, code: INVALID, message });
+    if (!isRecord(patch)) {
+        add('patch', 'Pass the switches to change as an object, e.g. { autoRedirectsEnabled: false }.');
+        return problems;
+    }
+    const named = Object.keys(patch).filter((key) => patch[key] !== undefined);
+    if (named.length === 0) {
+        add('patch', `Name at least one switch to change: ${PATCH_KEYS.join(', ')}.`);
+    }
+    for (const key of named) {
+        if (!KNOWN_KEYS.has(key)) {
+            add(key, OWN_DOORS[key] ??
+                `${key} is not an SEO automation switch; they are ${PATCH_KEYS.join(', ')}.`);
+        }
+        else if (patch[key] === null) {
+            // The service's validation lets a null through to a NOT NULL column, whose refusal names
+            // no field (the meta catalog's `SEO_NULL`); nothing here has a "cleared" state.
+            add(key, `${key} cannot be cleared; send a value, or leave it out to keep it.`);
+        }
+    }
+    return problems;
+}
+/**
+ * The camelised wire body, its source fields filled in: they came with #882, and a service from
+ * before it leaves them out, which is the store's own settings. Every other field is the
+ * service's, as answered.
+ */
+function configOf(body) {
+    return {
+        ...body,
+        source: body.source ?? 'channel',
+        locked: body.locked === true,
+        overridden: body.overridden === true,
+        inheritable: body.inheritable === true,
+        organizationName: body.organizationName ?? null,
+    };
+}
+export function createSeoConfigModule(transport) {
+    return {
+        async get(options) {
+            return configOf(await transport.rest('plugins', { method: 'GET', path: '/seo/config' }, options));
+        },
+        async set(patch, options) {
+            const problems = problemsOf(patch);
+            if (problems.length > 0) {
+                throw new ValidationError({
+                    code: INVALID,
+                    message: problems.map((problem) => problem.message).join(' '),
+                    status: 400,
+                    service: 'plugins',
+                    details: problems,
+                });
+            }
+            // Only the named switches go out. The transport snake-cases them, and every key here
+            // camelises from a wire name, so the round trip is exact (`indexnowEnabled` →
+            // `indexnow_enabled`); a key spelt any other way would be refused whole by the service.
+            const body = {};
+            for (const key of PATCH_KEYS) {
+                if (patch[key] !== undefined)
+                    body[key] = patch[key];
+            }
+            return configOf(await transport.rest('plugins', { method: 'PUT', path: '/seo/config', body }, options));
+        },
+        rotateIndexnowKey(options) {
+            return transport.rest('plugins', { method: 'POST', path: '/seo/config/indexnow-key/rotate' }, options);
+        },
+    };
+}