@instockng/api-client 1.0.3 → 1.0.4

package/dist/apps/backend/src/lib/discount-code-response.d.ts

@@ -0,0 +1,42 @@
+import type { Prisma } from "@prisma/client";
+export type DiscountCodeDBResponse = Prisma.DiscountCodeGetPayload<{
+    include: {
+        brand: true;
+    };
+}>;
+export declare function formatDiscountCodeResponse(discountCode: DiscountCodeDBResponse): {
+    value: number;
+    minPurchase: number;
+    maxDiscount: number;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt: string;
+    brand: {
+        createdAt: string;
+        updatedAt: string;
+        deletedAt: string;
+        name: string;
+        id: string;
+        slug: string;
+        logoUrl: string | null;
+        siteUrl: string;
+        domain: string;
+        metaPixelId: string | null;
+    };
+    isExpired: boolean;
+    usagePercentage: number;
+    id: string;
+    brandId: string | null;
+    isActive: boolean;
+    code: string;
+    type: string;
+    usageLimit: number | null;
+    usageCount: number;
+    perCustomerLimit: number | null;
+    validFrom: Date;
+    validUntil: Date | null;
+    isAutoApply: boolean;
+    description: string | null;
+    category: string;
+    createdBy: string | null;
+};

package/dist/apps/backend/src/lib/discount-code-response.js

@@ -0,0 +1,19 @@
+import { formatBrandResponse } from "./brand-response";
+import { toNumber } from "./utils";
+export function formatDiscountCodeResponse(discountCode) {
+    const now = new Date();
+    return {
+        ...discountCode,
+        value: toNumber(discountCode.value),
+        minPurchase: discountCode.minPurchase ? toNumber(discountCode.minPurchase) : null,
+        maxDiscount: discountCode.maxDiscount ? toNumber(discountCode.maxDiscount) : null,
+        createdAt: discountCode.createdAt.toISOString(),
+        updatedAt: discountCode.updatedAt.toISOString(),
+        deletedAt: discountCode.deletedAt ? discountCode.deletedAt.toISOString() : null,
+        brand: discountCode.brand ? formatBrandResponse(discountCode.brand) : null,
+        isExpired: discountCode.validUntil ? discountCode.validUntil < now : false,
+        usagePercentage: discountCode.usageLimit
+            ? (discountCode.usageCount / discountCode.usageLimit) * 100
+            : null,
+    };
+}

package/dist/apps/backend/src/lib/discount.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Discount code generation and validation utilities
+ */
+/**
+ * Generate a unique discount code for abandoned cart recovery
+ * Format: CART{RANDOM8} (e.g., CART5A9F3B2E)
+ */
+export declare function generateDiscountCode(): string;
+/**
+ * Calculate discount amount based on cart recovery attempt
+ */
+export declare function getRecoveryDiscountPercentage(attemptNumber: number): number;
+/**
+ * Calculate discount amount in currency
+ */
+export declare function calculateDiscountAmount(subtotal: number, discountPercent: number): number;
+/**
+ * Validate discount code format
+ */
+export declare function isValidDiscountCodeFormat(code: string): boolean;

package/dist/apps/backend/src/lib/discount.js

@@ -0,0 +1,35 @@
+/**
+ * Discount code generation and validation utilities
+ */
+import { RECOVERY_SCHEDULE } from './cart-recovery';
+/**
+ * Generate a unique discount code for abandoned cart recovery
+ * Format: CART{RANDOM8} (e.g., CART5A9F3B2E)
+ */
+export function generateDiscountCode() {
+    const chars = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789'; // Excluding similar characters
+    let code = 'CART';
+    for (let i = 0; i < 8; i++) {
+        code += chars.charAt(Math.floor(Math.random() * chars.length));
+    }
+    return code;
+}
+/**
+ * Calculate discount amount based on cart recovery attempt
+ */
+export function getRecoveryDiscountPercentage(attemptNumber) {
+    const schedule = RECOVERY_SCHEDULE.find((s) => s.attemptNumber === attemptNumber);
+    return schedule ? schedule.discountPercent : 0;
+}
+/**
+ * Calculate discount amount in currency
+ */
+export function calculateDiscountAmount(subtotal, discountPercent) {
+    return Math.round(subtotal * (discountPercent / 100));
+}
+/**
+ * Validate discount code format
+ */
+export function isValidDiscountCodeFormat(code) {
+    return /^CART[A-Z2-9]{8}$/.test(code);
+}

package/dist/apps/backend/src/lib/inventory.d.ts

@@ -0,0 +1,26 @@
+import { PrismaClient, InventoryTransactionType } from '@prisma/client';
+export interface InventoryAdjustment {
+    variantId: string;
+    warehouseId: string;
+    quantity: number;
+    type: InventoryTransactionType;
+    reason?: string;
+    userId?: string;
+    metadata?: any;
+    orderId?: string;
+}
+export declare function adjustInventory(prisma: PrismaClient, adjustment: InventoryAdjustment): Promise<void>;
+export declare function transferInventory(prisma: PrismaClient, params: {
+    variantId: string;
+    fromWarehouseId: string;
+    toWarehouseId: string;
+    quantity: number;
+    userId?: string;
+    reason?: string;
+}): Promise<void>;
+export declare function getTotalInventoryForVariant(prisma: PrismaClient, variantId: string): Promise<number>;
+export declare function checkInventoryAvailability(prisma: PrismaClient, variantId: string, requiredQuantity: number, warehouseId?: string): Promise<{
+    available: boolean;
+    totalInventory: number;
+}>;
+export declare function getLowStockVariants(prisma: PrismaClient, brandId?: string): Promise<any[]>;

package/dist/apps/backend/src/lib/inventory.js

@@ -0,0 +1,160 @@
+export async function adjustInventory(prisma, adjustment) {
+    const { variantId, warehouseId, quantity, type, reason, userId, metadata, orderId } = adjustment;
+    // Get current inventory
+    let inventory = await prisma.warehouseInventory.findUnique({
+        where: {
+            variantId_warehouseId: {
+                variantId,
+                warehouseId,
+            },
+        },
+    });
+    // Create inventory record if it doesn't exist
+    if (!inventory) {
+        inventory = await prisma.warehouseInventory.create({
+            data: {
+                variantId,
+                warehouseId,
+                inventoryCount: 0,
+            },
+        });
+    }
+    // Calculate new balance
+    const balanceAfter = inventory.inventoryCount + quantity;
+    // TODO:Prevent negative inventory (optional - can be configured per variant)
+    if (balanceAfter < 0) {
+        // throw new Error('Insufficient inventory');
+    }
+    // Update inventory count
+    await prisma.warehouseInventory.update({
+        where: {
+            variantId_warehouseId: {
+                variantId,
+                warehouseId,
+            },
+        },
+        data: {
+            inventoryCount: balanceAfter,
+        },
+    });
+    // Create transaction record
+    await prisma.inventoryTransaction.create({
+        data: {
+            variantId,
+            warehouseId,
+            type,
+            quantity,
+            balanceAfter,
+            reason,
+            userId,
+            metadata,
+            orderId,
+        },
+    });
+}
+export async function transferInventory(prisma, params) {
+    const { variantId, fromWarehouseId, toWarehouseId, quantity, userId, reason } = params;
+    if (quantity <= 0) {
+        throw new Error('Transfer quantity must be positive');
+    }
+    const metadata = {
+        transferFrom: fromWarehouseId,
+        transferTo: toWarehouseId,
+        transferQuantity: quantity,
+    };
+    // Use transaction to ensure atomicity
+    await prisma.$transaction(async (tx) => {
+        // Decrement from source warehouse
+        await adjustInventory(tx, {
+            variantId,
+            warehouseId: fromWarehouseId,
+            quantity: -quantity,
+            type: 'transfer_out',
+            reason: reason || `Transfer to ${toWarehouseId}`,
+            userId,
+            metadata,
+        });
+        // Increment to destination warehouse
+        await adjustInventory(tx, {
+            variantId,
+            warehouseId: toWarehouseId,
+            quantity: quantity,
+            type: 'transfer_in',
+            reason: reason || `Transfer from ${fromWarehouseId}`,
+            userId,
+            metadata,
+        });
+    });
+}
+export async function getTotalInventoryForVariant(prisma, variantId) {
+    const inventories = await prisma.warehouseInventory.findMany({
+        where: { variantId },
+    });
+    return inventories.reduce((sum, inv) => sum + inv.inventoryCount, 0);
+}
+export async function checkInventoryAvailability(prisma, variantId, requiredQuantity, warehouseId) {
+    let totalInventory = 0;
+    if (warehouseId) {
+        // Check specific warehouse
+        const inventory = await prisma.warehouseInventory.findUnique({
+            where: {
+                variantId_warehouseId: {
+                    variantId,
+                    warehouseId,
+                },
+            },
+        });
+        totalInventory = inventory?.inventoryCount || 0;
+    }
+    else {
+        // Check total across all warehouses
+        totalInventory = await getTotalInventoryForVariant(prisma, variantId);
+    }
+    return {
+        available: totalInventory >= requiredQuantity,
+        totalInventory,
+    };
+}
+export async function getLowStockVariants(prisma, brandId) {
+    const where = {
+        trackInventory: true,
+        lowStockThreshold: { not: null },
+        deletedAt: null,
+    };
+    if (brandId) {
+        where.product = { brandId };
+    }
+    const variants = await prisma.productVariant.findMany({
+        where,
+        include: {
+            product: {
+                include: { brand: true },
+            },
+            warehouseInventories: {
+                include: { warehouse: true },
+            },
+        },
+    });
+    // Filter variants where total inventory is below threshold
+    const lowStockVariants = variants.filter((variant) => {
+        const totalInventory = variant.warehouseInventories.reduce((sum, inv) => sum + inv.inventoryCount, 0);
+        return totalInventory < (variant.lowStockThreshold || 0);
+    });
+    return lowStockVariants.map((variant) => {
+        const totalInventory = variant.warehouseInventories.reduce((sum, inv) => sum + inv.inventoryCount, 0);
+        return {
+            id: variant.id,
+            sku: variant.sku,
+            productName: variant.product.name,
+            name: variant.name,
+            brandName: variant.product.brand.name,
+            totalInventory,
+            threshold: variant.lowStockThreshold,
+            warehouses: variant.warehouseInventories.map((inv) => ({
+                warehouseId: inv.warehouseId,
+                warehouseName: inv.warehouse.name,
+                inventory: inv.inventoryCount,
+            })),
+        };
+    });
+}

package/dist/apps/backend/src/lib/meta-capi.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Meta Conversions API (CAPI) Service
+ *
+ * Sends server-side events to Meta for conversion tracking.
+ * Used alongside browser pixel for maximum reliability and iOS 14+ compliance.
+ */
+export type MetaEventName = 'AddToCart' | 'InitiateCheckout' | 'Purchase' | 'ViewContent';
+export interface MetaCapiQueueMessage {
+    pixelId: string;
+    eventName: MetaEventName;
+    eventId: string;
+    eventTime: number;
+    eventSourceUrl: string;
+    userData: {
+        email?: string;
+        phone?: string;
+        firstName?: string;
+        lastName?: string;
+        city?: string;
+        state?: string;
+        country?: string;
+        zipCode?: string;
+        clientIpAddress?: string;
+        clientUserAgent?: string;
+        fbc?: string;
+        fbp?: string;
+    };
+    customData: {
+        value?: number;
+        currency?: string;
+        contentIds?: string[];
+        contentType?: string;
+        numItems?: number;
+        contentName?: string;
+    };
+}
+/**
+ * Send event to Meta Conversions API
+ *
+ * @param accessToken - Meta Access Token (from Cloudflare secrets)
+ * @param message - Queue message with event data
+ */
+export declare function sendMetaCapiEvent(accessToken: string, message: MetaCapiQueueMessage): Promise<void>;
+/**
+ * Helper to generate event ID for deduplication
+ * Uses existing DB IDs to ensure same event from browser and server have same ID
+ */
+export declare function generateEventId(type: 'cart' | 'order', id: string, suffix?: string): string;

package/dist/apps/backend/src/lib/meta-capi.js

@@ -0,0 +1,120 @@
+/**
+ * Meta Conversions API (CAPI) Service
+ *
+ * Sends server-side events to Meta for conversion tracking.
+ * Used alongside browser pixel for maximum reliability and iOS 14+ compliance.
+ */
+import crypto from 'crypto';
+/**
+ * Hash data with SHA256 for Meta CAPI
+ * Meta requires PII to be hashed before sending
+ */
+function hashData(data) {
+    // Normalize: lowercase and trim whitespace
+    const normalized = data.toLowerCase().trim();
+    return crypto.createHash('sha256').update(normalized).digest('hex');
+}
+/**
+ * Normalize phone number to E.164 format
+ * Meta requires: country code + digits only (no spaces, dashes, etc.)
+ */
+function normalizePhone(phone) {
+    // Remove all non-digit characters
+    let digits = phone.replace(/\D/g, '');
+    // If starts with 0, assume Nigerian number and add +234
+    if (digits.startsWith('0')) {
+        digits = '234' + digits.slice(1);
+    }
+    // If doesn't start with country code, assume Nigerian
+    if (!digits.startsWith('234')) {
+        digits = '234' + digits;
+    }
+    return digits;
+}
+/**
+ * Send event to Meta Conversions API
+ *
+ * @param accessToken - Meta Access Token (from Cloudflare secrets)
+ * @param message - Queue message with event data
+ */
+export async function sendMetaCapiEvent(accessToken, message) {
+    const { pixelId, eventName, eventId, eventTime, eventSourceUrl, userData, customData } = message;
+    // Build user_data with hashed PII
+    const user_data = {
+        client_ip_address: userData.clientIpAddress,
+        client_user_agent: userData.clientUserAgent,
+        fbc: userData.fbc,
+        fbp: userData.fbp,
+    };
+    // Hash email if provided
+    if (userData.email) {
+        user_data.em = [hashData(userData.email)];
+    }
+    // Hash phone if provided
+    if (userData.phone) {
+        const normalized = normalizePhone(userData.phone);
+        user_data.ph = [hashData(normalized)];
+    }
+    // Hash name if provided
+    if (userData.firstName) {
+        user_data.fn = [hashData(userData.firstName)];
+    }
+    if (userData.lastName) {
+        user_data.ln = [hashData(userData.lastName)];
+    }
+    // Hash location if provided
+    if (userData.city) {
+        user_data.ct = [hashData(userData.city)];
+    }
+    if (userData.state) {
+        user_data.st = [hashData(userData.state)];
+    }
+    if (userData.zipCode) {
+        user_data.zp = [hashData(userData.zipCode)];
+    }
+    if (userData.country) {
+        user_data.country = [hashData(userData.country)];
+    }
+    // Build event
+    const event = {
+        event_name: eventName,
+        event_time: eventTime,
+        event_id: eventId,
+        event_source_url: eventSourceUrl,
+        action_source: 'website',
+        user_data,
+        custom_data: customData,
+    };
+    // Send to Meta CAPI
+    const url = `https://graph.facebook.com/v21.0/${pixelId}/events`;
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+            data: [event],
+            access_token: accessToken,
+        }),
+    });
+    if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`Meta CAPI error: ${response.status} ${error}`);
+    }
+    const result = await response.json();
+    // Log if Meta returned any errors
+    if (result.events_received !== 1) {
+        console.error('[Meta CAPI] Event not received:', result);
+        throw new Error('Meta CAPI did not receive event');
+    }
+}
+/**
+ * Helper to generate event ID for deduplication
+ * Uses existing DB IDs to ensure same event from browser and server have same ID
+ */
+export function generateEventId(type, id, suffix) {
+    if (type === 'order') {
+        return `order_${id}`;
+    }
+    return suffix ? `cart_${id}_${suffix}` : `cart_${id}`;
+}

package/dist/apps/backend/src/lib/openapi.d.ts

@@ -0,0 +1,36 @@
+import { OpenAPIHono } from '@hono/zod-openapi';
+import { AppContext } from '../types';
+/**
+ * Create a new OpenAPI-enabled Hono app instance
+ * This extends the standard Hono with OpenAPI documentation capabilities
+ */
+export declare function createOpenAPIApp(): OpenAPIHono<AppContext, {}, "/">;
+/**
+ * OpenAPI documentation configuration
+ */
+export declare const openapiConfig: {
+    openapi: string;
+    info: {
+        title: string;
+        version: string;
+        description: string;
+    };
+    servers: {
+        url: string;
+        description: string;
+    }[];
+    tags: {
+        name: string;
+        description: string;
+    }[];
+    components: {
+        securitySchemes: {
+            clerkAuth: {
+                type: string;
+                scheme: string;
+                bearerFormat: string;
+                description: string;
+            };
+        };
+    };
+};

package/dist/apps/backend/src/lib/openapi.js

@@ -0,0 +1,69 @@
+import { OpenAPIHono } from '@hono/zod-openapi';
+/**
+ * Create a new OpenAPI-enabled Hono app instance
+ * This extends the standard Hono with OpenAPI documentation capabilities
+ */
+export function createOpenAPIApp() {
+    return new OpenAPIHono({
+        defaultHook: (result, c) => {
+            if (!result.success) {
+                return c.json({
+                    success: false,
+                    error: {
+                        code: 'VALIDATION_ERROR',
+                        message: 'Request validation failed',
+                        details: 'error' in result ? result.error.flatten() : undefined,
+                    },
+                }, 400);
+            }
+        },
+    });
+}
+/**
+ * OpenAPI documentation configuration
+ */
+export const openapiConfig = {
+    openapi: '3.1.0',
+    info: {
+        title: 'OMS API',
+        version: '1.0.0',
+        description: 'Order Management System API - A comprehensive e-commerce backend',
+    },
+    servers: [
+        {
+            url: 'https://api.example.com',
+            description: 'Production server',
+        },
+        {
+            url: 'http://localhost:8787',
+            description: 'Local development server',
+        },
+    ],
+    tags: [
+        { name: 'Public - Orders', description: 'Public order tracking endpoints' },
+        { name: 'Public - Products', description: 'Public product catalog endpoints' },
+        { name: 'Public - Carts', description: 'Public shopping cart endpoints' },
+        { name: 'Public - Delivery Zones', description: 'Public delivery zone endpoints' },
+        { name: 'Admin - Orders', description: 'Admin order management endpoints' },
+        { name: 'Admin - Products', description: 'Admin product management endpoints' },
+        { name: 'Admin - Brands', description: 'Admin brand management endpoints' },
+        { name: 'Admin - Variants', description: 'Admin variant management endpoints' },
+        { name: 'Admin - Warehouses', description: 'Admin warehouse management endpoints' },
+        { name: 'Admin - Inventory', description: 'Admin inventory management endpoints' },
+        { name: 'Admin - Customers', description: 'Admin customer management endpoints' },
+        { name: 'Admin - Stats', description: 'Admin statistics endpoints' },
+        { name: 'Admin - Abandoned Carts', description: 'Admin abandoned cart management endpoints' },
+        { name: 'Admin - Discount Codes', description: 'Admin discount code management endpoints' },
+        { name: 'Admin - Delivery Zones', description: 'Admin delivery zone management endpoints' },
+    ],
+    components: {
+        securitySchemes: {
+            clerkAuth: {
+                type: 'http',
+                scheme: 'bearer',
+                bearerFormat: 'JWT',
+                description: 'Clerk JWT token for admin authentication',
+            },
+        },
+    },
+};