[!WARNING] This project is under active development and is not ready for production use. Please proceed with caution. Use at your own risk.

📚 Documentation: 86d.app/docs/modules/toast

Toast Module

Toast POS integration for 86d. Bidirectional sync for menus, orders, and inventory between your store and Toast POS.

Installation

npm install @86d-app/toast

Usage

import toast from "@86d-app/toast";

const module = toast({
  apiKey: "your-toast-api-key",
  restaurantGuid: "your-restaurant-guid",
  sandbox: "true",
});

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | — | Toast API key | | restaurantGuid | string | — | Toast restaurant GUID | | sandbox | string | "true" | Use sandbox mode |

Store Endpoints

| Method | Path | Description | |--------|------|-------------| | POST | /toast/sync/menu | Sync a menu item | | POST | /toast/sync/order | Sync an order |

Admin Endpoints

| Method | Path | Description | |--------|------|-------------| | GET | /admin/toast/sync-records | List all sync records | | GET | /admin/toast/menu-mappings | List menu mappings | | POST | /admin/toast/menu-mappings/create | Create a menu mapping | | POST | /admin/toast/menu-mappings/:id/delete | Delete a menu mapping | | GET | /admin/toast/sync-stats | Get sync statistics |

Controller API

interface ToastController extends ModuleController {
  syncMenu(params: { entityId: string; externalId: string; direction?: SyncDirection }): Promise<SyncRecord>;
  syncOrder(params: { entityId: string; externalId: string; direction?: SyncDirection }): Promise<SyncRecord>;
  syncInventory(params: { entityId: string; externalId: string; direction?: SyncDirection }): Promise<SyncRecord>;

  getSyncRecord(id: string): Promise<SyncRecord | null>;
  listSyncRecords(params?: { entityType?: SyncEntityType; status?: SyncStatus; take?: number; skip?: number }): Promise<SyncRecord[]>;

  createMenuMapping(params: { localProductId: string; externalMenuItemId: string }): Promise<MenuMapping>;
  getMenuMapping(id: string): Promise<MenuMapping | null>;
  listMenuMappings(params?: { isActive?: boolean; take?: number; skip?: number }): Promise<MenuMapping[]>;
  deleteMenuMapping(id: string): Promise<boolean>;

  getLastSyncTime(entityType?: SyncEntityType): Promise<Date | null>;
  getSyncStats(): Promise<SyncStats>;
}

Types

type SyncEntityType = "menu-item" | "order" | "inventory";
type SyncDirection = "inbound" | "outbound";
type SyncStatus = "pending" | "synced" | "failed";

interface SyncRecord {
  id: string;
  entityType: SyncEntityType;
  entityId: string;
  externalId: string;
  direction: SyncDirection;
  status: SyncStatus;
  error?: string;
  syncedAt?: Date;
  createdAt: Date;
  updatedAt: Date;
}

interface MenuMapping {
  id: string;
  localProductId: string;
  externalMenuItemId: string;
  isActive: boolean;
  lastSyncedAt?: Date;
  createdAt: Date;
  updatedAt: Date;
}

interface SyncStats {
  total: number;
  pending: number;
  synced: number;
  failed: number;
  byEntityType: Record<string, number>;
}

Notes

• Supports bidirectional sync via inbound and outbound directions; defaults to outbound.
• Menu mappings link local product IDs to Toast external menu item IDs for ongoing synchronization.
• Sync records track every individual sync operation with status and optional error messages.
• getLastSyncTime returns the most recent successful sync timestamp, optionally filtered by entity type.
• Events emitted: toast.order.synced, toast.menu.synced, toast.inventory.updated, toast.webhook.received.