@campfire-interactive/volume-api-client

@campfire-interactive/volume-api-client

TypeScript client for the Volume Access API — pull a built, mixed volume timeline (actuals blended with a forecast) from the forecast app, without knowing its schema.

Install

npm install @campfire-interactive/volume-api-client

Usage

import { VolumeApiClient } from '@campfire-interactive/volume-api-client';

const client = new VolumeApiClient({
  baseUrl: 'https://forecast.dev.campfiresuite.com/api',
  getToken: async () => myIdentityToken, // platform-identity token for an allowlisted caller
});

// What can I ask for?
const catalog = await client.getCatalog();
// → { volumes: [{ key: 'vehicle', forecasts: ['campfire','IHS','AFS'], … }, { key: 'edi', forecasts: ['campfire'] }] }

// Build the blended monthly timeline for Ford / Ohio, broken out by OEM.
const timeline = await client.getTimeline({
  volume: 'vehicle',
  forecast: 'campfire',
  from: '2026-W01',
  to: '2026-W52',
  granularity: 'monthly',
  filters: { OEM: ['Ford'], Plant: ['Ohio'] },
  groupBy: ['OEM'],
});
// timeline.rows → [{ period: '2026-04', OEM: 'Ford', value: 178420, source: 'actual' }, …]
// timeline.meta.actualsThrough marks the actual→forecast boundary.

// Large pulls: get a presigned CSV download instead of an inline result.
const exported = await client.exportTimeline({ volume: 'edi', from: '2026-W01', to: '2027-W52' });
// exported.url → presigned download

Concepts

• volume — vehicle or edi; sets the actuals stream and the unit.
• forecast — campfire (default) or a named base source (IHS/AFS) for the forward part. EDI is always campfire.
• the mix — per week, the API takes the highest-priority available tier (actual → [EDI demand] → forecast) — one value per week, never summed. Each row reports its source; meta.actualsThrough is the boundary.
• granularity — weekly (native), monthly/yearly (ISO-week-by-Thursday, summed). Edge buckets that don't fully fall in range are listed in meta.partialBuckets.

Errors

UnauthorizedError (401), ForbiddenError (403, not allowlisted), ResultTooLargeError (413 — switch to exportTimeline), RateLimitedError (429), or VolumeApiError for anything else (.status, .code, .requestId).

See openapi.yaml for the full HTTP contract.