@rovela-ai/sdk 0.3.22 → 0.3.30

package/dist/core/db/queries.js

@@ -4,7 +4,7 @@
  * Type-safe query helpers for e-commerce stores
  * Each store has its own database (via Neon branches) - no tenant filtering needed
  */
-import { eq, and, desc, asc, ilike, sql, inArray, isNull } from 'drizzle-orm';
+import { eq, and, or, desc, asc, ilike, sql, inArray, isNull } from 'drizzle-orm';
 import { getDb } from './client';
 import * as schema from './schema';
 /**
@@ -22,6 +22,9 @@ export async function findProducts(options = {}) {
     if (options.search) {
         conditions.push(ilike(schema.products.name, `%${options.search}%`));
     }
+    if (options.outOfStock) {
+        conditions.push(buildOutOfStockCondition());
+    }
     // Determine sort order
     let orderBy;
     switch (options.sort) {
@@ -100,12 +103,123 @@ export async function countProducts(options = {}) {
     if (options.search) {
         conditions.push(ilike(schema.products.name, `%${options.search}%`));
     }
+    if (options.outOfStock) {
+        conditions.push(buildOutOfStockCondition());
+    }
     const result = await db
         .select({ count: sql `count(*)` })
         .from(schema.products)
         .where(conditions.length > 0 ? and(...conditions) : undefined);
     return Number(result[0]?.count || 0);
 }
+/**
+ * Build the SQL condition for "effectively out of stock":
+ *   - non-variant products: trackInventory=true AND inventory <= 0
+ *   - variant products:     no variant exists with inventory > 0
+ *
+ * Reused by both `findProducts` (the OOS chip filter) and the OOS metric card.
+ * The variant subquery uses `product_variants_product_id_idx` (already in schema)
+ * so it's an index lookup, not a scan.
+ */
+function buildOutOfStockCondition() {
+    return or(and(eq(schema.products.hasVariants, false), eq(schema.products.trackInventory, true), sql `${schema.products.inventory} <= 0`), and(eq(schema.products.hasVariants, true), sql `NOT EXISTS (
+        SELECT 1 FROM ${schema.productVariants} pv
+        WHERE pv.product_id = ${schema.products.id} AND pv.inventory > 0
+      )`));
+}
+// =============================================================================
+// Product Metrics & Inventory Aggregation (admin product list page)
+// =============================================================================
+/**
+ * For products with `hasVariants=true`, the parent `products.inventory` column
+ * is unused — inventory lives on `product_variants`. This helper returns a
+ * Map of `productId → effectiveInventory` for an arbitrary set of variant
+ * product IDs. The page-list handler calls this for the products it just
+ * returned and merges the sums into each row before responding to the client.
+ *
+ * Empty input → empty map. Single SQL query, GROUP BY product_id.
+ */
+export async function getInventoryByProductIds(productIds) {
+    if (productIds.length === 0)
+        return new Map();
+    const db = getDb();
+    const rows = await db
+        .select({
+        productId: schema.productVariants.productId,
+        total: sql `COALESCE(SUM(${schema.productVariants.inventory}), 0)`,
+    })
+        .from(schema.productVariants)
+        .where(inArray(schema.productVariants.productId, productIds))
+        .groupBy(schema.productVariants.productId);
+    const result = new Map();
+    for (const r of rows) {
+        result.set(r.productId, Number(r.total) || 0);
+    }
+    return result;
+}
+/**
+ * Count of products in `status='active'`. Drives the "Active products"
+ * metric card on the admin product list page.
+ */
+export async function getActiveProductCount() {
+    const db = getDb();
+    const result = await db
+        .select({ count: sql `count(*)` })
+        .from(schema.products)
+        .where(eq(schema.products.status, 'active'));
+    return Number(result[0]?.count || 0);
+}
+/**
+ * Count of *active* products that are effectively out of stock. Excludes
+ * drafts / archived (they're irrelevant noise on the product list view).
+ *
+ * Uses the same OOS condition as the chip filter (single source of truth).
+ */
+export async function getOutOfStockProductCount() {
+    const db = getDb();
+    const result = await db
+        .select({ count: sql `count(*)` })
+        .from(schema.products)
+        .where(and(eq(schema.products.status, 'active'), buildOutOfStockCondition()));
+    return Number(result[0]?.count || 0);
+}
+/**
+ * Best-selling product over the last `days` window, by units sold.
+ *
+ * Counts only orders that actually moved revenue: `paid`, `shipped`,
+ * `delivered`. Excludes pending (might fail), cancelled, refunded, and
+ * return_requested (not yet finalized).
+ *
+ * Returns null when no qualifying orders exist in the window — the UI
+ * renders an empty state rather than a broken card.
+ */
+export async function getBestSellerProduct(days = 30) {
+    const db = getDb();
+    const since = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
+    const rows = await db
+        .select({
+        id: schema.products.id,
+        name: schema.products.name,
+        unitsSold: sql `SUM(${schema.orderItems.quantity})`,
+        revenue: sql `SUM(${schema.orderItems.quantity} * ${schema.orderItems.price})`,
+    })
+        .from(schema.orderItems)
+        .innerJoin(schema.orders, eq(schema.orders.id, schema.orderItems.orderId))
+        .innerJoin(schema.products, eq(schema.products.id, schema.orderItems.productId))
+        .where(and(inArray(schema.orders.status, ['paid', 'shipped', 'delivered']), sql `${schema.orders.createdAt} >= ${since}`))
+        .groupBy(schema.products.id, schema.products.name)
+        .orderBy(desc(sql `SUM(${schema.orderItems.quantity})`))
+        .limit(1);
+    const row = rows[0];
+    if (!row)
+        return null;
+    return {
+        id: row.id,
+        name: row.name,
+        unitsSold: Number(row.unitsSold) || 0,
+        revenue: String(row.revenue ?? '0'),
+    };
+}
 // =============================================================================
 // Categories
 // =============================================================================
@@ -296,10 +410,13 @@ export async function getStoreStats() {
             .select({ count: sql `count(*)` })
             .from(schema.products)
             .where(eq(schema.products.status, 'active')),
-        // Total orders
+        // Total orders — same status filter as revenue so the two metrics tell
+        // the same story. Counting cancelled/refunded/pending here would inflate
+        // the number relative to revenue and confuse merchants.
         db
             .select({ count: sql `count(*)` })
-            .from(schema.orders),
+            .from(schema.orders)
+            .where(inArray(schema.orders.status, ['paid', 'shipped', 'delivered'])),
         // Total customers
         db
             .select({ count: sql `count(*)` })
@@ -317,6 +434,137 @@ export async function getStoreStats() {
         revenue: Number(revenue[0]?.total || 0),
     };
 }
+// =============================================================================
+// Period-scoped store stats (for time-window selector)
+// =============================================================================
+/**
+ * Same shape as `getStoreStats()` but scoped to a window of `days` ago to now.
+ * Powers the "Today / 7d / 30d / 90d" selector on the admin dashboard. Both
+ * Orders and Revenue use the same status filter (paid + shipped + delivered)
+ * so they tell the same story.
+ *
+ * Note: `products` and `customers` here mean *new* products created in the
+ * window and *new* customers registered in the window — this is what makes
+ * the period-vs-prior-period delta meaningful. For the absolute "how many
+ * active products do I have" use `getStoreStats()`.
+ */
+export async function getStoreStatsForPeriod(startDate, endDate) {
+    const db = getDb();
+    const [orderRow, revenueRow, productRow, customerRow] = await Promise.all([
+        db
+            .select({ count: sql `count(*)` })
+            .from(schema.orders)
+            .where(and(inArray(schema.orders.status, ['paid', 'shipped', 'delivered']), sql `${schema.orders.createdAt} >= ${startDate.toISOString()}`, sql `${schema.orders.createdAt} < ${endDate.toISOString()}`)),
+        db
+            .select({ total: sql `COALESCE(SUM(total), 0)` })
+            .from(schema.orders)
+            .where(and(inArray(schema.orders.status, ['paid', 'shipped', 'delivered']), sql `${schema.orders.createdAt} >= ${startDate.toISOString()}`, sql `${schema.orders.createdAt} < ${endDate.toISOString()}`)),
+        db
+            .select({ count: sql `count(*)` })
+            .from(schema.products)
+            .where(and(eq(schema.products.status, 'active'), sql `${schema.products.createdAt} >= ${startDate.toISOString()}`, sql `${schema.products.createdAt} < ${endDate.toISOString()}`)),
+        db
+            .select({ count: sql `count(*)` })
+            .from(schema.customers)
+            .where(and(sql `${schema.customers.createdAt} >= ${startDate.toISOString()}`, sql `${schema.customers.createdAt} < ${endDate.toISOString()}`)),
+    ]);
+    return {
+        orders: Number(orderRow[0]?.count || 0),
+        revenue: Number(revenueRow[0]?.total || 0),
+        newProducts: Number(productRow[0]?.count || 0),
+        newCustomers: Number(customerRow[0]?.count || 0),
+    };
+}
+/**
+ * Count of refunded orders in the window. Used to compute refund rate.
+ */
+export async function getRefundedOrdersCount(startDate, endDate) {
+    const db = getDb();
+    const result = await db
+        .select({ count: sql `count(*)` })
+        .from(schema.orders)
+        .where(and(eq(schema.orders.status, 'refunded'), sql `${schema.orders.createdAt} >= ${startDate.toISOString()}`, sql `${schema.orders.createdAt} < ${endDate.toISOString()}`));
+    return Number(result[0]?.count || 0);
+}
+/**
+ * Count of all orders in the window (any status, used as the denominator
+ * for refund rate so the rate isn't artificially inflated by excluding
+ * pending/cancelled). Cancelled orders DO count here — they represent
+ * customer behavior even if they don't represent revenue.
+ */
+async function getTotalOrdersInPeriod(startDate, endDate) {
+    const db = getDb();
+    const result = await db
+        .select({ count: sql `count(*)` })
+        .from(schema.orders)
+        .where(and(sql `${schema.orders.createdAt} >= ${startDate.toISOString()}`, sql `${schema.orders.createdAt} < ${endDate.toISOString()}`));
+    return Number(result[0]?.count || 0);
+}
+function pctDelta(current, previous) {
+    if (previous === 0)
+        return null;
+    return (current - previous) / previous;
+}
+/**
+ * Build the full dashboard summary in a single round-trip. Runs eight
+ * parallel queries (current period + previous period × four metrics) and
+ * computes derived ratios + deltas in-process. Total wall-clock ~30–50ms
+ * on a warm Neon connection.
+ */
+export async function getDashboardSummary(periodDays = 30) {
+    // Anchor windows to UTC midnight so day boundaries are stable.
+    const now = new Date();
+    const todayUtc = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+    // `endDate` is the start of tomorrow (exclusive upper bound) so today's
+    // orders are included.
+    const endDate = new Date(todayUtc);
+    endDate.setUTCDate(endDate.getUTCDate() + 1);
+    const currentStart = new Date(todayUtc);
+    currentStart.setUTCDate(currentStart.getUTCDate() - (periodDays - 1));
+    const previousEnd = new Date(currentStart);
+    const previousStart = new Date(currentStart);
+    previousStart.setUTCDate(previousStart.getUTCDate() - periodDays);
+    const [currentStats, previousStats, currentTotalOrders, previousTotalOrders, currentRefunded, previousRefunded, bestSeller,] = await Promise.all([
+        getStoreStatsForPeriod(currentStart, endDate),
+        getStoreStatsForPeriod(previousStart, previousEnd),
+        getTotalOrdersInPeriod(currentStart, endDate),
+        getTotalOrdersInPeriod(previousStart, previousEnd),
+        getRefundedOrdersCount(currentStart, endDate),
+        getRefundedOrdersCount(previousStart, previousEnd),
+        getBestSellerProduct(periodDays),
+    ]);
+    const currentAov = currentStats.orders > 0 ? currentStats.revenue / currentStats.orders : 0;
+    const previousAov = previousStats.orders > 0 ? previousStats.revenue / previousStats.orders : 0;
+    const currentRefundRate = currentTotalOrders > 0 ? currentRefunded / currentTotalOrders : 0;
+    const previousRefundRate = previousTotalOrders > 0 ? previousRefunded / previousTotalOrders : 0;
+    return {
+        periodDays,
+        current: {
+            revenue: currentStats.revenue,
+            orders: currentStats.orders,
+            newCustomers: currentStats.newCustomers,
+            newProducts: currentStats.newProducts,
+            aov: currentAov,
+            refundRate: currentRefundRate,
+            bestSeller,
+        },
+        previous: {
+            revenue: previousStats.revenue,
+            orders: previousStats.orders,
+            newCustomers: previousStats.newCustomers,
+            newProducts: previousStats.newProducts,
+            aov: previousAov,
+            refundRate: previousRefundRate,
+        },
+        deltas: {
+            revenue: pctDelta(currentStats.revenue, previousStats.revenue),
+            orders: pctDelta(currentStats.orders, previousStats.orders),
+            aov: pctDelta(currentAov, previousAov),
+            refundRate: pctDelta(currentRefundRate, previousRefundRate),
+            customers: pctDelta(currentStats.newCustomers, previousStats.newCustomers),
+        },
+    };
+}
 /**
  * Get low stock products (inventory < threshold)
  */
@@ -737,12 +985,24 @@ export async function countOrders(options = {}) {
     return Number(result[0]?.count || 0);
 }
 /**
- * Get revenue by period (for analytics)
+ * Get revenue by period (for analytics).
+ *
+ * Returns one row per calendar day in the window, **including days with zero
+ * revenue**. The SQL GROUP BY only emits rows where orders exist, which made
+ * the chart skip empty days and look discontinuous (e.g., a Friday-only seller
+ * showed 5 floating points instead of 30). Fill happens in-process, so the
+ * chart can render a continuous line without the consumer thinking about it.
+ *
+ * Date format is `YYYY-MM-DD` in UTC (matches Postgres `DATE()` output).
  */
 export async function getRevenueByPeriod(days) {
     const db = getDb();
-    const startDate = new Date();
-    startDate.setDate(startDate.getDate() - days);
+    // Normalize to UTC midnight so the day boundaries match Postgres DATE()
+    // and our in-process fill loop produces stable keys.
+    const now = new Date();
+    const todayUtc = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+    const startDate = new Date(todayUtc);
+    startDate.setUTCDate(startDate.getUTCDate() - days);
     const result = await db
         .select({
         date: sql `DATE(${schema.orders.createdAt})`,
@@ -752,10 +1012,21 @@ export async function getRevenueByPeriod(days) {
         .where(and(inArray(schema.orders.status, ['paid', 'shipped', 'delivered']), sql `${schema.orders.createdAt} >= ${startDate.toISOString()}`))
         .groupBy(sql `DATE(${schema.orders.createdAt})`)
         .orderBy(sql `DATE(${schema.orders.createdAt})`);
-    return result.map((r) => ({
-        date: String(r.date),
-        revenue: Number(r.revenue),
-    }));
+    // Index actual revenue rows by date for O(1) lookup during fill.
+    const revenueByDate = new Map();
+    for (const row of result) {
+        revenueByDate.set(String(row.date), Number(row.revenue));
+    }
+    // Walk every day from startDate through today and emit a row for each —
+    // empty days get revenue=0 so the chart renders a continuous line.
+    const filled = [];
+    const cursor = new Date(startDate);
+    while (cursor <= todayUtc) {
+        const key = cursor.toISOString().slice(0, 10);
+        filled.push({ date: key, revenue: revenueByDate.get(key) ?? 0 });
+        cursor.setUTCDate(cursor.getUTCDate() + 1);
+    }
+    return filled;
 }
 /**
  * Get orders by status count (for analytics)
@@ -1403,4 +1674,121 @@ export async function findTaxRateForAddress(country, state) {
     }
     return null; // No matching tax zone
 }
+/**
+ * Runtime self-heal for the `onboarding` column. Stores generated before this
+ * column shipped don't have it; this idempotent migration adds it on first
+ * call and caches success in-process so subsequent calls are no-ops.
+ *
+ * Same pattern as the analytics JSONB self-heal documented in CLAUDE.md §27.
+ * No fleet rollout needed — the column appears on each store's first hit
+ * to the setup-guide endpoint or the writeback hooks.
+ */
+let onboardingColumnEnsured = false;
+export async function ensureOnboardingColumn() {
+    if (onboardingColumnEnsured)
+        return;
+    const db = getDb();
+    try {
+        await db.execute(sql `
+      ALTER TABLE store_settings
+      ADD COLUMN IF NOT EXISTS onboarding jsonb NOT NULL DEFAULT '{}'::jsonb
+    `);
+        onboardingColumnEnsured = true;
+    }
+    catch (err) {
+        // Don't poison the cache on transient failures — try again next call.
+        console.error('[ensureOnboardingColumn] migration failed:', err);
+        throw err;
+    }
+}
+/**
+ * Read the onboarding JSONB. Returns `{}` when the row is missing or the
+ * column hasn't been initialized yet (legacy stores). Always safe to call.
+ */
+export async function getOnboardingState() {
+    await ensureOnboardingColumn();
+    const db = getDb();
+    const rows = await db
+        .select({ onboarding: schema.storeSettings.onboarding })
+        .from(schema.storeSettings)
+        .limit(1);
+    return (rows[0]?.onboarding ?? {});
+}
+/**
+ * Set or clear a single key on the onboarding JSONB. Uses `jsonb_set` so it
+ * never clobbers other keys written by parallel requests. Safe to call
+ * fire-and-forget from mutating API routes (products POST/PUT, settings PUT).
+ */
+export async function setOnboardingFlag(key, value) {
+    await ensureOnboardingColumn();
+    const db = getDb();
+    // jsonb_set with create_missing=true so the column starts at '{}' and
+    // gradually accretes keys. We JSON-stringify the value first so that
+    // booleans, numbers, strings, and null all round-trip with their proper
+    // JSONB types. Earlier versions used `to_jsonb(value::text)::jsonb`
+    // which incorrectly produced JSONB string `"true"` for boolean true —
+    // breaking strict-equality reads in the GET handler so the setup-guide
+    // tasks never marked complete.
+    const jsonValue = JSON.stringify(value);
+    await db.execute(sql `
+    UPDATE store_settings
+    SET onboarding = jsonb_set(
+      COALESCE(onboarding, '{}'::jsonb),
+      ${sql.raw(`'{${String(key)}}'`)},
+      ${jsonValue}::jsonb,
+      true
+    )
+  `);
+}
+/**
+ * Aggregated signal counts used by the setup-guide GET handler. One round-trip
+ * via Promise.all instead of four sequential queries.
+ */
+export async function getSetupGuideSignals() {
+    await ensureOnboardingColumn();
+    const db = getDb();
+    const [products, shipping, tax, admins, settings] = await Promise.all([
+        db
+            .select({ count: sql `count(*)` })
+            .from(schema.products),
+        db
+            .select({ count: sql `count(*)` })
+            .from(schema.shippingZones)
+            .where(eq(schema.shippingZones.isActive, true)),
+        db
+            .select({ count: sql `count(*)` })
+            .from(schema.taxZones)
+            .where(eq(schema.taxZones.isActive, true)),
+        db
+            .select({ count: sql `count(*)` })
+            .from(schema.storeAdmins),
+        db
+            .select({
+            logoUrl: schema.storeSettings.logoUrl,
+            // `analytics` is self-healed by the pixel cards (see CLAUDE.md §27);
+            // we read it via raw SQL so the SDK works on stores where the
+            // column doesn't exist yet — the COALESCE keeps that path safe.
+            analytics: sql `COALESCE(
+          (SELECT analytics FROM store_settings LIMIT 1),
+          '{}'::jsonb
+        )`,
+            onboarding: schema.storeSettings.onboarding,
+        })
+            .from(schema.storeSettings)
+            .limit(1),
+    ]);
+    return {
+        productCount: Number(products[0]?.count || 0),
+        shippingZonesCount: Number(shipping[0]?.count || 0),
+        taxZonesCount: Number(tax[0]?.count || 0),
+        adminCount: Number(admins[0]?.count || 0),
+        storeSettings: settings[0]
+            ? {
+                logoUrl: settings[0].logoUrl ?? null,
+                analytics: settings[0].analytics ?? {},
+                onboarding: settings[0].onboarding ?? {},
+            }
+            : null,
+    };
+}
 //# sourceMappingURL=queries.js.map