@forkbit/js

Official JavaScript/TypeScript SDK for the Forkbit API. Semantic food search, natural-language nutrition parsing, and recipe analysis.

Install

npm install @forkbit/js

Quickstart

import { Forkbit } from '@forkbit/js';

const forkbit = new Forkbit({ apiKey: process.env.FORKBIT_API_KEY! });

const { data } = await forkbit.foods.search('banana');
console.log(data[0].name);

Get an API key from your Forkbit dashboard.

Usage

foods.search(query, options?)

Semantic search over the Forkbit food database.

const { data, meta } = await forkbit.foods.search('chicken breast', { limit: 10 });
console.log(meta?.total, data.length);

foods.get(id)

Fetch a single food by id, with full nutrient and portion detail.

const { data: food } = await forkbit.foods.get('f1a2b3c4-...');
console.log(food.name, food.nutrients);

foods.batch(ids)

Fetch up to 50 foods by id in one call. Unknown ids resolve to null in the same position.

const { data: foods } = await forkbit.foods.batch(['id-1', 'id-2']);

parse.nutrition(text)

Parse a free-text food or meal description into matched foods with calculated nutrition.

const { data } = await forkbit.parse.nutrition('2 eggs and a slice of toast with butter');
console.log(data.matched, data.unmatched);

recipes.analyze({ servings, ingredients })

Analyze a full recipe (servings plus one ingredient line per food) into total and per-serving nutrition.

const { data } = await forkbit.recipes.analyze({
  servings: 4,
  ingredients: ['200g chicken breast', '1 tbsp olive oil'],
});
console.log(data.totals, data.perServing);

Error handling

Every method throws ForkbitError on a non-2xx response.

import { ForkbitError } from '@forkbit/js';

try {
  await forkbit.foods.get('missing-id');
} catch (error) {
  if (error instanceof ForkbitError) {
    console.error(error.code, error.message, error.statusCode);
  } else {
    throw error;
  }
}

Response shape

Every method resolves to a ForkbitResponse<T>:

interface ForkbitResponse<T> {
  data: T;
  meta?: { total: number; page: number; limit: number; hasMore: boolean };
  credits?: { consumed: number; remaining: number; reset: string };
  rateLimit?: { limit: number; remaining: number; reset: number };
  status: number;
  headers: Headers;
}

Links

• Forkbit API docs
• Contact support

License

MIT