@rovela-ai/sdk 0.4.1 → 0.4.2

package/dist/core/db/queries.d.ts

@@ -0,0 +1,1427 @@
+/**
+ * @rovela/sdk/core/db/queries
+ *
+ * Type-safe query helpers for e-commerce stores
+ * Each store has its own database (via Neon branches) - no tenant filtering needed
+ */
+import * as schema from './schema';
+export interface FindProductsOptions {
+    categoryId?: string;
+    status?: 'draft' | 'active' | 'archived';
+    search?: string;
+    sort?: 'newest' | 'price-asc' | 'price-desc' | 'name';
+    limit?: number;
+    offset?: number;
+    /**
+     * When true, return only products effectively out of stock.
+     * For non-variant products: `inventory <= 0 AND track_inventory = true`.
+     * For variant products: no variant has `inventory > 0`.
+     */
+    outOfStock?: boolean;
+    /**
+     * When true, return only products with a sale price (compare_price > price).
+     * Used by the auto-curated /sale collection card. Cheap to evaluate — no
+     * subquery, just a column comparison.
+     */
+    onSale?: boolean;
+    /**
+     * When set, return only products whose `tags` JSONB array overlaps any of
+     * the provided tags. Used by the product-quiz card to filter to products
+     * matching the merchant's quiz answer→tag mapping. Empty array is a
+     * no-op (returns all products).
+     */
+    tags?: string[];
+}
+/**
+ * Find products with filtering, sorting, and pagination
+ */
+export declare function findProducts(options?: FindProductsOptions): Promise<{
+    id: string;
+    name: string;
+    slug: string;
+    description: string;
+    price: string;
+    comparePrice: string | null;
+    images: string[];
+    videos: string[];
+    status: "draft" | "active" | "archived";
+    categoryId: string | null;
+    hasVariants: boolean;
+    sku: string | null;
+    inventory: number | null;
+    trackInventory: boolean | null;
+    continueSellingWhenOutOfStock: boolean | null;
+    productType: string | null;
+    vendor: string | null;
+    tags: string[] | null;
+    metaTitle: string | null;
+    metaDescription: string | null;
+    metaKeywords: string[] | null;
+    createdAt: Date;
+    updatedAt: Date;
+}[]>;
+/**
+ * Find a single product by slug
+ */
+export declare function findProductBySlug(slug: string): Promise<{
+    id: string;
+    name: string;
+    slug: string;
+    description: string;
+    price: string;
+    comparePrice: string | null;
+    images: string[];
+    videos: string[];
+    status: "draft" | "active" | "archived";
+    categoryId: string | null;
+    hasVariants: boolean;
+    sku: string | null;
+    inventory: number | null;
+    trackInventory: boolean | null;
+    continueSellingWhenOutOfStock: boolean | null;
+    productType: string | null;
+    vendor: string | null;
+    tags: string[] | null;
+    metaTitle: string | null;
+    metaDescription: string | null;
+    metaKeywords: string[] | null;
+    createdAt: Date;
+    updatedAt: Date;
+}>;
+/**
+ * Find a single product by ID
+ */
+export declare function findProductById(id: string): Promise<{
+    id: string;
+    name: string;
+    slug: string;
+    description: string;
+    price: string;
+    comparePrice: string | null;
+    images: string[];
+    videos: string[];
+    status: "draft" | "active" | "archived";
+    categoryId: string | null;
+    hasVariants: boolean;
+    sku: string | null;
+    inventory: number | null;
+    trackInventory: boolean | null;
+    continueSellingWhenOutOfStock: boolean | null;
+    productType: string | null;
+    vendor: string | null;
+    tags: string[] | null;
+    metaTitle: string | null;
+    metaDescription: string | null;
+    metaKeywords: string[] | null;
+    createdAt: Date;
+    updatedAt: Date;
+}>;
+/**
+ * Get product variants for a product
+ */
+export declare function findProductVariants(productId: string): Promise<{
+    id: string;
+    productId: string;
+    sku: string;
+    name: string;
+    price: string | null;
+    inventory: number;
+    image: string | null;
+    video: string | null;
+    attributes: Record<string, string>;
+    createdAt: Date;
+}[]>;
+/**
+ * Count total products matching filters
+ */
+export declare function countProducts(options?: Pick<FindProductsOptions, 'categoryId' | 'status' | 'search' | 'outOfStock'>): Promise<number>;
+/**
+ * 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 declare function getInventoryByProductIds(productIds: string[]): Promise<Map<string, number>>;
+/**
+ * Count of products in `status='active'`. Drives the "Active products"
+ * metric card on the admin product list page.
+ */
+export declare function getActiveProductCount(): Promise<number>;
+/**
+ * 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 declare function getOutOfStockProductCount(): Promise<number>;
+/**
+ * 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 declare function getBestSellerProduct(days?: number): Promise<{
+    id: string;
+    name: string;
+    unitsSold: number;
+    revenue: string;
+} | null>;
+/**
+ * Best-selling products in the last N days, capped to `limit`.
+ *
+ * Same SQL shape as `getBestSellerProduct` (paid+shipped+delivered window,
+ * ordered by units sold desc) but returns up to `limit` rows. Used by the
+ * Best Sellers homepage section card. Returns an empty array when no
+ * qualifying orders exist — callers MUST hide their UI when length === 0
+ * (don't render an empty rail).
+ *
+ * `order_items_product_id_idx` covers the JOIN; cost is the same as the
+ * existing single-row helper.
+ */
+export declare function getBestSellers(days?: number, limit?: number): Promise<Array<{
+    id: string;
+    slug: string;
+    name: string;
+    price: string;
+    comparePrice: string | null;
+    images: string[];
+    unitsSold: number;
+}>>;
+/**
+ * Most-popular products by distinct buyer count (last N days), capped.
+ *
+ * Different from best sellers — best sellers is units sold (revenue lens);
+ * this is buyer reach (how many distinct customers bought it). Used by the
+ * Most Popular homepage section card. Same JOIN path; same status window.
+ *
+ * Excludes guest orders (`customer_id IS NULL`) so we count real distinct
+ * buyers, not anonymous sessions. Returns empty array when no data — UI
+ * must hide.
+ */
+export declare function getMostPopularProducts(days?: number, limit?: number): Promise<Array<{
+    id: string;
+    slug: string;
+    name: string;
+    price: string;
+    comparePrice: string | null;
+    images: string[];
+    buyerCount: number;
+}>>;
+/**
+ * Distinct-buyer count for a single product within the last N hours.
+ *
+ * Powers the "X people bought this in the last 24h" social-proof card on
+ * PDPs. Server-only — caller MUST cache via Server Component + ISR
+ * (`revalidate: 300`); calling this per page view is a perf trap.
+ *
+ * Returns 0 when no qualifying orders exist. UI gates on a `minThreshold`
+ * (default 5) — never render "1 person bought this" (awkward + reads as
+ * dead store).
+ */
+export declare function getProductRecentBuyerCount(productId: string, hours?: number): Promise<number>;
+/**
+ * Check whether a customer has purchased a specific product.
+ *
+ * Powers the verified-purchase badge on the C2 reviews card. Returns true
+ * iff the customer has at least one paid+shipped+delivered order containing
+ * the product (variant-agnostic — buying any variant counts).
+ *
+ * Uses EXISTS for short-circuit evaluation; cheap even on large order
+ * histories. Index `order_items_product_id_idx` covers the inner lookup;
+ * `orders_customer_id_idx` covers the join.
+ */
+export declare function hasCustomerPurchasedProduct(customerId: string, productId: string): Promise<boolean>;
+/**
+ * Find all categories
+ */
+export declare function findCategories(): Promise<{
+    id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    image: string | null;
+    parentId: string | null;
+    order: number;
+    createdAt: Date;
+}[]>;
+/**
+ * Find a category by slug
+ */
+export declare function findCategoryBySlug(slug: string): Promise<{
+    id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    image: string | null;
+    parentId: string | null;
+    order: number;
+    createdAt: Date;
+}>;
+export interface FindOrdersOptions {
+    status?: schema.Order['status'];
+    customerId?: string;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Find orders with filtering and pagination
+ */
+export declare function findOrders(options?: FindOrdersOptions): Promise<{
+    id: string;
+    customerId: string | null;
+    email: string;
+    status: "pending" | "paid" | "shipped" | "delivered" | "cancelled" | "refunded" | "return_requested";
+    subtotal: string;
+    tax: string;
+    shipping: string;
+    total: string;
+    refundAmount: string | null;
+    returnReason: string | null;
+    discountCode: string | null;
+    discountAmount: string | null;
+    stripePromotionCodeId: string | null;
+    shippingAddress: {
+        firstName: string;
+        lastName: string;
+        line1: string;
+        line2?: string;
+        city: string;
+        state: string;
+        postalCode: string;
+        country: string;
+        phone?: string;
+    } | null;
+    billingAddress: {
+        firstName: string;
+        lastName: string;
+        line1: string;
+        line2?: string;
+        city: string;
+        state: string;
+        postalCode: string;
+        country: string;
+        phone?: string;
+    } | null;
+    stripePaymentIntentId: string | null;
+    stripeChargeId: string | null;
+    receiptUrl: string | null;
+    trackingNumber: string | null;
+    trackingUrl: string | null;
+    carrier: string | null;
+    labelUrl: string | null;
+    shippoRateId: string | null;
+    shippingMethod: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}[]>;
+/**
+ * Find order by ID with items (includes product images)
+ */
+export declare function findOrderById(id: string): Promise<{
+    items: {
+        id: string;
+        orderId: string;
+        productId: string;
+        variantId: string | null;
+        name: string;
+        price: string;
+        quantity: number;
+        attributes: Record<string, string> | null;
+        createdAt: Date;
+        image: string | null;
+    }[];
+    id: string;
+    customerId: string | null;
+    email: string;
+    status: "pending" | "paid" | "shipped" | "delivered" | "cancelled" | "refunded" | "return_requested";
+    subtotal: string;
+    tax: string;
+    shipping: string;
+    total: string;
+    refundAmount: string | null;
+    returnReason: string | null;
+    discountCode: string | null;
+    discountAmount: string | null;
+    stripePromotionCodeId: string | null;
+    shippingAddress: {
+        firstName: string;
+        lastName: string;
+        line1: string;
+        line2?: string;
+        city: string;
+        state: string;
+        postalCode: string;
+        country: string;
+        phone?: string;
+    } | null;
+    billingAddress: {
+        firstName: string;
+        lastName: string;
+        line1: string;
+        line2?: string;
+        city: string;
+        state: string;
+        postalCode: string;
+        country: string;
+        phone?: string;
+    } | null;
+    stripePaymentIntentId: string | null;
+    stripeChargeId: string | null;
+    receiptUrl: string | null;
+    trackingNumber: string | null;
+    trackingUrl: string | null;
+    carrier: string | null;
+    labelUrl: string | null;
+    shippoRateId: string | null;
+    shippingMethod: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+} | null>;
+/**
+ * Get order items for an order
+ */
+export declare function findOrderItems(orderId: string): Promise<{
+    id: string;
+    orderId: string;
+    productId: string;
+    variantId: string | null;
+    name: string;
+    price: string;
+    quantity: number;
+    attributes: Record<string, string> | null;
+    createdAt: Date;
+}[]>;
+/**
+ * Find customer by email
+ */
+export declare function findCustomerByEmail(email: string): Promise<{
+    id: string;
+    email: string;
+    name: string | null;
+    passwordHash: string;
+    stripeCustomerId: string | null;
+    emailVerified: Date | null;
+    createdAt: Date;
+}>;
+/**
+ * Find customer by ID
+ */
+export declare function findCustomerById(id: string): Promise<{
+    id: string;
+    email: string;
+    name: string | null;
+    passwordHash: string;
+    stripeCustomerId: string | null;
+    emailVerified: Date | null;
+    createdAt: Date;
+}>;
+/**
+ * Find all customers with pagination
+ */
+export declare function findCustomers(options?: {
+    limit?: number;
+    offset?: number;
+    search?: string;
+}): Promise<{
+    id: string;
+    email: string;
+    name: string | null;
+    passwordHash: string;
+    stripeCustomerId: string | null;
+    emailVerified: Date | null;
+    createdAt: Date;
+}[]>;
+/**
+ * Find admin by email
+ */
+export declare function findAdminByEmail(email: string): Promise<{
+    id: string;
+    email: string;
+    name: string;
+    passwordHash: string | null;
+    role: "owner" | "administrator" | "manager" | "user";
+    status: "active" | "invited" | "deactivated";
+    createdBy: string | null;
+    createdAt: Date;
+    lastLoginAt: Date | null;
+    deactivatedAt: Date | null;
+    deactivatedBy: string | null;
+    sessionVersion: number;
+}>;
+/**
+ * Get store statistics for admin dashboard
+ */
+export declare function getStoreStats(): Promise<{
+    products: number;
+    orders: number;
+    customers: number;
+    revenue: number;
+}>;
+/**
+ * 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 declare function getStoreStatsForPeriod(startDate: Date, endDate: Date): Promise<{
+    revenue: number;
+    orders: number;
+    newProducts: number;
+    newCustomers: number;
+}>;
+/**
+ * Count of refunded orders in the window. Used to compute refund rate.
+ */
+export declare function getRefundedOrdersCount(startDate: Date, endDate: Date): Promise<number>;
+export interface DashboardSummary {
+    /** Window the metrics cover (in calendar days). */
+    periodDays: number;
+    current: {
+        revenue: number;
+        orders: number;
+        newCustomers: number;
+        newProducts: number;
+        /** Average order value: revenue / orders. 0 when orders=0. */
+        aov: number;
+        /** Refund rate as a decimal (0.05 = 5%). 0 when no orders. */
+        refundRate: number;
+        /** Best-selling product in the window, or null when no qualifying orders. */
+        bestSeller: {
+            id: string;
+            name: string;
+            unitsSold: number;
+            revenue: string;
+        } | null;
+    };
+    /** Same shape, scoped to the previous window of equal length. */
+    previous: {
+        revenue: number;
+        orders: number;
+        newCustomers: number;
+        newProducts: number;
+        aov: number;
+        refundRate: number;
+    };
+    /**
+     * Percentage delta of current vs previous, expressed as a decimal where
+     * 0.124 = +12.4%. Null when prior period had zero (delta is undefined).
+     * Refund-rate delta is *signed by direction*: a fall in refund rate is
+     * positive (good) — we report the raw direction here and let the UI
+     * invert the color semantics (down arrow with green when refund rate
+     * decreases).
+     */
+    deltas: {
+        revenue: number | null;
+        orders: number | null;
+        aov: number | null;
+        refundRate: number | null;
+        customers: number | null;
+    };
+}
+/**
+ * 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 declare function getDashboardSummary(periodDays?: number): Promise<DashboardSummary>;
+/**
+ * Get low stock products (inventory < threshold)
+ */
+export declare function getLowStockProducts(threshold?: number): Promise<{
+    product: {
+        id: string;
+        name: string;
+        slug: string;
+        description: string;
+        price: string;
+        comparePrice: string | null;
+        images: string[];
+        videos: string[];
+        status: "draft" | "active" | "archived";
+        categoryId: string | null;
+        hasVariants: boolean;
+        sku: string | null;
+        inventory: number | null;
+        trackInventory: boolean | null;
+        continueSellingWhenOutOfStock: boolean | null;
+        productType: string | null;
+        vendor: string | null;
+        tags: string[] | null;
+        metaTitle: string | null;
+        metaDescription: string | null;
+        metaKeywords: string[] | null;
+        createdAt: Date;
+        updatedAt: Date;
+    };
+    variant: {
+        id: string;
+        productId: string;
+        sku: string;
+        name: string;
+        price: string | null;
+        inventory: number;
+        image: string | null;
+        video: string | null;
+        attributes: Record<string, string>;
+        createdAt: Date;
+    };
+}[]>;
+/**
+ * Get recent orders
+ */
+export declare function getRecentOrders(limit?: number): Promise<{
+    id: string;
+    customerId: string | null;
+    email: string;
+    status: "pending" | "paid" | "shipped" | "delivered" | "cancelled" | "refunded" | "return_requested";
+    subtotal: string;
+    tax: string;
+    shipping: string;
+    total: string;
+    refundAmount: string | null;
+    returnReason: string | null;
+    discountCode: string | null;
+    discountAmount: string | null;
+    stripePromotionCodeId: string | null;
+    shippingAddress: {
+        firstName: string;
+        lastName: string;
+        line1: string;
+        line2?: string;
+        city: string;
+        state: string;
+        postalCode: string;
+        country: string;
+        phone?: string;
+    } | null;
+    billingAddress: {
+        firstName: string;
+        lastName: string;
+        line1: string;
+        line2?: string;
+        city: string;
+        state: string;
+        postalCode: string;
+        country: string;
+        phone?: string;
+    } | null;
+    stripePaymentIntentId: string | null;
+    stripeChargeId: string | null;
+    receiptUrl: string | null;
+    trackingNumber: string | null;
+    trackingUrl: string | null;
+    carrier: string | null;
+    labelUrl: string | null;
+    shippoRateId: string | null;
+    shippingMethod: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}[]>;
+/**
+ * Create a new order
+ */
+export declare function createOrder(data: schema.NewOrder): Promise<{
+    status: "pending" | "paid" | "shipped" | "delivered" | "cancelled" | "refunded" | "return_requested";
+    carrier: string | null;
+    email: string;
+    id: string;
+    total: string;
+    createdAt: Date;
+    updatedAt: Date;
+    customerId: string | null;
+    subtotal: string;
+    tax: string;
+    shipping: string;
+    refundAmount: string | null;
+    returnReason: string | null;
+    discountCode: string | null;
+    discountAmount: string | null;
+    stripePromotionCodeId: string | null;
+    shippingAddress: {
+        firstName: string;
+        lastName: string;
+        line1: string;
+        line2?: string;
+        city: string;
+        state: string;
+        postalCode: string;
+        country: string;
+        phone?: string;
+    } | null;
+    billingAddress: {
+        firstName: string;
+        lastName: string;
+        line1: string;
+        line2?: string;
+        city: string;
+        state: string;
+        postalCode: string;
+        country: string;
+        phone?: string;
+    } | null;
+    stripePaymentIntentId: string | null;
+    stripeChargeId: string | null;
+    receiptUrl: string | null;
+    trackingNumber: string | null;
+    trackingUrl: string | null;
+    labelUrl: string | null;
+    shippoRateId: string | null;
+    shippingMethod: string | null;
+}>;
+/**
+ * Create order items for an order
+ */
+export declare function createOrderItems(items: schema.NewOrderItem[]): Promise<{
+    name: string;
+    id: string;
+    attributes: Record<string, string> | null;
+    quantity: number;
+    price: string;
+    createdAt: Date;
+    productId: string;
+    orderId: string;
+    variantId: string | null;
+}[]>;
+/**
+ * Update order status
+ */
+export declare function updateOrderStatus(orderId: string, status: 'pending' | 'paid' | 'shipped' | 'delivered' | 'cancelled' | 'refunded' | 'return_requested'): Promise<{
+    id: string;
+    customerId: string | null;
+    email: string;
+    status: "pending" | "paid" | "shipped" | "delivered" | "cancelled" | "refunded" | "return_requested";
+    subtotal: string;
+    tax: string;
+    shipping: string;
+    total: string;
+    refundAmount: string | null;
+    returnReason: string | null;
+    discountCode: string | null;
+    discountAmount: string | null;
+    stripePromotionCodeId: string | null;
+    shippingAddress: {
+        firstName: string;
+        lastName: string;
+        line1: string;
+        line2?: string;
+        city: string;
+        state: string;
+        postalCode: string;
+        country: string;
+        phone?: string;
+    } | null;
+    billingAddress: {
+        firstName: string;
+        lastName: string;
+        line1: string;
+        line2?: string;
+        city: string;
+        state: string;
+        postalCode: string;
+        country: string;
+        phone?: string;
+    } | null;
+    stripePaymentIntentId: string | null;
+    stripeChargeId: string | null;
+    receiptUrl: string | null;
+    trackingNumber: string | null;
+    trackingUrl: string | null;
+    carrier: string | null;
+    labelUrl: string | null;
+    shippoRateId: string | null;
+    shippingMethod: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}>;
+/**
+ * Update order shipping information (for Shippo integration)
+ */
+export declare function updateOrderShipping(orderId: string, shippingData: {
+    trackingNumber?: string;
+    trackingUrl?: string;
+    carrier?: string;
+    labelUrl?: string;
+    shippoRateId?: string;
+    shippingMethod?: string;
+    status?: 'pending' | 'paid' | 'shipped' | 'delivered' | 'cancelled' | 'refunded';
+}): Promise<{
+    id: string;
+    customerId: string | null;
+    email: string;
+    status: "pending" | "paid" | "shipped" | "delivered" | "cancelled" | "refunded" | "return_requested";
+    subtotal: string;
+    tax: string;
+    shipping: string;
+    total: string;
+    refundAmount: string | null;
+    returnReason: string | null;
+    discountCode: string | null;
+    discountAmount: string | null;
+    stripePromotionCodeId: string | null;
+    shippingAddress: {
+        firstName: string;
+        lastName: string;
+        line1: string;
+        line2?: string;
+        city: string;
+        state: string;
+        postalCode: string;
+        country: string;
+        phone?: string;
+    } | null;
+    billingAddress: {
+        firstName: string;
+        lastName: string;
+        line1: string;
+        line2?: string;
+        city: string;
+        state: string;
+        postalCode: string;
+        country: string;
+        phone?: string;
+    } | null;
+    stripePaymentIntentId: string | null;
+    stripeChargeId: string | null;
+    receiptUrl: string | null;
+    trackingNumber: string | null;
+    trackingUrl: string | null;
+    carrier: string | null;
+    labelUrl: string | null;
+    shippoRateId: string | null;
+    shippingMethod: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}>;
+/**
+ * Find order by Stripe Payment Intent ID
+ * Used for idempotency in webhook handling
+ */
+export declare function findOrderByPaymentIntent(paymentIntentId: string): Promise<{
+    id: string;
+    customerId: string | null;
+    email: string;
+    status: "pending" | "paid" | "shipped" | "delivered" | "cancelled" | "refunded" | "return_requested";
+    subtotal: string;
+    tax: string;
+    shipping: string;
+    total: string;
+    refundAmount: string | null;
+    returnReason: string | null;
+    discountCode: string | null;
+    discountAmount: string | null;
+    stripePromotionCodeId: string | null;
+    shippingAddress: {
+        firstName: string;
+        lastName: string;
+        line1: string;
+        line2?: string;
+        city: string;
+        state: string;
+        postalCode: string;
+        country: string;
+        phone?: string;
+    } | null;
+    billingAddress: {
+        firstName: string;
+        lastName: string;
+        line1: string;
+        line2?: string;
+        city: string;
+        state: string;
+        postalCode: string;
+        country: string;
+        phone?: string;
+    } | null;
+    stripePaymentIntentId: string | null;
+    stripeChargeId: string | null;
+    receiptUrl: string | null;
+    trackingNumber: string | null;
+    trackingUrl: string | null;
+    carrier: string | null;
+    labelUrl: string | null;
+    shippoRateId: string | null;
+    shippingMethod: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}>;
+/**
+ * Update order refund amount (for partial refund tracking)
+ * Adds the refund amount to the existing refund total
+ */
+export declare function updateOrderRefundAmount(orderId: string, refundAmountCents: number): Promise<schema.Order | null>;
+/**
+ * Update order receipt information (for Stripe receipt URL)
+ */
+export declare function updateOrderReceipt(orderId: string, receiptData: {
+    stripeChargeId?: string;
+    receiptUrl?: string;
+}): Promise<schema.Order | null>;
+/**
+ * Update order with return request
+ * Sets status to 'return_requested' and stores the return reason
+ */
+export declare function updateOrderReturnRequest(orderId: string, returnReason: string): Promise<schema.Order | null>;
+/**
+ * Clear order return request
+ * Sets status back to 'delivered' and clears the return reason
+ */
+export declare function clearOrderReturnRequest(orderId: string): Promise<schema.Order | null>;
+/**
+ * Create a new product
+ */
+export declare function createProduct(data: schema.NewProduct): Promise<schema.Product>;
+/**
+ * Update a product by ID
+ */
+export declare function updateProduct(id: string, data: Partial<Omit<schema.NewProduct, 'id'>>): Promise<schema.Product | null>;
+/**
+ * Archive a product by ID (soft delete).
+ * Sets status to 'archived' instead of deleting to preserve order history.
+ * Use hardDeleteProduct() for permanent deletion if needed.
+ */
+export declare function deleteProduct(id: string): Promise<boolean>;
+/**
+ * Permanently delete a product by ID.
+ * WARNING: This will fail if there are order_items referencing this product.
+ * Use deleteProduct() (soft delete) for most cases.
+ */
+export declare function hardDeleteProduct(id: string): Promise<boolean>;
+/**
+ * Create a new product variant
+ */
+export declare function createProductVariant(data: schema.NewProductVariant): Promise<schema.ProductVariant>;
+/**
+ * Update a product variant by ID
+ */
+export declare function updateProductVariant(id: string, data: Partial<Omit<schema.NewProductVariant, 'id' | 'productId'>>): Promise<schema.ProductVariant | null>;
+/**
+ * Delete a product variant by ID
+ */
+export declare function deleteProductVariant(id: string): Promise<boolean>;
+/**
+ * Update variant inventory
+ */
+export declare function updateVariantInventory(id: string, inventory: number): Promise<void>;
+/**
+ * Find a variant by ID
+ */
+export declare function findVariantById(id: string): Promise<schema.ProductVariant | null>;
+/**
+ * Find a category by ID
+ */
+export declare function findCategoryById(id: string): Promise<schema.Category | null>;
+/**
+ * Create a new category
+ */
+export declare function createCategory(data: schema.NewCategory): Promise<schema.Category>;
+/**
+ * Update a category by ID
+ */
+export declare function updateCategory(id: string, data: Partial<Omit<schema.NewCategory, 'id'>>): Promise<schema.Category | null>;
+/**
+ * Delete a category by ID
+ */
+export declare function deleteCategory(id: string): Promise<boolean>;
+/**
+ * Count categories
+ */
+export declare function countCategories(): Promise<number>;
+/**
+ * Count customers with optional search
+ */
+export declare function countCustomers(options?: {
+    search?: string;
+}): Promise<number>;
+/**
+ * Find orders for a specific customer
+ */
+export declare function findCustomerOrders(customerId: string): Promise<{
+    id: string;
+    customerId: string | null;
+    email: string;
+    status: "pending" | "paid" | "shipped" | "delivered" | "cancelled" | "refunded" | "return_requested";
+    subtotal: string;
+    tax: string;
+    shipping: string;
+    total: string;
+    refundAmount: string | null;
+    returnReason: string | null;
+    discountCode: string | null;
+    discountAmount: string | null;
+    stripePromotionCodeId: string | null;
+    shippingAddress: {
+        firstName: string;
+        lastName: string;
+        line1: string;
+        line2?: string;
+        city: string;
+        state: string;
+        postalCode: string;
+        country: string;
+        phone?: string;
+    } | null;
+    billingAddress: {
+        firstName: string;
+        lastName: string;
+        line1: string;
+        line2?: string;
+        city: string;
+        state: string;
+        postalCode: string;
+        country: string;
+        phone?: string;
+    } | null;
+    stripePaymentIntentId: string | null;
+    stripeChargeId: string | null;
+    receiptUrl: string | null;
+    trackingNumber: string | null;
+    trackingUrl: string | null;
+    carrier: string | null;
+    labelUrl: string | null;
+    shippoRateId: string | null;
+    shippingMethod: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}[]>;
+/**
+ * Claim guest orders by email when a customer registers.
+ * Updates all orders with matching email and null customerId to the new customer.
+ *
+ * @param email - Email address (will be lowercased)
+ * @param customerId - New customer ID to assign
+ * @returns Number of orders claimed
+ */
+export declare function claimGuestOrders(email: string, customerId: string): Promise<number>;
+/**
+ * Delete (anonymize) a customer by ID.
+ *
+ * This is a SOFT DELETE that anonymizes customer data instead of removing the record.
+ * This approach:
+ * - Preserves order history integrity (orders reference customerId)
+ * - Complies with GDPR "right to erasure" through anonymization
+ * - Prevents login by invalidating passwordHash
+ * - Keeps the record for audit trail purposes
+ *
+ * Related tokens (verification, password reset) are auto-deleted via CASCADE.
+ *
+ * @param id - Customer UUID
+ * @returns true if customer was found and anonymized, false if not found
+ */
+export declare function deleteCustomer(id: string): Promise<boolean>;
+/**
+ * Count orders with optional status filter
+ */
+export declare function countOrders(options?: {
+    status?: schema.Order['status'];
+}): Promise<number>;
+/**
+ * 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 declare function getRevenueByPeriod(days: number): Promise<{
+    date: string;
+    revenue: number;
+}[]>;
+/**
+ * Get orders by status count (for analytics)
+ */
+export declare function getOrdersByStatus(): Promise<{
+    status: string;
+    count: number;
+}[]>;
+/**
+ * Settings data type for API responses
+ */
+export interface StoreSettingsData {
+    storeName: string | null;
+    storeEmail: string | null;
+    logoUrl: string | null;
+    storeCurrency: string | null;
+    storeTimezone: string | null;
+    taxIncludedInPrices: boolean | null;
+    shippingEnabled: boolean | null;
+    freeShippingThreshold: number | null;
+    shippingCountries: string[] | null;
+    guestCheckout: boolean | null;
+    customerAccounts: boolean | null;
+    shippingMode: 'manual' | 'shippo' | null;
+    shippoApiKey: string | null;
+    shippoTestMode: boolean | null;
+    shippoFromAddress: {
+        name: string;
+        company?: string;
+        street1: string;
+        street2?: string;
+        city: string;
+        state: string;
+        zip: string;
+        country: string;
+        phone?: string;
+        email?: string;
+    } | null;
+    shippoDefaultParcel: {
+        length: number;
+        width: number;
+        height: number;
+        weight: number;
+    } | null;
+    promotionCodesEnabled: boolean | null;
+    cookieBannerEnabled: boolean | null;
+}
+/**
+ * Find store settings.
+ * Returns null if no settings exist (first time access).
+ * Each store has only one settings row.
+ */
+export declare function findSettings(): Promise<StoreSettingsData | null>;
+/**
+ * Upsert (create or update) store settings.
+ * Each store has only one settings row.
+ */
+export declare function upsertSettings(data: Partial<StoreSettingsData>): Promise<StoreSettingsData>;
+/**
+ * Shipping carrier data for API responses
+ */
+export interface ShippingCarrierData {
+    id: string;
+    name: string;
+    code: string;
+    description: string | null;
+    isActive: boolean;
+    sortOrder: number;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Shipping carrier with nested zones and rates for full hierarchy
+ */
+export interface ShippingCarrierWithZones extends ShippingCarrierData {
+    zones: ShippingZoneWithRates[];
+}
+/**
+ * Find all shipping carriers
+ */
+export declare function findShippingCarriers(): Promise<ShippingCarrierData[]>;
+/**
+ * Find active shipping carriers only
+ */
+export declare function findActiveShippingCarriers(): Promise<ShippingCarrierData[]>;
+/**
+ * Find a shipping carrier by ID
+ */
+export declare function findShippingCarrierById(id: string): Promise<ShippingCarrierData | null>;
+/**
+ * Create a new shipping carrier
+ */
+export declare function createShippingCarrier(data: {
+    name: string;
+    code: string;
+    description?: string;
+    isActive?: boolean;
+    sortOrder?: number;
+}): Promise<schema.ShippingCarrier>;
+/**
+ * Update a shipping carrier
+ */
+export declare function updateShippingCarrier(id: string, data: Partial<{
+    name: string;
+    code: string;
+    description: string | null;
+    isActive: boolean;
+    sortOrder: number;
+}>): Promise<schema.ShippingCarrier | null>;
+/**
+ * Delete a shipping carrier (cascades to zones and rates)
+ */
+export declare function deleteShippingCarrier(id: string): Promise<boolean>;
+/**
+ * Find all carriers with their zones and rates (full hierarchy for admin UI)
+ */
+export declare function findCarriersWithZonesAndRates(): Promise<ShippingCarrierWithZones[]>;
+/**
+ * Shipping zone with nested rates for API responses
+ */
+export interface ShippingZoneWithRates {
+    id: string;
+    carrierId: string;
+    carrier?: {
+        id: string;
+        name: string;
+        code: string;
+    };
+    name: string;
+    countries: string[];
+    isActive: boolean;
+    sortOrder: number;
+    createdAt: Date;
+    updatedAt: Date;
+    rates: Array<{
+        id: string;
+        name: string;
+        description: string | null;
+        price: number;
+        minOrderAmount: number | null;
+        maxOrderAmount: number | null;
+        estimatedDays: string | null;
+        isActive: boolean;
+        sortOrder: number;
+    }>;
+}
+/**
+ * Find all shipping zones with their rates and carrier info
+ */
+export declare function findShippingZones(): Promise<ShippingZoneWithRates[]>;
+/**
+ * Find active shipping zones only
+ */
+export declare function findActiveShippingZones(): Promise<ShippingZoneWithRates[]>;
+/**
+ * Find a shipping zone by ID
+ */
+export declare function findShippingZoneById(id: string): Promise<ShippingZoneWithRates | null>;
+/**
+ * Create a new shipping zone under a carrier
+ */
+export declare function createShippingZone(data: {
+    carrierId: string;
+    name: string;
+    countries: string[];
+    isActive?: boolean;
+    sortOrder?: number;
+}): Promise<schema.ShippingZone>;
+/**
+ * Update a shipping zone
+ */
+export declare function updateShippingZone(id: string, data: Partial<{
+    carrierId: string;
+    name: string;
+    countries: string[];
+    isActive: boolean;
+    sortOrder: number;
+}>): Promise<schema.ShippingZone | null>;
+/**
+ * Delete a shipping zone (cascades to rates)
+ */
+export declare function deleteShippingZone(id: string): Promise<boolean>;
+/**
+ * Create a shipping rate for a zone
+ */
+export declare function createShippingRate(data: {
+    zoneId: string;
+    name: string;
+    description?: string;
+    price: number;
+    minOrderAmount?: number;
+    maxOrderAmount?: number;
+    estimatedDays?: string;
+    isActive?: boolean;
+    sortOrder?: number;
+}): Promise<schema.ShippingRate>;
+/**
+ * Update a shipping rate
+ */
+export declare function updateShippingRate(id: string, data: Partial<{
+    name: string;
+    description: string | null;
+    price: number;
+    minOrderAmount: number | null;
+    maxOrderAmount: number | null;
+    estimatedDays: string | null;
+    isActive: boolean;
+    sortOrder: number;
+}>): Promise<schema.ShippingRate | null>;
+/**
+ * Delete a shipping rate
+ */
+export declare function deleteShippingRate(id: string): Promise<boolean>;
+/**
+ * Find shipping rates applicable to a specific country and order amount.
+ * Used during checkout to determine which shipping options to show.
+ *
+ * @param country - ISO country code (e.g., 'US', 'CA')
+ * @param orderAmount - Order subtotal in dollars
+ * @returns Array of applicable shipping rates with carrier info
+ */
+export declare function findShippingRatesForCountry(country: string, orderAmount: number): Promise<Array<{
+    id: string;
+    carrierId: string;
+    carrierName: string;
+    carrierCode: string;
+    zoneName: string;
+    name: string;
+    description: string | null;
+    price: number;
+    estimatedDays: string | null;
+}>>;
+/**
+ * Shipping option for checkout UI (unified format for both manual and Shippo modes)
+ * Compatible with checkout/types.ts ShippingOption
+ */
+export interface ShippingOptionForCheckout {
+    id: string;
+    carrierId: string;
+    carrierName: string;
+    carrierCode: string;
+    /** Display name (e.g., "Standard Shipping", "Priority Mail") - matches ShippingOption.name */
+    name: string;
+    /** Description - optional to match ShippingOption */
+    description?: string;
+    price: number;
+    /** Estimated delivery time - optional to match ShippingOption */
+    estimatedDays?: string;
+    source: 'manual' | 'shippo';
+}
+/**
+ * Shipping options grouped by carrier for checkout UI
+ */
+export interface ShippingOptionsGroupedByCarrier {
+    carrier: {
+        id: string;
+        name: string;
+        code: string;
+    };
+    options: ShippingOptionForCheckout[];
+}
+/**
+ * Find shipping options for checkout grouped by carrier.
+ * This is the main function used by the pre-checkout flow.
+ *
+ * @param country - ISO country code (e.g., 'US', 'CA')
+ * @param orderAmount - Order subtotal in dollars
+ * @returns Shipping options grouped by carrier
+ */
+export declare function findShippingOptionsForCountry(country: string, orderAmount: number): Promise<ShippingOptionsGroupedByCarrier[]>;
+/**
+ * Tax zone data for API responses
+ */
+export interface TaxZoneData {
+    id: string;
+    name: string;
+    countries: string[];
+    states: string[];
+    taxRate: number;
+    isActive: boolean;
+    sortOrder: number;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Find all tax zones ordered by priority (sortOrder ascending)
+ */
+export declare function findTaxZones(): Promise<TaxZoneData[]>;
+/**
+ * Find only active tax zones
+ */
+export declare function findActiveTaxZones(): Promise<TaxZoneData[]>;
+/**
+ * Find a tax zone by ID
+ */
+export declare function findTaxZoneById(id: string): Promise<TaxZoneData | null>;
+/**
+ * Create a new tax zone
+ */
+export declare function createTaxZone(data: {
+    name: string;
+    countries: string[];
+    states?: string[];
+    taxRate: number;
+    isActive?: boolean;
+    sortOrder?: number;
+}): Promise<schema.TaxZone>;
+/**
+ * Update a tax zone
+ */
+export declare function updateTaxZone(id: string, data: Partial<{
+    name: string;
+    countries: string[];
+    states: string[];
+    taxRate: number;
+    isActive: boolean;
+    sortOrder: number;
+}>): Promise<schema.TaxZone | null>;
+/**
+ * Delete a tax zone
+ */
+export declare function deleteTaxZone(id: string): Promise<boolean>;
+/**
+ * Result of tax zone matching for checkout
+ */
+export interface TaxRateMatch {
+    zoneId: string;
+    zoneName: string;
+    taxRate: number;
+}
+/**
+ * Find the applicable tax rate for a given address.
+ * Returns the first matching zone based on priority (sortOrder).
+ *
+ * Matching logic:
+ * 1. For US addresses: Match country='US' AND state matches (if zone has states)
+ * 2. For non-US addresses: Match country only
+ * 3. Wildcard '*' in countries matches any country
+ *
+ * @param country - ISO-2 country code (e.g., 'US', 'FR')
+ * @param state - State/province code for US (e.g., 'CA', 'NY')
+ * @returns Tax rate info or null if no matching zone
+ */
+export declare function findTaxRateForAddress(country: string, state?: string): Promise<TaxRateMatch | null>;
+/**
+ * Shape of the `store_settings.onboarding` JSONB column. Mirrors the type in
+ * schema.ts. Re-declared here as a plain interface so non-Drizzle consumers
+ * (API handlers, tests) don't have to import the schema's inferred type.
+ */
+export interface OnboardingState {
+    firstProductTouched?: boolean;
+    logoUploaded?: boolean;
+    taxNoneNeeded?: boolean;
+    legalPagesReviewed?: boolean;
+    dismissedAt?: string;
+}
+export declare function ensureOnboardingColumn(): Promise<void>;
+/**
+ * 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 declare function getOnboardingState(): Promise<OnboardingState>;
+/**
+ * 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 declare function setOnboardingFlag<K extends keyof OnboardingState>(key: K, value: OnboardingState[K]): Promise<void>;
+/**
+ * Aggregated signal counts used by the setup-guide GET handler. One round-trip
+ * via Promise.all instead of four sequential queries.
+ */
+export declare function getSetupGuideSignals(): Promise<{
+    productCount: number;
+    shippingZonesCount: number;
+    taxZonesCount: number;
+    adminCount: number;
+    storeSettings: {
+        logoUrl: string | null;
+        analytics: Record<string, unknown>;
+        onboarding: OnboardingState;
+    } | null;
+}>;
+//# sourceMappingURL=queries.d.ts.map