@withpotter/lib 0.13.0-next.101

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

@@ -0,0 +1,311 @@
+/**
+ * ONBOARDING 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 ProvisionTenantResult {
+    tenant: {
+        id: string;
+        slug: string;
+        businessName: string;
+        status: string;
+        templateId: string;
+    };
+    onboardingChecklist?: {
+        id: string;
+        steps: Array<{
+            id: string;
+            stepKey: string;
+            status: string;
+        }>;
+    };
+}
+export interface OnboardingStep {
+    id: string;
+    stepKey: string;
+    status: 'pending' | 'in_progress' | 'completed' | 'skipped';
+    label: string;
+    description?: string;
+    itemCount?: number;
+    requiredCount?: number;
+    /**
+     * A ready-made destination. The progress endpoint has never sent one — it
+     * sends `dashboardPath` — so nothing may depend on this being present. Kept
+     * because the accept/agency responses do carry it, and because the day the
+     * API starts sending a real link, `stepHref` should prefer it.
+     */
+    link?: string;
+    /**
+     * Where the API thinks this step is done, in the OLD editor's addresses:
+     * `/content/packages`, `/settings/branding`, `/settings/payments`. None of
+     * them are dashboard routes. `stepHref` in `setup-steps` translates.
+     */
+    dashboardPath?: string;
+}
+export interface OnboardingProgress {
+    checklist: {
+        id: string;
+        tenantId: string;
+        dismissed: boolean;
+        steps: OnboardingStep[];
+    };
+    progress: number;
+    allComplete: boolean;
+}
+export interface Settlement {
+    id: string;
+    grossAmount: number;
+    paystackFee: number;
+    platformFee: number;
+    netAmount: number;
+    currency: string;
+    status: string;
+    settlementType?: 'auto' | 'withdrawal' | 'reconciliation';
+    bankAccount?: {
+        bankName: string;
+        accountNumber: string;
+    };
+    settledAt: string | null;
+    createdAt: string;
+}
+export interface SettlementSummary {
+    totalSettled: number;
+    totalPending: number;
+    totalFailed: number;
+    count: number;
+    platformFeesCollected: number;
+    currency: string;
+}
+/**
+ * Where the merchant's money currently is, split by who can actually move it.
+ *
+ * There is no `availableBalance` because there is no such thing. Box does
+ * not custody merchant money: once a bank account exists, every payment
+ * carries that merchant's provider subaccount and the provider settles their
+ * share straight to them. The old single figure added money already paid to
+ * the merchant to money Box genuinely owed, and the page rendered the sum
+ * as "Available to withdraw" beside a Withdraw button.
+ */
+export interface MerchantBalance {
+    /** Collected by the provider, on its way to the merchant's bank. NGN. */
+    inTransit: number;
+    /** Taken before a bank account existed. Box holds and owes this. NGN. */
+    heldByPotter: number;
+    /** Payouts of heldByPotter still in flight. NGN. */
+    pendingWithdrawals: number;
+    /** Reached the merchant's bank via the provider, all time. NGN. */
+    settledToBank: number;
+    currency: string;
+}
+/**
+ * One chargeback: money being taken back off the merchant.
+ *
+ * The only money record in this product with a deadline attached. Missing it
+ * auto-approves the claim, so `daysLeft` is the field the surface leads on.
+ */
+export interface Dispute {
+    id: string;
+    /** open | awaiting_merchant | awaiting_provider | won | lost | accepted */
+    status: string;
+    /** The provider's own reason string. Shown as given. */
+    category: string | null;
+    disputedAmount: number;
+    currency: string;
+    dueAt: string | null;
+    /**
+     * Whole days left to answer, computed by the API. Negative means the deadline
+     * has passed, deliberately — clamping to zero would imply there is still time.
+     */
+    daysLeft: number | null;
+    resolvedAt: string | null;
+    merchantResponse: string | null;
+    respondedAt: string | null;
+    providerReference: string | null;
+    transactionId: string | null;
+    /** Who paid. Null when the dispute matched no payment we hold. */
+    customerName: string | null;
+    /** What the merchant attached. The bank decides on these, not on prose. */
+    evidenceFiles: DisputeEvidenceFile[];
+    createdAt: string;
+}
+/** One file attached to a dispute. */
+export interface DisputeEvidenceFile {
+    /** The provider's handle, quoted back when the dispute is answered. */
+    fileName: string;
+    /** What the merchant called it, which is the only name they recognise. */
+    originalName: string;
+    uploadedAt: string;
+}
+export interface DisputeStats {
+    /** How many are waiting on the merchant. The number that badges. */
+    needsMerchant: number;
+    amountAtRisk: number;
+    nextDueAt: string | null;
+    daysLeft: number | null;
+    amountLost: number;
+    /** Answered and with the bank. Optional on an API that predates the counts. */
+    responded?: number;
+    won?: number;
+    lost?: number;
+    total: number;
+    currency: string;
+}
+/**
+ * When the provider actually pays this merchant.
+ *
+ * The rail used to assert "goes to your bank automatically" for everyone, which
+ * is false for a subaccount on a `manual` schedule and answered a question
+ * nobody had while dodging the one they did: when.
+ */
+export interface PayoutSchedule {
+    /** Null means we could not establish it. Never the same as `manual`. */
+    schedule: 'auto' | 'weekly' | 'monthly' | 'manual' | null;
+    /** ISO date, or null when nothing can be said honestly. */
+    nextPayoutDate: string | null;
+    /**
+     * Where the date came from. `schedule` is the provider's own rule; `history`
+     * is a pattern observed in this merchant's past payouts, which is a weaker
+     * claim and has to read as one ("usually" rather than "expected").
+     */
+    dateSource: 'schedule' | 'history' | null;
+    /** True only when the provider moves money without being asked. */
+    automatic: boolean;
+}
+/** One payment the provider included in a payout. */
+export interface SettlementLineItem {
+    id: string;
+    reference: string;
+    amount: number;
+    fees: number;
+    channel: string | null;
+    paidAt: string | null;
+    customerName: string | null;
+    customerEmail: string | null;
+}
+/** What one bank deposit was made of. */
+export interface SettlementReceipt {
+    settlementId: string;
+    grossAmount: number;
+    providerFee: number;
+    platformFee: number;
+    netAmount: number;
+    currency: string;
+    status: string;
+    settledAt: string | null;
+    bankAccountId: string | null;
+    transactions: SettlementLineItem[];
+    transactionCount: number;
+}
+export interface WithdrawalResult {
+    settlementId: string;
+    grossAmount: number;
+    paystackFee: number;
+    platformFee: number;
+    netAmount: number;
+    status: string;
+    message: string;
+}
+export interface OnboardingAgencyProposalOperation {
+    id?: string;
+    target?: string;
+    proposal?: Record<string, unknown>;
+    requiresApproval?: boolean;
+}
+export interface OnboardingAgencySetupProposal {
+    metadata?: {
+        patchFormat?: string;
+        confidence?: Record<string, unknown>;
+    };
+    operations?: OnboardingAgencyProposalOperation[];
+    evidenceEventIds?: string[];
+}
+export type OnboardingAgencyProposalReviewActionId = 'accept' | 'apply' | 'reject' | 'request_clarification';
+export interface OnboardingAgencyProposalReviewAction {
+    id: OnboardingAgencyProposalReviewActionId;
+    label: string;
+}
+export interface OnboardingAgencyProposalReviewState {
+    statusLabel: string;
+    guidance: string | null;
+    actions: OnboardingAgencyProposalReviewAction[];
+}
+export interface OnboardingAgencyConversationQuestion {
+    id: string;
+    prompt: string;
+    options: string[];
+    allowNotSure: boolean;
+    skippable: boolean;
+    evidenceTarget: string | null;
+    proposalImpact: string[];
+    reason: string | null;
+}
+export interface OnboardingAgencyConversation {
+    mode: string;
+    message: string;
+    understanding: string;
+    interactionStyle: Record<string, unknown>;
+    nextQuestion: OnboardingAgencyConversationQuestion | null;
+    suggestedNextSteps: string[];
+}
+export interface OnboardingAgencyProposal {
+    id: string;
+    tenantId: string;
+    status: 'review_required' | 'clarification_required' | 'accepted' | 'edited' | 'applied' | 'rejected' | 'failed';
+    reviewState: OnboardingAgencyProposalReviewState;
+    rawIntent: string;
+    proposal: OnboardingAgencySetupProposal | null;
+    memoryCandidates: Record<string, unknown>[];
+    agencyExpressionProposals: Record<string, unknown>[];
+    agencyConversation: OnboardingAgencyConversation | null;
+    clarificationRequests: string[];
+    audit: Record<string, unknown>;
+    runtime: {
+        traceId: string | null;
+        version: string | null;
+    };
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ProposeOnboardingAgencySetupInput {
+    rawIntent: string;
+    contextPack?: Record<string, unknown>;
+}
+export interface ReviewOnboardingAgencyProposalInput {
+    decision: 'accept' | 'reject' | 'edit' | 'request_clarification';
+    note?: string;
+    editedProposal?: Record<string, unknown>;
+}
+export interface ApplyOnboardingAgencyProposalInput {
+    note?: string;
+}
+/**
+ * Why a storefront cannot take an order yet.
+ *
+ * Mirrors GetStorefrontReadinessUseCase in potter-api. `reason` is shown to the
+ * merchant verbatim and says what BREAKS rather than what is absent — a
+ * merchant who knew a shipping zone was also the checkout's address book would
+ * have made one already.
+ */
+export type CoreReadinessKey = 'sellable' | 'reachable' | 'payable' | 'contactable' | 'bookable' | 'schedulable';
+/**
+ * A go-live check a host box adds of its own ("host_wallet" on a box whose
+ * wallet must be set up first). The dashboard knows nothing about it beyond
+ * what the blocker says: `title` is the row's label and `dashboardPath` its
+ * link. When the checklist has a step with the same key, that step is the row,
+ * marked as needed to go live.
+ */
+export type HostReadinessKey = `host_${string}`;
+export interface ReadinessBlocker {
+    key: CoreReadinessKey | HostReadinessKey;
+    title: string;
+    reason: string;
+    dashboardPath: string;
+}
+export interface StorefrontReadiness {
+    ready: boolean;
+    blockers: ReadinessBlocker[];
+    /** Checks that passed, so the dialog can show the work already done. */
+    satisfied: ReadinessBlocker['key'][];
+}

package/dist/api/types/onboarding.js

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

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

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

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

@@ -0,0 +1,136 @@
+/**
+ * ANALYTICS API — the operating panels.
+ *
+ * What each endpoint under /analytics sends for the panels that say how the
+ * business is running: stock, orders to send, bookings, invoices, tickets,
+ * benchmarks and the weekly summary. Mirrors `dto/performance.dto.ts` in
+ * potter-api. Split from `analytics.ts`, which had reached its size limit.
+ */
+export interface StockRiskRow {
+    id: string;
+    title: string;
+    available: number;
+    lowStockThreshold: number;
+    unitsSold: number;
+    unitsPerDay: number;
+    /** At the current pace. Null when nothing sold, so there is no pace. */
+    daysLeft: number | null;
+}
+export interface StockCover {
+    windowDays: number;
+    deadAfterDays: number;
+    tracked: number;
+    outOfStockCount: number;
+    runningOutCount: number;
+    deadCount: number;
+    outOfStock: StockRiskRow[];
+    runningOut: StockRiskRow[];
+    dead: StockRiskRow[];
+}
+export interface StaffBookingRow {
+    staffId: string | null;
+    name: string;
+    total: number;
+    attended: number;
+    noShows: number;
+    cancelled: number;
+    noShowRate: number | null;
+}
+export interface BookingPerformance {
+    total: number;
+    attended: number;
+    noShows: number;
+    cancelled: number;
+    /** 0 to 100, over bookings whose time has come. */
+    noShowRate: number | null;
+    cancellationRate: number | null;
+    priorNoShowRate: number | null;
+    byStaff: StaffBookingRow[];
+}
+export interface Fulfilment {
+    waiting: number;
+    waitingOverThreeDays: number;
+    oldestWaitingDays: number | null;
+    avgHoursToFulfil: number | null;
+    /** How many fulfilments the average rests on. */
+    sample: number;
+}
+export interface CollectionSpeed {
+    paidCount: number;
+    avgDaysToPay: number | null;
+    medianDaysToPay: number | null;
+    paidOnTimePercent: number | null;
+}
+/** The room: tabs open now, and what settled ones looked like. */
+export interface DineIn {
+    openTabs: number;
+    /** What the open tabs add up to so far, in major units. */
+    openValue: number;
+    settledTabs: number;
+    settledValue: number;
+    averageBill: number | null;
+    /** Opening a tab to settling it: how long a table is held. */
+    averageMinutesAtTable: number | null;
+    voidedTabs: number;
+}
+export interface EventTierSales {
+    id: string;
+    name: string;
+    price: number;
+    quantity: number;
+    sold: number;
+    revenue: number;
+    checkedIn: number;
+}
+export interface EventSalesRow {
+    id: string;
+    title: string;
+    eventDate: string | null;
+    sold: number;
+    capacity: number;
+    revenue: number;
+    checkedIn: number;
+    tiers: EventTierSales[];
+}
+export interface EventSales {
+    events: EventSalesRow[];
+}
+export interface BenchmarkMetric {
+    key: string;
+    label: string;
+    yours: number;
+    median: number;
+    /** 0 to 100, with 100 the good end whichever way the metric points. */
+    percentile: number;
+    unit: 'percent';
+    higherIsBetter: boolean;
+}
+export interface Benchmarks {
+    available: boolean;
+    peers: number;
+    reason: string | null;
+    metrics: BenchmarkMetric[];
+}
+export interface WeeklyDigest {
+    periodLabel: string;
+    headline: string;
+    lines: string[];
+    actions: string[];
+    /** Plain text, short enough for a WhatsApp message. */
+    text: string;
+}
+/** Orders, discount cost and refunds in each bucket of the ledger; each sums to its total. */
+export interface LedgerSeries {
+    ordersTimeSeries?: {
+        date: string;
+        value: number;
+    }[];
+    discountsTimeSeries?: {
+        date: string;
+        value: number;
+    }[];
+    refundsTimeSeries?: {
+        date: string;
+        value: number;
+    }[];
+}

package/dist/api/types/operations.js

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

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

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

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

@@ -0,0 +1,242 @@
+import { type DeliveryMethod, type FulfillmentStatus, type OrderEventType, type OrderStatus, type PaymentStatus } from './filters';
+/**
+ * ORDERS 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.
+ */
+/** One line of an order's history. */
+export interface OrderTimelineEntry {
+    id: string;
+    type: OrderEventType;
+    summary: string;
+    fromValue?: string | null;
+    toValue?: string | null;
+    /** Null when the system did it (webhook, checkout, scheduler). */
+    actorName?: string | null;
+    accountId?: string | null;
+    data: Record<string, unknown>;
+    occurredAt: string;
+}
+/**
+ * Result of a batch order action. The success key differs per action so a
+ * caller reads the verb that actually happened.
+ */
+export type BulkOrderResult<K extends string> = {
+    [key in K]: string[];
+} & {
+    failed: {
+        orderId: string;
+        reason: string;
+    }[];
+};
+/**
+ * Scope for `GET /orders/stats`. Mirrors the list query minus the status
+ * filters: the stats are the status breakdown, so filtering by one would
+ * collapse the rest to zero.
+ */
+export interface OrderStatsQuery {
+    /** Same narrowing as OrdersQuery, so the counts describe the rows shown. */
+    locationIds?: string[];
+    /**
+     * And the same three the hardware build added, for the same reason.
+     *
+     * A band reading "42 unfulfilled" above a list filtered to one till is worse
+     * than no band at all — the count would be describing the whole business
+     * while the rows describe one machine.
+     */
+    deviceIds?: string[];
+    operatorAccountIds?: string[];
+    channels?: string[];
+    intent?: string;
+    memberId?: string;
+    search?: string;
+    fromDate?: string;
+    toDate?: string;
+}
+export interface OrdersQuery {
+    /**
+     * Branches to show. A view preference, not a boundary: the API intersects
+     * whatever is sent with the caller's own scope, so a member assigned to one
+     * branch cannot widen this to see another's.
+     */
+    locationIds?: string[];
+    status?: OrderStatus;
+    paymentStatus?: PaymentStatus;
+    fulfillmentStatus?: FulfillmentStatus;
+    /**
+     * How the order reaches the customer. A set, because the useful ask is one:
+     * the handover queue wants everything with somewhere to be, so that a
+     * download or a dine-in tab (`none`) never joins a list of things to send.
+     */
+    deliveryMethod?: DeliveryMethod[];
+    bookingStatus?: string;
+    /**
+     * Which machines rang it, by the merchant's own name for them.
+     *
+     * Not our uuid: the same key `transactions.device_id` uses, so one filter
+     * covers an order and the money it produced.
+     */
+    deviceIds?: string[];
+    /** Who was signed in at the machine. */
+    operatorAccountIds?: string[];
+    /**
+     * How the sale arrived: `storefront`, `walk_in`, `whatsapp`, `cafe`.
+     *
+     * Kept distinct from `deviceIds`. A merchant with one till asks "what did we
+     * take at the counter" long before they ask "what did till 2 take", and a
+     * merchant with no hardware at all still asks the first.
+     */
+    channels?: string[];
+    intent?: string;
+    search?: string;
+    memberId?: string;
+    fromDate?: string;
+    toDate?: string;
+    page?: number;
+    limit?: number;
+}
+export interface UpdateFulfillmentInput {
+    fulfillmentStatus: FulfillmentStatus;
+    /** "GIG", "Kwik", "DHL", or the rider's name. */
+    carrier?: string;
+    trackingNumber?: string;
+    trackingUrl?: string;
+    /**
+     * `YYYY-MM-DD`. The API rejects anything else — this date is what makes an
+     * order late, and prose cannot be compared to today.
+     */
+    estimatedDelivery?: string;
+}
+/**
+ * A batch handover. No `trackingNumber`: that is per parcel, and one number
+ * spread across twenty orders is wrong nineteen times.
+ */
+export interface BulkUpdateFulfillmentInput {
+    orderIds: string[];
+    fulfillmentStatus: FulfillmentStatus;
+    carrier?: string;
+    /** `YYYY-MM-DD`. */
+    estimatedDelivery?: string;
+}
+export interface UpdateOrderStatusInput {
+    status: OrderStatus;
+    note?: string;
+}
+export interface UpdatePaymentStatusInput {
+    paymentStatus: PaymentStatus;
+    paymentReference?: string;
+}
+export type CustomerType = 'subscriber' | 'lead' | 'guest' | 'registered';
+export type CustomerSource = 'newsletter' | 'checkout' | 'signup' | 'inquiry' | 'import' | 'manual' | 'referral' | 'booking';
+export type CustomerStatus = 'active' | 'suspended' | 'archived';
+export interface MemberAddress {
+    id: string;
+    label?: string;
+    firstName?: string;
+    lastName?: string;
+    line1: string;
+    line2?: string;
+    city: string;
+    state: string;
+    postalCode?: string;
+    country: string;
+    phone?: string;
+    isDefault?: boolean;
+}
+/** An address without its server-assigned id — the shape for create/edit. */
+export type MemberAddressInput = Omit<MemberAddress, 'id'>;
+/** One parsed CSV row for bulk import. */
+export interface ImportMemberRow {
+    email?: string;
+    phone?: string;
+    name?: string;
+    tags?: string[];
+    acceptsMarketing?: boolean;
+}
+export interface ImportMembersResult {
+    created: number;
+    skipped: number;
+    errors: {
+        row: number;
+        reason: string;
+    }[];
+}
+export interface CustomerNote {
+    id: string;
+    text: string;
+    authorId: string;
+    authorName: string;
+    createdAt: string;
+}
+export interface Member {
+    id: string;
+    tenantId: string;
+    email: string;
+    phone?: string | null;
+    name?: string | null;
+    type: CustomerType;
+    source?: CustomerSource | null;
+    status: CustomerStatus;
+    emailVerified: boolean;
+    avatar?: {
+        url: string;
+        alt?: string;
+    } | null;
+    addresses: MemberAddress[];
+    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[];
+    totalOrders: number;
+    totalSpent: number;
+    lastOrderAt?: string | null;
+    convertedAt?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface MembersListResponse {
+    members: Member[];
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+}
+export interface MembersQuery {
+    page?: number;
+    limit?: number;
+    search?: string;
+    type?: CustomerType;
+    status?: CustomerStatus;
+    source?: CustomerSource;
+    acceptsMarketing?: boolean;
+    minSpent?: number;
+    maxSpent?: number;
+    sortBy?: string;
+    sortOrder?: 'ASC' | 'DESC';
+    /**
+     * Only members created on or after this ISO date.
+     *
+     * Lets a caller ask the database to COUNT a window instead of fetching a
+     * page and filtering it — which is how "new clients this week" came to be
+     * capped at five.
+     */
+    createdFrom?: string;
+}
+export interface CreateMemberInput {
+    email?: string;
+    name?: string;
+    phone?: string;
+    password?: string;
+    acceptsMarketing?: boolean;
+    /** `YYYY-MM-DD`. Omitted when the merchant does not know it. */
+    birthday?: string | null;
+    addresses?: MemberAddress[];
+    tags?: string[];
+}

package/dist/api/types/orders.js

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

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

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