npm install @marginfront/sdk

import { MarginFrontClient } from "@marginfront/sdk";

// Your secret API key from the MarginFront dashboard (Settings > API Keys).
// NEVER put the actual key in your code -- use an environment variable.
const mf = new MarginFrontClient(process.env.MF_API_SECRET_KEY);

import OpenAI from "openai";
import { MarginFrontClient } from "@marginfront/sdk";

const openai = new OpenAI();
const mf = new MarginFrontClient(process.env.MF_API_SECRET_KEY);

async function handleCustomerQuestion(customerId: string, question: string) {
  // Step 1: Call OpenAI like you normally would
  const response = await openai.chat.completions.create({
    model: "gpt-4o",
    messages: [
      { role: "system", content: "You are a helpful customer support agent." },
      { role: "user", content: question },
    ],
  });

  // Step 2: Get the answer to send back to the customer
  const answer = response.choices[0].message.content;

  // Step 3: Tell MarginFront what just happened.
  //
  // This runs in the background by default (fireAndForget: true).
  // If the network is down, it retries automatically.
  // If MarginFront is unreachable, your agent keeps running -- the customer
  // still gets their answer. Billing is important, but never more important
  // than your core product working.
  try {
    await mf.usage.record({
      customerExternalId: customerId, // your customer's ID in your system
      agentCode: "cs-bot-v2", // the agent code from the dashboard
      signalName: "messages", // the metric you're tracking
      model: response.model, // "gpt-4o" -- straight from OpenAI's response
      modelProvider: "openai", // always lowercase
      inputTokens: response.usage.prompt_tokens, // how many tokens the prompt used
      outputTokens: response.usage.completion_tokens, // how many tokens the answer used
    });
  } catch (error) {
    // With fireAndForget ON (the default), this catch block almost never runs.
    // The SDK handles retries internally. This is just a safety net.
    console.error("MarginFront tracking failed (non-blocking):", error);
  }

  return answer;
}

import twilio from "twilio";
import { MarginFrontClient } from "@marginfront/sdk";

const twilioClient = twilio(
  process.env.TWILIO_SID,
  process.env.TWILIO_AUTH_TOKEN,
);
const mf = new MarginFrontClient(process.env.MF_API_SECRET_KEY);

async function sendSmsForCustomer(
  customerId: string,
  to: string,
  body: string,
) {
  // Step 1: Send the SMS through Twilio
  const message = await twilioClient.messages.create({
    to,
    from: process.env.TWILIO_PHONE_NUMBER,
    body,
  });

  // Step 2: Twilio confirmed it was sent -- now tell MarginFront.
  //
  // quantity is 1 here (one SMS). You could omit it since 1 is the default,
  // but being explicit makes the code easier to read later.
  try {
    await mf.usage.record({
      customerExternalId: customerId,
      agentCode: "notification-agent",
      signalName: "sms-sent",
      model: "sms-send", // not an LLM model -- just a label for the service
      modelProvider: "twilio", // which provider handled it
      quantity: 1, // one SMS sent
    });
  } catch (error) {
    console.error("MarginFront tracking failed (non-blocking):", error);
  }

  return message.sid;
}

import Anthropic from "@anthropic-ai/sdk";
import { MarginFrontClient } from "@marginfront/sdk";

const anthropic = new Anthropic();
const mf = new MarginFrontClient(process.env.MF_API_SECRET_KEY);

async function generateReport(customerId: string, topic: string) {
  // Step 1: Generate the report with Claude
  const response = await anthropic.messages.create({
    model: "claude-sonnet-4-20250514",
    max_tokens: 8000,
    messages: [
      { role: "user", content: `Write a market research report on: ${topic}` },
    ],
  });

  const reportText =
    response.content[0].type === "text" ? response.content[0].text : "";

  // Step 2: Figure out how many pages the report is.
  // (Your real logic might be more sophisticated -- this is just an example.)
  const estimated_pages = Math.ceil(reportText.length / 3000);

  // Step 3: Tell MarginFront about the report.
  //
  // quantity = number of pages. This is what the customer gets billed for.
  // inputTokens / outputTokens = LLM usage. This tracks your cost from Anthropic.
  // Both matter, but for different reasons.
  try {
    await mf.usage.record({
      customerExternalId: customerId,
      agentCode: "research-agent",
      signalName: "report-pages", // the billable metric is pages
      model: response.model, // "claude-sonnet-4-20250514"
      modelProvider: "anthropic",
      inputTokens: response.usage.input_tokens, // Anthropic uses input_tokens (not prompt_tokens)
      outputTokens: response.usage.output_tokens, // Anthropic uses output_tokens (not completion_tokens)
      quantity: estimated_pages, // 15 pages = 15 units billed
    });
  } catch (error) {
    console.error("MarginFront tracking failed (non-blocking):", error);
  }

  return { reportText, pages: estimated_pages };
}

await mf.usage.record({
  customerExternalId: "acme-001",
  agentCode: "cs-bot-v2",
  signalName: "messages",
  model: "gpt-4o",
  modelProvider: "openai",
  inputTokens: 812,
  outputTokens: 245,

  // metadata is free-form. Put whatever is useful for YOUR debugging and analytics.
  // MarginFront stores it with the event but does NOT use it for billing or
  // cost calculation. It will not appear on invoices.
  metadata: {
    conversationId: "conv_abc123", // link this event back to a chat thread
    promptTemplate: "support-v3.2", // which prompt version generated this
    abTestVariant: "concise-responses", // for your own A/B test analysis
    customerTier: "enterprise", // useful for segmenting cost reports
    responseLatencyMs: 1243, // track performance alongside cost
  },
});

import Anthropic from "@anthropic-ai/sdk";
import { MarginFrontClient } from "@marginfront/sdk";

const anthropic = new Anthropic();
const mf = new MarginFrontClient(process.env.MF_API_SECRET_KEY);

async function sendColdOutreach(customerId: string, prospectQuery: string) {
  // Step 1: Find the prospect via Exa
  const exaResults = await exa.search({ query: prospectQuery, type: "people" });
  const prospect = exaResults.results[0];

  // Step 2: Enrich with verified email + role via Hunter.io
  const enrichment = await hunter.enrich({
    domain: prospect.domain,
    name: prospect.name,
  });

  // Step 3: Generate the personalized message with Claude Opus
  const llmResponse = await anthropic.messages.create({
    model: "claude-opus-4-1",
    max_tokens: 1500,
    messages: [
      {
        role: "user",
        content: `Write a personalized cold outreach to ${enrichment.name} at ${enrichment.company}, role: ${enrichment.role}.`,
      },
    ],
  });
  const message =
    llmResponse.content[0].type === "text" ? llmResponse.content[0].text : "";

  // Step 4: Send via Pipedream workflow
  await pipedream.invoke("send-cold-email", {
    to: enrichment.email,
    body: message,
  });

  // Step 5: Tell MarginFront about the WHOLE outreach (one event, four services)
  try {
    await mf.usage.record({
      customerExternalId: customerId,
      agentCode: "outreach-bot",
      signalName: "outreaches-sent",
      // Top-level quantity stays signal-level: ONE outreach to ONE prospect.
      // Per-service volume lives inside each services[] entry.
      quantity: 1,
      services: [
        {
          // Exa people-search API call
          model: "exa-search",
          modelProvider: "exa",
          quantity: 1, // 1 search call
        },
        {
          // Hunter.io enrichment call
          model: "hunter-enrich",
          modelProvider: "hunter",
          quantity: 1, // 1 enrichment call
        },
        {
          // Claude Opus writing the message. Track tokens AND the call count.
          model: llmResponse.model,
          modelProvider: "anthropic",
          inputTokens: llmResponse.usage.input_tokens,
          outputTokens: llmResponse.usage.output_tokens,
          quantity: 1, // 1 LLM call
        },
        {
          // Pipedream workflow firing the email
          model: "pipedream-workflow",
          modelProvider: "pipedream",
          quantity: 1, // 1 send
        },
      ],
    });
  } catch (error) {
    console.error("MarginFront tracking failed (non-blocking):", error);
  }

  return message;
}

services: [
  {
    model: "claude-opus-4-1",
    modelProvider: "anthropic",
    inputTokens: 4500,
    outputTokens: 800,
    quantity: 1,
  },
  {
    model: "claude-opus-4-1",
    modelProvider: "anthropic",
    inputTokens: 1200,
    outputTokens: 400,
    quantity: 1,
  },
];

services: [
  {
    model: "claude-opus-4-1",
    modelProvider: "anthropic",
    inputTokens: 5700, // 4500 + 1200
    outputTokens: 1200, // 800 + 400
    quantity: 2, // 2 LLM calls aggregated
  },
];

const response = await mf.usage.recordBatch([
  // LLM event
  {
    customerExternalId: "acme-001",
    agentCode: "cs-bot-v2",
    signalName: "messages",
    model: "gpt-4o",
    modelProvider: "openai",
    inputTokens: 523,
    outputTokens: 117,
  },
  // Non-LLM event (different customer, different agent)
  {
    customerExternalId: "beta-corp",
    agentCode: "notification-agent",
    signalName: "sms-sent",
    model: "sms-send",
    modelProvider: "twilio",
    quantity: 3,
  },
  // Another LLM event with metadata
  {
    customerExternalId: "acme-001",
    agentCode: "research-agent",
    signalName: "report-pages",
    model: "claude-sonnet-4-20250514",
    modelProvider: "anthropic",
    inputTokens: 4000,
    outputTokens: 6500,
    quantity: 12,
    metadata: { reportTopic: "Q2 market trends" },
  },
]);

const response = await mf.usage.recordBatch(records);

// Check if any events in the batch had problems
if (response.failed > 0) {
  console.warn(
    `${response.failed} of ${response.processed} events had issues:`,
  );

  for (const failure of response.results.failed) {
    // "error" tells you what went wrong in plain English
    console.warn(`  - ${failure.error}`);

    // "record" echoes back the original data so you can identify which event failed
    console.warn(`    Record:`, failure.record);
  }
}

// The rest of the batch still succeeded -- you don't need to resend the whole thing
console.log(`${response.successful} events recorded successfully`);

const mf = new MarginFrontClient(process.env.MF_API_SECRET_KEY, {
  fireAndForget: false, // Now usage.record() can throw errors
});

try {
  await mf.usage.record({
    customerExternalId: "acme-001",
    agentCode: "cs-bot-v2",
    signalName: "messages",
    model: "gpt-4o",
    modelProvider: "openai",
    inputTokens: 100,
    outputTokens: 50,
  });
} catch (error) {
  // With fireAndForget OFF, this catch block WILL run on network errors.
  // You're responsible for retrying or logging.
  console.error("Failed to record usage event:", error);
}

const response = await mf.usage.record({
  customerExternalId: "acme-001",
  agentCode: "cs-bot-v2",
  signalName: "messages",
  model: "my-custom-model",
  modelProvider: "custom",
  inputTokens: 500,
  outputTokens: 200,
});

// For single events, the response still tells you if there was a problem
if (response.failed > 0) {
  for (const failure of response.results.failed) {
    console.warn("Event issue:", failure.error);
  }
}

// Your core product logic -- this MUST work
const answer = await openai.chat.completions.create({ ... });

// Billing -- important but never more important than the answer
try {
  await mf.usage.record({ ... });
} catch (error) {
  // Log it. Investigate later. The customer got their answer.
  console.error('Usage tracking failed:', error);
}