Node.js SDK

The official Node.js SDK provides a typed client for server-side integrations.

Macrofy is API-first. The SDK is a convenience layer over the HTTP API — you can always call endpoints directly.

Packages

Name
@macrofy/core
Type
npm
Description
Shared TypeScript client with typed request/response models.
Name
@macrofy/node
Type
npm
Description
Node.js-specific conveniences: file uploads, automatic retries.

Install

npm install @macrofy/node
# or
pnpm add @macrofy/node

Setup

import { MacrofyClient } from '@macrofy/node'

const macrofy = new MacrofyClient({
  apiKey: process.env.MACROFY_API_KEY!,
})

Core methods

searchFoods

Search foods by name and return structured macros.

const results = await macrofy.searchFoods({ q: 'banana' })

// Response
[
  {
    id: 'food_123',
    name: 'Banana',
    brand: null,
    serving: { amount: 118, unit: 'g' },
    macros: { calories: 105, protein: 1.3, carbs: 27, fat: 0.4 }
  }
]

lookupBarcode

Resolve a UPC/EAN barcode to a food item.

const food = await macrofy.lookupBarcode({ upc: '012000161155' })

// Response
{
  id: 'food_coke',
  name: 'Coca-Cola Classic',
  brand: 'Coca-Cola',
  serving: { amount: 12, unit: 'fl_oz' },
  macros: { calories: 140, protein: 0, carbs: 39, fat: 0 }
}

createImageScan / getImageScan

Create an async image scan job and poll for results.

// 1. Create scan job
const job = await macrofy.createImageScan({
  clientId: 'your-app',
  contentType: 'image/jpeg',
})

// job.jobId = 'scan_abc123'
// job.uploadUrl = 'https://storage.googleapis.com/...'

// 2. Upload image to signed URL (PUT request)
await fetch(job.uploadUrl, {
  method: 'PUT',
  headers: { 'Content-Type': 'image/jpeg' },
  body: imageBuffer,
})

// 3. Poll for results
const result = await macrofy.getImageScan({ jobId: job.jobId })

// result.status = 'complete'
// result.result.items = [{ name: 'Chicken bowl', macros: {...} }]

scanImageFromFile (Node.js only)

Convenience method that handles the full async pipeline.

import { MacrofyClient } from '@macrofy/node'

const macrofy = new MacrofyClient({ apiKey: process.env.MACROFY_API_KEY! })

const result = await macrofy.scanImageFromFile('/path/to/image.jpg', {
  clientId: 'your-app',
})

// Returns the completed scan result

Error handling

All methods throw MacrofyError on failure. See Errors for the full list.

import { MacrofyError } from '@macrofy/node'

try {
  await macrofy.lookupBarcode({ upc: 'invalid' })
} catch (err) {
  if (err instanceof MacrofyError) {
    console.log(err.code)      // 'barcode_not_found'
    console.log(err.message)   // 'No food found for barcode.'
    console.log(err.requestId) // 'req_abc123'
  }
}

TypeScript

The SDK is fully typed. Import types directly:

import type { Food, MacrosData, ScanResult } from '@macrofy/node'