@aglyn/plugins-commerce 1.0.0-beta.278 → 1.0.0-beta.283

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

@@ -0,0 +1,288 @@
+/**
+ * @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.
+ */
+/** The register's currency, and so the shop's: US dollars. */
+export declare const POS_HARDWARE_CURRENCY = "usd";
+/**
+ * Where the shop ships. Stripe's Terminal hardware shop ships to many
+ * countries, but the register sells in US dollars only and the readers a
+ * merchant buys here are registered to a US Location, so the shop is US-only
+ * (Stripe itself excludes the US Virgin Islands, military addresses and
+ * P.O. boxes).
+ */
+export declare const POS_HARDWARE_SHIP_COUNTRIES: readonly string[];
+/** The most of one item, and the most units, a single order may hold. */
+export declare const POS_HARDWARE_MAX_PER_LINE = 10;
+export declare const POS_HARDWARE_MAX_UNITS = 20;
+/** The env names the shop reads, named once for the reader and the docs. */
+export declare const POS_HARDWARE_ENV: {
+    /** `true` releases the shop. Absent or anything else keeps it hidden. */
+    readonly enabled: "POS_HARDWARE_SHOP_ENABLED";
+    /** JSON `{ "<sku>": <Stripe's price in cents> }`. */
+    readonly prices: "POS_HARDWARE_PRICES";
+    /**
+     * The markup on Stripe's price, an integer in basis points (100 = 1%).
+     * Absent, {@link POS_HARDWARE_DEFAULT_MARKUP_BPS} applies.
+     */
+    readonly markupBps: "POS_HARDWARE_MARKUP_BPS";
+    /** JSON `{ "standard" | "express" | "priority": <cents> }`. */
+    readonly shipping: "POS_HARDWARE_SHIPPING";
+    /** `true` turns Stripe automatic tax on for hardware checkouts. */
+    readonly automaticTax: "POS_HARDWARE_AUTOMATIC_TAX";
+};
+/**
+ * The markup when the deployment sets none: 3000 basis points on Stripe's
+ * price. The business sets it; this is the one place the default lives, and
+ * `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 interface PosHardwareSku {
+    id: PosHardwareSkuId;
+    kind: 'reader' | 'accessory';
+    /** What Stripe's hardware shop calls it, for the staff member ordering it. */
+    stripeProductName: string;
+    /** What the merchant sees. */
+    displayName: string;
+    /** One line on what it is for. */
+    use: string;
+}
+/**
+ * Every item the shop can sell. An item is offered only once its Stripe
+ * price is configured, so one Stripe stops selling disappears by deleting its
+ * price, not by a release.
+ */
+export declare const POS_HARDWARE_SKUS: readonly PosHardwareSku[];
+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;
+/** 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. */
+    costs: Partial<Record<PosHardwareSkuId, number>>;
+    markupBps: number;
+    shipping: Array<{
+        method: PosHardwareShippingMethod;
+        cents: number;
+    }>;
+    automaticTax: boolean;
+}
+/**
+ * The shop's configuration from the environment, or `null` while the shop is
+ * hidden: not released, no reader priced, a malformed markup, or no shipping
+ * figure. An ABSENT markup is the default
+ * ({@link POS_HARDWARE_DEFAULT_MARKUP_BPS}), so a deployment can never sell
+ * at cost by forgetting a variable; `0` is a valid, explicit choice to sell
+ * at Stripe's price. A markup that is set but unreadable hides the shop
+ * rather than guessing.
+ *
+ * Unknown item ids and malformed figures are dropped one by one rather than
+ * 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;
+/**
+ * What the merchant pays for one item: Stripe's price plus the markup,
+ * rounded half up to the cent, in integer math throughout.
+ *
+ * `cost + round(cost × bps / 10 000)`. The markup is basis points ON COST, so
+ * a 50% markup is `5000` and a price at which half of it is profit (a 50%
+ * margin) is `10000`. Whichever the business means, it is this one number.
+ */
+export declare function posHardwareUnitCents(costCents: number, markupBps: number): number;
+/** An item as the shop offers it: the merchant's price, never Stripe's. */
+export interface PosHardwareOffer {
+    sku: PosHardwareSkuId;
+    kind: PosHardwareSku['kind'];
+    name: string;
+    use: string;
+    unitCents: number;
+}
+/** The items on offer, readers first, in catalog order. */
+export declare function posHardwareOffers(config: PosHardwareConfig): PosHardwareOffer[];
+export interface PosHardwareLine {
+    sku: PosHardwareSkuId;
+    name: string;
+    quantity: number;
+    unitCents: number;
+    lineCents: number;
+}
+export type PosHardwareCartResult = {
+    ok: true;
+    lines: PosHardwareLine[];
+    subtotalCents: number;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * A merchant's basket priced on the SERVER: every item must be on offer, each
+ * quantity a whole number from 1 to {@link POS_HARDWARE_MAX_PER_LINE}, and
+ * the order at most {@link POS_HARDWARE_MAX_UNITS} units. A repeated item is
+ * folded into one line. Prices come from the config, never the request.
+ */
+export declare function pricePosHardwareCart(config: PosHardwareConfig, requested: unknown): PosHardwareCartResult;
+export declare const POS_HARDWARE_METADATA_TYPE = "pos-hardware-order";
+export declare function encodePosHardwareLines(lines: readonly PosHardwareLine[]): string;
+export declare function decodePosHardwareLines(encoded: unknown): PosHardwareLine[] | null;
+export type PosHardwareOrderStatus = 'paid' | 'ordered' | 'shipped' | 'delivered' | 'registered' | 'canceled' | 'refunded';
+export declare const POS_HARDWARE_ORDER_STATUSES: readonly PosHardwareOrderStatus[];
+export declare function isPosHardwareOrderStatus(value: unknown): value is PosHardwareOrderStatus;
+/** What the merchant reads on the Hardware card. */
+export declare const POS_HARDWARE_STATUS_LABELS: Record<PosHardwareOrderStatus, string>;
+/** What staff read on the orders page: where the order is in fulfillment. */
+export declare const POS_HARDWARE_STAFF_STATUS_LABELS: Record<PosHardwareOrderStatus, string>;
+export declare function nextPosHardwareStatus(status: PosHardwareOrderStatus): PosHardwareOrderStatus | null;
+/**
+ * Whether the order may still be canceled or refunded in full: only before it
+ * ships. Once a parcel is on its way the money comes back through a return of
+ * the hardware, which is a separate process this phase does not automate.
+ */
+export declare function posHardwareRefundable(status: PosHardwareOrderStatus): boolean;
+export interface PosHardwareAddress {
+    line1: string;
+    line2?: string;
+    city: string;
+    state?: string;
+    postalCode: string;
+    country: string;
+}
+/**
+ * What sales tax is sourced by: where the order shipped, without the street
+ * or the person. An erasure keeps this much of the address (see
+ * {@link posHardwareBuyerErasedPatch}) and the retained sale record holds
+ * nothing finer ({@link PosHardwareSaleRecord}).
+ */
+export interface PosHardwareTaxRegion {
+    country: string;
+    state: string | null;
+    postalCode: string | null;
+}
+export interface PosHardwareTracking {
+    carrier: string;
+    number: string;
+    url: string | null;
+}
+/** `orgs/{orgId}/hardwareOrders/{orderId}`, written only by the server. */
+export interface PosHardwareOrder {
+    orgId: string;
+    /** The site whose POS settings the order was placed from. */
+    hostId: string;
+    /** The member who started the checkout; `null` once their account is erased. */
+    createdBy: string | null;
+    /** Where the order emails go: the address entered at checkout. */
+    contactEmail: string | null;
+    lines: PosHardwareLine[];
+    subtotalCents: number;
+    shipping: {
+        method: PosHardwareShippingMethod;
+        label: string;
+        cents: number;
+        name: string | null;
+        phone: string | null;
+        address: PosHardwareAddress | null;
+        /**
+         * Set when the buyer's account is erased, in place of `address`: the part
+         * of it sales tax is sourced by.
+         */
+        taxRegion?: PosHardwareTaxRegion | null;
+    };
+    taxCents: number;
+    totalCents: number;
+    currency: string;
+    stripeCheckoutSessionId: string;
+    stripePaymentIntentId: string | null;
+    /** Stripe's hardware order id, recorded by staff (phase 2 sets it itself). */
+    stripeHardwareOrderId: string | null;
+    tracking: PosHardwareTracking | null;
+    status: PosHardwareOrderStatus;
+    livemode: boolean;
+    createdAtMs: number;
+    updatedAtMs: number;
+    paidAtMs: number;
+    orderedAtMs?: number;
+    shippedAtMs?: number;
+    deliveredAtMs?: number;
+    registeredAtMs?: number;
+    canceledAtMs?: number;
+    refundedAtMs?: number;
+    refundId?: string | null;
+    /** The cents Stripe reported refunding. */
+    refundedCents?: number;
+    /** When the buyer's account was erased and their details taken off the order. */
+    buyerErasedAtMs?: number;
+}
+/** The timestamp field each status stamps when it is reached. */
+export declare const POS_HARDWARE_STATUS_STAMP: Record<PosHardwareOrderStatus, keyof PosHardwareOrder>;
+/** The Hardware card's anchor: Checkout returns to it and the emails link at it. */
+export declare const POS_HARDWARE_ANCHOR = "pos-hardware";
+/** The collection under `orgs/{orgId}`, named once. */
+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. */
+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;
+    shippingCents: number;
+    taxCents: number;
+    totalCents: number;
+    currency: string;
+    /** The sales tax sourcing input: country, state and postal code, never the street. */
+    shipTo: PosHardwareTaxRegion | null;
+    stripeCheckoutSessionId: string | null;
+    stripePaymentIntentId: string | null;
+    stripeHardwareOrderId: string | null;
+    refundId: string | null;
+    refundedCents: number | null;
+    status: PosHardwareOrderStatus;
+    livemode: boolean;
+    createdAtMs: number;
+    updatedAtMs: number;
+    paidAtMs: number | null;
+    orderedAtMs: number | null;
+    shippedAtMs: number | null;
+    deliveredAtMs: number | null;
+    registeredAtMs: number | null;
+    canceledAtMs: number | null;
+    refundedAtMs: number | 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;
+/**
+ * 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;
+/**
+ * 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 —
+ * who started it, the email, the name, the phone, the street and the
+ * tracking, which names the parcel to a carrier who would say where it went.
+ * 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.
+ */
+export declare function posHardwareBuyerErasedPatch(order: Pick<PosHardwareOrder, 'shipping'>, 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. */
+export declare function formatPosHardwareCents(cents: number): string;