@emagri_112/foodforagentsapi

Typed JavaScript SDK, REST API and website demo for agent-driven food ordering.

The repository is operational in sandbox mode: an agent can search the included catalog, resolve a menu item, create a confirmed idempotent order and read its status. A real delivery transaction is created only when the backend runs in live mode with a contracted provider adapter configured.

Install the SDK

npm install @emagri_112/foodforagentsapi

import { FoodAPI } from "@emagri_112/foodforagentsapi";

const food = new FoodAPI({
  apiKey: process.env.FOODAPI_KEY,
  baseUrl: process.env.FOODAPI_BASE_URL,
});

const order = await food.order({
  query: "Crispy McBacon",
  location: "Milano",
  delivery: { address: "Via Roma 1, Milano" },
  confirm: true,
});

console.log(order.id, order.status, order.delivery.estimated_time);

confirm: true is mandatory. An agent should set it only after the user has explicitly approved the order.

Agent tools

The SDK exposes JSON-schema function tools and a dispatcher compatible with common LLM tool-calling loops:

const tools = food.agentTools();
const result = await food.executeTool(toolCall.function.name, JSON.parse(toolCall.function.arguments));

Available tools are search_restaurants, get_restaurant_menu, create_order and get_order_status.

Run the complete project

Install dependencies at the repository root and in the API directory, then start both processes:

pnpm install
pnpm dev

cd server
pnpm install
pnpm start

The website defaults to http://localhost:5173; the API defaults to http://localhost:3001. The local sandbox key is foodapi_test_sk_local and must never be reused in a shared or production environment.

REST endpoints

• GET /health
• GET /v1/restaurants?query=...&location=...
• GET /v1/restaurants/:id
• POST /v1/orders (requires confirm: true and an Idempotency-Key header)
• GET /v1/orders/:id
• GET /v1/tools

All /v1 requests accept Authorization: Bearer <FOODAPI_API_KEY>. The legacy X-API-Key header is also accepted.

Live provider adapter

Set these backend variables to forward confirmed orders to your ordering provider:

FOODAPI_MODE=live
FOODAPI_API_KEY=replace-with-a-private-key
FOODAPI_ORDER_WEBHOOK_URL=https://provider.example/orders
FOODAPI_ORDER_WEBHOOK_TOKEN=replace-with-provider-token
FOODAPI_CORS_ORIGIN=https://your-site.example

The provider endpoint receives the normalized order JSON plus the same Idempotency-Key. It must return JSON with an id or order_id and may return a status. Without this adapter, the API intentionally remains in sandbox and does not claim to purchase food.

Verify

pnpm test
pnpm build

Before publishing a new SDK version, inspect the package with pnpm pack --dry-run.