1 min read

Node.js SDK

Integrate Aforo metering into Express, Fastify, and Koa applications.

Get the Node.js SDK

The Node.js SDK lives in the public repo github.com/aforoai/SDKs under aforo-metering-sdks/node.

View on GitHub Download ZIPgit clone https://github.com/aforoai/SDKs.git

Install & Quickstart#

Add Aforo metering to your Node.js service. Express, Fastify, and Koa middleware plus a manual track() client.

@aforo/metering requires Node 18+ (it uses the built-in fetch). Events POST to https://ingest.aforo.ai/v1/ingest/batch.

terminal

# Not yet on npm — clone or Download ZIP and install from source:
git clone https://github.com/aforoai/SDKs.git
cd SDKs/aforo-metering-sdks/node
npm install && npm run build && npm pack
# then in your app:
npm i /path/to/aforo-metering-1.0.0.tgz

Manual Tracking

usage.js

import { AforoClient } from '@aforo/metering';

const aforo = new AforoClient({ apiKey: process.env.AFORO_API_KEY });

// Count one billable action — non-blocking, flushes in the background
await aforo.track({
  customerId: 'cust_123',
  metricName: 'api_calls',
  quantity: 1,
});

// Flush remaining events before the process exits:
await aforo.shutdown();

Express Middleware

app.js

import { expressMiddleware } from '@aforo/metering/middleware/express';

// Meters every request after the response is sent — zero added latency
app.use(expressMiddleware({
  apiKey: process.env.AFORO_API_KEY,
  customerId: (req) => req.user?.id ?? null,  // return null to skip metering
}));

The middleware hooks res.on('finish'), so it runs after the response. The default metric name is "<METHOD> <normalized-path>" (e.g. GET /users/:id). Fastify and Koa adapters live under the same @aforo/metering/middleware/* path.