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

package/src/lib/transfer/records-transfer.d.ts

@@ -0,0 +1,182 @@
+/**
+ * @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 BuildTransferPlanInput, type MatchKeySpec, type PlannedTransferRow, type TransferField, type TransferPlan } from '@aglyn/aglyn/data-transfer';
+import type { PicklistSpec } from '@aglyn/aglyn/app-utils/picklists';
+import type { DiscountKind, HostDiscount } from '../model/commerce-discounts';
+import { type HostGiftCard } from '../model/commerce-gift-cards';
+import { type HostOrder } from '../model/commerce-orders';
+/** A planned row's changes, by field id. */
+export declare function rowChanges(row: PlannedTransferRow): Record<string, unknown>;
+/**
+ * The core's plan with the fields a NEW record cannot be made without
+ * marked required — never in the catalog, where a required field must be
+ * mapped, and a file that only switches discounts off would be refused.
+ */
+export declare function planWithCreateRequired(input: BuildTransferPlanInput, required: readonly string[]): TransferPlan;
+export declare const ORDER_TRANSFER_FIELDS: readonly TransferField[];
+export declare const ORDER_TRANSFER_GROUPS: {
+    id: string;
+    label: string;
+}[];
+/** An order as a stored document, with the id the export reads it under. */
+export type StoredOrder = Partial<HostOrder> & {
+    createdAt?: unknown;
+    createdAtMs?: number;
+    amountCents?: number;
+    feeCents?: number;
+    productId?: string;
+};
+/**
+ * One order as a file names it. The money is what was ACTUALLY charged:
+ * the order's `totals`, and the legacy flat fields only where a buy-now order
+ * of old carries nothing else (AGL-1747) — a POS or draft order has no flat
+ * field, and reading those first exported every one of them at $0.00. A
+ * legacy row is named from `productNames`, never as "Product".
+ */
+export declare function orderRecord(id: string, stored: StoredOrder, productNames?: Readonly<Record<string, string>>): Record<string, unknown>;
+export declare const DISCOUNT_KIND_PICKLIST = "commerce.discountKind";
+export declare const DISCOUNT_KIND_SPEC: PicklistSpec;
+/** A discount kind's id from a label or id in any case, or `null`. */
+export declare function discountKindOf(value: unknown): DiscountKind | null;
+export declare const DISCOUNT_TRANSFER_FIELDS: readonly TransferField[];
+export declare const DISCOUNT_MATCH_KEYS: readonly MatchKeySpec[];
+/** A code as the discounts card stores it: upper case, letters, digits, `_` and `-`. */
+export declare function promotionCode(value: unknown, max?: number): string;
+export declare function discountRecord(id: string, stored: Partial<HostDiscount> & {
+    code?: string | null;
+}): Record<string, unknown>;
+/**
+ * The document a discount's changes make, over what it holds: the stored
+ * shape the discounts card writes, or the sentence refusing it.
+ */
+export declare function discountWrite(current: (Partial<HostDiscount> & {
+    code?: string | null;
+}) | null, changes: Readonly<Record<string, unknown>>): {
+    doc: Record<string, unknown>;
+} | {
+    problem: string;
+};
+export declare const COUPON_TRANSFER_FIELDS: readonly TransferField[];
+export declare const COUPON_MATCH_KEYS: readonly MatchKeySpec[];
+export interface StoredCoupon {
+    percentOff?: number;
+    enabled?: boolean;
+    redemptions?: number;
+    maxRedemptions?: number;
+    expiresAtMs?: number;
+    createdAt?: unknown;
+}
+export declare function couponRecord(id: string, stored: StoredCoupon): Record<string, unknown>;
+/** A coupon's document from its changes, as the coupons card writes one, or the refusal. */
+export declare function couponWrite(current: StoredCoupon | null, changes: Readonly<Record<string, unknown>>): {
+    doc: Record<string, unknown>;
+} | {
+    problem: string;
+};
+export declare const GIFT_CARD_TRANSFER_FIELDS: readonly TransferField[];
+/** A card is found by its code, which is its ID. */
+export declare const GIFT_CARD_MATCH_KEYS: readonly MatchKeySpec[];
+/** The fields an issued card's undo entry holds: any of them moving means the card was spent. */
+export declare const GIFT_CARD_UNDO_FIELDS: readonly ["balance", "status", "lastUsedAt"];
+export type StoredGiftCard = HostGiftCard & {
+    initialCents?: number;
+    recipientEmail?: string | null;
+    orderId?: string | null;
+    note?: string;
+    createdAtMs?: number;
+    lastUsedAtMs?: number;
+    importJobId?: string;
+    importRow?: number;
+};
+export declare function giftCardRecord(id: string, stored: StoredGiftCard): Record<string, unknown>;
+/** Dollars and cents as a person reads them: `$1,250.00`. */
+export declare function giftCardMoney(amountCents: number): string;
+/** A total as a person types it (`1250`, `$1,250.00`), in cents; `null` for anything else. */
+export declare function typedDollarsToCents(typed: unknown): number | null;
+/** The Confirm step's answer. */
+export interface GiftCardConfirmation {
+    /** The total the person typed, in cents. */
+    totalCents: number;
+    /** Email each card's recipient their code as it is issued. */
+    email: boolean;
+}
+/** The Confirm step's answer from `extras`, or `null` for none: a total is a whole number of cents. */
+export declare function readGiftCardConfirmation(extras: Readonly<Record<string, unknown>> | undefined): GiftCardConfirmation | null;
+/** The card one planned row issues, as the plan decided it. */
+export interface GiftCardRowPlan {
+    /** The code the card is issued under. */
+    code: string;
+    /** The file's code was taken, and the person chose a new one. */
+    newCode: boolean;
+    /** The file named no code, so one was made. */
+    madeCode: boolean;
+    amountCents: number;
+    recipientEmail: string | null;
+    note: string | null;
+    /** Why the row issues nothing; the `gift-card-issuable` invariant fails it. */
+    problem?: string;
+    /** What every card this import issues adds up to. */
+    totalCents: number;
+    /** Whether the person typed exactly that total on the Confirm step. */
+    confirmed: boolean;
+}
+export type GiftCardPlannedRow = PlannedTransferRow & {
+    giftCard?: GiftCardRowPlan;
+};
+/** The card a row's changes issue, or the sentence refusing it. */
+export declare function giftCardIssueOf(changes: Readonly<Record<string, unknown>>, code: {
+    value: string;
+    fromFile: boolean;
+}): Omit<GiftCardRowPlan, 'newCode' | 'madeCode' | 'totalCents' | 'confirmed'>;
+/**
+ * The core's plan for a gift card file, made into the cards it issues: each
+ * create carrying the card it issues ({@link GiftCardRowPlan}), each row
+ * that would change an existing card refused, the total of every card
+ * counted, and a `screening` warning stating that total — and, when the
+ * Confirm step's answer is missing or names another total, that nothing is
+ * issued until it is confirmed.
+ */
+export declare function planGiftCardRows(plan: TransferPlan, input: {
+    confirmation: GiftCardConfirmation | null;
+    mintCode: () => string;
+    /** The file's codes a card on the site already holds, however the file spelled them. */
+    taken?: ReadonlySet<string>;
+}): TransferPlan;
+export declare const CATEGORY_TRANSFER_FIELDS: readonly TransferField[];
+export declare const CATEGORY_MATCH_KEYS: readonly MatchKeySpec[];
+export interface StoredCategory {
+    name?: string;
+    slug?: string;
+    parentId?: string | null;
+    order?: number;
+}
+export declare function categoryRecord(id: string, stored: StoredCategory, slugs?: ReadonlyMap<string, string>): Record<string, unknown>;
+/** Every category's slug, name and parent, by id: what a parent is resolved against. */
+export type CategoryIndex = Map<string, StoredCategory>;
+/** The category a parent cell names — by id, slug, then name — or `null`. */
+export declare function resolveCategoryParent(index: CategoryIndex, value: unknown): string | null;
+/**
+ * A category's document from its changes: the name and the slug made from
+ * it, the parent resolved — never itself or one of its own descendants —
+ * and the position. A parent the site does not have is refused, not
+ * guessed.
+ */
+export declare function categoryWrite(id: string, current: StoredCategory | null, changes: Readonly<Record<string, unknown>>, index: CategoryIndex): {
+    doc: Record<string, unknown>;
+} | {
+    problem: string;
+};