@bisondesk/core-sdk 1.0.602 → 1.0.604

package/src/types/reports-sales.ts

@@ -0,0 +1,126 @@
+/**
+ * Sales report — the payload for the `Reports → Sales` tab. Everything is computed
+ * from the per-tenant `opportunities` OpenSearch index, keyed on
+ * `opportunity.reviewedAt` (the moment an opportunity ENTERS Preparation — our
+ * "sale" event; `preparedAt` is when it leaves Preparation into Delivery).
+ *
+ * The API returns raw numbers only; the client formats (€, %, pp, "younger") and
+ * colors the deltas.
+ */
+
+/**
+ * Period presets driving every metric except the fixed 18-month histogram, in
+ * selector order. Single source of truth — `SalesPeriodKey` is derived from it.
+ * `mtd`/`ytd` are to-date ranges (start of month/year → now); `lastMonth`/`lastYear`
+ * are the previous complete calendar month/year.
+ */
+export const SALES_PERIOD_KEYS = [
+  '30d',
+  '45d',
+  '60d',
+  '90d',
+  'lastMonth',
+  'mtd',
+  'ytd',
+  'lastYear',
+  '12m',
+] as const;
+
+export type SalesPeriodKey = (typeof SALES_PERIOD_KEYS)[number];
+
+export const DEFAULT_SALES_PERIOD: SalesPeriodKey = 'mtd';
+
+export type SalesReportRequest = { period: SalesPeriodKey };
+
+/**
+ * A metric for the selected window with its year-over-year counterpart.
+ * - `value`: current window (null when undefined, e.g. no data / no median).
+ * - `prev`: same metric in the window shifted back exactly one year.
+ * - `pct`: fractional change `(value - prev) / prev` (null when prev is 0 or
+ *   either side is undefined). The client renders/colors the delta.
+ */
+export type YoyMetric = { value: number | null; prev: number | null; pct: number | null };
+
+/** Tenure buckets for returning-customer analysis (share of buyers in the window). */
+export type TenureBucketKey = '2y' | '1-2y' | '<1y' | 'new';
+
+export type TenureBucket = {
+  bucket: TenureBucketKey;
+  /** Share of buyers in this bucket, 0–100. */
+  sharePct: number;
+  /** Year-over-year change in this share, as a fractional relative change (null when no prior data). */
+  yoyPct: number | null;
+};
+
+export type SalesReportCountry = {
+  /** ISO country code (lowercase) from `org.countryCode`. */
+  code: string;
+  units: number;
+  yoyPct: number | null;
+};
+
+export type SalesReportSalesperson = {
+  /** User id from `opportunity.accountManager`; the client resolves name + avatar. */
+  id: string;
+  units: number;
+  yoyPct: number | null;
+};
+
+/** A conglomerate-flagged organization (there is no group/parent model — each org stands alone). */
+export type SalesReportConglomerateOrg = {
+  /** `org.id`. */
+  id: string;
+  /** `org.name` (resolved server-side); falls back to the id when missing. */
+  name: string;
+  units: number;
+  yoyPct: number | null;
+};
+
+export type SalesReportConglomerate = {
+  /** Share of units going to conglomerate-flagged customers, 0–100 (null when no sales). */
+  sharePct: number | null;
+  /** Year-over-year change in that share, as a fractional relative change (null when no prior data). */
+  yoyPct: number | null;
+  /** The conglomerate share in the year-ago window, 0–100. */
+  lastYearPct: number | null;
+  /** Top conglomerate-flagged organizations by units in the current window. */
+  orgs: SalesReportConglomerateOrg[];
+};
+
+export type SalesReportHistogramBucket = {
+  /** Calendar month, `YYYY-MM`. */
+  month: string;
+  count: number;
+};
+
+export type SalesReportResponse = {
+  period: {
+    key: SalesPeriodKey;
+    /** Current window, half-open `[start, end)` (ISO strings). */
+    start: string;
+    end: string;
+    /** Number of days in the window (the `salesPerDay` denominator). */
+    days: number;
+    /** Year-ago window `[yoyStart, yoyEnd)`. */
+    yoyStart: string;
+    yoyEnd: string;
+  };
+  /** All-types overview KPIs. `medianAge` is in years (a decrease is good — younger stock). */
+  overview: {
+    salesPerDay: YoyMetric;
+    salesTotal: YoyMetric;
+    medianRoi: YoyMetric;
+    medianPrice: YoyMetric;
+    medianAge: YoyMetric;
+    uniqueCustomers: YoyMetric;
+  };
+  /** Top countries by units in the current window. */
+  countries: SalesReportCountry[];
+  /** All sales people with units in either window (capped; the client list scrolls). */
+  salespeople: SalesReportSalesperson[];
+  /** Returning-customer tenure shares (4 buckets). */
+  returning: TenureBucket[];
+  conglomerate: SalesReportConglomerate;
+  /** Fixed last-18-calendar-months histogram of opps into Preparation (period-independent). */
+  histogram: SalesReportHistogramBucket[];
+};

package/src/types/vehicle-performance.ts

@@ -33,6 +33,7 @@ export type VehicleSaleOverview = {
   createdAt: string;
   engagedAt?: string;
   acceptedAt?: string;
+  firstAcceptedAt?: string;
   validatedAt?: string;
   reviewedAt?: string;
   preparedAt?: string;
@@ -47,6 +48,7 @@ export type VehicleSaleOverview = {
   lastInvoiceIssuedAt?: string;
   firstPaymentAt?: string;
   fullPaymentAt?: string;
+  daysSaleUnpaid?: number;
   expectedAmount: string; // from quote(s)
   actualAmount: string; // from all invoices
   lifetimeActualAmount: string; // sum of all invoices from all opportunities for this vehicle
@@ -146,7 +148,7 @@ export type VehicleBusinessOverviewXL = VehicleBusinessOverview & {
     daysInRealInventory?: number; // days since check-in until opportunity goes to Review (vehicle reserved)
     daysInVirtualInventory?: number; // days since vehicle created in the system until opportunity goes to Review
     cashConversionCycle?: number; // days since full payment sent until full payment received
-    daysSaleUnpaid?: number; // days since opportunity goes to Review until it is fully paid
+    daysSaleUnpaid?: number; // days from first Review until fully paid
   };
 };