Node.js and server SDK (@metricraven/node)

@metricraven/node sends what only your backend knows: confirmed sign-ups, verified identities, payments and refunds. It runs anywhere fetch does, including Node 18+, Bun, Deno, Cloudflare Workers and Vercel Edge, and it has no dependencies.

It wraps the same secret-key endpoints as server events, identify and the Payments API, with types, timeouts and retries. Calls never throw into your request handler: each one returns a result.

Install

1. Add the package

   terminal

   Copy

   1

   npm install @metricraven/node

2. Set your secret key on the server

   Copy the site secret key (ana_sec_…) from Settings and store it as METRICRAVEN_SECRET_KEY. Never ship it to the browser or a mobile app.

3. Send an event after the action succeeds

   server.ts

   Copy

   1

   2

   3

   4

   5

   6

   7

   8

   9

   10

   11

   12

   // lib/metricraven.ts — server only. Reads METRICRAVEN_SECRET_KEY.
   import { createMetricRaven, getVisitorId } from "@metricraven/node";
   
   export const metricraven = createMetricRaven();
   
   // In your sign-up route handler, after the account exists:
   await metricraven.track({
     name: "signup",
     userId: user.id,
     visitorId: getVisitorId(request), // the tracker cookie, or null
     props: { plan: "free" },
   });

Calls

await metricraven.identify({
  visitorId,
  userId: user.id,
  email: user.email,
  name: user.name,
  traits: { plan: "pro" },
});

// After the payment succeeds. amount is in major units: 29 means $29.
await metricraven.payment({
  amount: 29,
  currency: "USD",
  transactionId: order.id,
  visitorId,
  userId: user.id,
  plan: "pro",
});

// Refunds send the cumulative amount refunded so far.
await metricraven.refund({ amount: 15, currency: "USD", transactionId: order.id });

track, identify, payment, refund and crawl are also exported as functions that use a shared client configured from the environment, or from configure(options).

Bot token for crawler reports

If a server only reports crawlers, give it the site's ingest-only bot token (mrbot_…) as METRICRAVEN_BOT_TOKEN or botToken, instead of the secret key. It can only send crawl events.

Attribute to the visit

getVisitorId(request) reads the visitor ID from a Fetch Request, a Node or Express request, Headers or a raw Cookie header. It checks the tracker's ana_vid cookie, then the metricraven_visitor_id cookie that the checkout recipes set. It returns null when there's neither.

Results and errors

const result = await metricraven.track({ name: "signup", userId: user.id });
if (!result.ok) console.warn("MetricRaven:", result.error, result.status);

Options

Edge and serverless

Don't hold the response while a call runs. Hand the promise to waitUntil (Workers ctx, Next.js after() or Vercel's waitUntil):

// Cloudflare Workers: don't hold the response for analytics.
import { createMetricRaven } from "@metricraven/node";

export default {
  async fetch(request, env, ctx) {
    const metricraven = createMetricRaven({ secretKey: env.METRICRAVEN_SECRET_KEY });
    ctx.waitUntil(metricraven.track({ name: "api_call", userId: "user_42" }));
    return new Response("ok");
  },
};