fd1Client.ts

Go to the documentation of this file.

/**
 * Fieldpine FD1/FD3 API Client
 * 
 * Modern TypeScript client for Fieldpine's FD1 and FD3 protocol.
 * Supports both HTTP POST and WebSocket connections.
 * 
 * @see /docs/FIELDPINE_FD1_API.md
 */
 
export interface FD1QueryOptions {
  [key: string]: boolean | string;
}
 
export interface FD1QueryFilters {
  [key: string]: any;
}
 
export interface FD1Request {
  a: string; // Action name
  q?: FD1QueryFilters; // Query filters
  qo?: FD1QueryOptions; // Query options (field selection)
  limit?: number;
  offset?: number;
  [key: string]: any; // Additional parameters
}
 
export interface FD1Response<T = any> {
  success?: boolean;
  data?: {
    rows?: T[];
  };
  rows?: T[]; // Alternative format
  error?: {
    code: string;
    message: string;
    details?: any;
  };
}
 
export interface FD1Product {
  pid?: number;
  physkey?: string;
  description?: string;
  sku?: string;
  barcode?: string;
  price?: number;
  cost?: number;
  stock_level?: number;
  department_id?: number;
  supplier_id?: number;
}
 
export interface FD1Sale {
  sale_id?: number;
  created_date?: string;
  completed_date?: string;
  total_inc_tax?: number;
  total_ex_tax?: number;
  tax_amount?: number;
  status?: string;
  phase_code?: number;
  location_id?: number;
  customer_id?: number;
  operator_id?: number;
}
 
export interface FD1SaleLine {
  line_id?: number;
  sale_id?: number;
  product_id?: number;
  description?: string;
  qty?: number;
  unit_price?: number;
  line_total?: number;
  tax_amount?: number;
}
 
export interface FD1Customer {
  customer_id?: number;
  name?: string;
  email?: string;
  phone?: string;
  address?: string;
  city?: string;
  state?: string;
  postcode?: string;
  country?: string;
  loyalty_points?: number;
}
 
export interface FD1Department {
  department_id?: number;
  name?: string;
  parent_id?: number;
  description?: string;
}
 
export interface FD1Location {
  location_id?: number;
  name?: string;
  address?: string;
  city?: string;
  state?: string;
  postcode?: string;
  country?: string;
}
 
export interface FD1SessionResponse {
  success: boolean;
  session_token?: string;
  user_id?: number;
  permissions?: string[];
  error?: {
    code: string;
    message: string;
  };
}
 
/**
 * FD1 Client Configuration
 */
export interface FD1ClientConfig {
  baseUrl: string; // e.g., 'http://127.0.0.1:3490' or 'https://store.fieldpine.com'
  apiKey?: string;
  sessionToken?: string;
  protocol?: 'fd1' | 'fd3'; // fd1 for local/ws, fd3 for cloud/https
}
 
/**
 * FD1 API Client
 */
export class FD1Client {
  private config: FD1ClientConfig;
  private ws?: WebSocket;
 
  constructor(config: FD1ClientConfig) {
    this.config = {
      protocol: 'fd3',
      ...config,
    };
  }
 
  /**
   * Execute a generic FD1 request
   */
  async request<T = any>(request: FD1Request): Promise<FD1Response<T>> {
    const url = `${this.config.baseUrl}/${this.config.protocol}/${request.a}`;
 
    const headers: Record<string, string> = {
      'Content-Type': 'application/json',
    };
 
    if (this.config.apiKey) {
      headers['x-api-key'] = this.config.apiKey;
    }
 
    if (this.config.sessionToken) {
      headers['x-session-token'] = this.config.sessionToken;
    }
 
    const response = await fetch(url, {
      method: 'POST',
      headers,
      body: JSON.stringify(request),
    });
 
    if (!response.ok) {
      throw new Error(`FD1 request failed: ${response.status} ${response.statusText}`);
    }
 
    return response.json();
  }
 
  /**
   * Products API
   */
  async listProducts(
    filters?: FD1QueryFilters,
    fields?: FD1QueryOptions,
    limit = 100,
    offset = 0
  ): Promise<FD1Product[]> {
    const response = await this.request<FD1Product>({
      a: 'products.list',
      q: filters,
      qo: fields || {
        internal_id_n: 'pid',
        internal_guid: 'physkey',
        description: true,
        sku: true,
        barcode: true,
        price: true,
        stock_level: true,
      },
      limit,
      offset,
    });
 
    return response.data?.rows || response.rows || [];
  }
 
  async getProduct(productId: number, fields?: FD1QueryOptions): Promise<FD1Product | null> {
    const products = await this.listProducts(
      { pid: productId },
      fields || {
        internal_id_n: 'pid',
        description: true,
        sku: true,
        price: true,
        cost: true,
        stock_level: true,
      },
      1
    );
 
    return products[0] || null;
  }
 
  async searchProducts(searchTerm: string, limit = 50): Promise<FD1Product[]> {
    return this.listProducts(
      { search: searchTerm },
      {
        internal_id_n: 'pid',
        description: true,
        sku: true,
        barcode: true,
        price: true,
      },
      limit
    );
  }
 
  /**
   * Sales API
   */
  async listSales(
    filters?: FD1QueryFilters,
    fields?: FD1QueryOptions,
    limit = 100,
    offset = 0
  ): Promise<FD1Sale[]> {
    const response = await this.request<FD1Sale>({
      a: 'sales.list',
      q: filters,
      qo: fields || {
        sale_id: true,
        created_date: true,
        completed_date: true,
        total_inc_tax: true,
        total_ex_tax: true,
        status: true,
        customer_id: true,
      },
      limit,
      offset,
    });
 
    return response.data?.rows || response.rows || [];
  }
 
  async getSale(saleId: number): Promise<FD1Sale | null> {
    const response = await this.request<FD1Sale>({
      a: 'sale.read',
      sale_id: saleId,
    });
 
    if (response.data?.rows && response.data.rows.length > 0) {
      return response.data.rows[0];
    }
 
    return null;
  }
 
  async createSale(saleData: {
    lines: Array<{ product_id: number; qty: number; price?: number }>;
    customer_id?: number;
    location_id?: number;
  }): Promise<FD1Sale> {
    const response = await this.request<FD1Sale>({
      a: 'sale.create',
      ...saleData,
    });
 
    if (response.data?.rows && response.data.rows.length > 0) {
      return response.data.rows[0];
    }
 
    throw new Error('Failed to create sale');
  }
 
  /**
   * Customers API
   */
  async listCustomers(
    filters?: FD1QueryFilters,
    fields?: FD1QueryOptions,
    limit = 100,
    offset = 0
  ): Promise<FD1Customer[]> {
    const response = await this.request<FD1Customer>({
      a: 'customers.list',
      q: filters,
      qo: fields || {
        customer_id: true,
        name: true,
        email: true,
        phone: true,
        loyalty_points: true,
      },
      limit,
      offset,
    });
 
    return response.data?.rows || response.rows || [];
  }
 
  async getCustomer(customerId: number): Promise<FD1Customer | null> {
    const customers = await this.listCustomers({ customer_id: customerId }, undefined, 1);
    return customers[0] || null;
  }
 
  async searchCustomers(searchTerm: string, limit = 50): Promise<FD1Customer[]> {
    return this.listCustomers(
      { search: searchTerm },
      {
        customer_id: true,
        name: true,
        email: true,
        phone: true,
      },
      limit
    );
  }
 
  /**
   * Departments API
   */
  async listDepartments(fields?: FD1QueryOptions): Promise<FD1Department[]> {
    const response = await this.request<FD1Department>({
      a: 'departments.list',
      qo: fields || {
        department_id: true,
        name: true,
        parent_id: true,
        description: true,
      },
    });
 
    return response.data?.rows || response.rows || [];
  }
 
  /**
   * Locations API
   */
  async listLocations(fields?: FD1QueryOptions): Promise<FD1Location[]> {
    const response = await this.request<FD1Location>({
      a: 'locations.list',
      qo: fields || {
        location_id: true,
        name: true,
        address: true,
        city: true,
      },
    });
 
    return response.data?.rows || response.rows || [];
  }
 
  /**
   * Session Management
   */
  async login(credentials: {
    username?: string;
    password?: string;
    api_key?: string;
  }): Promise<FD1SessionResponse> {
    const response = await this.request<FD1SessionResponse>({
      a: 'session.login',
      ...credentials,
    });
 
    if (response.success && response.data?.rows?.[0]?.session_token) {
      this.config.sessionToken = response.data.rows[0].session_token;
    }
 
    const result = response.data?.rows?.[0];
    if (result) {
      return result;
    }
 
    // If no row data, construct response from top-level response
    return {
      success: response.success || false,
      session_token: response.data?.rows?.[0]?.session_token,
      user_id: response.data?.rows?.[0]?.user_id,
      permissions: response.data?.rows?.[0]?.permissions,
      error: response.error,
    };
  }
 
  async logout(): Promise<void> {
    await this.request({
      a: 'session.logout',
    });
 
    this.config.sessionToken = undefined;
  }
 
  /**
   * WebSocket Support
   */
  connectWebSocket(
    onMessage: (data: any) => void,
    onError?: (error: Event) => void
  ): Promise<void> {
    return new Promise((resolve, reject) => {
      const wsProtocol = this.config.baseUrl.startsWith('https') ? 'wss' : 'ws';
      const wsUrl = `${wsProtocol}://${this.config.baseUrl.replace(/^https?:\/\//, '')}/fd1/ws`;
 
      this.ws = new WebSocket(wsUrl);
 
      this.ws.onopen = () => {
        // Send authentication as first message
        if (this.config.apiKey) {
          this.ws?.send(
            JSON.stringify({
              a: 'session.login',
              api_key: this.config.apiKey,
            })
          );
        }
        resolve();
      };
 
      this.ws.onmessage = (event) => {
        try {
          const data = JSON.parse(event.data);
          onMessage(data);
        } catch (error) {
          console.error('Failed to parse WebSocket message:', error);
        }
      };
 
      this.ws.onerror = (error) => {
        if (onError) {
          onError(error);
        }
        reject(error);
      };
 
      this.ws.onclose = () => {
        console.log('WebSocket connection closed');
      };
    });
  }
 
  sendWebSocketMessage(message: FD1Request): void {
    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
      this.ws.send(JSON.stringify(message));
    } else {
      throw new Error('WebSocket not connected');
    }
  }
 
  disconnectWebSocket(): void {
    if (this.ws) {
      this.ws.close();
      this.ws = undefined;
    }
  }
 
  /**
   * Firehose (Real-time Events)
   */
  async subscribeToFirehose(topics: string[]): Promise<void> {
    await this.request({
      a: 'firehose.subscribe',
      topics,
    });
  }
 
  /**
   * Generic Data Query (using /fd1/data endpoint)
   */
  async queryData(table: string, filter?: string, fields?: string): Promise<any> {
    const params = new URLSearchParams({
      '_v.table': filter ? `${table}[${filter}]` : table,
    });
 
    if (fields) {
      params.append('_qo', fields);
    }
 
    const url = `${this.config.baseUrl}/fd1/data?${params.toString()}`;
 
    const headers: Record<string, string> = {};
 
    if (this.config.apiKey) {
      headers['x-api-key'] = this.config.apiKey;
    }
 
    const response = await fetch(url, { headers });
 
    if (!response.ok) {
      throw new Error(`FD1 data query failed: ${response.status} ${response.statusText}`);
    }
 
    return response.json();
  }
}
 
/**
 * Create FD1 client instance
 */
export function createFD1Client(config: FD1ClientConfig): FD1Client {
  return new FD1Client(config);
}