@withpotter/lib 0.13.0-next.101

package/dist/api/types/customers.d.ts

@@ -0,0 +1,269 @@
+import { type CustomerNote, type CustomerStatus } from './orders';
+/**
+ * MEMBERS / CUSTOMERS API — as the API sends it.
+ *
+ * One slice of what was a 4,164-line `types.ts`. The sections were already
+ * here as comment fences; they are files now, so a type is found by the
+ * endpoint it belongs to rather than by scrolling.
+ */
+export interface UpdateMemberInput {
+    name?: string;
+    phone?: string;
+    email?: string;
+    status?: CustomerStatus;
+    acceptsMarketing?: boolean;
+    /**
+     * `YYYY-MM-DD`, and null for nearly everybody — most customers never give
+     * one. Day and month drive the birthday automation; the year is kept because
+     * a birth date is also an age, which an age-restricted seller needs.
+     */
+    birthday?: string | null;
+    tags?: string[];
+    notes?: CustomerNote[];
+}
+export type ReviewStatus = 'pending' | 'approved' | 'rejected' | 'flagged';
+export interface ReviewItem {
+    id: string;
+    tenantId: string;
+    contentId: string;
+    memberId: string | null;
+    rating: number;
+    title: string | null;
+    body: string | null;
+    reviewerName: string;
+    reviewerEmail: string | null;
+    status: ReviewStatus;
+    isVerifiedPurchase: boolean;
+    helpfulCount: number;
+    reportCount: number;
+    media: {
+        url: string;
+        type: 'image' | 'video';
+        alt?: string;
+    }[];
+    merchantResponse: string | null;
+    merchantRespondedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ReviewsListResponse {
+    reviews: ReviewItem[];
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+}
+export interface ReviewsQuery {
+    status?: ReviewStatus;
+    contentId?: string;
+    /** Filter to reviews written by a single member (GET /reviews/admin/all). */
+    memberId?: string;
+    rating?: number;
+    isVerifiedPurchase?: boolean;
+    search?: string;
+    page?: number;
+    limit?: number;
+}
+export interface ReviewStats {
+    averageRating: number;
+    totalReviews: number;
+    ratingDistribution: {
+        rating: number;
+        count: number;
+    }[];
+    verifiedPurchaseCount: number;
+}
+export type InvoiceStatus = 'draft' | 'sent' | 'viewed' | 'paid' | 'partially_paid' | 'overdue' | 'cancelled' | 'refunded' | 'void';
+export interface InvoiceItem {
+    id: string;
+    invoiceId: string;
+    contentId?: string | null;
+    title: string;
+    description?: string | null;
+    quantity: number;
+    unitPrice: number;
+    discount: number;
+    tax: number;
+    total: number;
+    position: number;
+}
+export interface Invoice {
+    id: string;
+    tenantId: string;
+    memberId?: string | null;
+    invoiceNumber: string;
+    status: InvoiceStatus;
+    customerEmail: string;
+    customerName?: string | null;
+    customerPhone?: string | null;
+    /** What the client wants printed — a company, often one line. All optional. */
+    customerAddress?: {
+        firstName?: string;
+        lastName?: string;
+        company?: string;
+        line1?: string;
+        line2?: string;
+        city?: string;
+        state?: string;
+        postalCode?: string;
+        country?: string;
+        phone?: string;
+    } | null;
+    /** `poNumber` and `clientTin` live here: what finance needs before it pays. */
+    metadata?: Record<string, unknown> | null;
+    subtotal: number;
+    discountTotal: number;
+    taxTotal: number;
+    total: number;
+    amountPaid: number;
+    amountDue: number;
+    /** What the client kept back — WHT, a settlement discount, a write-off. */
+    deductionTotal?: number;
+    deductions?: InvoiceDeduction[];
+    /** Set when this invoice is the start of a series. */
+    recurrence?: InvoiceRecurrence | null;
+    currency: string;
+    issueDate: string;
+    dueDate: string;
+    paidAt?: string | null;
+    sentAt?: string | null;
+    viewedAt?: string | null;
+    viewCount: number;
+    cancelledAt?: string | null;
+    paymentReference?: string | null;
+    paymentMethod?: string | null;
+    paymentLink?: string | null;
+    note?: string | null;
+    internalNote?: string | null;
+    terms?: string | null;
+    relatedType?: string | null;
+    relatedId?: string | null;
+    items: InvoiceItem[];
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * A balance that closed without money arriving.
+ *
+ * A corporate client here deducts withholding tax at source and remits it to
+ * the FIRS; the merchant gets a credit note and a smaller transfer. It is not a
+ * payment — nothing reaches the ledger or the revenue charts — and the reason
+ * travels with it, because a total nobody can explain is no use in March.
+ */
+export interface InvoiceDeduction {
+    kind: 'wht' | 'discount' | 'write-off';
+    amount: number;
+    label: string;
+    recordedAt: string;
+}
+/**
+ * How often an invoice comes back, kept on the one that started the series.
+ *
+ * Not a subscription: that charges a saved card on Paystack's clock. A retainer
+ * is a document that recurs while the money arrives by transfer, on terms the
+ * merchant set.
+ */
+export interface InvoiceRecurrence {
+    interval: 'weekly' | 'monthly' | 'quarterly' | 'yearly';
+    /** ISO date the next copy is written. */
+    nextRunOn: string;
+    endsOn?: string | null;
+    /** Send each copy as it is written, rather than leaving a draft to check. */
+    autoSend?: boolean;
+    issued?: number;
+}
+export interface RecordDeductionInput {
+    kind: InvoiceDeduction['kind'];
+    amount: number;
+    label: string;
+}
+export interface InvoicesListResponse {
+    invoices: Invoice[];
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+}
+export interface InvoiceStats {
+    draft: number;
+    sent: number;
+    paid: number;
+    overdue: number;
+    cancelled: number;
+    total: number;
+    totalRevenue: number;
+    /** Still owed. Excludes drafts: nobody has been asked to pay them yet. */
+    totalOutstanding: number;
+    /**
+     * How many invoices make up `totalOutstanding`.
+     *
+     * Optional for an API deployed before it shipped. Callers used to add
+     * `sent + overdue` themselves, which missed `viewed` and `partially_paid` —
+     * invoices inside the total but outside the count describing it.
+     */
+    outstanding?: number;
+}
+export interface InvoicesQuery {
+    memberId?: string;
+    /**
+     * One status, or `outstanding` for every status that still means money is
+     * coming. The API resolves the shorthand, so the set can never drift from the
+     * outstanding TOTAL it reports beside it.
+     */
+    status?: InvoiceStatus | 'outstanding';
+    search?: string;
+    fromDate?: string;
+    toDate?: string;
+    page?: number;
+    limit?: number;
+}
+export interface CreateInvoiceInput {
+    memberId?: string;
+    customerEmail: string;
+    customerName?: string;
+    customerPhone?: string;
+    items: {
+        contentId?: string;
+        title: string;
+        description?: string;
+        quantity: number;
+        unitPrice: number;
+        discount?: number;
+        tax?: number;
+        metadata?: Record<string, unknown>;
+    }[];
+    customerAddress?: {
+        company?: string;
+        line1?: string;
+        line2?: string;
+        city?: string;
+        state?: string;
+        country?: string;
+    };
+    issueDate?: string;
+    dueDate: string;
+    currency?: string;
+    note?: string;
+    internalNote?: string;
+    terms?: string;
+    metadata?: Record<string, unknown>;
+    /** Set to make this invoice the start of a series. */
+    recurrence?: InvoiceRecurrence | null;
+    relatedType?: string;
+    relatedId?: string;
+}
+export type UpdateInvoiceInput = Partial<CreateInvoiceInput>;
+export interface RecordPaymentInput {
+    amount: number;
+    paymentReference?: string;
+    paymentMethod?: string;
+}
+export type TabStatus = 'open' | 'settled' | 'voided';
+export interface TabItem {
+    /** Sellable content (menu item) id. */
+    contentId: string;
+    title: string;
+    quantity: number;
+    /** Menu price captured at the time of adding. */
+    unitPrice: number;
+}

package/dist/api/types/customers.js

@@ -0,0 +1 @@
+//# sourceMappingURL=customers.js.map

package/dist/api/types/customers.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/api/types/devices.d.ts

@@ -0,0 +1,390 @@
+/**
+ * Prefixed `BusinessDevice*` deliberately.
+ *
+ * `DeviceKind` already exists in this same barrel and means something else
+ * entirely — which browser an *account* has signed in from. Sharing the word
+ * would eventually put somebody's laptop in a list of card terminals, and here
+ * it collided outright.
+ *
+ * The physical endpoints a business runs: counters, gates, readers, handhelds.
+ *
+ * A payment is one thing a device can emit, not the reason devices exist — a
+ * door reader produces no transaction at all — so what a device IS and what it
+ * may DO are separate fields.
+ */
+export type BusinessDeviceKind = 'pos' | 'nfc_reader' | 'access_reader' | 'gate' | 'kiosk' | 'handheld';
+export type BusinessDeviceCapability = 'capture_payment' | 'verify_access' | 'issue_credential';
+/**
+ * `pending` is a real state, not a gap.
+ *
+ * A device that has been registered and has never spoken to us is not the same
+ * as one working perfectly and quietly, and the pairing screen is built around
+ * that wait.
+ */
+export type BusinessDeviceStatus = 'pending' | 'active' | 'suspended' | 'revoked';
+/**
+ * How a device is allowed to behave.
+ *
+ * Policy, not facts. A gate on a toll road must take money offline — no signal,
+ * car moving — and the most one wrong capture costs is a toll. A terminal
+ * behind a bar has signal, and letting it accept an unbounded card nobody has
+ * authorised is how a merchant finds out on Monday that Saturday was partly
+ * fictional.
+ */
+export interface BusinessDeviceConfig {
+    /** May it take money at all while it cannot reach us. */
+    offlineCapture: boolean;
+    /**
+     * Ceiling on one offline payment, in minor units. Null means no ceiling.
+     *
+     * The number that decides how much a compromised or malfunctioning device can
+     * cost before anybody notices.
+     */
+    offlineMaxAmount: number | null;
+    /** How old a queued payment may be when it finally reaches us. */
+    offlineMaxAgeHours: number;
+    /** How far ahead of us its clock may run before we stop believing it. */
+    clockSkewToleranceSeconds: number;
+    /** How often it should check in with nothing to say. */
+    heartbeatSeconds: number;
+    receiptFooter: string | null;
+}
+/**
+ * Who may sign in at a machine.
+ *
+ * `any_member` is the honest default for a one-till shop — assigning people to
+ * the only machine in the building is ceremony — and `assigned` is what a
+ * four-branch business needs when only three people should open the bar till.
+ */
+export type DeviceOperatorAccess = 'any_member' | 'assigned';
+/**
+ * What somebody may do AT A MACHINE.
+ *
+ * Deliberately not the dashboard's permission map, and the two must never be
+ * merged: a person who may not open Finance still has to close a till, and the
+ * person who runs the books may never touch one.
+ *
+ * This is also the half a merchant actually buys. Sales-by-person is mildly
+ * interesting; who-discounted-that, who-voided-that, who-opened-the-drawer-with-
+ * no-sale is why anybody sets operators up at all.
+ */
+export interface PosPermissions {
+    applyDiscount?: boolean;
+    voidLine?: boolean;
+    voidSale?: boolean;
+    refund?: boolean;
+    openDrawerNoSale?: boolean;
+    closeShift?: boolean;
+    viewShiftTotals?: boolean;
+    editPrice?: boolean;
+}
+/** One person allowed to work one machine. */
+export interface DeviceOperatorRow {
+    memberId: string;
+    accountId: string | null;
+    name: string | null;
+    email: string | null;
+    role: string | null;
+    /**
+     * Whether they can actually sign in.
+     *
+     * A grant with no passcode behind it is a row that does nothing, and the
+     * screen has to say so — otherwise a merchant assigns three people to a till
+     * and none of them can open it.
+     */
+    hasPasscode: boolean;
+    addedAt: string;
+}
+export interface DeviceOperators {
+    operatorAccess: DeviceOperatorAccess;
+    operators: DeviceOperatorRow[];
+}
+export interface BusinessDevice {
+    id: string;
+    /** What the merchant calls it. Matches the sticker on the front of the thing. */
+    deviceId: string;
+    label: string;
+    kind: BusinessDeviceKind;
+    capabilities: BusinessDeviceCapability[];
+    /**
+     * Deliberately absent: which make of terminal, and whose bank estate it
+     * belongs to.
+     *
+     * Box's software runs on the terminal, and which terminal varies per
+     * estate — so it is vendor trivia to the person reading this list. They are
+     * looking for one machine in a room and they find it by its id and its name.
+     * The API keeps both for matching a bank's own report later; neither belongs
+     * on screen.
+     */
+    locationId: string | null;
+    /** Whether the operator list is consulted, or anyone with a passcode may in. */
+    operatorAccess: DeviceOperatorAccess;
+    /** The named config it follows. Null means the defaults. */
+    profileId?: string | null;
+    status: BusinessDeviceStatus;
+    /** A reading, not a stored state — a device that died cannot tell us. */
+    online: boolean;
+    tokenHint: string | null;
+    lastSeenAt: string | null;
+    createdAt: string;
+    /** Resolved, not stored — what somebody set merged over the defaults. */
+    config: BusinessDeviceConfig;
+}
+export interface RegisteredDevice extends BusinessDevice {
+    /** Shown once and never recoverable. Null for a referenced third-party till. */
+    token: string | null;
+    /** The short code to type into the machine. Null for a referenced till. */
+    pairingCode: string | null;
+    pairingExpiresAt: string | null;
+    /**
+     * When this particular code was issued — not the device's `createdAt`.
+     *
+     * A code reissued for a device registered last week would otherwise make any
+     * "time left" indicator start almost empty, because it would be measuring
+     * against the registration rather than against the code in front of the person.
+     */
+    pairingIssuedAt: string | null;
+    /**
+     * The API's clock at the moment of the answer.
+     *
+     * The expiry is the server's and the countdown runs on the browser's, and the
+     * two disagree more often than is comfortable. Having both lets the panel
+     * work in offsets rather than trusting a clock nobody controls.
+     */
+    serverTime: string;
+}
+/**
+ * A machine standing in a room that does not belong to anybody yet.
+ *
+ * What the merchant sees after typing the six characters off its screen and
+ * before pressing Link. Every field is what the MACHINE said about itself while
+ * holding no credential at all, which is why the screen shows it for
+ * confirmation rather than saving it: a merchant looking at the thing can tell
+ * whether they read the code off the right one.
+ */
+export interface DeviceEnrolmentPreview {
+    code: string;
+    /** What it says it is. Pre-selects the kind, and is overridable. */
+    kind: BusinessDeviceKind | null;
+    /**
+     * Model, serial, OS, app version — whatever it knows about itself.
+     *
+     * Free-form because the fleet is not ours: an Android terminal, a browser on
+     * a laptop and a purpose-built gate report different things, and a fixed
+     * shape would be wrong for two of the three.
+     */
+    descriptor: Record<string, string>;
+    /** The name it proposes, usually its serial. Pre-filled, not imposed. */
+    suggestedDeviceId: string | null;
+    expiresAt: string;
+    serverTime: string;
+}
+/**
+ * The device record a claim brought into existence.
+ *
+ * `pending`, and that is not a delay to hide: a device is live at the moment
+ * the MACHINE confirms it holds its credential, which it is already asking for.
+ * The linking screen waits on that rather than declaring success on the strength
+ * of its own request having succeeded.
+ */
+export interface LinkedDevice extends BusinessDevice {
+    linkedAt: string;
+}
+/** What a reissued code comes back as. Same three facts, no device attached. */
+export interface ReissuedPairingCode {
+    pairingCode: string;
+    pairingExpiresAt: string;
+    pairingIssuedAt: string;
+    serverTime: string;
+}
+/**
+ * One offline payment somebody has to say yes or no to.
+ *
+ * A device took the money while it had no connection, so nobody has confirmed
+ * it. There is no provider record to check — the charge happened on the machine
+ * — so the merchant establishes it from their bank, their till, or the customer.
+ */
+export interface OfflineCapture {
+    id: string;
+    reference: string;
+    /** Minor units. */
+    amount: number;
+    currency: string;
+    deviceId: string | null;
+    customerName: string | null;
+    description: string | null;
+    /** When the device took it, not when we heard about it. */
+    capturedAt: string;
+}
+/** One provider message we could not finish recording, and may be able to retry. */
+export interface WebhookFailure {
+    id: string;
+    provider: string;
+    eventType: string;
+    reference: string | null;
+    errorMessage: string | null;
+    receivedAt: string;
+}
+/**
+ * One disagreement between what the bank did and what we recorded.
+ *
+ * Not a log line — a piece of work. Somebody has to look at it, decide, and be
+ * able to say later what they decided, which is why it carries a status rather
+ * than being counted and forgotten.
+ */
+export interface PaymentDiscrepancy {
+    id: string;
+    kind: 'unrecorded_payment' | 'amount_mismatch' | 'fee_mismatch' | 'unsettled';
+    status: 'open' | 'resolved' | 'ignored';
+    summary: string;
+    currency: string;
+    /** Minor units. What our ledger says, and what the bank says. */
+    expectedAmount: number | null;
+    actualAmount: number | null;
+    transactionId: string | null;
+    providerReference: string | null;
+    providerSettlementId: string | null;
+    detectedAt: string;
+}
+/**
+ * A customer who spent more than they had.
+ *
+ * Only reachable offline, where a reader was working from a balance that was
+ * already out of date and could not know what another one had just taken.
+ */
+export interface OverdrawnAccount {
+    memberId: string;
+    /** Positive: what is owed, not a negative holding. Minor units. */
+    owed: number;
+    currency: string;
+}
+/** A band, with the two things a counter needs beside it. */
+export interface Band {
+    id: string;
+    memberId: string;
+    kind: 'wristband' | 'card' | 'fob' | 'sticker' | 'phone';
+    uid: string;
+    label: string | null;
+    status: 'active' | 'lost' | 'replaced' | 'expired' | 'revoked';
+    /** Whether this tag can prove it is not a copy. */
+    secure: boolean;
+    expiresAt: string | null;
+    issuedAt: string;
+    holderName: string | null;
+    holderEmail: string | null;
+    /** Minor units. Zero for a holder who has never topped up. */
+    balance: number;
+    currency: string;
+}
+/**
+ * A drawer session: opened with a float, closed with a count.
+ *
+ * Every figure is MINOR units, and every one of them is CASH except
+ * `otherTakings`. That separation is the design rather than an omission: card
+ * money reconciles against the provider, not against a drawer, and a figure
+ * mixing the two is never zero and therefore never read.
+ */
+export type ShiftStatus = 'open' | 'closed' | 'abandoned';
+export interface DeviceShift {
+    id: string;
+    /** Our uuid for the machine. `deviceLabel` is what a person reads. */
+    deviceId: string;
+    deviceLabel: string | null;
+    locationId: string | null;
+    status: ShiftStatus;
+    openedByName: string | null;
+    openedByAccountId: string | null;
+    openedAt: string;
+    openingFloat: number;
+    closedByName: string | null;
+    closedAt: string | null;
+    /**
+     * What a human counted. Null on a shift nobody closed — and null is not
+     * zero: a zero is a claim that the drawer balanced.
+     */
+    countedCash: number | null;
+    /** float + cash taken - cash refunded - paid out, frozen at closing. */
+    expectedCash: number | null;
+    cashSales: number | null;
+    cashRefunds: number | null;
+    paidOut: number;
+    /** counted - expected. Negative is short. Over is not good news either. */
+    variance: number | null;
+    /** Card and the rest. Below the rule: it settles somewhere else. */
+    otherTakings: number | null;
+    orderCount: number | null;
+    currency: string;
+    shiftNoteId: string | null;
+}
+/**
+ * One row of a sales report: a machine, a person, or a channel.
+ *
+ * Deliberately the same shape for all three, because they are the same question
+ * asked three ways and a screen showing them side by side should not need three
+ * renderers to do it.
+ */
+export interface HardwareReportRow {
+    /** The machine's name, the person's name, or the channel key. */
+    key: string;
+    label: string;
+    orders: number;
+    /** Minor units, like the rest of the ledger. */
+    revenue: number;
+}
+/** Where an order for machines has got to. */
+export type HardwareOrderState = 'requested' | 'confirmed' | 'shipped' | 'delivered' | 'cancelled';
+/** Where the box goes. Frozen at the order. */
+export interface ShipTo {
+    name: string;
+    phone: string;
+    address: string;
+    city?: string | null;
+    notes?: string | null;
+}
+export interface HardwareSkuOption {
+    sku: string;
+    name: string;
+    summary: string;
+    kind: BusinessDeviceKind;
+    includes: string[];
+    /** Working days, as a range a merchant can plan around. */
+    leadTimeDays: [number, number];
+    /** Minor units. Never null here: unpriced SKUs are filtered out server-side. */
+    price: number;
+}
+export interface HardwareOrder {
+    id: string;
+    /** What support asks for on the phone. */
+    reference: string;
+    sku: string;
+    name: string;
+    /** What kind of machine, so a row can carry its glyph. */
+    kind: BusinessDeviceKind;
+    quantity: number;
+    /** Minor units, frozen at the order. */
+    unitAmount: number;
+    currency: string;
+    state: HardwareOrderState;
+    shipTo: ShipTo;
+    courier: string | null;
+    trackingReference: string | null;
+    expectedAt: string | null;
+    placedAt: string;
+    deliveredAt: string | null;
+}
+/**
+ * A named config, applied to many machines.
+ *
+ * Carries both the patch somebody chose and the resolved whole, because they
+ * answer different questions: what did I set, and how will a machine following
+ * this actually behave.
+ */
+export interface DeviceProfile {
+    id: string;
+    name: string;
+    isDefault: boolean;
+    config: Partial<BusinessDeviceConfig>;
+    resolved: BusinessDeviceConfig;
+    /** How many machines follow it. The number that makes editing frightening. */
+    deviceCount: number;
+}

package/dist/api/types/devices.js

@@ -0,0 +1 @@
+//# sourceMappingURL=devices.js.map

package/dist/api/types/devices.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}