@dispatch9/client-sdk/src/index.d.ts

Official Node.js SDK for Dispatch9 API - Complete solution with email/phone client creation, order management, client management, and dual-method authentication

export interface Address {
  id: string;
  street: string;
  city: string;
  state: string;
  zipCode: string;
  country: string;
  name?: string;
  contactName?: string;
  contactPhone?: string;
  contactEmail?: string;
  notes?: string;
  coordinates?: {
    lat: number;
    lng: number;
  };
  createdAt: string;
  updatedAt: string;
}

export interface AddressInput {
  street: string;
  city: string;
  state: string;
  zipCode: string;
  country: string;
  name?: string;
  contactName?: string;
  contactPhone?: string;
  contactEmail?: string;
  notes?: string;
  coordinates?: {
    lat: number;
    lng: number;
  };
}

export interface Item {
  SKU: string;
  itemName: string;
  category?: string;
  description?: string;
  price: number;
  currency?: string;
  quantity: number;
  weight?: number;
  weightUnit?: 'kg' | 'lb' | 'g' | 'oz';
  dimensionH?: number;
  dimensionW?: number;
  dimensionL?: number;
  dimensionUnit?: 'cm' | 'in';
  packaging?: string;
  handling?: string;
  notes?: string;
  status?: {
    isCollected?: boolean;
    isMissing?: boolean;
    isDamaged?: boolean;
    isReturned?: boolean;
  };
  deliveredQuantity?: number;
}

export interface Service {
  serviceCode: string;
  serviceName: string;
  category: string;
  description?: string;
  estimatedDuration?: number;
  price: number;
  currency?: string;
  requirements?: Array<string | {
    type: 'workers' | 'tools' | 'qualifications' | 'equipment';
    count?: number;
    workers?: number;
    numberOfWorkers?: number;
    description?: string;
    mandatory?: boolean;
  }>;
  notes?: string;
  status?: {
    isCompleted?: boolean;
    isSkipped?: boolean;
    needsReschedule?: boolean;
  };
  completionTime?: string;
  workerNotes?: string;
}

export interface Client {
  id: string;
  name: string;
  email: string;
  websiteURL?: string;
  logoURL?: string;
  businessType?: 'restaurant' | 'retail' | 'grocery' | 'pharmacy' | 'other';
  taxId?: string;
  address?: string;
  webhookURL?: string;
  apiConfig?: {
    enabled: boolean;
    rateLimit: number;
  };
  integrations?: Array<{
    platform: string;
    enabled: boolean;
    config: Record<string, any>;
    webhookSecret?: string;
    syncOrders: boolean;
  }>;
  orderSettings?: {
    autoAccept: boolean;
    autoAssign: boolean;
    maxOrdersPerHour: number;
    preparationTime: number;
    deliveryRadius: number;
  };
  permissions?: {
    modify: boolean;
    delete: boolean;
    createOrders: boolean;
    viewOrders: boolean;
  };
  authentication?: {
    enablePortalAccess: boolean;
    phone?: string;
    password?: string;
    firstName?: string;
    lastName?: string;
    businessName?: string;
  };
  createdAt: string;
  updatedAt: string;
}

export interface ClientInput {
  name: string;
  email?: string; // Optional - either email or phone required
  phone?: string; // Optional - either email or phone required
  websiteURL?: string;
  logoURL?: string;
  businessType?: 'restaurant' | 'retail' | 'grocery' | 'pharmacy' | 'other';
  taxId?: string;
  address?: string;
  webhookURL?: string;
  apiConfig?: {
    enabled?: boolean;
    rateLimit?: number;
  };
  integrations?: Array<{
    platform: string;
    enabled?: boolean;
    config?: Record<string, any>;
    webhookSecret?: string;
    syncOrders?: boolean;
  }>;
  orderSettings?: {
    autoAccept?: boolean;
    autoAssign?: boolean;
    maxOrdersPerHour?: number;
    preparationTime?: number;
    deliveryRadius?: number;
  };
  permissions?: {
    modify?: boolean;
    delete?: boolean;
    createOrders?: boolean;
    viewOrders?: boolean;
  };
  authentication?: {
    enablePortalAccess: boolean;
    phone?: string;
    password?: string;
    firstName?: string;
    lastName?: string;
    businessName?: string;
  };
}

export interface Order {
  id: string;
  orderNumber?: string;
  orderTotal: number;
  orderCurrency: string;
  isPaid: boolean;
  client: string;
  hasGoods: boolean;
  hasServices: boolean;
  hasWorkers: boolean;
  priority: number;
  autoAssign: boolean;
  manualAssignWorker?: string;
  status: 'created' | 'assigned' | 'in_progress' | 'completed' | 'failed' | 'partially_completed';
  completeAfter?: number;
  completeBefore?: number;
  items?: Item[];
  services?: Service[];
  workers?: any[];
  pickupLocation?: string;
  deliveryLocation?: string;
  serviceLocation?: string;
  specialInstructions?: string;
  customerNotes?: string;
  metadata?: Record<string, any>;
  isRecurring: boolean;
  recurringSettings?: any;
  requiredProof?: {
    signature?: boolean;
    photo?: boolean;
    notes?: boolean;
  };
  createdAt: string;
  updatedAt: string;
}

export interface OrderInput {
  client: string;
  orderTotal: number;
  orderCurrency?: string;
  isPaid?: boolean;
  hasGoods?: boolean;
  hasServices?: boolean;
  hasWorkers?: boolean;
  priority?: number;
  autoAssign?: boolean;
  manualAssignWorker?: string;
  status?: 'created' | 'assigned' | 'in_progress' | 'completed' | 'failed' | 'partially_completed';
  completeAfter?: number;
  completeBefore?: number;
  items?: Item[];
  services?: Service[];
  workers?: any[];
  pickupLocation?: string;
  deliveryLocation?: string;
  serviceLocation?: string;
  specialInstructions?: string;
  customerNotes?: string;
  metadata?: Record<string, any>;
  isRecurring?: boolean;
  recurringSettings?: any;
  requiredProof?: {
    signature?: boolean;
    photo?: boolean;
    notes?: boolean;
  };
}

export interface DeliveryOrderInput {
  client: string;
  orderTotal: number;
  orderCurrency?: string;
  priority?: number;
  pickupAddress: AddressInput;
  deliveryAddress: AddressInput;
  items: Item[];
  specialInstructions?: string;
  customerNotes?: string;
}

export interface ServiceOrderInput {
  client: string;
  orderTotal: number;
  orderCurrency?: string;
  priority?: number;
  serviceAddress: AddressInput;
  services: Service[];
  specialInstructions?: string;
  customerNotes?: string;
}

export interface PaginatedResponse<T> {
  results: T[];
  page: number;
  limit: number;
  totalPages: number;
  totalResults: number;
}

export interface QueryOptions {
  page?: number;
  limit?: number;
  sortBy?: string;
  [key: string]: any;
}

export interface Dispatch9Config {
  apiKey: string;
  baseURL?: string;
  timeout?: number;
  debug?: boolean;
  headers?: Record<string, string>;
}

export class Dispatch9Client {
  constructor(config: Dispatch9Config);

  // Connection
  ping(): Promise<any>;

  // Orders
  getOrders(options?: QueryOptions): Promise<PaginatedResponse<Order>>;
  getOrder(orderId: string): Promise<Order>;
  createOrder(orderData: OrderInput): Promise<Order>;
  createDeliveryOrder(orderData: DeliveryOrderInput): Promise<{
    order: Order;
    pickupAddress: Address;
    deliveryAddress: Address;
  }>;
  createServiceOrder(orderData: ServiceOrderInput): Promise<{
    order: Order;
    serviceAddress: Address;
  }>;
  updateOrder(orderId: string, updateData: Partial<OrderInput>): Promise<Order>;
  getOrderById(orderId: string, options?: {
    populate?: string;
    includeJobs?: boolean;
  }): Promise<Order>;
  cancelOrder(orderId: string, reason?: string): Promise<Order>;
  trackOrder(orderId: string): Promise<any>;

  // Clients
  getClients(options?: QueryOptions): Promise<PaginatedResponse<Client>>;
  getClient(clientId: string): Promise<Client>;
  getClientById(clientId: string, options?: {
    populate?: string;
    includeStats?: boolean;
  }): Promise<Client>;
  createClient(clientData: ClientInput): Promise<Client>;

  // Client Authentication
  loginClient(credentials: {
    identifier: string;
    password: string;
    providerId?: string;
  }): Promise<{
    success: boolean;
    requiresProviderSelection?: boolean;
    requiresOTP?: boolean;
    clientId?: string;
    providers?: Array<{
      providerId: string;
      database: string;
      permissions: Record<string, boolean>;
      registeredAt: string;
    }>;
    tokens?: {
      access: { token: string; expires: string };
      refresh: { token: string; expires: string };
    };
    client?: {
      id: string;
      email: string;
      phone?: string;
      name: string;
      isFirstLogin: boolean;
      registrationStatus: string;
    };
    message?: string;
  }>;

  selectClientProvider(selection: {
    clientId: string;
    providerId: string;
  }): Promise<{
    success: boolean;
    tokens: {
      access: { token: string; expires: string };
      refresh: { token: string; expires: string };
    };
    client: {
      id: string;
      email: string;
      phone?: string;
      name: string;
      selectedProvider: {
        providerId: string;
        database: string;
      };
    };
    message?: string;
  }>;

  verifyClientLoginOTP(verification: {
    clientId: string;
    otp: string;
  }): Promise<{
    success: boolean;
    tokens: {
      access: { token: string; expires: string };
      refresh: { token: string; expires: string };
    };
    client: {
      id: string;
      email: string;
      phone?: string;
      name: string;
    };
    message?: string;
  }>;

  getClientProfile(): Promise<{
    id: string;
    email: string;
    phone?: string;
    name: string;
    businessName?: string;
    status: string;
    registrationStatus: string;
    isFirstLogin: boolean;
    lastLogin?: string;
    providers: Array<{
      providerId: string;
      database: string;
      status: string;
    }>;
  }>;

  // Addresses
  getAddresses(options?: QueryOptions): Promise<PaginatedResponse<Address>>;
  getAddress(addressId: string): Promise<Address>;
  createAddress(addressData: AddressInput): Promise<Address>;
  updateAddress(addressId: string, updateData: Partial<AddressInput>): Promise<Address>;
  deleteAddress(addressId: string): Promise<void>;

  // Workers
  getWorkers(options?: QueryOptions): Promise<PaginatedResponse<any>>;
  getWorker(workerId: string): Promise<any>;
  getWorkerLocation(workerId: string): Promise<any>;

  // Analytics
  getAnalytics(options?: any): Promise<any>;
  getPerformanceMetrics(options?: any): Promise<any>;
  getOrderStats(options?: any): Promise<any>;

  // Webhooks
  getWebhooks(): Promise<any[]>;
  createWebhook(webhookData: any): Promise<any>;
  updateWebhook(webhookId: string, updateData: any): Promise<any>;
  deleteWebhook(webhookId: string): Promise<void>;
}

export function createClient(config: Dispatch9Config): Dispatch9Client;

export default Dispatch9Client;