@aglyn/plugins-commerce 1.0.0-beta.285 → 1.0.0-beta.288

package/src/lib/model/pos-hardware.d.ts

@@ -14,6 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import type { PosHardwareTermsAcceptance } from './pos-hardware-terms';
 /** The register's currency, and so the shop's: US dollars. */
 export declare const POS_HARDWARE_CURRENCY = "usd";
 /**
@@ -42,6 +43,16 @@ export declare const POS_HARDWARE_ENV: {
     readonly shipping: "POS_HARDWARE_SHIPPING";
     /** `true` turns Stripe automatic tax on for hardware checkouts. */
     readonly automaticTax: "POS_HARDWARE_AUTOMATIC_TAX";
+    /**
+     * `true` lets the platform's own store sell hardware IN PERSON at its
+     * register (AGL-4038): a reader handed over at an event, attached to the
+     * buyer's workspace. Absent or anything else keeps it off.
+     */
+    readonly inPersonEnabled: "POS_HARDWARE_IN_PERSON_ENABLED";
+    /** The site id of the platform's own store whose register sells hardware in person. */
+    readonly sellerHostId: "POS_HARDWARE_SELLER_HOST_ID";
+    /** The workspace that owns that store. */
+    readonly sellerOrgId: "POS_HARDWARE_SELLER_ORG_ID";
 };
 /**
  * The markup when the deployment sets none: 3000 basis points on Stripe's
@@ -49,7 +60,7 @@ export declare const POS_HARDWARE_ENV: {
  * `POS_HARDWARE_MARKUP_BPS` overrides it.
  */
 export declare const POS_HARDWARE_DEFAULT_MARKUP_BPS = 3000;
-export type PosHardwareSkuId = 'stripe-reader-s710' | 'stripe-reader-s700' | 'stripe-reader-m2' | 'bbpos-wisepos-e' | 'stripe-reader-s700-dock' | 'bbpos-wisepos-e-dock' | 'stripe-reader-m2-mount';
+export type PosHardwareSkuId = 'stripe-reader-s710' | 'stripe-reader-s700' | 'stripe-reader-t600' | 'stripe-reader-m2' | 'bbpos-wisepos-e' | 'stripe-reader-s700-dock' | 'stripe-reader-hub' | 'stripe-reader-s700-case' | 'stripe-reader-s700-cable' | 'stripe-reader-charger' | 'stripe-reader-m2-dock' | 'stripe-reader-m2-mount' | 'bbpos-wisepos-e-dock' | 'bbpos-wisepos-e-power-cable';
 export interface PosHardwareSku {
     id: PosHardwareSkuId;
     kind: 'reader' | 'accessory';
@@ -70,6 +81,15 @@ export declare function posHardwareSku(id: string): PosHardwareSku | null;
 export type PosHardwareShippingMethod = 'standard' | 'express' | 'priority';
 export declare const POS_HARDWARE_SHIPPING_LABELS: Record<PosHardwareShippingMethod, string>;
 export declare function isPosHardwareShippingMethod(value: unknown): value is PosHardwareShippingMethod;
+/**
+ * How an order reached the buyer: one of the shop's shipping speeds, or
+ * `in_person` — handed over at the platform's own register (AGL-4038), with
+ * no parcel, address or carrier. Never offered at checkout.
+ */
+export type PosHardwareOrderShippingMethod = PosHardwareShippingMethod | 'in_person';
+export declare const POS_HARDWARE_IN_PERSON_SHIPPING_LABEL = "Handed over in person";
+/** The label of any order's method, the in-person one included. */
+export declare function posHardwareShippingLabel(method: PosHardwareOrderShippingMethod | null | undefined): string;
 /** The shop's configuration, once every figure it needs is present and sane. */
 export interface PosHardwareConfig {
     /** Stripe's price for each configured item, in cents. */
@@ -94,6 +114,25 @@ export interface PosHardwareConfig {
  * failing the whole shop, so a typo in one price hides that one item.
  */
 export declare function parsePosHardwareConfig(env: Record<string, string | undefined>): PosHardwareConfig | null;
+/** The platform's own store, once the in-person sale is turned on and named. */
+export interface PosHardwareInPersonConfig {
+    sellerHostId: string;
+    sellerOrgId: string;
+}
+/**
+ * The in-person sale's configuration from the environment, or `null` while
+ * it is off: not turned on, or the store or its workspace not named, or
+ * named with something that cannot be an id. It needs nothing of the online
+ * shop's: the store's own products carry the prices.
+ */
+export declare function parsePosHardwareInPersonConfig(env: Record<string, string | undefined>): PosHardwareInPersonConfig | null;
+export declare function isPosHardwareSkuId(value: unknown): value is PosHardwareSkuId;
+/**
+ * A reader's serial number as staff scanned or typed it, in the one form
+ * every comparison uses: upper case, letters, digits and dashes only, at
+ * most 64 characters. Empty when nothing usable was given.
+ */
+export declare function normalizePosHardwareSerial(value: unknown): string;
 /**
  * What the merchant pays for one item: Stripe's price plus the markup,
  * rounded half up to the cent, in integer math throughout.
@@ -176,10 +215,162 @@ export interface PosHardwareTracking {
     number: string;
     url: string | null;
 }
+/**
+ * Why an order was canceled and refunded: by staff on the Hardware orders
+ * page, or because the workspace that bought it was deleted or the account
+ * that placed it was closed before it shipped (AGL-4038 closure).
+ */
+export type PosHardwareCancelReason = 'staff' | 'workspace-closed' | 'account-closed';
+/**
+ * One entry of the tax Stripe computed on a hardware checkout, as the
+ * storefront's tax rows store it (`StorefrontTaxLine`): the amount, the base
+ * it was applied to (`taxable_amount`, null when Stripe did not state one)
+ * and the rate, for the working papers of the platform's own return.
+ */
+export interface PosHardwareTaxLine {
+    amountCents: number;
+    taxabilityReason: string | null;
+    taxRateId: string | null;
+    taxableAmountCents: number | null;
+    jurisdiction: string | null;
+    rateState: string | null;
+    percentage: number | null;
+}
+/**
+ * Where an order was sold (AGL-4038): the Hardware card's checkout, or the
+ * platform's own register, in person. Absent on every order sold before the
+ * in-person sale existed, which were all online; read it through
+ * {@link posHardwareOrderSource}.
+ */
+export type PosHardwareOrderSource = 'online' | 'in_person';
+export declare function posHardwareOrderSource(order: {
+    source?: unknown;
+} | null | undefined): PosHardwareOrderSource;
+/**
+ * The register sale an in-person order came from: the platform's own store,
+ * the register order and its number, and how it was rung.
+ */
+export interface PosHardwareRegisterSale {
+    hostId: string;
+    orgId: string;
+    orderId: string;
+    /** The register order's number, as its receipt shows it. */
+    number: number | null;
+    registerId: string | null;
+    /** A customer built it at the self-service kiosk. */
+    kiosk: boolean;
+    /** It was rung while the register was offline, and synced later. */
+    offline: boolean;
+    /**
+     * The Checkout Session of the register's payment link, when the sale was
+     * paid by one: the storefront's tax record of the sale is filed under it.
+     */
+    paymentLinkSessionId: string | null;
+}
+/**
+ * Where an in-person sale's money went, for the books to reconcile it
+ * against: the selling store's own takings — cash in its drawer, cards into
+ * its connected Stripe account, exactly as every sale on its register. The
+ * hardware order records it because the platform's online sales land in the
+ * platform's own account instead, and the two must never be summed as one.
+ */
+export interface PosHardwarePaidTo {
+    account: 'seller_store';
+    hostId: string;
+    orgId: string;
+    /** The register sale's tenders, as its payments name them (`cash`, `card_present`, …). */
+    tenders: string[];
+    /** The store's connected Stripe account, when its owner has one. */
+    stripeAccountId: string | null;
+}
+/**
+ * Who an in-person order belongs to (AGL-4038). `attached` once it is in the
+ * buyer's workspace; `pending` while staff have still to say whose it is —
+ * a kiosk or offline sale, a buyer with no account yet (`email`, invited to
+ * sign up), or one with an account and no workspace yet (`uid`). A pending
+ * order is kept in the selling workspace's own `hardwareOrders`, on its "To
+ * attach" list, and moves to the buyer's workspace when it is attached.
+ */
+export interface PosHardwareAttachment {
+    state: 'attached' | 'pending';
+    /** The buyer's address: the account's, or the one typed for a buyer with no account. */
+    email: string | null;
+    uid: string | null;
+    /** The buyer's workspace, once there is one. */
+    orgId: string | null;
+    /** The store the buyer chose for the reader, when they chose one at the sale. */
+    hostId: string | null;
+    /** The register user who attached it; null for the buyer's own sign-up. */
+    attachedBy: string | null;
+    attachedAtMs: number | null;
+    /** When the sign-up invitation went to `email`, for a buyer with no account. */
+    invitedAtMs?: number | null;
+    /**
+     * The buyer's name, for the platform's reseller records (AGL-4038): the
+     * account's name, or the one typed at the sale. An online order keeps it
+     * in `shipping.name` instead. Taken off with the buyer's account.
+     */
+    name?: string | null;
+    /**
+     * The buyer's business address, for the same records: typed at the sale,
+     * or the address of the store the readers are set up on. Never the tax
+     * region, which stays the selling store's. Taken off with the account.
+     */
+    address?: PosHardwareAddress | null;
+}
+/**
+ * One reader of an in-person order, by its serial number when staff scanned
+ * it at the sale (AGL-4038). The order moves to Set up when every reader on
+ * it is registered to the buyer's store.
+ */
+export interface PosHardwareUnit {
+    sku: PosHardwareSkuId;
+    /** Normalized ({@link normalizePosHardwareSerial}); null when none was taken. */
+    serialNumber: string | null;
+    /** The Stripe Terminal reader it was registered as, and on which store. */
+    readerId: string | null;
+    hostId: string | null;
+    registeredAtMs: number | null;
+}
+/**
+ * One refund of an in-person order (AGL-4038), once by its key: a return at
+ * the selling store's register (`register:{returnId}`), or a refund from the
+ * staff Hardware orders page (`staff:{n}`), both paid back from the selling
+ * store's own takings the way the sale was paid.
+ */
+export interface PosHardwareRefund {
+    key: string;
+    via: 'register' | 'staff';
+    cents: number;
+    /** Hardware items it took back; 0 when the refund named none. */
+    quantity: number;
+    atMs: number;
+    stripeRefundId: string | null;
+}
+/**
+ * The buyer's request to return an in-person order, from their own
+ * purchase history (AGL-4038). Staff refund it (`refunded`) or decline it.
+ * Returns follow Stripe's hardware terms.
+ */
+export interface PosHardwareReturnRequest {
+    state: 'requested' | 'declined' | 'refunded';
+    /** The buyer's words; taken off with the buyer when their account is erased. */
+    reason: string | null;
+    requestedBy: string | null;
+    requestedAtMs: number;
+    decidedBy: string | null;
+    decidedAtMs: number | null;
+    /** What staff told the buyer when declining. */
+    note: string | null;
+}
+export declare const POS_HARDWARE_RETURN_REASON_MAX = 500;
 /** `orgs/{orgId}/hardwareOrders/{orderId}`, written only by the server. */
 export interface PosHardwareOrder {
     orgId: string;
-    /** The site whose POS settings the order was placed from. */
+    /**
+     * The site whose POS settings the order was placed from; for an in-person
+     * order, the buyer's store once known, else the selling store.
+     */
     hostId: string;
     /** The member who started the checkout; `null` once their account is erased. */
     createdBy: string | null;
@@ -188,7 +379,7 @@ export interface PosHardwareOrder {
     lines: PosHardwareLine[];
     subtotalCents: number;
     shipping: {
-        method: PosHardwareShippingMethod;
+        method: PosHardwareOrderShippingMethod;
         label: string;
         cents: number;
         name: string | null;
@@ -201,9 +392,20 @@ export interface PosHardwareOrder {
         taxRegion?: PosHardwareTaxRegion | null;
     };
     taxCents: number;
+    /**
+     * The register sale's discounts that fell on this order's lines, for an
+     * in-person order (AGL-4038): `totalCents` is the lines less this, plus
+     * the tax. Absent, and so nothing, on every online order.
+     */
+    discountCents?: number;
     totalCents: number;
     currency: string;
-    stripeCheckoutSessionId: string;
+    /** Whether Stripe Tax computed the tax on the checkout. Absent on orders before it was recorded. */
+    automaticTax?: boolean;
+    /** Stripe's tax breakdown for the checkout, when Stripe Tax computed it. */
+    taxLines?: PosHardwareTaxLine[];
+    /** The Hardware card's checkout; null for an in-person sale, which had none. */
+    stripeCheckoutSessionId: string | null;
     stripePaymentIntentId: string | null;
     /** Stripe's hardware order id, recorded by staff (phase 2 sets it itself). */
     stripeHardwareOrderId: string | null;
@@ -222,8 +424,41 @@ export interface PosHardwareOrder {
     refundId?: string | null;
     /** The cents Stripe reported refunding. */
     refundedCents?: number;
+    /** Why it was canceled, when it was. */
+    cancelReason?: PosHardwareCancelReason;
     /** When the buyer's account was erased and their details taken off the order. */
     buyerErasedAtMs?: number;
+    /** Where it was sold; absent reads as online ({@link posHardwareOrderSource}). */
+    source?: PosHardwareOrderSource;
+    /** The register sale an in-person order came from. */
+    posSale?: PosHardwareRegisterSale;
+    /** Where an in-person sale's money went. */
+    paidTo?: PosHardwarePaidTo;
+    /** Whose an in-person order is, or that staff have still to say. */
+    attachment?: PosHardwareAttachment;
+    /**
+     * How the buyer of an in-person order agreed to the terms of sale
+     * (AGL-4038): copied from the register sale, or the receipt-and-sign
+     * notice when they did not accept electronically.
+     */
+    termsAcceptance?: PosHardwareTermsAcceptance;
+    /** Each reader of an in-person order, with its serial when one was taken. */
+    units?: PosHardwareUnit[];
+    /** The units' serial numbers, for finding the order when a reader is registered. */
+    serialNumbers?: string[];
+    /** An in-person order's refunds, each once by its key. */
+    refunds?: PosHardwareRefund[];
+    /** The buyer's request to return it, and what staff decided. */
+    returnRequest?: PosHardwareReturnRequest;
+    /**
+     * The emails that are sent once (AGL-4038), by key: `canceled`, or
+     * `refunded:{refund key}`. Claimed before the send, so the staff page and a
+     * closure never both send one.
+     */
+    buyerEmails?: Record<string, {
+        state: 'sending' | 'sent' | 'skipped' | 'failed';
+        atMs: number;
+    }>;
 }
 /** The timestamp field each status stamps when it is reached. */
 export declare const POS_HARDWARE_STATUS_STAMP: Record<PosHardwareOrderStatus, keyof PosHardwareOrder>;
@@ -233,20 +468,50 @@ export declare const POS_HARDWARE_ANCHOR = "pos-hardware";
 export declare const POS_HARDWARE_ORDERS_COLLECTION = "hardwareOrders";
 /** The top-level collection of retained hardware sale records. */
 export declare const POS_HARDWARE_SALES_COLLECTION = "posHardwareSales";
-/** `posHardwareSales/{orderId}`: an order with every personal detail left out. */
+/**
+ * A street address as the sale record keeps it: every key present, so a
+ * later write of a different address replaces each one.
+ */
+export interface PosHardwareSaleAddress {
+    line1: string;
+    line2: string | null;
+    city: string;
+    state: string | null;
+    postalCode: string | null;
+    country: string;
+}
+/**
+ * Who bought it, for the reseller's records (AGL-4038): the buyer's name and
+ * address and nothing else of theirs. An online order's are the shipping
+ * name and address; an in-person order's are on its attachment.
+ */
+export interface PosHardwareSaleBuyer {
+    name: string | null;
+    address: PosHardwareSaleAddress | null;
+}
+/**
+ * `posHardwareSales/{orderId}`: an order with every personal detail left out
+ * but the buyer's name and address.
+ */
 export interface PosHardwareSaleRecord {
     orderId: string;
     /** The workspace that bought it, by id; the record outlives the workspace. */
     orgId: string;
     lines: Array<Pick<PosHardwareLine, 'sku' | 'name' | 'quantity' | 'unitCents' | 'lineCents'>>;
     subtotalCents: number;
-    shippingMethod: PosHardwareShippingMethod;
+    shippingMethod: PosHardwareOrderShippingMethod;
     shippingCents: number;
     taxCents: number;
+    /** The register discount on an in-person order's lines; 0 for every online one. */
+    discountCents: number;
     totalCents: number;
     currency: string;
     /** The sales tax sourcing input: country, state and postal code, never the street. */
     shipTo: PosHardwareTaxRegion | null;
+    /** Whether Stripe Tax computed the tax; null on orders before it was recorded. */
+    automaticTax: boolean | null;
+    /** Stripe's tax breakdown: the base each rate was applied to, for the return. */
+    taxLines: PosHardwareTaxLine[];
     stripeCheckoutSessionId: string | null;
     stripePaymentIntentId: string | null;
     stripeHardwareOrderId: string | null;
@@ -263,15 +528,88 @@ export interface PosHardwareSaleRecord {
     registeredAtMs: number | null;
     canceledAtMs: number | null;
     refundedAtMs: number | null;
+    /** Where it was sold; `online` for every order before the in-person sale. */
+    source: PosHardwareOrderSource;
+    /** The register sale an in-person order came from: the selling store and its order. */
+    posHostId: string | null;
+    posOrderId: string | null;
+    /**
+     * Where the money went: `platform` for the Hardware card's checkout, on
+     * the platform's own Stripe account; `seller_store` for an in-person sale,
+     * the selling store's own takings ({@link PosHardwarePaidTo}).
+     */
+    paidTo: {
+        account: 'platform';
+    } | PosHardwarePaidTo;
+    /**
+     * The `storefrontTaxCollected` row the register sale ALSO filed, when it
+     * was paid by a payment link. That row is the whole register sale; the
+     * storefront section leaves this order's part of it out, so the sale is on
+     * the return once, in the hardware section.
+     */
+    storefrontTaxRowId: string | null;
+    /**
+     * The buyer's name and address, for the reseller's records; null when the
+     * order names none (a sale not attached to anyone yet). Absent from a write
+     * whose order no longer has them because the buyer's account was erased,
+     * so the stored ones stay ({@link posHardwareSaleSetOptions}).
+     */
+    buyer?: PosHardwareSaleBuyer | null;
+    /**
+     * When the record is deleted: {@link POS_HARDWARE_SALE_RETENTION_YEARS}
+     * after the sale, by the Firestore TTL policy on `posHardwareSales.expiresAt`.
+     * Null when the record states no sale date, which keeps it rather than
+     * guessing a date to delete it by.
+     */
+    expiresAt: Date | null;
 }
+/**
+ * How long the platform keeps a hardware sale record (AGL-4038): seven years
+ * from the sale, then the record is deleted. Longer than the four years Texas
+ * requires for sales tax records, a margin for an audit of an older period.
+ */
+export declare const POS_HARDWARE_SALE_RETENTION_YEARS = 7;
+/**
+ * When a sale record expires: the same calendar instant, seven years after
+ * the sale was paid (the order's creation where no payment time is stated).
+ * A sale on 29 February expires on 1 March, a day late rather than early.
+ * Null when there is no sale time, so the record is kept, never reaped at
+ * the epoch.
+ */
+export declare function posHardwareSaleExpiry(order: Pick<PosHardwareOrder, 'paidAtMs' | 'createdAtMs'>): Date | null;
 /** The tax region of an order: its address cut down, or what an erasure left. */
 export declare function posHardwareTaxRegion(order: Pick<PosHardwareOrder, 'shipping'>): PosHardwareTaxRegion | null;
+/**
+ * A buyer's business address as an in-person order keeps it (AGL-4038):
+ * trimmed and cut to length, or null when it lacks a street, city, postal
+ * code or two-letter country.
+ */
+export declare function posHardwareBuyerAddress(value: unknown): PosHardwareAddress | null;
+/**
+ * The buyer's name and address as the order holds them now (AGL-4038): the
+ * shipping name and address of an online order, the attachment's of an
+ * in-person one. `undefined` when the order has none BECAUSE its buyer's
+ * account was erased, which tells the write to keep what the record has;
+ * null when it simply names no one yet.
+ */
+export declare function posHardwareSaleBuyer(order: Pick<PosHardwareOrder, 'shipping' | 'attachment' | 'source' | 'buyerErasedAtMs'>): PosHardwareSaleBuyer | null | undefined;
 /**
  * The retained sale record of an order, as it stands. Every field is picked
  * by name, so a field added to the order later reaches the record only when
  * someone decides it should.
  */
 export declare function posHardwareSaleRecord(orderId: string, order: PosHardwareOrder): PosHardwareSaleRecord;
+/**
+ * How every write of a sale record is made (AGL-4038): `set` with exactly
+ * the record's own fields as `mergeFields`, so each one is replaced whole —
+ * a map included, never merged key by key — and a field the record leaves
+ * out is left as stored. The record leaves out only `buyer`, and only once
+ * the buyer's account was erased ({@link posHardwareSaleBuyer}), so the
+ * buyer's name and address outlive the erasure and every write after it.
+ */
+export declare function posHardwareSaleSetOptions(order: PosHardwareOrder): {
+    mergeFields: string[];
+};
 /**
  * What an account erasure does to an order the person placed (AGL-4038): the
  * workspace keeps the order and every amount on it; the buyer comes off it —
@@ -280,8 +618,12 @@ export declare function posHardwareSaleRecord(orderId: string, order: PosHardwar
  * The country, state and postal code stay, because sales tax is sourced by
  * them. Deterministic but for the stamp, and an order already erased no
  * longer answers to the person's uid, so a second run finds nothing.
+ *
+ * The buyer's NAME and ADDRESS stay on the platform's sale record, not on
+ * the order: `buyerErasedAtMs` is what tells the record's next write to keep
+ * them ({@link posHardwareSaleBuyer}, {@link posHardwareSaleSetOptions}).
  */
-export declare function posHardwareBuyerErasedPatch(order: Pick<PosHardwareOrder, 'shipping'>, now: number): Record<string, unknown>;
+export declare function posHardwareBuyerErasedPatch(order: Pick<PosHardwareOrder, 'shipping' | 'attachment' | 'returnRequest'>, now: number): Record<string, unknown>;
 /** An order id: `hw_` and twenty hex characters. */
 export declare const POS_HARDWARE_ORDER_ID: RegExp;
 /** Dollars and cents for the card and the emails. */