@rovela-ai/sdk 0.4.1 → 0.4.2

package/dist/admin/types.d.ts

@@ -0,0 +1,1161 @@
+/**
+ * @rovela/sdk/admin/types
+ *
+ * Type definitions for admin dashboard module.
+ *
+ * PATTERN: Admin-specific types only. Shared types are imported from core.
+ * This ensures consistency across the SDK and avoids duplication.
+ */
+import type { ReactNode } from 'react';
+import type { AdminRole } from '../core/types';
+export type { OrderStatus, ProductStatus, AdminRole, AdminStatus, Order, OrderItem, Product, ProductVariant, Customer, StoreAdmin, Category, PaginatedResponse, ApiError, Address, } from '../core/types';
+/**
+ * API error response for admin endpoints.
+ */
+export interface AdminApiError {
+    /** Error message */
+    error: string;
+    /** Error code for programmatic handling */
+    code: 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | 'VALIDATION_ERROR' | 'INTERNAL_ERROR' | 'INVALID_CREDENTIALS' | 'EMAIL_EXISTS';
+}
+/**
+ * Admin session data stored in JWT token.
+ *
+ * `role` covers the four-role union ('owner' | 'administrator' | 'manager' | 'user').
+ *
+ * `sessionVersion` is a Phase 4 addition: an integer that's bumped on every
+ * password change (self-service, forgot-password reset, accept-invite,
+ * emergency reset). `requireAdmin` compares the JWT value to the DB value
+ * on every request and returns 401 on mismatch → forced logout after
+ * password rotation.
+ */
+export interface AdminSession {
+    id: string;
+    email: string;
+    name: string;
+    role: AdminRole;
+    sessionVersion?: number;
+}
+/**
+ * Authentication state returned by useAdminAuth hook.
+ */
+export interface AdminAuthState {
+    admin: AdminSession | null;
+    isAuthenticated: boolean;
+    isLoading: boolean;
+    isOwner: boolean;
+}
+/**
+ * Options for admin sign in.
+ */
+export interface AdminSignInOptions {
+    email: string;
+    password: string;
+    redirectTo?: string;
+    /**
+     * When true, the session cookie is honored for up to 30 days instead of
+     * the default admin session window. Enforced via an absolute `token.exp`
+     * in the unified NextAuth JWT callback.
+     */
+    rememberMe?: boolean;
+}
+/**
+ * Result of admin sign in attempt.
+ */
+export interface AdminSignInResult {
+    success: boolean;
+    error?: string;
+}
+/**
+ * Safe projection of a store admin for list/detail views. Mirrors the shape
+ * returned by `GET /api/admin/users` — no `passwordHash`, dates as ISO strings.
+ */
+export interface AdminListItem {
+    id: string;
+    email: string;
+    name: string;
+    role: AdminRole;
+    status: 'active' | 'invited' | 'deactivated';
+    createdBy: string | null;
+    createdAt: string;
+    lastLoginAt: string | null;
+    deactivatedAt: string | null;
+    deactivatedBy: string | null;
+}
+/**
+ * Options for the `GET /api/admin/users` list endpoint, mirrored into the
+ * `useAdminUsers` hook.
+ */
+export interface AdminUserListOptions {
+    search?: string;
+    status?: 'all' | 'active' | 'invited' | 'deactivated';
+    role?: 'all' | AdminRole;
+    page?: number;
+    limit?: number;
+}
+/**
+ * Payload for inviting a new admin.
+ */
+export interface AdminInviteData {
+    email: string;
+    name: string;
+    role: AdminRole;
+}
+/**
+ * Successful-invite result returned from hook methods. `inviteUrl` is
+ * always present so the UI can show a "copy link manually" fallback if
+ * email delivery is unreliable.
+ */
+export interface AdminInviteHookResult {
+    success: boolean;
+    error?: string;
+    inviteUrl?: string;
+    adminId?: string;
+}
+/**
+ * Return shape of the `useAdminUsers` hook.
+ */
+export interface UseAdminUsersReturn {
+    users: AdminListItem[];
+    total: number;
+    page: number;
+    isLoading: boolean;
+    error: string | null;
+    fetchUsers: (options?: AdminUserListOptions) => Promise<void>;
+    getUser: (id: string) => Promise<AdminListItem | null>;
+    deactivate: (id: string) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    reactivate: (id: string) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    deleteUser: (id: string) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    invite: (data: AdminInviteData) => Promise<AdminInviteHookResult>;
+    resendInvite: (id: string) => Promise<AdminInviteHookResult>;
+    cancelInvite: (id: string) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    changeRole: (id: string, newRole: AdminRole) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+}
+/**
+ * Return shape of the `useAdminPermissions` hook — client-side helpers
+ * that wrap the pure permission functions from `admin/permissions.ts`.
+ */
+export interface UseAdminPermissionsReturn {
+    /** Current admin's role, or `null` if unauthenticated. */
+    role: AdminRole | null;
+    /** True if the current admin is an owner. */
+    isOwner: boolean;
+    /** True if the current admin is an administrator. */
+    isAdministrator: boolean;
+    /** Check whether the current admin has a named permission. */
+    can: (permission: import('./permissions').Permission) => boolean;
+    /**
+     * Check whether the current admin can lifecycle-manage (deactivate, delete,
+     * reactivate, change role of) the given target admin. Enforces the
+     * "administrators cannot touch owners or other administrators" rule.
+     */
+    canManageUser: (target: {
+        id: string;
+        role: AdminRole;
+    }) => boolean;
+}
+/**
+ * Props for the `UsersTable` component.
+ */
+export interface UsersTableProps {
+    /** Rows per page (default: 20). */
+    pageSize?: number;
+    /** Optional className for the root element. */
+    className?: string;
+}
+/**
+ * Props for the `InviteUserDialog` component.
+ */
+export interface InviteUserDialogProps {
+    /** Whether the dialog is visible. */
+    isOpen: boolean;
+    /** Called when the user closes the dialog (cancel or after successful done). */
+    onClose: () => void;
+    /** Called once after a successful invite completes, with the invite data. */
+    onInvited?: (result: {
+        adminId: string;
+        inviteUrl: string;
+    }) => void;
+    /** Optional className for the dialog container. */
+    className?: string;
+}
+/**
+ * Props for the `AdminAcceptInviteForm` component.
+ */
+export interface AdminAcceptInviteFormProps {
+    /** Optional className for the root element. */
+    className?: string;
+    /** URL to redirect to after a successful accept (default: /admin/login). */
+    loginUrl?: string;
+    /** Delay in ms before redirecting after success (default: 2000). */
+    redirectDelayMs?: number;
+}
+/**
+ * Dashboard statistics data.
+ */
+export interface DashboardStats {
+    products: number;
+    orders: number;
+    customers: number;
+    revenue: number;
+}
+/**
+ * Low stock product alert.
+ */
+export interface LowStockItem {
+    productId: string;
+    productName: string;
+    variantId: string;
+    variantName: string;
+    inventory: number;
+}
+/**
+ * Recent order for dashboard display.
+ * Note: status is string to allow flexibility in API responses.
+ */
+export interface RecentOrder {
+    id: string;
+    email: string;
+    status: string;
+    total: string;
+    createdAt: string;
+}
+/**
+ * Public period codes for the dashboard time-window selector. Server maps
+ * these to days: today=1, 7d=7, 30d=30, 90d=90.
+ */
+export type DashboardPeriod = 'today' | '7d' | '30d' | '90d';
+/**
+ * Period-scoped summary returned by `GET /api/admin/stats?period=...`.
+ *
+ * - `current` and `previous` are the two equal-length windows.
+ * - `deltas` are decimal ratios (0.124 = +12.4%) — null when prior period
+ *   was zero (delta is undefined). Refund-rate delta is *signed by raw
+ *   direction*; the UI is responsible for inverting color semantics so
+ *   "refund rate went down" reads as a green improvement.
+ */
+export interface DashboardSummaryPayload {
+    periodDays: number;
+    current: {
+        revenue: number;
+        orders: number;
+        newCustomers: number;
+        newProducts: number;
+        aov: number;
+        refundRate: number;
+        bestSeller: {
+            id: string;
+            name: string;
+            unitsSold: number;
+            revenue: string;
+        } | null;
+    };
+    previous: {
+        revenue: number;
+        orders: number;
+        newCustomers: number;
+        newProducts: number;
+        aov: number;
+        refundRate: number;
+    };
+    deltas: {
+        revenue: number | null;
+        orders: number | null;
+        aov: number | null;
+        refundRate: number | null;
+        customers: number | null;
+    };
+}
+/**
+ * Options for useAdminStats hook.
+ */
+export interface UseAdminStatsOptions {
+    lowStockThreshold?: number;
+    recentOrdersLimit?: number;
+}
+/**
+ * Product form data for create/update.
+ */
+export interface ProductFormData {
+    name: string;
+    slug?: string;
+    description: string;
+    price: number;
+    comparePrice?: number;
+    images: string[];
+    videos?: string[];
+    status: 'draft' | 'active' | 'archived';
+    categoryId?: string;
+    hasVariants: boolean;
+    sku?: string;
+    inventory?: number;
+    trackInventory?: boolean;
+    continueSellingWhenOutOfStock?: boolean;
+    productType?: string;
+    vendor?: string;
+    tags?: string[];
+    metaTitle?: string;
+    metaDescription?: string;
+    metaKeywords?: string[];
+}
+/**
+ * Variant form data for create/update.
+ */
+export interface VariantFormData {
+    id?: string;
+    sku: string;
+    name: string;
+    price?: number;
+    inventory: number;
+    image?: string;
+    video?: string;
+    attributes: Record<string, string>;
+}
+/**
+ * Category form data for create/update.
+ */
+export interface CategoryFormData {
+    name: string;
+    slug?: string;
+    description?: string;
+    image?: string;
+    parentId?: string;
+    order?: number;
+}
+/**
+ * Product list options for admin queries.
+ */
+export interface ProductListOptions {
+    search?: string;
+    category?: string;
+    status?: 'draft' | 'active' | 'archived';
+    sort?: 'newest' | 'name' | 'price-asc' | 'price-desc';
+    page?: number;
+    limit?: number;
+    /** Filter to products effectively out of stock (the OOS chip on the list page). */
+    outOfStock?: boolean;
+}
+/**
+ * Order list options for admin queries.
+ */
+export interface OrderListOptions {
+    search?: string;
+    status?: 'pending' | 'paid' | 'shipped' | 'delivered' | 'cancelled' | 'refunded' | 'return_requested';
+    sort?: 'newest' | 'oldest' | 'total-asc' | 'total-desc';
+    page?: number;
+    limit?: number;
+}
+/**
+ * Customer list options for admin queries.
+ */
+export interface CustomerListOptions {
+    search?: string;
+    page?: number;
+    limit?: number;
+}
+/**
+ * Generic CRUD operation result.
+ */
+export interface CrudResult<T> {
+    success: boolean;
+    data?: T;
+    error?: string;
+}
+/**
+ * Refund result.
+ */
+export interface RefundResult {
+    success: boolean;
+    refundId?: string;
+    error?: string;
+}
+/**
+ * Return request result (approve/reject).
+ */
+export interface ReturnResult {
+    success: boolean;
+    /** Stripe refund ID (only present when approved) */
+    refundId?: string;
+    /** Message describing the action taken */
+    message?: string;
+    error?: string;
+}
+/**
+ * Store settings data from database queries.
+ * Uses `| null` to match database results.
+ */
+export interface StoreSettingsData {
+    storeName: string | null;
+    storeEmail: string | null;
+    storeCurrency: string | null;
+    storeTimezone: string | null;
+    /** Whether prices include tax (true = extract tax, false = add tax on top) */
+    taxIncludedInPrices: boolean | null;
+    shippingEnabled: boolean | null;
+    freeShippingThreshold: number | null;
+    shippingCountries: string[] | null;
+    guestCheckout: boolean | null;
+    customerAccounts: boolean | null;
+    shippingMode: ShippingMode | null;
+    shippoApiKey: string | null;
+    shippoTestMode: boolean | null;
+    shippoFromAddress: ShippoAddress | null;
+    shippoDefaultParcel: ShippoParcel | null;
+    promotionCodesEnabled: boolean | null;
+    cookieBannerEnabled: boolean | null;
+}
+/**
+ * Store settings input for forms and API updates.
+ * Uses concrete types (no nulls) as forms always provide actual values.
+ */
+export interface StoreSettingsInput {
+    storeName: string;
+    storeEmail: string;
+    storeCurrency: string;
+    storeTimezone: string;
+    /** Whether prices include tax (true = extract, false = add on top) - managed in TaxSettings */
+    taxIncludedInPrices?: boolean;
+    guestCheckout?: boolean;
+    customerAccounts?: boolean;
+    cookieBannerEnabled?: boolean;
+    shippingEnabled?: boolean;
+    freeShippingThreshold?: number;
+    shippingCountries?: string[];
+    promotionCodesEnabled?: boolean;
+}
+/**
+ * Shipping carrier (root of manual shipping hierarchy).
+ * Carriers are store-defined (e.g., "USPS", "FedEx", "Local Delivery").
+ */
+export interface ShippingCarrierData {
+    id: string;
+    name: string;
+    code: string;
+    description: string | null;
+    isActive: boolean;
+    sortOrder: number;
+    createdAt: Date | string;
+    updatedAt: Date | string;
+    /** Zones belonging to this carrier (populated when fetching carrier details) */
+    zones?: ShippingZoneData[];
+}
+/**
+ * Input for creating/updating a shipping carrier.
+ */
+export interface ShippingCarrierInput {
+    name: string;
+    code: string;
+    description?: string;
+    isActive?: boolean;
+    sortOrder?: number;
+}
+/**
+ * Shipping rate within a zone.
+ */
+export interface ShippingRateData {
+    id: string;
+    name: string;
+    description: string | null;
+    price: number;
+    minOrderAmount: number | null;
+    maxOrderAmount: number | null;
+    estimatedDays: string | null;
+    isActive: boolean;
+    sortOrder: number;
+}
+/**
+ * Shipping zone with its rates.
+ */
+export interface ShippingZoneData {
+    id: string;
+    /** Carrier this zone belongs to */
+    carrierId: string;
+    /** Carrier name (populated from join) */
+    carrierName?: string;
+    /** Carrier code (populated from join) */
+    carrierCode?: string;
+    name: string;
+    countries: string[];
+    isActive: boolean;
+    sortOrder: number;
+    createdAt: Date | string;
+    updatedAt: Date | string;
+    rates: ShippingRateData[];
+}
+/**
+ * Input for creating/updating a shipping zone.
+ */
+export interface ShippingZoneInput {
+    /** Carrier this zone belongs to (required) */
+    carrierId: string;
+    name: string;
+    countries: string[];
+    isActive?: boolean;
+    sortOrder?: number;
+}
+/**
+ * Input for creating/updating a shipping rate.
+ */
+export interface ShippingRateInput {
+    zoneId: string;
+    name: string;
+    description?: string;
+    price: number;
+    minOrderAmount?: number;
+    maxOrderAmount?: number;
+    estimatedDays?: string;
+    isActive?: boolean;
+    sortOrder?: number;
+}
+/**
+ * Props for ShippingSettings component.
+ */
+export interface ShippingSettingsProps {
+    className?: string;
+}
+/**
+ * Tax zone data for API responses.
+ * Tax zones define tax rates by country/state for zone-based tax calculation.
+ */
+export interface TaxZoneData {
+    id: string;
+    /** Zone name (e.g., "US - California", "EU Standard") */
+    name: string;
+    /** ISO-2 country codes or ['*'] for wildcard */
+    countries: string[];
+    /** US state codes (only used when countries includes 'US') */
+    states: string[];
+    /** Tax rate as percentage (e.g., 8.25 = 8.25%) */
+    taxRate: number;
+    /** Whether this zone is active */
+    isActive: boolean;
+    /** Priority order (lower = checked first during matching) */
+    sortOrder: number;
+    createdAt: Date | string;
+    updatedAt: Date | string;
+}
+/**
+ * Input for creating/updating a tax zone.
+ */
+export interface TaxZoneInput {
+    name: string;
+    countries: string[];
+    states?: string[];
+    taxRate: number;
+    isActive?: boolean;
+    sortOrder?: number;
+}
+/**
+ * Props for TaxSettings component.
+ */
+export interface TaxSettingsProps {
+    className?: string;
+}
+/**
+ * Props for ShippingZoneForm component.
+ */
+export interface ShippingZoneFormProps {
+    zone?: ShippingZoneData;
+    isOpen: boolean;
+    onClose: () => void;
+    onSuccess?: () => void;
+}
+/**
+ * Props for ShippingRateForm component.
+ */
+export interface ShippingRateFormProps {
+    zoneId: string;
+    rate?: ShippingRateData;
+    isOpen: boolean;
+    onClose: () => void;
+    onSuccess?: () => void;
+}
+/**
+ * Shipping mode: manual zones/rates or Shippo carrier rates.
+ */
+export type ShippingMode = 'manual' | 'shippo';
+/**
+ * Shippo address for ship-from location.
+ */
+export interface ShippoAddress {
+    name: string;
+    company?: string;
+    street1: string;
+    street2?: string;
+    city: string;
+    state: string;
+    zip: string;
+    country: string;
+    phone?: string;
+    email?: string;
+}
+/**
+ * Shippo parcel dimensions for rate calculation.
+ */
+export interface ShippoParcel {
+    length: number;
+    width: number;
+    height: number;
+    weight: number;
+}
+/**
+ * Shippo rate from API response.
+ */
+export interface ShippoRate {
+    objectId: string;
+    provider: string;
+    servicelevel: {
+        name: string;
+        token: string;
+    };
+    amount: string;
+    currency: string;
+    estimatedDays: number;
+}
+/**
+ * Shippo label purchase result.
+ */
+export interface ShippoLabelResult {
+    trackingNumber: string;
+    trackingUrl: string;
+    labelUrl: string;
+    carrier: string;
+}
+/**
+ * Shippo API validation result.
+ */
+export interface ShippoValidationResult {
+    valid: boolean;
+    error?: string;
+}
+/**
+ * Props for AdminLayout component.
+ */
+export interface AdminLayoutProps {
+    children: ReactNode;
+    storeName?: string;
+    activeNav?: 'dashboard' | 'products' | 'orders' | 'customers' | 'settings';
+    className?: string;
+}
+/**
+ * Props for AdminGuard component.
+ */
+export interface AdminGuardProps {
+    children: ReactNode;
+    fallback?: ReactNode;
+    redirectTo?: string;
+    requireOwner?: boolean;
+    loadingComponent?: ReactNode;
+}
+/**
+ * Props for AdminLoginForm component.
+ */
+export interface AdminLoginFormProps {
+    redirectTo?: string;
+    onSuccess?: () => void;
+    className?: string;
+    /**
+     * Show the "Keep me signed in for 30 days" checkbox. Default: true.
+     * Set to false on shared-device flows (e.g. kiosk mode).
+     */
+    showRememberMe?: boolean;
+}
+/**
+ * Props for AdminNav component.
+ */
+export interface AdminNavProps {
+    storeName?: string;
+    activeNav?: 'dashboard' | 'products' | 'orders' | 'customers' | 'settings';
+    className?: string;
+}
+/**
+ * Props for StatsCards component.
+ */
+export interface StatsCardsProps {
+    stats?: DashboardStats | null;
+    isLoading?: boolean;
+    currency?: string;
+    className?: string;
+}
+/**
+ * Props for RecentOrders component.
+ */
+export interface RecentOrdersProps {
+    limit?: number;
+    viewAllHref?: string;
+    className?: string;
+}
+/**
+ * Props for LowStockAlert component.
+ */
+export interface LowStockAlertProps {
+    threshold?: number;
+    viewAllHref?: string;
+    className?: string;
+}
+/**
+ * Props for ProductTable component.
+ */
+export interface ProductTableProps {
+    initialSearch?: string;
+    initialCategory?: string;
+    initialStatus?: 'draft' | 'active' | 'archived';
+    pageSize?: number;
+    onProductClick?: (productId: string) => void;
+    className?: string;
+}
+/**
+ * Props for ProductForm component.
+ */
+export interface ProductFormProps {
+    productId?: string;
+    initialData?: Partial<ProductFormData>;
+    onSuccess?: (productId: string) => void;
+    onCancel?: () => void;
+    className?: string;
+}
+/**
+ * Props for InventoryEditor component.
+ */
+export interface InventoryEditorProps {
+    productId: string;
+    variants: Array<{
+        id: string;
+        productId: string;
+        sku: string;
+        name: string;
+        price: string | null;
+        inventory?: number;
+        attributes: Record<string, string>;
+        createdAt: string;
+    }>;
+    onUpdate?: () => void;
+    className?: string;
+}
+/**
+ * Props for OrderTable component.
+ */
+export interface OrderTableProps {
+    initialSearch?: string;
+    initialStatus?: 'pending' | 'paid' | 'shipped' | 'delivered' | 'cancelled' | 'refunded';
+    pageSize?: number;
+    onOrderClick?: (orderId: string) => void;
+    className?: string;
+}
+/**
+ * Props for OrderDetails component.
+ */
+export interface OrderDetailsProps {
+    orderId: string;
+    onStatusUpdate?: (status: string) => void;
+    /** Callback when refund button is clicked. Receives orderId and orderTotal for RefundDialog. */
+    onRefund?: (orderId: string, orderTotal: string | number) => void;
+    onBack?: () => void;
+    className?: string;
+}
+/**
+ * Props for RefundDialog component.
+ */
+export interface RefundDialogProps {
+    orderId: string;
+    orderTotal: string | number;
+    isOpen: boolean;
+    onClose: () => void;
+    onSuccess?: () => void;
+}
+/**
+ * Props for StoreSettings component.
+ */
+export interface StoreSettingsProps {
+    initialSettings?: Partial<StoreSettingsData>;
+    onSave?: (settings: StoreSettingsInput) => Promise<void> | void;
+    className?: string;
+}
+/**
+ * Props for CustomerTable component.
+ */
+export interface CustomerTableProps {
+    pageSize?: number;
+    onCustomerClick?: (customerId: string) => void;
+    className?: string;
+}
+/**
+ * Props for CustomerDetails component.
+ */
+export interface CustomerDetailsProps {
+    /** Customer ID to display */
+    customerId: string;
+    /** Called when user clicks back button */
+    onBack?: () => void;
+    /** Called after successful delete (navigates away) */
+    onDelete?: () => void;
+    /** Additional CSS classes */
+    className?: string;
+}
+/**
+ * Options for creating admin auth configuration.
+ */
+export interface AdminAuthConfigOptions {
+    /** Session duration when rememberMe is NOT ticked (seconds). Default: 24h. */
+    sessionMaxAge?: number;
+    /** Session duration when rememberMe IS ticked (seconds). Default: 30d. */
+    rememberMeMaxAge?: number;
+    signInPage?: string;
+    errorPage?: string;
+    dashboardPage?: string;
+}
+/**
+ * Return type for useAdminAuth hook.
+ */
+export interface UseAdminAuthReturn extends AdminAuthState {
+    signIn: (options: AdminSignInOptions) => Promise<AdminSignInResult>;
+    signOut: () => Promise<void>;
+}
+/** Revenue data point for charts. */
+export interface RevenueDataPoint {
+    date: string;
+    revenue: number;
+}
+/** Order status data point for charts. */
+export interface OrderStatusDataPoint {
+    status: string;
+    count: number;
+}
+/**
+ * Return type for useAdminStats hook.
+ */
+export interface UseAdminStatsReturn {
+    stats: DashboardStats | null;
+    lowStock: LowStockItem[];
+    recentOrders: RecentOrder[];
+    /** Revenue by day data for charts (requires includeRevenue option) */
+    revenueByDay: RevenueDataPoint[];
+    /** Order breakdown by status for charts (requires includeOrderStatus option) */
+    ordersByStatus: OrderStatusDataPoint[];
+    /** Period-scoped summary with deltas + best seller (requires `period` option). */
+    summary: DashboardSummaryPayload | null;
+    isLoading: boolean;
+    error: string | null;
+    refresh: () => Promise<void>;
+}
+/**
+ * Return type for useAdminOrders hook.
+ * Note: Matches actual implementation in useAdminOrders.ts
+ */
+export interface UseAdminOrdersReturn {
+    orders: AdminOrderListItem[];
+    total: number;
+    page: number;
+    isLoading: boolean;
+    error: string | null;
+    fetchOrders: (options?: OrderListOptions) => Promise<void>;
+    getOrder: (orderId: string) => Promise<AdminOrderDetail | null>;
+    updateStatus: (orderId: string, status: string, notifyCustomer?: boolean, trackingInfo?: {
+        trackingNumber?: string;
+        trackingUrl?: string;
+    }) => Promise<CrudResult<void>>;
+    processRefund: (orderId: string, amount: number, reason?: string) => Promise<RefundResult>;
+    /** Approve a return request and process Stripe refund */
+    approveReturn: (orderId: string, notifyCustomer?: boolean) => Promise<ReturnResult>;
+    /** Reject a return request (order returns to 'delivered' status) */
+    rejectReturn: (orderId: string, reason?: string, notifyCustomer?: boolean) => Promise<ReturnResult>;
+}
+/**
+ * Return type for useAdminProducts hook.
+ */
+export interface UseAdminProductsReturn {
+    products: AdminProductListItem[];
+    total: number;
+    page: number;
+    isLoading: boolean;
+    error: string | null;
+    fetchProducts: (options?: ProductListOptions) => Promise<void>;
+    getProduct: (id: string) => Promise<AdminProductDetail | null>;
+    createProduct: (data: ProductFormData) => Promise<CrudResult<AdminProductDetail>>;
+    updateProduct: (id: string, data: Partial<ProductFormData>) => Promise<CrudResult<AdminProductDetail>>;
+    deleteProduct: (id: string) => Promise<CrudResult<void>>;
+    updateVariant: (productId: string, variantId: string, data: Partial<VariantFormData>) => Promise<CrudResult<unknown>>;
+    /** Bulk activate / archive / delete by ID list. Always resolves with both succeeded and failed arrays. */
+    bulkAction: (ids: string[], action: 'activate' | 'archive' | 'delete') => Promise<BulkActionResult>;
+}
+/**
+ * Return type for useAdminProductMetrics hook.
+ */
+export interface UseAdminProductMetricsReturn {
+    metrics: ProductMetrics | null;
+    isLoading: boolean;
+    error: string | null;
+    fetchMetrics: () => Promise<void>;
+}
+/**
+ * Return type for useAdminCustomers hook.
+ */
+export interface UseAdminCustomersReturn {
+    customers: AdminCustomerListItem[];
+    total: number;
+    page: number;
+    isLoading: boolean;
+    error: string | null;
+    fetchCustomers: (options?: CustomerListOptions) => Promise<void>;
+    getCustomer: (id: string) => Promise<AdminCustomerDetail | null>;
+    updateCustomer: (id: string, data: {
+        name?: string;
+        email?: string;
+    }) => Promise<CrudResult<AdminCustomerDetail>>;
+    deleteCustomer: (id: string) => Promise<CrudResult<void>>;
+}
+/**
+ * Return type for useAdminCategories hook.
+ */
+export interface UseAdminCategoriesReturn {
+    categories: AdminCategoryListItem[];
+    isLoading: boolean;
+    error: string | null;
+    fetchCategories: () => Promise<void>;
+    createCategory: (data: CategoryFormData) => Promise<CrudResult<unknown>>;
+    updateCategory: (id: string, data: Partial<CategoryFormData>) => Promise<CrudResult<unknown>>;
+    deleteCategory: (id: string) => Promise<CrudResult<void>>;
+}
+/**
+ * Order list item for OrderTable component.
+ */
+export interface AdminOrderListItem {
+    id: string;
+    email: string;
+    status: string;
+    total: string;
+    createdAt: string;
+}
+/**
+ * Order detail for OrderDetails component.
+ */
+export interface AdminOrderDetail {
+    id: string;
+    email: string;
+    status: string;
+    subtotal: string;
+    tax: string;
+    shipping: string;
+    total: string;
+    createdAt: string;
+    updatedAt: string;
+    customerId?: string;
+    stripePaymentIntentId?: string;
+    shippingAddress?: {
+        firstName: string;
+        lastName: string;
+        line1: string;
+        line2?: string;
+        city: string;
+        state: string;
+        postalCode: string;
+        country: string;
+        phone?: string;
+    };
+    items?: AdminOrderItem[];
+    discountCode?: string;
+    discountAmount?: string;
+    stripePromotionCodeId?: string;
+    trackingNumber?: string;
+    trackingUrl?: string;
+    carrier?: string;
+    labelUrl?: string;
+    shippoRateId?: string;
+    shippingMethod?: string;
+    receiptUrl?: string;
+    returnReason?: string;
+}
+/**
+ * Order item in order detail.
+ */
+export interface AdminOrderItem {
+    id: string;
+    name: string;
+    price: string;
+    quantity: number;
+    attributes?: Record<string, string>;
+    /** Product image URL (first image from product) */
+    image?: string;
+}
+/**
+ * Product list item for ProductTable component.
+ */
+export interface AdminProductListItem {
+    id: string;
+    name: string;
+    slug: string;
+    price: string;
+    comparePrice?: string | null;
+    status: string;
+    images: string[];
+    categoryId?: string;
+    sku?: string;
+    inventory?: number;
+    /** True when inventory lives on `productVariants`; the parent `inventory` is unused. */
+    hasVariants?: boolean;
+    trackInventory?: boolean;
+    /**
+     * Server-computed inventory shown in the product list. For non-variant
+     * products this equals `inventory`. For variant products this is the sum
+     * of variant inventory (computed via `getInventoryByProductIds`). Always
+     * a number — the API normalizes nulls to 0.
+     */
+    effectiveInventory?: number;
+    productType?: string;
+    vendor?: string;
+    createdAt: string;
+}
+/**
+ * Aggregate metrics surfaced on the admin product list page (3 cards).
+ * Returned by `GET /api/admin/products/stats`.
+ */
+export interface ProductMetrics {
+    /** Count of products with status='active'. */
+    activeCount: number;
+    /** Count of *active* products effectively out of stock (drafts/archived excluded). */
+    outOfStockCount: number;
+    /** Best seller in the last 30 days, by units sold. Null when no qualifying orders. */
+    bestSeller: {
+        id: string;
+        name: string;
+        unitsSold: number;
+        /** Decimal string (matches the rest of the SDK's price serialization). */
+        revenue: string;
+    } | null;
+}
+/**
+ * Bulk action request for `POST /api/admin/products/bulk`.
+ */
+export interface BulkActionRequest {
+    ids: string[];
+    action: 'activate' | 'archive' | 'delete';
+}
+/**
+ * Bulk action result. Per-id partial success — the server doesn't roll back
+ * on a single failure, so callers should always inspect both arrays.
+ */
+export interface BulkActionResult {
+    succeeded: string[];
+    failed: {
+        id: string;
+        error: string;
+    }[];
+}
+/**
+ * Product detail for ProductForm component.
+ */
+export interface AdminProductDetail {
+    id: string;
+    name: string;
+    slug: string;
+    description: string;
+    price: string;
+    comparePrice?: string;
+    images: string[];
+    videos?: string[];
+    status: string;
+    categoryId?: string;
+    hasVariants: boolean;
+    sku?: string;
+    inventory?: number;
+    trackInventory?: boolean;
+    continueSellingWhenOutOfStock?: boolean;
+    productType?: string;
+    vendor?: string;
+    tags?: string[];
+    metaTitle?: string;
+    metaDescription?: string;
+    metaKeywords?: string[];
+    createdAt: string;
+    updatedAt: string;
+    variants?: AdminProductVariant[];
+}
+/**
+ * Product variant in product detail.
+ */
+export interface AdminProductVariant {
+    id: string;
+    productId: string;
+    sku: string;
+    name: string;
+    price: string | null;
+    inventory: number;
+    image?: string | null;
+    video?: string | null;
+    attributes: Record<string, string>;
+    createdAt: string;
+}
+/**
+ * Customer list item for CustomerTable component.
+ */
+export interface AdminCustomerListItem {
+    id: string;
+    email: string;
+    name?: string;
+    emailVerified?: string | null;
+    createdAt: string;
+    orderCount?: number;
+}
+/**
+ * Customer detail.
+ */
+export interface AdminCustomerDetail {
+    id: string;
+    email: string;
+    name?: string;
+    emailVerified?: string | null;
+    stripeCustomerId?: string | null;
+    createdAt: string;
+    orders?: AdminOrderListItem[];
+    stats?: {
+        totalOrders: number;
+        totalSpent: number;
+    };
+}
+/**
+ * Category list item.
+ */
+export interface AdminCategoryListItem {
+    id: string;
+    name: string;
+    slug: string;
+    description?: string;
+    image?: string;
+    parentId?: string;
+    order: number;
+}
+/**
+ * Stripe connection and tax status data.
+ */
+export interface StripeStatusData {
+    /** Whether a Stripe connected account is configured */
+    connected: boolean;
+    /** The connected account ID (e.g., acct_xxx) */
+    accountId: string | null;
+    /** Stripe Tax configuration status */
+    taxStatus: 'active' | 'pending' | 'not_configured' | 'unknown';
+    /** URL to Stripe Dashboard for this connected account */
+    dashboardUrl: string | null;
+}
+/**
+ * Props for PaymentSettings component.
+ */
+export interface PaymentSettingsProps {
+    className?: string;
+}
+//# sourceMappingURL=types.d.ts.map