@aglyn/plugins-commerce 1.0.0-beta.220 → 1.0.0-beta.222

package/src/lib/transfer/gift-cards.server.js

@@ -0,0 +1,296 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { planTransferUndo } from "@aglyn/aglyn/data-transfer";
+import { firebaseAdmin, getOrgForHost, logHostActivity, resolveOrgMembership } from "@aglyn/tenant-data-admin";
+import { TransferEngineError, TransferPlanRefusedError } from "@aglyn/tenant-data-admin/server/transfer-jobs";
+import { hostRoleFor } from "@aglyn/aglyn/app-utils/organizations";
+import { transferImportRoleAllowed, transferImportRoleRefusal } from "@aglyn/aglyn/data-transfer";
+import { declaredTransferResource } from "@aglyn/aglyn/plugin-manager/plugin-transfer-resources";
+import { COMMERCE_GIFT_CARDS_TRANSFER } from "./transfer-keys.js";
+import { giftCardsPlanRefusal } from "./gift-cards-plan.js";
+import { giftCardCodeOf, giftCardRedeemed } from "../model/commerce-gift-cards.js";
+import { GIFT_CARD_ACTIVITY_TYPE, GiftCardIssueRefusal, giftCardActivityName, issueGiftCard, mintGiftCardCode } from "../server/gift-card-issue.js";
+import { GIFT_CARD_MATCH_KEYS, GIFT_CARD_UNDO_FIELDS, giftCardRecord, planGiftCardRows, planWithCreateRequired, readGiftCardConfirmation } from "./records-transfer.js";
+import { readableRecords } from "./records.server.js";
+import { ROW_BUDGET_MS, firestoreOf, hostRefOf } from "./server-common.js";
+/** A code that could be a card's: the document id `in` query refuses anything with a slash. */ const CARD_ID = /^[A-Z0-9][A-Z0-9_-]*$/;
+const GIFT_CARDS = {
+    collection: (firestore, ctx)=>hostRefOf(firestore, ctx).collection('giftCards'),
+    record: (id, data)=>giftCardRecord(id, data),
+    matchValues: (id)=>({
+            id,
+            code: id
+        }),
+    // A card's code is its document id: a code is looked up by id. A value
+    // that cannot be a code still asks one id no card holds, rather than an
+    // empty `in`, which the store refuses.
+    find: {
+        code: (collection, values)=>{
+            const codes = values.map((value)=>giftCardCodeOf(value)).filter((code)=>CARD_ID.test(code));
+            return collection.where(firebaseAdmin.firestore.FieldPath.documentId(), 'in', codes.length ? codes : [
+                '-'
+            ]);
+        }
+    }
+};
+/** The member importing, checked for the role and the plan, or the refusal. */ async function issuerOf(ctx) {
+    var _ref;
+    var _membership_member;
+    const hostId = ctx.hostId;
+    if (!hostId) throw new TransferEngineError('invalid', 400, 'Gift cards belong to a site; name the site.');
+    const uid = ctx.actorUid;
+    const membership = uid ? await resolveOrgMembership(uid, ctx.orgId) : null;
+    // The declaration's `importRoles` (AGL-3554), which the transfer gate
+    // asked already; asked again here for the sweep that resumes an import.
+    const declared = declaredTransferResource(COMMERCE_GIFT_CARDS_TRANSFER);
+    const role = (membership == null ? void 0 : membership.member) ? hostRoleFor(membership.member, hostId) : null;
+    if (!uid || !declared || !transferImportRoleAllowed('import', declared, role)) {
+        throw new TransferEngineError('forbidden', 403, declared ? transferImportRoleRefusal(declared) : 'Gift cards can’t be imported here.');
+    }
+    const owner = await getOrgForHost(hostId).catch(()=>null);
+    // The transfer gate asked already (the resource's `planGate`); asked again
+    // here, in the same words, for the sweep that resumes an import.
+    const refusal = giftCardsPlanRefusal(owner == null ? void 0 : owner.org);
+    if (refusal) throw new TransferPlanRefusedError(refusal);
+    const email = (_ref = membership == null ? void 0 : (_membership_member = membership.member) == null ? void 0 : _membership_member.email) != null ? _ref : null;
+    return {
+        hostId,
+        uid,
+        email,
+        ownerOrg: owner == null ? void 0 : owner.org
+    };
+}
+/** The codes among `codes` that a card on the site already holds. */ async function takenCodes(firestore, ctx, codes) {
+    const collection = GIFT_CARDS.collection(firestore, ctx);
+    const taken = new Set();
+    const ids = [
+        ...new Set(codes.filter((code)=>CARD_ID.test(code)))
+    ];
+    for(let at = 0; at < ids.length; at += 100){
+        for (const doc of (await firestore.getAll(...ids.slice(at, at + 100).map((id)=>collection.doc(id))))){
+            if (doc.exists) taken.add(doc.id);
+        }
+    }
+    return taken;
+}
+/**
+ * The dry run: the core's plan with a Balance required of every card, made
+ * into the cards it issues. The codes the file names are read once, so a
+ * code another card holds — however the file spaced or cased it — is never
+ * planned as a new card.
+ */ export async function planGiftCards(ctx, input) {
+    await issuerOf(ctx);
+    const firestore = firestoreOf();
+    const rows = input.rows.map((row)=>'code' in row.values ? _extends({}, row, {
+            values: _extends({}, row.values, {
+                code: giftCardCodeOf(row.values['code']) || null
+            })
+        }) : row);
+    const taken = await takenCodes(firestore, ctx, rows.map((row)=>{
+        var _row_values_code;
+        return String((_row_values_code = row.values['code']) != null ? _row_values_code : '');
+    }));
+    return planGiftCardRows(planWithCreateRequired(_extends({}, input, {
+        rows
+    }), [
+        'balance'
+    ]), {
+        confirmation: readGiftCardConfirmation(ctx.extras),
+        mintCode: mintGiftCardCode,
+        taken
+    });
+}
+/** Whether the card under `code` is the one this job's `row` issued: a retried chunk finds its own card. */ async function issuedByRow(firestore, ctx, code, row) {
+    const doc = await GIFT_CARDS.collection(firestore, ctx).doc(code).get();
+    return doc.exists && doc.get('importJobId') === ctx.jobId && doc.get('importRow') === row;
+}
+/** Issues one chunk's cards, each through the Gift cards card's own issue path. */ export async function applyGiftCards(ctx, chunk, writer) {
+    const issuer = await issuerOf(ctx);
+    const confirmation = readGiftCardConfirmation(ctx.extras);
+    const firestore = firestoreOf();
+    const results = [];
+    const undo = [];
+    const refuse = async (row, message)=>{
+        const result = {
+            row,
+            outcome: 'failed',
+            reason: 'refusedValue',
+            message
+        };
+        results.push(result);
+        await writer.markApplied(result);
+    };
+    for (const row of chunk.rows){
+        var _issued_data;
+        const earlier = await writer.alreadyApplied(row.index);
+        if (earlier) {
+            results.push(earlier);
+            continue;
+        }
+        if (writer.timeLeftMs() < ROW_BUDGET_MS) break;
+        const card = row.giftCard;
+        if (row.verdict !== 'create' || !card) {
+            await refuse(row.index, 'A gift card import only issues new cards; it never changes one.');
+            continue;
+        }
+        if (card.problem) {
+            await refuse(row.index, card.problem);
+            continue;
+        }
+        // The typed total, read again here: the plan's verdict is not enough.
+        if (!card.confirmed || !confirmation || confirmation.totalCents !== card.totalCents) {
+            await refuse(row.index, 'The total value was not confirmed, so no card was issued. Confirm the total and import again.');
+            continue;
+        }
+        try {
+            var _ctx_jobId;
+            await issueGiftCard({
+                firestore,
+                hostId: issuer.hostId,
+                amountCents: card.amountCents,
+                recipientEmail: card.recipientEmail,
+                note: card.note,
+                code: card.code,
+                issuer: {
+                    uid: issuer.uid,
+                    email: issuer.email
+                },
+                email: confirmation.email,
+                ownerOrg: issuer.ownerOrg,
+                source: {
+                    importJobId: (_ctx_jobId = ctx.jobId) != null ? _ctx_jobId : '',
+                    importRow: row.index
+                }
+            });
+        } catch (error) {
+            if (!(error instanceof GiftCardIssueRefusal)) throw error;
+            // A retry after the card landed and before its row was recorded.
+            if (!(error.reason === 'taken' && await issuedByRow(firestore, ctx, card.code, row.index))) {
+                await refuse(row.index, error.message);
+                continue;
+            }
+        }
+        const issued = await GIFT_CARDS.collection(firestore, ctx).doc(card.code).get();
+        const record = giftCardRecord(card.code, (_issued_data = issued.data()) != null ? _issued_data : {});
+        const result = {
+            row: row.index,
+            outcome: 'created',
+            recordId: card.code
+        };
+        const entry = {
+            row: row.index,
+            recordId: card.code,
+            action: 'created',
+            written: Object.fromEntries(GIFT_CARD_UNDO_FIELDS.map((fieldId)=>{
+                var _record_fieldId;
+                return [
+                    fieldId,
+                    (_record_fieldId = record[fieldId]) != null ? _record_fieldId : null
+                ];
+            }))
+        };
+        results.push(result);
+        undo.push(entry);
+        await writer.markApplied(result, entry);
+    }
+    return {
+        results,
+        undo
+    };
+}
+/**
+ * Undoes one chunk: each card voided — zeroed, never deleted — when nobody
+ * has spent from it; a spent or held card is a conflict that stays as it is,
+ * whatever the person decided, because a shopper holds that money.
+ */ export async function revertGiftCards(ctx, snapshot) {
+    const issuer = await issuerOf(ctx);
+    const firestore = firestoreOf();
+    const collection = GIFT_CARDS.collection(firestore, ctx);
+    const done = [];
+    const conflicts = [];
+    for (const entry of [
+        ...snapshot.entries
+    ].reverse()){
+        const ref = collection.doc(entry.recordId);
+        const step = await firestore.runTransaction(async (tx)=>{
+            var _doc_data, _ctx_jobId;
+            const doc = await tx.get(ref);
+            if (!doc.exists) return {
+                action: 'nothing',
+                recordId: entry.recordId,
+                why: 'gone'
+            };
+            const card = (_doc_data = doc.data()) != null ? _doc_data : {};
+            if (Number(card.voidedAtMs) > 0) return {
+                action: 'nothing',
+                recordId: entry.recordId,
+                why: 'alreadyReverted'
+            };
+            if (giftCardRedeemed(card)) {
+                const planned = planTransferUndo(entry, giftCardRecord(entry.recordId, card));
+                return {
+                    action: 'conflict',
+                    recordId: entry.recordId,
+                    fields: planned.action === 'conflict' ? planned.fields : [
+                        'balance'
+                    ],
+                    values: {}
+                };
+            }
+            tx.set(ref, {
+                balanceCents: 0,
+                voidedAtMs: Date.now(),
+                voidedBy: issuer.uid,
+                voidedByImportUndo: (_ctx_jobId = ctx.jobId) != null ? _ctx_jobId : null
+            }, {
+                merge: true
+            });
+            return {
+                action: 'delete',
+                recordId: entry.recordId
+            };
+        });
+        if (step.action === 'conflict') {
+            conflicts.push(step);
+            continue;
+        }
+        if (step.action === 'delete') {
+            await logHostActivity(issuer.hostId, {
+                uid: issuer.uid,
+                email: issuer.email
+            }, 'Voided gift card: import undone', {
+                type: GIFT_CARD_ACTIVITY_TYPE,
+                id: entry.recordId,
+                name: giftCardActivityName(entry.recordId)
+            });
+        }
+        done.push(step);
+    }
+    return {
+        done,
+        conflicts
+    };
+}
+export const giftCardsTransfer = _extends({
+    matchKeys: GIFT_CARD_MATCH_KEYS
+}, readableRecords(GIFT_CARDS), {
+    plan: (ctx, input)=>planGiftCards(ctx, input),
+    apply: (ctx, chunk, writer)=>applyGiftCards(ctx, chunk, writer),
+    revert: (ctx, snapshot)=>revertGiftCards(ctx, snapshot)
+});
+
+//# sourceMappingURL=gift-cards.server.js.map

package/src/lib/transfer/gift-cards.server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/transfer/gift-cards.server.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  planTransferUndo,\n  type BuildTransferPlanInput,\n  type TransferChunk,\n  type PlannedTransferRow,\n  type TransferPlan,\n  type TransferRowResult,\n  type TransferUndoEntry,\n  type TransferUndoSnapshot,\n  type TransferUndoStep,\n} from '@aglyn/aglyn/data-transfer'\nimport type {\n  PluginTransferResource,\n  TransferApplyResult,\n  TransferApplyWriter,\n  TransferResourceContext,\n  TransferRevertResult,\n} from '@aglyn/aglyn/plugin-manager/plugin-transfer-resources'\nimport { firebaseAdmin, getOrgForHost, logHostActivity, resolveOrgMembership } from '@aglyn/tenant-data-admin'\nimport { TransferEngineError, TransferPlanRefusedError } from '@aglyn/tenant-data-admin/server/transfer-jobs'\nimport { hostRoleFor } from '@aglyn/aglyn/app-utils/organizations'\nimport { transferImportRoleAllowed, transferImportRoleRefusal } from '@aglyn/aglyn/data-transfer'\nimport { declaredTransferResource } from '@aglyn/aglyn/plugin-manager/plugin-transfer-resources'\nimport { COMMERCE_GIFT_CARDS_TRANSFER } from './transfer-keys'\nimport { giftCardsPlanRefusal } from './gift-cards-plan'\nimport { giftCardCodeOf, giftCardRedeemed } from '../model/commerce-gift-cards'\nimport {\n  GIFT_CARD_ACTIVITY_TYPE,\n  GiftCardIssueRefusal,\n  giftCardActivityName,\n  issueGiftCard,\n  mintGiftCardCode,\n} from '../server/gift-card-issue'\nimport {\n  GIFT_CARD_MATCH_KEYS,\n  GIFT_CARD_UNDO_FIELDS,\n  giftCardRecord,\n  planGiftCardRows,\n  planWithCreateRequired,\n  readGiftCardConfirmation,\n  type GiftCardPlannedRow,\n  type StoredGiftCard,\n} from './records-transfer'\nimport { readableRecords, type RecordsSpec } from './records.server'\nimport { ROW_BUDGET_MS, firestoreOf, hostRefOf, type Firestore } from './server-common'\n\n/*\n * THE GIFT CARD IMPORT'S SERVER HALF (AGL-3551). A file issues cards; it\n * never writes a balance. The plan (`planGiftCardRows`) decides each card and\n * the total; this module makes the three promises the dry run states:\n *\n * - WHO: the workspace's owners and admins, and a site's admins (the\n *   declaration's `importRoles: [\"admin\"]`, AGL-3554), on a plan that\n *   includes gift cards. The plan,\n *   the apply and the undo each ask again, server-side.\n * - HOW: each card through `issueGiftCard`, the Gift cards card's own issue\n *   path — so its amount is bounded, its code is created and never\n *   overwritten, its activity line is written — and only when the total the\n *   person typed on the Confirm step is the total the plan counted.\n * - UNDO: a card nobody has spent from is voided (zeroed, never deleted,\n *   AGL-1767). A card with a redemption, or a checkout holding part of it,\n *   is reported as a conflict and left as it is, whatever the decision says:\n *   that money has been spent, or is being spent, by a shopper.\n */\n\ntype Doc = Record<string, unknown>\n\n/** A code that could be a card's: the document id `in` query refuses anything with a slash. */\nconst CARD_ID = /^[A-Z0-9][A-Z0-9_-]*$/\n\nconst GIFT_CARDS: RecordsSpec = {\n  collection: (firestore, ctx) => hostRefOf(firestore, ctx).collection('giftCards'),\n  record: (id, data) => giftCardRecord(id, data as StoredGiftCard),\n  matchValues: (id) => ({ id, code: id }),\n  // A card's code is its document id: a code is looked up by id. A value\n  // that cannot be a code still asks one id no card holds, rather than an\n  // empty `in`, which the store refuses.\n  find: {\n    code: (collection, values) => {\n      const codes = values.map((value) => giftCardCodeOf(value)).filter((code) => CARD_ID.test(code))\n      return collection.where(firebaseAdmin.firestore.FieldPath.documentId(), 'in', codes.length ? codes : ['-'])\n    },\n  },\n}\n\n\ninterface GiftCardIssuer {\n  hostId: string\n  uid: string\n  email: string | null\n  ownerOrg: unknown\n}\n\n/** The member importing, checked for the role and the plan, or the refusal. */\nasync function issuerOf(ctx: TransferResourceContext): Promise<GiftCardIssuer> {\n  const hostId = ctx.hostId\n  if (!hostId) throw new TransferEngineError('invalid', 400, 'Gift cards belong to a site; name the site.')\n  const uid = ctx.actorUid\n  const membership = uid ? await resolveOrgMembership(uid, ctx.orgId) : null\n  // The declaration's `importRoles` (AGL-3554), which the transfer gate\n  // asked already; asked again here for the sweep that resumes an import.\n  const declared = declaredTransferResource(COMMERCE_GIFT_CARDS_TRANSFER)\n  const role = membership?.member ? hostRoleFor(membership.member, hostId as never) : null\n  if (!uid || !declared || !transferImportRoleAllowed('import', declared, role)) {\n    throw new TransferEngineError(\n      'forbidden',\n      403,\n      declared ? transferImportRoleRefusal(declared) : 'Gift cards can’t be imported here.',\n    )\n  }\n  const owner = await getOrgForHost(hostId).catch(() => null)\n  // The transfer gate asked already (the resource's `planGate`); asked again\n  // here, in the same words, for the sweep that resumes an import.\n  const refusal = giftCardsPlanRefusal(owner?.org)\n  if (refusal) throw new TransferPlanRefusedError(refusal)\n  const email = (membership?.member as { email?: string } | undefined)?.email ?? null\n  return { hostId, uid, email, ownerOrg: owner?.org }\n}\n\n/** The codes among `codes` that a card on the site already holds. */\nasync function takenCodes(firestore: Firestore, ctx: TransferResourceContext, codes: readonly string[]): Promise<Set<string>> {\n  const collection = GIFT_CARDS.collection(firestore, ctx)\n  const taken = new Set<string>()\n  const ids = [...new Set(codes.filter((code) => CARD_ID.test(code)))]\n  for (let at = 0; at < ids.length; at += 100) {\n    for (const doc of await firestore.getAll(...ids.slice(at, at + 100).map((id) => collection.doc(id)))) {\n      if (doc.exists) taken.add(doc.id)\n    }\n  }\n  return taken\n}\n\n/**\n * The dry run: the core's plan with a Balance required of every card, made\n * into the cards it issues. The codes the file names are read once, so a\n * code another card holds — however the file spaced or cased it — is never\n * planned as a new card.\n */\nexport async function planGiftCards(ctx: TransferResourceContext, input: BuildTransferPlanInput): Promise<TransferPlan> {\n  await issuerOf(ctx)\n  const firestore = firestoreOf()\n  const rows = input.rows.map((row) =>\n    'code' in row.values ? { ...row, values: { ...row.values, code: giftCardCodeOf(row.values['code']) || null } } : row,\n  )\n  const taken = await takenCodes(\n    firestore,\n    ctx,\n    rows.map((row) => String(row.values['code'] ?? '')),\n  )\n  return planGiftCardRows(planWithCreateRequired({ ...input, rows }, ['balance']), {\n    confirmation: readGiftCardConfirmation(ctx.extras),\n    mintCode: mintGiftCardCode,\n    taken,\n  })\n}\n\n/** Whether the card under `code` is the one this job's `row` issued: a retried chunk finds its own card. */\nasync function issuedByRow(firestore: Firestore, ctx: TransferResourceContext, code: string, row: number): Promise<boolean> {\n  const doc = await GIFT_CARDS.collection(firestore, ctx).doc(code).get()\n  return doc.exists && doc.get('importJobId') === ctx.jobId && doc.get('importRow') === row\n}\n\n/** Issues one chunk's cards, each through the Gift cards card's own issue path. */\nexport async function applyGiftCards(\n  ctx: TransferResourceContext,\n  chunk: TransferChunk<PlannedTransferRow>,\n  writer: TransferApplyWriter,\n): Promise<TransferApplyResult> {\n  const issuer = await issuerOf(ctx)\n  const confirmation = readGiftCardConfirmation(ctx.extras)\n  const firestore = firestoreOf()\n  const results: TransferRowResult[] = []\n  const undo: TransferUndoEntry[] = []\n  const refuse = async (row: number, message: string) => {\n    const result: TransferRowResult = { row, outcome: 'failed', reason: 'refusedValue', message }\n    results.push(result)\n    await writer.markApplied(result)\n  }\n  for (const row of chunk.rows as GiftCardPlannedRow[]) {\n    const earlier = await writer.alreadyApplied(row.index)\n    if (earlier) {\n      results.push(earlier)\n      continue\n    }\n    if (writer.timeLeftMs() < ROW_BUDGET_MS) break\n    const card = row.giftCard\n    if (row.verdict !== 'create' || !card) {\n      await refuse(row.index, 'A gift card import only issues new cards; it never changes one.')\n      continue\n    }\n    if (card.problem) {\n      await refuse(row.index, card.problem)\n      continue\n    }\n    // The typed total, read again here: the plan's verdict is not enough.\n    if (!card.confirmed || !confirmation || confirmation.totalCents !== card.totalCents) {\n      await refuse(row.index, 'The total value was not confirmed, so no card was issued. Confirm the total and import again.')\n      continue\n    }\n    try {\n      await issueGiftCard({\n        firestore,\n        hostId: issuer.hostId,\n        amountCents: card.amountCents,\n        recipientEmail: card.recipientEmail,\n        note: card.note,\n        code: card.code,\n        issuer: { uid: issuer.uid, email: issuer.email },\n        email: confirmation.email,\n        ownerOrg: issuer.ownerOrg,\n        source: { importJobId: ctx.jobId ?? '', importRow: row.index },\n      })\n    } catch (error) {\n      if (!(error instanceof GiftCardIssueRefusal)) throw error\n      // A retry after the card landed and before its row was recorded.\n      if (!(error.reason === 'taken' && (await issuedByRow(firestore, ctx, card.code, row.index)))) {\n        await refuse(row.index, error.message)\n        continue\n      }\n    }\n    const issued = await GIFT_CARDS.collection(firestore, ctx).doc(card.code).get()\n    const record = giftCardRecord(card.code, (issued.data() ?? {}) as StoredGiftCard)\n    const result: TransferRowResult = { row: row.index, outcome: 'created', recordId: card.code }\n    const entry: TransferUndoEntry = {\n      row: row.index,\n      recordId: card.code,\n      action: 'created',\n      written: Object.fromEntries(GIFT_CARD_UNDO_FIELDS.map((fieldId) => [fieldId, record[fieldId] ?? null])),\n    }\n    results.push(result)\n    undo.push(entry)\n    await writer.markApplied(result, entry)\n  }\n  return { results, undo }\n}\n\n/**\n * Undoes one chunk: each card voided — zeroed, never deleted — when nobody\n * has spent from it; a spent or held card is a conflict that stays as it is,\n * whatever the person decided, because a shopper holds that money.\n */\nexport async function revertGiftCards(ctx: TransferResourceContext, snapshot: TransferUndoSnapshot): Promise<TransferRevertResult> {\n  const issuer = await issuerOf(ctx)\n  const firestore = firestoreOf()\n  const collection = GIFT_CARDS.collection(firestore, ctx)\n  const done: TransferUndoStep[] = []\n  const conflicts: TransferUndoStep[] = []\n  for (const entry of [...snapshot.entries].reverse()) {\n    const ref = collection.doc(entry.recordId)\n    const step = await firestore.runTransaction(async (tx): Promise<TransferUndoStep> => {\n      const doc = await tx.get(ref)\n      if (!doc.exists) return { action: 'nothing', recordId: entry.recordId, why: 'gone' }\n      const card = (doc.data() ?? {}) as StoredGiftCard & Doc\n      if (Number(card.voidedAtMs) > 0) return { action: 'nothing', recordId: entry.recordId, why: 'alreadyReverted' }\n      if (giftCardRedeemed(card)) {\n        const planned = planTransferUndo(entry, giftCardRecord(entry.recordId, card))\n        return {\n          action: 'conflict',\n          recordId: entry.recordId,\n          fields: planned.action === 'conflict' ? planned.fields : ['balance'],\n          values: {},\n        }\n      }\n      tx.set(\n        ref,\n        { balanceCents: 0, voidedAtMs: Date.now(), voidedBy: issuer.uid, voidedByImportUndo: ctx.jobId ?? null },\n        { merge: true },\n      )\n      return { action: 'delete', recordId: entry.recordId }\n    })\n    if (step.action === 'conflict') {\n      conflicts.push(step)\n      continue\n    }\n    if (step.action === 'delete') {\n      await logHostActivity(\n        issuer.hostId,\n        { uid: issuer.uid, email: issuer.email },\n        'Voided gift card: import undone',\n        { type: GIFT_CARD_ACTIVITY_TYPE, id: entry.recordId, name: giftCardActivityName(entry.recordId) },\n      )\n    }\n    done.push(step)\n  }\n  return { done, conflicts }\n}\n\nexport const giftCardsTransfer: PluginTransferResource = {\n  matchKeys: GIFT_CARD_MATCH_KEYS,\n  ...readableRecords(GIFT_CARDS),\n  plan: (ctx, input) => planGiftCards(ctx, input),\n  apply: (ctx, chunk, writer) => applyGiftCards(ctx, chunk, writer),\n  revert: (ctx, snapshot) => revertGiftCards(ctx, snapshot),\n}\n"],"names":["planTransferUndo","firebaseAdmin","getOrgForHost","logHostActivity","resolveOrgMembership","TransferEngineError","TransferPlanRefusedError","hostRoleFor","transferImportRoleAllowed","transferImportRoleRefusal","declaredTransferResource","COMMERCE_GIFT_CARDS_TRANSFER","giftCardsPlanRefusal","giftCardCodeOf","giftCardRedeemed","GIFT_CARD_ACTIVITY_TYPE","GiftCardIssueRefusal","giftCardActivityName","issueGiftCard","mintGiftCardCode","GIFT_CARD_MATCH_KEYS","GIFT_CARD_UNDO_FIELDS","giftCardRecord","planGiftCardRows","planWithCreateRequired","readGiftCardConfirmation","readableRecords","ROW_BUDGET_MS","firestoreOf","hostRefOf","CARD_ID","GIFT_CARDS","collection","firestore","ctx","record","id","data","matchValues","code","find","values","codes","map","value","filter","test","where","FieldPath","documentId","length","issuerOf","membership","hostId","uid","actorUid","orgId","declared","role","member","owner","catch","refusal","org","email","ownerOrg","takenCodes","taken","Set","ids","at","doc","getAll","slice","exists","add","planGiftCards","input","rows","row","String","confirmation","extras","mintCode","issuedByRow","get","jobId","applyGiftCards","chunk","writer","issuer","results","undo","refuse","message","result","outcome","reason","push","markApplied","issued","earlier","alreadyApplied","index","timeLeftMs","card","giftCard","verdict","problem","confirmed","totalCents","amountCents","recipientEmail","note","source","importJobId","importRow","error","recordId","entry","action","written","Object","fromEntries","fieldId","revertGiftCards","snapshot","done","conflicts","entries","reverse","ref","step","runTransaction","tx","why","Number","voidedAtMs","planned","fields","set","balanceCents","Date","now","voidedBy","voidedByImportUndo","merge","type","name","giftCardsTransfer","matchKeys","plan","apply","revert"],"mappings":"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"}

package/src/lib/transfer/list-filter.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { ListQueryDeclaration, ListQueryFilter, ListQueryPlan, ListQuerySort } from '@aglyn/shared-ui-jsx/const/list-query-plan';
+/** What a list sends as its export filter. */
+export interface CommerceListFilter {
+    filters: ListQueryFilter[];
+    orderBy: ListQuerySort;
+}
+/** The filter a list hands the export dialog: its plan's predicates and order, as plain data. */
+export declare function commerceListFilter(plan: Pick<ListQueryPlan, 'filters' | 'orderBy'>): CommerceListFilter;
+/**
+ * The filter a request carried, checked against the list's declaration.
+ * Throws a sentence naming what was refused.
+ */
+export declare function readCommerceListFilter(value: unknown, declaration: ListQueryDeclaration, base?: readonly string[]): CommerceListFilter;

package/src/lib/transfer/list-filter.js

@@ -0,0 +1,112 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ const OPS = [
+    '==',
+    '!=',
+    '<',
+    '<=',
+    '>',
+    '>=',
+    'in',
+    'array-contains',
+    'array-contains-any'
+];
+/** The id path a plan names the document id by. */ const ID_PATH = '__name__';
+/** The filter a list hands the export dialog: its plan's predicates and order, as plain data. */ export function commerceListFilter(plan) {
+    return {
+        filters: plan.filters.map((filter)=>({
+                path: filter.path,
+                op: filter.op,
+                value: filter.value instanceof Date ? filter.value.getTime() : Array.isArray(filter.value) ? [
+                    ...filter.value
+                ] : filter.value
+            })),
+        orderBy: {
+            path: plan.orderBy.path,
+            direction: plan.orderBy.direction
+        }
+    };
+}
+/** Every path the declaration lets a query name. */ function allowedPaths(declaration, base) {
+    const paths = new Set([
+        ID_PATH,
+        ...base
+    ]);
+    for (const field of declaration.fields){
+        for (const path of [
+            field.path,
+            field.lowerPath,
+            field.tokensPath,
+            field.containsOrderBy
+        ]){
+            if (path) paths.add(path);
+        }
+    }
+    if (declaration.search) paths.add(declaration.search.tokensPath);
+    for (const sort of declaration.sorts)paths.add(sort.path);
+    return paths;
+}
+const plain = (value)=>value === null || [
+        'string',
+        'number',
+        'boolean'
+    ].includes(typeof value);
+/**
+ * The filter a request carried, checked against the list's declaration.
+ * Throws a sentence naming what was refused.
+ */ export function readCommerceListFilter(value, declaration, base = []) {
+    var _raw_orderBy, _ref;
+    var _declaration_sorts_;
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('The filter could not be read.');
+    }
+    const raw = value;
+    const paths = allowedPaths(declaration, base);
+    const filters = [];
+    for (const entry of Array.isArray(raw.filters) ? raw.filters : []){
+        const { path, op, value: operand } = entry != null ? entry : {};
+        if (typeof path !== 'string' || !paths.has(path)) {
+            throw new Error(`The filter names "${String(path)}", which this list does not filter by.`);
+        }
+        if (!OPS.includes(op)) throw new Error(`The filter uses an unknown operator.`);
+        const list = op === 'in' || op === 'array-contains-any';
+        if (list) {
+            if (!Array.isArray(operand) || !operand.length || operand.length > 30 || !operand.every(plain)) {
+                throw new Error('The filter holds a list it cannot ask for.');
+            }
+        } else if (!plain(operand)) {
+            throw new Error('The filter holds a value it cannot ask for.');
+        }
+        filters.push({
+            path,
+            op: op,
+            value: operand
+        });
+    }
+    const order = (_raw_orderBy = raw.orderBy) != null ? _raw_orderBy : {};
+    const direction = order.direction === 'desc' ? 'desc' : 'asc';
+    const orderPath = typeof order.path === 'string' ? order.path : (_ref = (_declaration_sorts_ = declaration.sorts[0]) == null ? void 0 : _declaration_sorts_.path) != null ? _ref : ID_PATH;
+    if (!paths.has(orderPath)) throw new Error(`The filter orders by "${orderPath}", which this list does not sort by.`);
+    return {
+        filters,
+        orderBy: {
+            path: orderPath,
+            direction
+        }
+    };
+}
+
+//# sourceMappingURL=list-filter.js.map

package/src/lib/transfer/list-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/transfer/list-filter.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type {\n  ListQueryDeclaration,\n  ListQueryFilter,\n  ListQueryOp,\n  ListQueryPlan,\n  ListQuerySort,\n} from '@aglyn/shared-ui-jsx/const/list-query-plan'\n\n/*\n * \"THE CURRENT FILTER\" OF A COMMERCE LIST, CARRIED TO AN EXPORT (AGL-3531).\n *\n * A list's filter is its Firestore query (AGL-3321): the predicates and the\n * one order `planListQuery` made of the chips and the search. The export\n * reads the same query on the server, so the list hands over exactly that —\n * the planned predicates and order — rather than the chips, whose dates the\n * browser resolved in the person's own timezone.\n *\n * The server reads through the Admin SDK, so it never takes a predicate on\n * faith: every path must be one the list's declaration names (a field's\n * path, lower-cased key or tokens, the search tokens, the list's base), the\n * operator one Firestore has, and the value plain data. Anything else is\n * refused, never widened to \"everything\".\n */\n\n/** What a list sends as its export filter. */\nexport interface CommerceListFilter {\n  filters: ListQueryFilter[]\n  orderBy: ListQuerySort\n}\n\nconst OPS: readonly ListQueryOp[] = [\n  '==',\n  '!=',\n  '<',\n  '<=',\n  '>',\n  '>=',\n  'in',\n  'array-contains',\n  'array-contains-any',\n]\n\n/** The id path a plan names the document id by. */\nconst ID_PATH = '__name__'\n\n/** The filter a list hands the export dialog: its plan's predicates and order, as plain data. */\nexport function commerceListFilter(plan: Pick<ListQueryPlan, 'filters' | 'orderBy'>): CommerceListFilter {\n  return {\n    filters: plan.filters.map((filter) => ({\n      path: filter.path,\n      op: filter.op,\n      value:\n        filter.value instanceof Date\n          ? filter.value.getTime()\n          : Array.isArray(filter.value)\n            ? [...filter.value]\n            : filter.value,\n    })),\n    orderBy: { path: plan.orderBy.path, direction: plan.orderBy.direction },\n  }\n}\n\n/** Every path the declaration lets a query name. */\nfunction allowedPaths(declaration: ListQueryDeclaration, base: readonly string[]): Set<string> {\n  const paths = new Set<string>([ID_PATH, ...base])\n  for (const field of declaration.fields) {\n    for (const path of [field.path, field.lowerPath, field.tokensPath, field.containsOrderBy]) {\n      if (path) paths.add(path)\n    }\n  }\n  if (declaration.search) paths.add(declaration.search.tokensPath)\n  for (const sort of declaration.sorts) paths.add(sort.path)\n  return paths\n}\n\nconst plain = (value: unknown): boolean =>\n  value === null || ['string', 'number', 'boolean'].includes(typeof value)\n\n/**\n * The filter a request carried, checked against the list's declaration.\n * Throws a sentence naming what was refused.\n */\nexport function readCommerceListFilter(\n  value: unknown,\n  declaration: ListQueryDeclaration,\n  base: readonly string[] = [],\n): CommerceListFilter {\n  if (!value || typeof value !== 'object' || Array.isArray(value)) {\n    throw new Error('The filter could not be read.')\n  }\n  const raw = value as { filters?: unknown; orderBy?: unknown }\n  const paths = allowedPaths(declaration, base)\n  const filters: ListQueryFilter[] = []\n  for (const entry of Array.isArray(raw.filters) ? raw.filters : []) {\n    const { path, op, value: operand } = (entry ?? {}) as Record<string, unknown>\n    if (typeof path !== 'string' || !paths.has(path)) {\n      throw new Error(`The filter names \"${String(path)}\", which this list does not filter by.`)\n    }\n    if (!OPS.includes(op as ListQueryOp)) throw new Error(`The filter uses an unknown operator.`)\n    const list = op === 'in' || op === 'array-contains-any'\n    if (list) {\n      if (!Array.isArray(operand) || !operand.length || operand.length > 30 || !operand.every(plain)) {\n        throw new Error('The filter holds a list it cannot ask for.')\n      }\n    } else if (!plain(operand)) {\n      throw new Error('The filter holds a value it cannot ask for.')\n    }\n    filters.push({ path, op: op as ListQueryOp, value: operand as ListQueryFilter['value'] })\n  }\n  const order = (raw.orderBy ?? {}) as Record<string, unknown>\n  const direction = order.direction === 'desc' ? 'desc' : 'asc'\n  const orderPath = typeof order.path === 'string' ? order.path : (declaration.sorts[0]?.path ?? ID_PATH)\n  if (!paths.has(orderPath)) throw new Error(`The filter orders by \"${orderPath}\", which this list does not sort by.`)\n  return { filters, orderBy: { path: orderPath, direction } }\n}\n"],"names":["OPS","ID_PATH","commerceListFilter","plan","filters","map","filter","path","op","value","Date","getTime","Array","isArray","orderBy","direction","allowedPaths","declaration","base","paths","Set","field","fields","lowerPath","tokensPath","containsOrderBy","add","search","sort","sorts","plain","includes","readCommerceListFilter","raw","Error","entry","operand","has","String","list","length","every","push","order","orderPath"],"mappings":"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"}

package/src/lib/transfer/product-import-results.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type MaybeTokenSource } from '@aglyn/shared-util-http/authorized-token';
+export interface PendingProductImport {
+    orgId: string;
+    jobId: string;
+    /** The options the `productImport` zone set, by key. */
+    options: Record<string, boolean>;
+}
+/** Files the import a site's wizard is running, with its options. */
+export declare function rememberProductImport(hostId: string, entry: PendingProductImport): void;
+/** The import the site's wizard last ran, once: the hub takes it when the wizard closes. */
+export declare function takeProductImport(hostId: string): PendingProductImport | null;
+/** The products an applied import created, from the job's results (`api/transfer/status`). */
+export declare function createdProductIds(user: MaybeTokenSource, entry: PendingProductImport): Promise<string[]>;

package/src/lib/transfer/product-import-results.js

@@ -0,0 +1,49 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { authorizedFetch } from "@aglyn/shared-util-http/authorized-token";
+const pending = new Map();
+/** Files the import a site's wizard is running, with its options. */ export function rememberProductImport(hostId, entry) {
+    pending.set(hostId, entry);
+}
+/** The import the site's wizard last ran, once: the hub takes it when the wizard closes. */ export function takeProductImport(hostId) {
+    var _pending_get;
+    const entry = (_pending_get = pending.get(hostId)) != null ? _pending_get : null;
+    pending.delete(hostId);
+    return entry;
+}
+/** The products an applied import created, from the job's results (`api/transfer/status`). */ export async function createdProductIds(user, entry) {
+    var _ref;
+    const response = await authorizedFetch(user, '/api/transfer/status', {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+            orgId: entry.orgId,
+            jobId: entry.jobId,
+            include: 'results'
+        })
+    });
+    if (!response.ok) return [];
+    const status = await response.json().catch(()=>null);
+    const ids = [];
+    for (const row of (_ref = status == null ? void 0 : status.rows) != null ? _ref : []){
+        if (row.outcome === 'created' && row.recordId && !ids.includes(row.recordId)) ids.push(row.recordId);
+    }
+    return ids;
+}
+
+//# sourceMappingURL=product-import-results.js.map

package/src/lib/transfer/product-import-results.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/transfer/product-import-results.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { authorizedFetch, type MaybeTokenSource } from '@aglyn/shared-util-http/authorized-token'\nimport type { TransferStatusResponse } from '@aglyn/aglyn/data-transfer'\n\n/*\n * WHAT A PRODUCT IMPORT LEFT FOR THE PRODUCTS HUB (AGL-3531).\n *\n * The `productImport` zone's options are set in the wizard's own step\n * (`ProductImportOptionsStep`) and the hub hands them to the `productsHub`\n * zone with the products the import CREATED — the AI copy option starts a\n * copy job for exactly those. The step files the job here; the hub takes it\n * when the wizard closes on its results and reads the created ids from the\n * job's results. Module state is enough: the step and the hub share one tab.\n */\n\nexport interface PendingProductImport {\n  orgId: string\n  jobId: string\n  /** The options the `productImport` zone set, by key. */\n  options: Record<string, boolean>\n}\n\nconst pending = new Map<string, PendingProductImport>()\n\n/** Files the import a site's wizard is running, with its options. */\nexport function rememberProductImport(hostId: string, entry: PendingProductImport): void {\n  pending.set(hostId, entry)\n}\n\n/** The import the site's wizard last ran, once: the hub takes it when the wizard closes. */\nexport function takeProductImport(hostId: string): PendingProductImport | null {\n  const entry = pending.get(hostId) ?? null\n  pending.delete(hostId)\n  return entry\n}\n\n/** The products an applied import created, from the job's results (`api/transfer/status`). */\nexport async function createdProductIds(user: MaybeTokenSource, entry: PendingProductImport): Promise<string[]> {\n  const response = await authorizedFetch(user, '/api/transfer/status', {\n    method: 'POST',\n    headers: { 'Content-Type': 'application/json' },\n    body: JSON.stringify({ orgId: entry.orgId, jobId: entry.jobId, include: 'results' }),\n  })\n  if (!response.ok) return []\n  const status = (await response.json().catch(() => null)) as TransferStatusResponse | null\n  const ids: string[] = []\n  for (const row of status?.rows ?? []) {\n    if (row.outcome === 'created' && row.recordId && !ids.includes(row.recordId)) ids.push(row.recordId)\n  }\n  return ids\n}\n"],"names":["authorizedFetch","pending","Map","rememberProductImport","hostId","entry","set","takeProductImport","get","delete","createdProductIds","user","response","method","headers","body","JSON","stringify","orgId","jobId","include","ok","status","json","catch","ids","row","rows","outcome","recordId","includes","push"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,eAAe,QAA+B,2CAA0C;AAqBjG,MAAMC,UAAU,IAAIC;AAEpB,mEAAmE,GACnE,OAAO,SAASC,sBAAsBC,MAAc,EAAEC,KAA2B;IAC/EJ,QAAQK,GAAG,CAACF,QAAQC;AACtB;AAEA,0FAA0F,GAC1F,OAAO,SAASE,kBAAkBH,MAAc;QAChCH;IAAd,MAAMI,SAAQJ,eAAAA,QAAQO,GAAG,CAACJ,mBAAZH,eAAuB;IACrCA,QAAQQ,MAAM,CAACL;IACf,OAAOC;AACT;AAEA,4FAA4F,GAC5F,OAAO,eAAeK,kBAAkBC,IAAsB,EAAEN,KAA2B;;IACzF,MAAMO,WAAW,MAAMZ,gBAAgBW,MAAM,wBAAwB;QACnEE,QAAQ;QACRC,SAAS;YAAE,gBAAgB;QAAmB;QAC9CC,MAAMC,KAAKC,SAAS,CAAC;YAAEC,OAAOb,MAAMa,KAAK;YAAEC,OAAOd,MAAMc,KAAK;YAAEC,SAAS;QAAU;IACpF;IACA,IAAI,CAACR,SAASS,EAAE,EAAE,OAAO,EAAE;IAC3B,MAAMC,SAAU,MAAMV,SAASW,IAAI,GAAGC,KAAK,CAAC,IAAM;IAClD,MAAMC,MAAgB,EAAE;IACxB,KAAK,MAAMC,eAAOJ,0BAAAA,OAAQK,IAAI,mBAAI,EAAE,CAAE;QACpC,IAAID,IAAIE,OAAO,KAAK,aAAaF,IAAIG,QAAQ,IAAI,CAACJ,IAAIK,QAAQ,CAACJ,IAAIG,QAAQ,GAAGJ,IAAIM,IAAI,CAACL,IAAIG,QAAQ;IACrG;IACA,OAAOJ;AACT"}

package/src/lib/transfer/product-import-step.component.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { TransferWizardStepProps } from '@aglyn/aglyn/plugin-manager/plugin-transfer-resources';
+/**
+ * The product import wizard's After import step (AGL-3531): the
+ * `productImport` zone, where another plugin offers what happens to the
+ * products once they land — the AI plugin's "write descriptions as they
+ * land". The options are filed with the job for the products hub, which
+ * hands them to `productsHub` with the ids the import created. Nothing here
+ * blocks the import: with no widget the step says so and lets it go on.
+ */
+export declare function ProductImportOptionsStep(props: TransferWizardStepProps): import("react").JSX.Element;
+export declare namespace ProductImportOptionsStep {
+    var displayName: string;
+}
+export default ProductImportOptionsStep;