fieldpineApi.ts

Go to the documentation of this file.

// Server-side Fieldpine API helper
// Handles all communication with Fieldpine APIs securely
//
// Fieldpine provides multiple API interfaces:
// 
// 1. OpenAPI2 - RESTful JSON API for general retail operations
//    - URL: /OpenApi2/{Resource}
//    - Methods: GET, POST, PUT, DELETE
//    - Auth: X-Api-Key header or FieldpineApiKey cookie
//
// 2. eLink API (BUCK/DATI) - Comprehensive retail data API
//    - BUCK (GET/Read): /GNAP/j/buck?3={endpoint}&9={filters}
//    - DATI (POST/Write): /GNAP/j/buck (POST DATI XML in body)
//    - Auth: FieldpineApiKey cookie
//    - See: /docs/elink-api-reference.md for complete endpoint list
//
// 3. GNAP Protocol - Generic network application protocol
//    - Base: /GNAP/{method}/{endpoint}
//    - Format prefixes: j (JSON numeric), J (JSON named), M (metadata)
//
// This class provides unified access to all Fieldpine APIs with:
// - Authentication management (API key / cookie)
// - Rate limiting
// - Error handling
// - Type-safe method wrappers
 
// ========================================
// Fieldpine Constants & Helpers
// Extracted from Fieldpine's reference implementation
// ========================================
 
// Field Number Constants
export const FIELDPINE_FIELDS = {
  // Product fields
  PRODUCT_ID: 'f100',
  PRODUCT_NAME: 'f101',
  PRODUCT_PLU: 'f105',
  PRODUCT_BARCODE: 'f501',
  
  // Customer fields
  CUSTOMER_ID: 'f100',
  CUSTOMER_NAME: 'f101',
  CUSTOMER_ACCOUNT_LINK: 'f132',
  
  // Account fields
  ACCOUNT_ID: 'f100',
  ACCOUNT_NAME: 'f101',
  ACCOUNT_CREDIT_LIMIT: 'f103',
  ACCOUNT_FLOOR_LIMIT: 'f105',
  ACCOUNT_BALANCE: 'f114',
  ACCOUNT_RETIRED: 'f147',
  ACCOUNT_EMAIL: 'f1100',
  ACCOUNT_RECEIPT_FORMAT: 'f1105',
  ACCOUNT_EXTERNAL_ID: 'f184',
  
  // Sale fields
  SALE_DATETIME: 'f110',
  SALE_STORE_ID: 'f120',
  
  // Location fields
  LOCATION_ID: 'f100',
  LOCATION_NAME: 'f101',
  
  // Staff fields
  STAFF_ID: 'f100',
  STAFF_NAME: 'f101',
} as const;
 
// Field predicate operators
export const FIELD_OPERATORS = {
  EQUALS: '0',
  NOT_EQUALS: '1',
  GREATER_THAN: '4',
  GREATER_THAN_EQUAL: '5',
  CONTAINS: '8',        // Default for text search
  LIKE: 'like',
  IN: 'in',
  REGEX: 'r',
} as const;
 
// Goods In History transaction types
export const GIH_TRANSACTION_TYPES = {
  5: 'Stocktake Point',
  100: 'Received',
  102: 'Transfer Received',
  200: 'Supplier Return',
  201: 'Write Off',
  202: 'Shrinkage',
  203: 'Transfer Out',
  204: 'Stocktake Adjustment',
  210: 'Sales',
} as const;
 
/**
 * Escape XML content for safe inclusion in DATI packets
 */
export function escapeXml(value: string | number): string {
  return String(value)
    .replace(/&/g, '&')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;')
    .replace(/"/g, '&quot;')
    .replace(/'/g, '&apos;');
}
 
/**
 * Build a field predicate string for BUCK API queries
 * @example buildFieldPredicate('f501', '0', '123456') // "f501,0,123456"
 */
export function buildFieldPredicate(fieldNum: string, operator: string, value: string | number): string {
  return `${fieldNum},${operator},${value}`;
}
 
/**
 * Convert GIH transaction type code to readable string
 */
export function gihTypeToString(typeCode: number): string {
  return GIH_TRANSACTION_TYPES[typeCode as keyof typeof GIH_TRANSACTION_TYPES] || `Type ${typeCode}`;
}
 
interface RateLimitEntry {
  count: number;
  resetTime: number;
}
 
// Simple in-memory rate limiting (use Redis in production)
const rateLimitMap = new Map<string, RateLimitEntry>();
 
export class FieldpineServerApi {
  private baseUrl: string;
  private retailerId: string;
  private apiKey: string;
 
  constructor(baseUrl?: string, apiKey?: string) {
    // Allow override via constructor (for session-based routing)
    this.baseUrl = baseUrl || process.env.FIELDPINE_BASE_URL || "https://iig.cwanz.online";
    this.retailerId = process.env.NEXT_PUBLIC_FIELDPINE_RETAILER_ID || "CWA";
    this.apiKey = apiKey || process.env.FIELDPINE_API_KEY || process.env.FIELDPINE_AUTH_HEADER || "";
    
    if (!this.apiKey) {
      console.warn("FIELDPINE_API_KEY not set - using store-specific authentication");
    }
  }
  
  /**
   * Get base URL (useful for debugging)
   */
  getBaseUrl(): string {
    return this.baseUrl;
  }
 
  // Rate limiting check
  private checkRateLimit(clientId: string, limit: number = 100, windowMs: number = 60000): boolean {
    const now = Date.now();
    const entry = rateLimitMap.get(clientId);
    
    if (!entry || now > entry.resetTime) {
      rateLimitMap.set(clientId, { count: 1, resetTime: now + windowMs });
      return true;
    }
    
    if (entry.count >= limit) {
      return false;
    }
    
    entry.count++;
    return true;
  }
 
  // Generic API call method with cookie support
  public async apiCall(endpoint: string, options: {
    method?: string;
    body?: any;
    params?: Record<string, any>;
    useOpenApi?: boolean;
    cookie?: string;
  } = {}): Promise<any> {
    const { method = "GET", body, params, useOpenApi = true, cookie } = options;
    
    // Build URL
    const apiBase = useOpenApi 
      ? `${this.baseUrl}/OpenApi2`
      : this.baseUrl;
    let url = `${apiBase}${endpoint}`;
    
    if (params) {
      const query = new URLSearchParams(params as Record<string, string>).toString();
      url += (url.includes("?") ? "&" : "?") + query;
    }
    
    console.log('Making Fieldpine API call to:', url);
 
    // Headers
    const headers: Record<string, string> = {
      "Accept": "application/json",
      "User-Agent": "EverydayPOS/1.0"
    };
    
    // Add authentication - prefer cookie over API key
    if (cookie) {
      headers["Cookie"] = `FieldpineApiKey=${cookie}`;
    } else if (this.apiKey && useOpenApi) {
      headers["X-Api-Key"] = this.apiKey;
    }
    
    if (body) {
      headers["Content-Type"] = "application/json";
    }
 
    try {
      const response = await fetch(url, {
        method,
        headers,
        body: body ? JSON.stringify(body) : undefined,
      });
 
      if (!response.ok) {
        throw new Error(`Fieldpine API error: ${response.status} ${response.statusText}`);
      }
 
      return await response.json();
    } catch (error) {
      console.error(`Fieldpine API call failed:`, { url, error });
      throw error;
    }
  }
 
  /**
   * Call Fieldpine BUCK (eLink) API
   * 
   * eLink is Fieldpine's comprehensive retail API for reading/writing data.
   * BUCK endpoints are used for GET operations.
   * 
   * @param paramsOrEndpoint - Either:
   *   - Object with query params: {"3": "retailmax.elink.products", "9": "f501,0,barcode"}
   *   - String endpoint: "/buck?3=retailmax.elink.products&9=f501,0,barcode"
   * @param cookie - API key for authentication (passed as FieldpineApiKey cookie)
   * 
   * Common parameters:
   * - "3" or "8": eLink endpoint name (e.g., "retailmax.elink.products")
   * - "8": Limit (max records)
   * - "9": Field predicate/filter (format: "f{fieldnum},{operator},{value}")
   * - "10": Field selection (which fields to return)
   * - "13": Dimensions for grouping
   * - "15": Format options
   * - "16": Response detail level (4 = detailed)
   * 
   * Field operators:
   * - 0: Equals
   * - 4: Greater than
   * - 5: Greater than or equal
   * - like: Pattern match
   * - in: In list
   * 
   * @example
   * // Get products by barcode
   * buckApiCall({"3": "retailmax.elink.products", "10": "199", "9": "f501,0,123456"}, apiKey)
   * 
   * // Get sales totals with string endpoint
   * buckApiCall("/buck?3=retailmax.elink.sale.totals&9=f110,4,today", apiKey)
   * 
   * @see /docs/elink-api-reference.md for full endpoint list
   */
  // BUCK API call method for alternative API access
  async buckApiCall(
    paramsOrEndpoint: Record<string, string | string[]> | string, 
    cookie?: string,
    baseUrlOverride?: string
  ): Promise<any> {
    const baseUrl = baseUrlOverride || this.baseUrl;
    let url: URL;
    
    if (typeof paramsOrEndpoint === 'string') {
      // If given a string starting with /, assume it's a relative path
      if (paramsOrEndpoint.startsWith('/')) {
        // Already has path, just prepend GNAP/j if not present
        if (paramsOrEndpoint.includes('/GNAP/j/')) {
          url = new URL(paramsOrEndpoint, baseUrl);
        } else if (paramsOrEndpoint.startsWith('/buck')) {
          url = new URL(`/GNAP/j${paramsOrEndpoint}`, baseUrl);
        } else {
          url = new URL(paramsOrEndpoint, baseUrl);
        }
      } else {
        // Relative endpoint without /, add full path
        url = new URL(`/GNAP/j/buck?${paramsOrEndpoint}`, baseUrl);
      }
    } else {
      // Build URL from params Record
      url = new URL('/GNAP/j/buck', baseUrl);
      
      // Add all parameters to URL
      Object.entries(paramsOrEndpoint).forEach(([key, value]) => {
        if (Array.isArray(value)) {
          value.forEach(v => url.searchParams.append(key, v));
        } else {
          url.searchParams.append(key, value);
        }
      });
    }
 
    const headers: Record<string, string> = {
      'Accept': 'application/json',
    };
 
    if (cookie) {
      headers['Cookie'] = `FieldpineApiKey=${cookie}`;
    }
 
    try {
      const response = await fetch(url.toString(), {
        method: 'GET',
        headers,
      });
 
      if (!response.ok) {
        // On 403 Forbidden, the API key has likely expired
        if (response.status === 403) {
          throw new Error(`BUCK API error: 403 Forbidden - API key expired or invalid. Please refresh the page and log in again.`);
        }
        throw new Error(`BUCK API error: ${response.status} ${response.statusText}`);
      }
 
      return await response.json();
    } catch (error) {
      console.error(`BUCK API call failed:`, { url: url.toString(), error });
      throw error;
    }
  }
 
  /**
   * Call Fieldpine DATI API
   * 
   * DATI is used for write operations (create, update, delete).
   * Sends XML data to modify records in Fieldpine.
   * 
   * @param xml - XML payload (DATI format)
   * @param cookie - API key for authentication
   * 
   * @example
   * ```xml
   * <DATI>
   *   <f8_s>retailmax.elink.customers.edit</f8_s>
   *   <f11_B>E</f11_B>
   *   <f100_E>12345</f100_E>
   *   <f101_s>John Smith</f101_s>
   * </DATI>
   * ```
   */
  async datiApiCall(xml: string, cookie?: string): Promise<{ success: boolean; data?: any; error?: string }> {
    const url = new URL('/GNAP/j/buck', this.baseUrl);
 
    const headers: Record<string, string> = {
      'Content-Type': 'application/xml',
      'Accept': 'application/json',
    };
 
    if (cookie) {
      headers['Cookie'] = `FieldpineApiKey=${cookie}`;
    }
 
    try {
      const response = await fetch(url.toString(), {
        method: 'POST',
        headers,
        body: xml,
      });
 
      if (!response.ok) {
        const errorText = await response.text();
        console.error(`DATI API error: ${response.status}`, errorText);
        return {
          success: false,
          error: `DATI API error: ${response.status} ${response.statusText}`,
        };
      }
 
      const data = await response.json();
      
      // Check if the response indicates success
      if (data && (data.error || data.Status === 'Error')) {
        return {
          success: false,
          error: data.error || data.Message || 'DATI operation failed',
        };
      }
 
      return {
        success: true,
        data,
      };
    } catch (error: any) {
      console.error(`DATI API call failed:`, error);
      return {
        success: false,
        error: error.message || 'DATI API call failed',
      };
    }
  }
 
  // Authentication using correct CWA format
  async authenticate(username: string, password: string, storeUrl?: string): Promise<{ success: boolean; data?: any; error?: string; cookie?: string }> {
    try {
      // Use provided store URL or fall back to default baseUrl
      const authUrl = storeUrl || this.baseUrl;
      console.log(`Attempting CWA authentication for user: ${username} at ${authUrl}`);
      
      // Demo credentials for testing
      if ((username === 'demo' && password === 'demo') ||
          (username === 'admin' && password === 'admin')) {
        console.log('Demo credentials accepted');
        return {
          success: true,
          data: {
            valid: 1,
            authenticated: true,
            user: username,
            demo: true,
            HomePage: '/pages/home'
          }
        };
      }
      
      // Use correct CWA login endpoint format
      const loginUrl = `${authUrl}/cwlogin`;
      
      const loginData = {
        Name: username,
        PassPlain: password,
        Realm: 'site'
      };
      
      console.log(`Trying CWA auth at: ${loginUrl}`);
      
      const response = await fetch(loginUrl, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Accept': 'application/json',
          'User-Agent': 'EverydayPOS/1.0'
        },
        body: JSON.stringify(loginData)
      });
      
      if (!response.ok) {
        console.log(`Auth response failed with status: ${response.status}`);
        return { 
          success: false, 
          error: `Authentication failed: Server returned ${response.status}` 
        };
      }
      
      // Extract the FieldpineApiKey cookie from response headers
      const setCookieHeader = response.headers.get('set-cookie');
      let fieldpineApiKey = '';
      
      if (setCookieHeader) {
        const cookieMatch = setCookieHeader.match(/FieldpineApiKey=([^;]+)/);
        if (cookieMatch) {
          fieldpineApiKey = cookieMatch[1];
          console.log('Extracted FieldpineApiKey from cookie');
        }
      }
      
      const result = await response.json();
      console.log(`Auth response:`, result);
      
      // Check for successful login using CWA format - also extract ApiKey from response
      if (result.data && result.data.valid === 1) {
        // Use ApiKey from response data if no cookie was found
        if (!fieldpineApiKey && result.data.ApiKey) {
          fieldpineApiKey = result.data.ApiKey;
          console.log('Using ApiKey from response data');
        }
        
        return { 
          success: true, 
          data: {
            valid: 1,
            authenticated: true, 
            user: username,
            HomePage: result.data.HomePage || '/pages/home',
            ApiKey: result.data.ApiKey,
            RmSystem: result.data.RmSystem,
            ...result.data
          },
          cookie: fieldpineApiKey
        };
      }
      
      return { 
        success: false, 
        error: `Invalid credentials` 
      };
      
    } catch (error) {
      console.error('CWA Authentication error:', error);
      return { 
        success: false, 
        error: `Authentication service error: ${error instanceof Error ? error.message : 'Unknown error'}` 
      };
    }
  }
 
  // Product operations with optional cookie authentication
  async getProducts(params: { search?: string; plu?: string; barcode?: string; limit?: number } = {}, cookie?: string): Promise<any> {
    try {
      // Map 'search' to 'EnglishQuery' for OpenAPI compatibility
      const apiParams: Record<string, string> = {};
      if (params.search) apiParams.EnglishQuery = params.search;
      if (params.plu) apiParams.plu = params.plu;
      if (params.barcode) apiParams.filter = `barcode=${params.barcode}`;
      if (params.limit) apiParams.limit = params.limit.toString();
      
      // Try main API first
      return await this.apiCall("/Products", { params: apiParams, cookie });
    } catch (error) {
      console.log('Fieldpine API call failed:', { url: `${this.baseUrl}/OpenApi2/Products`, error });
    }
 
    try {
      // Try BUCK API fallback with consistent method
      const searchTerm = params.search || params.plu || params.barcode || '';
      let buckParams: Record<string, string> = {
        "3": "retailmax.elink.products.list",
        "8": (params.limit || 30).toString(),
        "9": `f101,8,${encodeURIComponent(searchTerm)}`  // f101 = Name/Description field
      };
      
      console.log('Trying BUCK API fallback:', `${this.baseUrl}/GNAP/j/buck?${Object.entries(buckParams).map(([k, v]) => `${k}=${v}`).join('&')}`);
      
      const buckResponse = await this.buckApiCall(buckParams, cookie);
      console.log('BUCK API Response:', JSON.stringify(buckResponse, null, 2));
      
      // Handle BUCK response format
      if (buckResponse && buckResponse.RootType === "ARAY") {
        if (buckResponse.DATS && Array.isArray(buckResponse.DATS)) {
          const products = buckResponse.DATS.map((item: any) => ({
            pid: item.f100,
            name: item.f101 || item.f500,
            barcode: item.f105,
            sellprice: item.f103,
            stocklevel: item.f106 || 0,
            category: item.f106
          }));
          
          console.log('Products API Response:', { data: products });
          console.log('Final product data:', JSON.stringify(products, null, 2));
          return { data: products };
        } else {
          // Empty result from BUCK API
          console.log('BUCK API returned empty result');
          console.log('Products API Response:', { data: [] });
          console.log('Final product data:', []);
          return { data: [] };
        }
      }
      
      console.log('BUCK response does not match expected format, returning raw result');
      console.log('Products API Response:', buckResponse);
      console.log('Final product data:', []);
      return { data: [] };
    } catch (buckError) {
      console.log('BUCK API also failed, returning empty result');
      console.log('Final product data:', []);
      return { data: [] };
    }
  }
 
  async getProductById(id: string, cookie?: string): Promise<any> {
    return this.apiCall(`/Product/${id}`, { cookie });
  }
 
  // Sales operations with optional cookie authentication
  async createSale(saleData: any, cookie?: string, storeUrl?: string): Promise<any> {
    const baseUrl = storeUrl || this.baseUrl;
    const url = new URL('/OpenApi2/Sales', baseUrl);
    
    const headers: Record<string, string> = {
      'Content-Type': 'application/json',
      'Accept': 'application/json',
      'X-Fieldpine-CallerHandling': 'audit'
    };
 
    if (cookie) {
      headers['Cookie'] = `FieldpineApiKey=${cookie}`;
    }
 
    console.log('Making Fieldpine Sale POST to:', url.toString());
    console.log('Sale payload:', JSON.stringify(saleData, null, 2));
 
    const response = await fetch(url.toString(), {
      method: 'POST',
      headers,
      body: JSON.stringify(saleData)
    });
 
    if (!response.ok) {
      const errorText = await response.text();
      console.error('Sale creation failed:', response.status, errorText);
      throw new Error(`Fieldpine API error: ${response.status} ${response.statusText}`);
    }
 
    return await response.json();
  }
 
  // Location operations with optional cookie authentication
  async getLocations(params: { limit?: number } = {}, cookie?: string): Promise<any> {
    try {
      return await this.apiCall("/Locations", { params, cookie });
    } catch (error) {
      console.warn('Location API not available, returning empty result');
      return { data: [] };
    }
  }
 
  // Supplier operations with optional cookie authentication
  async getSuppliers(params: { search?: string; limit?: number } = {}, cookie?: string): Promise<any> {
    try {
      // Try BUCK API first with format that works
      let buckParams: Record<string, string> = {
        "3": "retailmax.elink.suppliers",
        "16": "4",
        "20": (params.limit || 100).toString(),
        "99": Math.random().toString()
      };
      
      const buckResponse = await this.buckApiCall(buckParams, cookie);
      console.log('BUCK Suppliers API Response:', buckResponse);
      
      // Handle BUCK response format
      if (buckResponse && buckResponse.RootType === "ARAY" && buckResponse.DATS && Array.isArray(buckResponse.DATS)) {
        return {
          data: buckResponse.DATS
        };
      } else {
        console.log('BUCK suppliers response contains no data or wrong format, trying main API');
      }
    } catch (buckError) {
      console.warn('BUCK suppliers API failed, trying main API:', buckError);
    }
 
    try {
      // Fallback to main API - but clean search parameter first
      const cleanParams = { ...params };
      if (cleanParams.search === 'undefined' || !cleanParams.search?.trim()) {
        delete cleanParams.search;
      }
      return await this.apiCall("/Supplier", { params: cleanParams, cookie });
    } catch (error) {
      console.warn('Supplier API not available, returning empty result');
      return { data: [] };
    }
  }
 
  // Customer operations with optional cookie authentication
  async getCustomers(params: { search?: string; limit?: number } = {}, cookie?: string): Promise<any> {
    try {
      // Try BUCK API first with format that works
      let buckParams: Record<string, string> = {
        "3": "retailmax.elink.customers",
        "16": "4",
        "20": (params.limit || 100).toString(),
        "99": Math.random().toString()
      };
      
      const buckResponse = await this.buckApiCall(buckParams, cookie);
      console.log('BUCK Customers API Response:', buckResponse);
      
      // Handle BUCK response format
      if (buckResponse && buckResponse.RootType === "ARAY" && buckResponse.DATS && Array.isArray(buckResponse.DATS)) {
        return {
          data: buckResponse.DATS
        };
      } else {
        console.log('BUCK customers response contains no data or wrong format, trying main API');
      }
    } catch (buckError) {
      console.warn('BUCK customers API failed, trying main API:', buckError);
    }
 
    try {
      // Fallback to main API - but clean search parameter first
      const cleanParams = { ...params };
      if (cleanParams.search === 'undefined' || !cleanParams.search?.trim()) {
        delete cleanParams.search;
      }
      return await this.apiCall("/Customer", { params: cleanParams, cookie });
    } catch (error) {
      console.warn('Customer API not available, returning empty result');
      return { data: [] };
    }
  }
 
  async getCustomerById(customerId: string | number, cookie?: string): Promise<any> {
    try {
      // Use BUCK API to get a single customer with account details
      let buckParams: Record<string, string> = {
        "3": "retailmax.elink.customers",
        "9": `f100,0,${customerId}`,
        "10": "132,1130,153,154,1131,1132", // Additional fields including account name fields
        "99": Math.random().toString()
      };
      
      const buckResponse = await this.buckApiCall(buckParams, cookie);
      console.log('BUCK Customer By ID API Response:', buckResponse);
      
      // Handle BUCK response format
      if (buckResponse && buckResponse.DATS && Array.isArray(buckResponse.DATS)) {
        const customerData = buckResponse.DATS[0];
        
        // If customer has an account link (f132), fetch the account details
        if (customerData && customerData.f132 && customerData.f132 > 0) {
          try {
            const accountParams: Record<string, string> = {
              "3": "retailmax.elink.accounts",
              "9": `f100,0,${customerData.f132}`,
              "99": Math.random().toString()
            };
            
            const accountResponse = await this.buckApiCall(accountParams, cookie);
            console.log('Account details response:', accountResponse);
            
            if (accountResponse && accountResponse.DATS && accountResponse.DATS[0]) {
              // Add account name to customer data
              customerData.accountName = accountResponse.DATS[0].f101;
              customerData.accountBalance = accountResponse.DATS[0].f114 || 0;
            }
          } catch (error) {
            console.error('Failed to fetch account details:', error);
          }
        }
        
        return buckResponse.DATS;
      }
      
      return [];
    } catch (error) {
      console.error('Failed to fetch customer by ID:', error);
      return [];
    }
  }
 
  // Rate limit check for client requests
  checkClientRateLimit(clientId: string): boolean {
    return this.checkRateLimit(clientId, 100, 60000); // 100 requests per minute
  }
 
  // ========================================
  // eLink API Helper Methods
  // ========================================
  // Based on official Fieldpine eLink API documentation
  // See: /docs/elink-api-reference.md
 
  /**
   * Get product stock levels
   * eLink: retailmax.elink.product.stocklevels
   */
  async getProductStockLevels(productId: string, cookie?: string): Promise<any> {
    return this.buckApiCall({
      "3": "retailmax.elink.product.stocklevels",
      "9": `f100,0,${productId}`
    }, cookie);
  }
 
  /**
   * Get all product stock levels (no product filter)
   * eLink: retailmax.elink.product.stocklevels
   * Returns DATS array with Pid, Description, Qty, Locid, LocationName, DispatchWait
   */
  async getAllProductStockLevels(cookie?: string): Promise<any> {
    return this.buckApiCall({
      "3": "retailmax.elink.product.stocklevels",
      "100": "2" // SelectionRange: specific
    }, cookie);
  }
 
  /**
   * Get product media/images
   * eLink: retailmax.elink.media.list
   */
  async getProductMedia(params: { productId?: string; limit?: number } = {}, cookie?: string): Promise<any> {
    const buckParams: Record<string, string> = {
      "3": "retailmax.elink.media.list"
    };
    
    if (params.productId) buckParams["9"] = `f100,0,${params.productId}`;
    if (params.limit) buckParams["8"] = params.limit.toString();
    
    return this.buckApiCall(buckParams, cookie);
  }
 
  /**
   * Get loyalty card details
   * eLink: retailmax.elink.cardinquiry
   */
  async getCardInquiry(cardNumber: string, cookie?: string): Promise<any> {
    return this.buckApiCall({
      "3": "retailmax.elink.cardinquiry",
      "9": `f100,0,${cardNumber}`
    }, cookie);
  }
 
  /**
   * Get staff list
   * eLink: retailmax.elink.staff.list
   */
  async getStaffList(params: { limit?: number; search?: string } = {}, cookie?: string): Promise<any> {
    const buckParams: Record<string, string> = {
      "3": "retailmax.elink.staff.list",
      "16": "4"
    };
    
    if (params.limit) buckParams["8"] = params.limit.toString();
    if (params.search) buckParams["9"] = `f101,like,${params.search}`;
    
    return this.buckApiCall(buckParams, cookie);
  }
 
  /**
   * Get staff usage/activity
   * eLink: retailmax.elink.staff.used.list
   */
  async getStaffUsage(cookie?: string): Promise<any> {
    return this.buckApiCall({
      "3": "retailmax.elink.staff.used.list"
    }, cookie);
  }
 
  /**
   * Get department statistics for today
   * eLink: retailmax.elink.stats.today.department
   */
  async getDepartmentStatsToday(cookie?: string): Promise<any> {
    return this.buckApiCall({
      "3": "retailmax.elink.stats.today.department"
    }, cookie);
  }
 
  /**
   * Get product Pareto analysis (top sellers)
   * eLink: retailmax.elink.product.paretolist
   */
  async getProductPareto(params: { limit?: number; storeId?: string } = {}, cookie?: string): Promise<any> {
    const buckParams: Record<string, string> = {
      "3": "retailmax.elink.product.paretolist"
    };
    
    if (params.limit) buckParams["8"] = params.limit.toString();
    if (params.storeId) buckParams["9"] = `f101,0,${params.storeId}`;
    
    return this.buckApiCall(buckParams, cookie);
  }
 
  /**
   * Get flat sale list (denormalized sales with items and payments)
   * eLink: retailmax.elink.saleflat.list
   */
  async getSaleFlatList(params: { 
    limit?: number; 
    startDate?: string;
    endDate?: string;
    storeId?: string;
  } = {}, cookie?: string): Promise<any> {
    const buckParams: Record<string, string> = {
      "3": "retailmax.elink.saleflat.list"
    };
    
    if (params.limit) buckParams["8"] = params.limit.toString();
    if (params.startDate) buckParams["9"] = `f110,5,${params.startDate}`;
    if (params.storeId) buckParams["9"] = `f120,0,${params.storeId}`;
    
    return this.buckApiCall(buckParams, cookie);
  }
 
  /**
   * Get single sale details
   * eLink: retailmax.elink.sale.fetch
   */
  async getSaleById(saleId: string, cookie?: string): Promise<any> {
    return this.buckApiCall({
      "3": "retailmax.elink.sale.fetch",
      "9": `f100,0,${saleId}`
    }, cookie);
  }
 
  /**
   * Get price map list
   * eLink: retailmax.elink.pricemap.list
   */
  async getPriceMapList(params: { limit?: number } = {}, cookie?: string): Promise<any> {
    const buckParams: Record<string, string> = {
      "3": "retailmax.elink.pricemap.list"
    };
    
    if (params.limit) buckParams["8"] = params.limit.toString();
    
    return this.buckApiCall(buckParams, cookie);
  }
 
  /**
   * Decode supplier pricebook
   * eLink: retailmax.elink.supplier.pricebook.decode
   */
  async decodeSupplierPricebook(supplierId: string, cookie?: string): Promise<any> {
    return this.buckApiCall({
      "3": "retailmax.elink.supplier.pricebook.decode",
      "9": `f100,0,${supplierId}`
    }, cookie);
  }
}
 
export const fieldpineServerApi = new FieldpineServerApi();