@withpotter/lib 0.13.0-next.101

package/dist/api/tenant.js

@@ -0,0 +1,51 @@
+import { apiFetch } from "./core";
+const tenantApi = {
+  getCurrent: (tenantSlug) => apiFetch("/tenants/current", { tenantSlug }),
+  getBySlug: (slug) => apiFetch(`/tenants/${slug}`),
+  /**
+   * What still stops this storefront taking an order.
+   *
+   * Asked BEFORE the publish request so the merchant reads what is missing
+   * instead of watching a save fail. The same check runs inside PATCH
+   * /tenants/current, which is the real gate — this is only the early look, so
+   * a stale answer here can never publish something the server would refuse.
+   */
+  readiness: (tenantSlug) => apiFetch("/tenants/current/readiness", { tenantSlug }),
+  update: (tenantSlug, data, options) => {
+    const qs = options?.target === "draft" ? "?target=draft" : "";
+    return apiFetch(`/tenants/current${qs}`, {
+      method: "PATCH",
+      tenantSlug,
+      body: JSON.stringify(data)
+    });
+  },
+  updateSettings: (tenantSlug, settings, options) => {
+    const qs = options?.target === "draft" ? "?target=draft" : "";
+    return apiFetch(`/tenants/current${qs}`, {
+      method: "PATCH",
+      tenantSlug,
+      body: JSON.stringify({ settings })
+    });
+  },
+  publishAppearance: (tenantSlug) => apiFetch("/tenants/current/publish-appearance", {
+    method: "POST",
+    tenantSlug
+  }),
+  discardAppearanceDraft: (tenantSlug) => apiFetch("/tenants/current/discard-appearance-draft", {
+    method: "POST",
+    tenantSlug
+  }),
+  deleteCurrent: (tenantSlug) => apiFetch("/tenants/current", {
+    method: "DELETE",
+    tenantSlug
+  }),
+  suggestColors: (tenantSlug, logoUrl) => apiFetch("/tenants/current/settings/colors/suggest", {
+    method: "POST",
+    tenantSlug,
+    body: JSON.stringify({ logoUrl })
+  })
+};
+export {
+  tenantApi
+};
+//# sourceMappingURL=tenant.js.map

package/dist/api/tenant.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/api/tenant.ts"],"sourcesContent":["import { apiFetch } from './core';\nimport type { Tenant, TenantUpdateInput } from './types';\nimport type { StorefrontReadiness } from './types';\n\n// Tenant API\nexport const tenantApi = {\n  getCurrent: (tenantSlug: string) =>\n    apiFetch<Tenant>('/tenants/current', { tenantSlug }),\n\n  getBySlug: (slug: string) => apiFetch<Tenant>(`/tenants/${slug}`),\n\n  /**\n   * What still stops this storefront taking an order.\n   *\n   * Asked BEFORE the publish request so the merchant reads what is missing\n   * instead of watching a save fail. The same check runs inside PATCH\n   * /tenants/current, which is the real gate — this is only the early look, so\n   * a stale answer here can never publish something the server would refuse.\n   */\n  readiness: (tenantSlug: string) =>\n    apiFetch<StorefrontReadiness>('/tenants/current/readiness', { tenantSlug }),\n\n  update: (\n    tenantSlug: string,\n    data: Partial<TenantUpdateInput>,\n    options?: { target?: 'draft' | 'live' },\n  ) => {\n    const qs = options?.target === 'draft' ? '?target=draft' : '';\n    return apiFetch<Tenant>(`/tenants/current${qs}`, {\n      method: 'PATCH',\n      tenantSlug,\n      body: JSON.stringify(data),\n    });\n  },\n\n  updateSettings: (\n    tenantSlug: string,\n    settings: Record<string, unknown>,\n    options?: { target?: 'draft' | 'live' },\n  ) => {\n    const qs = options?.target === 'draft' ? '?target=draft' : '';\n    return apiFetch<Tenant>(`/tenants/current${qs}`, {\n      method: 'PATCH',\n      tenantSlug,\n      body: JSON.stringify({ settings }),\n    });\n  },\n\n  publishAppearance: (tenantSlug: string) =>\n    apiFetch<Tenant>('/tenants/current/publish-appearance', {\n      method: 'POST',\n      tenantSlug,\n    }),\n\n  discardAppearanceDraft: (tenantSlug: string) =>\n    apiFetch<Tenant>('/tenants/current/discard-appearance-draft', {\n      method: 'POST',\n      tenantSlug,\n    }),\n\n  deleteCurrent: (tenantSlug: string) =>\n    apiFetch<{ deleted: true }>('/tenants/current', {\n      method: 'DELETE',\n      tenantSlug,\n    }),\n\n  suggestColors: (tenantSlug: string, logoUrl: string) =>\n    apiFetch<{\n      primary: string;\n      secondary: string;\n      accent: string;\n      background: string;\n      text: string;\n    }>('/tenants/current/settings/colors/suggest', {\n      method: 'POST',\n      tenantSlug,\n      body: JSON.stringify({ logoUrl }),\n    }),\n};\n\n// ---------------------------------------------------------------------------\n// Template Settings API (draft / saved / published state model)\n// Endpoints shipped in api#102. See merchant-dashboard#177 for surfaces.\n// ---------------------------------------------------------------------------\n"],"mappings":"AAAA,SAAS,gBAAgB;AAKlB,MAAM,YAAY;AAAA,EACvB,YAAY,CAAC,eACX,SAAiB,oBAAoB,EAAE,WAAW,CAAC;AAAA,EAErD,WAAW,CAAC,SAAiB,SAAiB,YAAY,IAAI,EAAE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUhE,WAAW,CAAC,eACV,SAA8B,8BAA8B,EAAE,WAAW,CAAC;AAAA,EAE5E,QAAQ,CACN,YACA,MACA,YACG;AACH,UAAM,KAAK,SAAS,WAAW,UAAU,kBAAkB;AAC3D,WAAO,SAAiB,mBAAmB,EAAE,IAAI;AAAA,MAC/C,QAAQ;AAAA,MACR;AAAA,MACA,MAAM,KAAK,UAAU,IAAI;AAAA,IAC3B,CAAC;AAAA,EACH;AAAA,EAEA,gBAAgB,CACd,YACA,UACA,YACG;AACH,UAAM,KAAK,SAAS,WAAW,UAAU,kBAAkB;AAC3D,WAAO,SAAiB,mBAAmB,EAAE,IAAI;AAAA,MAC/C,QAAQ;AAAA,MACR;AAAA,MACA,MAAM,KAAK,UAAU,EAAE,SAAS,CAAC;AAAA,IACnC,CAAC;AAAA,EACH;AAAA,EAEA,mBAAmB,CAAC,eAClB,SAAiB,uCAAuC;AAAA,IACtD,QAAQ;AAAA,IACR;AAAA,EACF,CAAC;AAAA,EAEH,wBAAwB,CAAC,eACvB,SAAiB,6CAA6C;AAAA,IAC5D,QAAQ;AAAA,IACR;AAAA,EACF,CAAC;AAAA,EAEH,eAAe,CAAC,eACd,SAA4B,oBAAoB;AAAA,IAC9C,QAAQ;AAAA,IACR;AAAA,EACF,CAAC;AAAA,EAEH,eAAe,CAAC,YAAoB,YAClC,SAMG,4CAA4C;AAAA,IAC7C,QAAQ;AAAA,IACR;AAAA,IACA,MAAM,KAAK,UAAU,EAAE,QAAQ,CAAC;AAAA,EAClC,CAAC;AACL;","names":[]}

package/dist/api/types/analytics-attribution.d.ts

@@ -0,0 +1,43 @@
+/** One row of the attribution report: a source, medium, campaign or campaign id. */
+export interface AttributionRow {
+    /** What the orders were grouped by. `direct` is every order carrying nothing. */
+    key: string;
+    /** Orders behind `revenue`. Cancelled and refunded ones are not counted. */
+    orders: number;
+    revenue: number;
+    /** `revenue` as a percentage of the period total. */
+    share: number;
+}
+/**
+ * What the marketing earned, by where the orders came from.
+ *
+ * `unattributedRevenue` is the figure that decides whether the rest is worth
+ * reading: a merchant whose orders are mostly `direct` is not looking at a
+ * report about their marketing, they are looking at proof that the storefront
+ * capture is not reaching checkout.
+ */
+export interface AttributionReport {
+    model: 'last_touch' | 'first_touch';
+    totalRevenue: number;
+    unattributedRevenue: number;
+    unattributedOrders: number;
+    bySource: AttributionRow[];
+    byMedium: AttributionRow[];
+    byCampaign: AttributionRow[];
+    byCampaignId: AttributionRow[];
+    /**
+     * Sales with no source whose customer was sent a message in the window before
+     * paying. Reach, not response (opens and clicks are not stored per person),
+     * and kept apart from the traced figures. Absent on an API that predates it.
+     */
+    assisted?: {
+        windowDays: number;
+        orders: number;
+        revenue: number;
+        /** Orders reached by each kind of message; one order can be in both. */
+        byChannel: {
+            campaign: number;
+            automation: number;
+        };
+    };
+}

package/dist/api/types/analytics-attribution.js

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

package/dist/api/types/analytics-attribution.js.map

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

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

@@ -0,0 +1,465 @@
+import type { LedgerSeries } from './operations';
+/**
+ * ANALYTICS 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 BookingAnalytics {
+    today: number;
+    upcomingThisWeek: number;
+    noShowCount: number;
+    totalRevenue: number;
+    /**
+     * The full status and type maps. The API used to pick `no_show` out of these
+     * and discard the rest, which left a no-show count with no denominator —
+     * a number nobody can act on.
+     *
+     * Optional because a business that takes no bookings has no maps to send,
+     * and a zeroed-out set of statuses reads as a bad week rather than an
+     * absent one.
+     */
+    byStatus?: Record<string, number>;
+    byType?: Record<string, number>;
+    totalBookings?: number;
+}
+/** The dashboard home's money band, fetched in one call. */
+export interface HomeSummary {
+    sales: {
+        totalRevenue: number;
+        totalOrders: number;
+        averageOrderValue: number;
+        conversionRate: number;
+    };
+    priorSales: {
+        totalRevenue: number;
+        totalOrders: number;
+        averageOrderValue: number;
+        conversionRate: number;
+    };
+    revenueTimeSeries: {
+        date: string;
+        value: number;
+    }[];
+    priorRevenueTimeSeries: {
+        date: string;
+        value: number;
+    }[];
+}
+export interface OutstandingInvoiceRow {
+    id: string;
+    invoiceNumber: string;
+    customerName: string;
+    amountDue: number;
+    currency: string;
+    dueDate: string | null;
+    status: string;
+    daysOverdue: number;
+}
+/**
+ * Revenue for one location, in one currency.
+ *
+ * An array rather than a number, and deliberately never summed across
+ * currencies: adding naira to dollars produces a figure that looks like
+ * revenue and is not one. Most tenants have exactly one entry; a location
+ * that sold nothing has none.
+ */
+export interface LocationRevenue {
+    currency: string;
+    amount: number;
+}
+export interface LocationPerformance {
+    locationId: string;
+    locationName: string;
+    isDefault: boolean;
+    orders: number;
+    revenue: LocationRevenue[];
+    staffCount: number;
+    /** Window start; null when the figures are all-time. Repeated on every row. */
+    since: string | null;
+}
+export interface OutstandingAgeingBucket {
+    bucket: string;
+    count: number;
+    amount: number;
+}
+export interface OutstandingInvoices {
+    totalOutstanding: number;
+    count: number;
+    overdueCount: number;
+    overdueAmount: number;
+    /**
+     * How old the debt is, computed server-side over EVERY unpaid invoice — not
+     * over `invoices` below, which is capped for display. Debt at ninety days is
+     * a different problem from debt at five, and one overdue total cannot tell
+     * them apart.
+     *
+     * Optional: an API older than this field sends nothing.
+     */
+    ageing?: OutstandingAgeingBucket[];
+    invoices: OutstandingInvoiceRow[];
+}
+export interface PaymentMethodShare {
+    method: string;
+    amount: number;
+    count: number;
+    percentage: number;
+}
+/**
+ * Gross to net, from the order ledger.
+ *
+ * Deliberately not related to `SalesStats.totalRevenue`, which is purchase
+ * beacons plus invoice revenue. These are all columns on `orders` summed in one
+ * query, so the lines can actually be subtracted from each other — which is the
+ * whole reason the endpoint exists.
+ */
+export interface SalesLedger extends LedgerSeries {
+    gross: number;
+    discounts: number;
+    refunds: number;
+    /** gross − discounts − refunds. Tax and shipping sit below it, not inside. */
+    net: number;
+    tax: number;
+    shipping: number;
+    total: number;
+    fees: number;
+    orders: number;
+    /** Invoice payments in the window — a separate rail, not folded into orders. */
+    invoices: number;
+    /** Above one, the sums have no unit and must not be rendered. */
+    currencyCount: number;
+    currency: string | null;
+    /** Finance-only profitability fields. Omitted for analytics-only callers. */
+    netSales?: number | null;
+    /** Known historical COGS. May be partial when coverage is incomplete. */
+    cogs?: number | null;
+    /** Null until every included line has a historical cost snapshot. */
+    grossProfit?: number | null;
+    grossMarginPercent?: number | null;
+    /** Gross profit less known payment fees; null with incomplete costs/fees. */
+    contributionProfit?: number | null;
+    costedSales?: number | null;
+    uncostedSales?: number | null;
+    costedLines?: number | null;
+    uncostedLines?: number | null;
+    pendingCostLines?: number | null;
+    /**
+     * `total` over time, from the same orders and invoice receipts and with the
+     * same filters, so the points add up to it. The dashboard's own series is
+     * drawn from purchase beacons and cannot promise that. Optional: an API older than this field sends nothing, and the page falls
+     * back to the dashboard's figures rather than drawing an empty chart.
+     */
+    revenueTimeSeries?: {
+        date: string;
+        value: number;
+    }[];
+}
+/** How much of the money came from people who had already bought. */
+export interface RevenueSplit {
+    newRevenue: number;
+    returningRevenue: number;
+    newOrders: number;
+    returningOrders: number;
+    /** Returning as a share of the total, to one decimal. */
+    returningShare: number;
+}
+/** One measure, cut by one dimension, over a window. Grouped server-side. */
+export interface OrderReport {
+    dimension: string;
+    measure: string;
+    granularity: string;
+    series: {
+        key: string;
+        total: number;
+    }[];
+    points: {
+        date: string;
+        values: Record<string, number>;
+    }[];
+    total: number;
+}
+export interface PaymentsMix {
+    totalAmount: number;
+    totalCount: number;
+    methods: PaymentMethodShare[];
+    /** The same money bucketed over the window, so the split can be drawn. */
+    series?: {
+        date: string;
+        values: Record<string, number>;
+    }[];
+}
+export interface Insight {
+    id: string;
+    kind: 'act' | 'nudge' | 'good';
+    title: string;
+    body: string;
+    actionLabel?: string;
+    actionHref?: string;
+}
+export interface UtilizationCell {
+    row: number;
+    col: number;
+    pct: number;
+}
+export interface GeoStat {
+    /** ISO-3166 alpha-2, or 'unknown' when the request carried no country. */
+    countryCode: string;
+    sessions: number;
+    percentage: number;
+}
+export interface CampaignStat {
+    campaign: string;
+    source: string | null;
+    medium: string | null;
+    sessions: number;
+}
+export interface SearchTermStat {
+    /** The query, folded to lower case. */
+    query: string;
+    searches: number;
+    /** How many of those searches returned nothing. */
+    empty: number;
+    /** `empty` as a percentage of `searches`. */
+    emptyRate: number;
+}
+export type MetricUnit = 'count' | 'money' | 'ratio';
+export interface MetricNode {
+    key: string;
+    label: string;
+    value: number;
+    prior: number;
+    /** Percent change against prior. Null when prior was zero. */
+    changePct: number | null;
+    /**
+     * Signed share of the revenue change this factor accounts for. The three
+     * top-level factors sum to 100. Null when the split is undefined.
+     */
+    contributionPct: number | null;
+    unit: MetricUnit;
+    children?: MetricNode[];
+}
+/**
+ * Revenue broken into the three things it is the product of, so a change in
+ * the headline can be attributed rather than merely reported.
+ */
+export interface MetricTree {
+    window: {
+        start: string;
+        end: string;
+    };
+    priorWindow: {
+        start: string;
+        end: string;
+    };
+    revenue: MetricNode;
+    factors: MetricNode[];
+    /** The factor carrying most of the movement, when one clearly does. */
+    driver: string | null;
+    /** False when the window holds too few orders for a percentage to mean anything. */
+    reliable: boolean;
+    note: string | null;
+}
+/**
+ * Whether the people served came back onto the book.
+ *
+ * Counted per person, not per booking, and "rebooked" means they hold a later
+ * booking that still stands — not one within a fixed window, because a
+ * barber's next visit is three weeks out and a dentist's is six months.
+ */
+/** One side of the loyalty comparison. */
+export interface LoyaltySide {
+    customers: number;
+    orders: number;
+    revenue: number;
+    averageOrder: number;
+    ordersPerCustomer: number;
+}
+/**
+ * Enrolled buyers against everyone else, on spend and on how often they come.
+ *
+ * Not proof of cause: people who join a loyalty scheme are already the people
+ * who come back, so the gap flatters the programme. A signal to watch over
+ * time, not a number to defend a budget with.
+ */
+export interface LoyaltyEffect {
+    members: LoyaltySide;
+    others: LoyaltySide;
+}
+/**
+ * Retention by the month somebody first bought, from `/analytics/cohorts`.
+ *
+ * A repeat rate is one number for the whole book and it moves for two
+ * unrelated reasons — this month's arrivals behaving differently, or last
+ * year's regulars finally lapsing — so it cannot say which. A cohort splits
+ * them: every row is the people who arrived in one month, and the row reads
+ * across as how many of THEM came back in each month since.
+ *
+ * `size` is the cohort at offset zero, so `customers / size` is the share
+ * still buying. Rows are ragged by construction — a cohort three months old
+ * has three cells — and a month with no repeat purchases has no entry at all
+ * rather than a zero, so the grid fills gaps itself.
+ */
+export interface CohortRow {
+    /** `YYYY-MM`, the month these customers first bought. */
+    cohort: string;
+    /** How many first bought that month. */
+    size: number;
+    offsets: {
+        offset: number;
+        customers: number;
+    }[];
+}
+export interface Rebooking {
+    served: number;
+    rebooked: number;
+    /** 0–1. */
+    rate: number;
+}
+/** GET /analytics/win-back: lost customers who ordered again in the window. */
+export interface WinBack {
+    /** Days without an order before a customer counts as lost. */
+    lostAfterDays: number;
+    customers: number;
+    orders: number;
+    revenue: number;
+}
+export interface Utilization {
+    rate: number;
+    bookedHours: number;
+    capacityHours: number;
+    resourceCount: number;
+    resourceLabel: string;
+    hours: number[];
+    grid: number[][];
+    maxCell: number;
+    pctGrid: number[][];
+    /** Cells the business is shut for, so a closed day is not read as a quiet one. */
+    closed?: boolean[][];
+    busiest: UtilizationCell | null;
+    quietest: UtilizationCell | null;
+}
+export interface RecentEvent {
+    id: string;
+    eventType: string;
+    eventName?: string;
+    pageUrl?: string;
+    pageTitle?: string;
+    deviceType?: string;
+    visitorId?: string;
+    sessionId: string;
+    contentId?: string;
+    orderId?: string;
+    revenue?: number;
+    metadata?: Record<string, unknown>;
+    createdAt: string;
+}
+export interface OrderStats {
+    pending: number;
+    confirmed: number;
+    processing: number;
+    checked_in?: number;
+    completed: number;
+    cancelled: number;
+    refunded: number;
+    unpaid: number;
+    awaiting_confirmation: number;
+    paid: number;
+    unfulfilled: number;
+    /**
+     * Paid, not handed over, and actually going somewhere. Narrower than
+     * `unfulfilled`, which also holds orders nobody has paid for and orders that
+     * are never going anywhere at all.
+     */
+    going_out: number;
+    today: number;
+    total: number;
+    /** Paid revenue over the requested range, or month-to-date when unscoped. */
+    revenue: number;
+}
+export interface CustomerStats {
+    totalCustomers: number;
+    subscribers: number;
+    leads: number;
+    guests: number;
+    registered: number;
+}
+export interface InventoryStats {
+    totalProducts: number;
+    activeProducts: number;
+    inStockCount: number;
+    lowStockCount: number;
+    outOfStockCount: number;
+    totalValue: number;
+    /**
+     * Units on hand across tracked products, and how much of the catalogue is
+     * not counted at all. Stock tracking is opt-in per product, so every other
+     * number here is scoped to the tracked subset — without these, "0 out of
+     * stock" is ambiguous between nothing has run out and nothing is watched.
+     *
+     * Optional: an API older than this field sends neither.
+     */
+    totalUnits?: number;
+    notTrackedCount?: number;
+    trackedCount?: number;
+    lowStockItems: Array<{
+        id: string;
+        title: string;
+        quantity: number;
+        lowStockThreshold: number;
+    }>;
+}
+export interface InventoryQuery {
+    search?: string;
+    stockStatus?: 'inStock' | 'lowStock' | 'outOfStock';
+    /**
+     * Report stock as this branch holds it rather than as the business does.
+     * The stored totals do not change; the numbers in the response do.
+     */
+    locationId?: string;
+    sortBy?: string;
+    sortOrder?: 'ASC' | 'DESC';
+    page?: number;
+    limit?: number;
+    behavior?: string;
+    excludeBehaviors?: string[];
+    intent?: string;
+    type?: 'physical' | 'digital' | 'service' | 'ticket' | 'package';
+    category?: string;
+    /**
+     * Products assigned to one team member, by member id.
+     *
+     * Newer than the rest of this block, so it is gated: send it only when
+     * `ApiFeatures.productAssigneeFilter` is true. A build without it rejects
+     * the whole request rather than ignoring the key.
+     */
+    assigneeId?: string;
+    featured?: boolean;
+    isActive?: boolean;
+    includeDrafts?: boolean;
+    /**
+     * An event window, as ISO dates against `behaviors.ticketed.eventDate`.
+     *
+     * Upcoming is `eventFrom = today`; past is `eventUntil = today`. A listing
+     * with no date matches neither, which is right: an event with no date is a
+     * draft somebody is still writing.
+     *
+     * Gated on `ApiFeatures.eventWindow` for the same reason `assigneeId` is —
+     * an older build rejects the whole request rather than ignoring the key.
+     */
+    eventFrom?: string;
+    eventUntil?: string;
+    minPrice?: number;
+    maxPrice?: number;
+    /**
+     * Products in this collection. Collections keep their membership in
+     * `data.productIds`, so the API resolves this as a reverse lookup; there is
+     * no join table behind it.
+     */
+    collectionId?: string;
+    /**
+     * `true` → only products that have ever sold, `false` → only those that
+     * never have. Counts paid, non-refunded, non-cancelled orders.
+     */
+    hasSold?: boolean;
+}

package/dist/api/types/analytics.js

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

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

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