Skip to main content

​
Constructor

new Margovia(options?: MargoviaOptions)

​
Options

type MargoviaOptions = {
  apiKey?: string;
  baseUrl?: string;
  timeoutMs?: number;
  debug?: boolean;
};
If omitted, the client reads:
  • MARGOVIA_API_KEY
  • MARGOVIA_BASE_URL
  • MARGOVIA_DEBUG
Installing the SDK alone sends nothing. Without MARGOVIA_API_KEY, the client skips Margovia tracking. With MARGOVIA_API_KEY, it sends to Margovia Cloud unless baseUrl or MARGOVIA_BASE_URL points at a self-hosted or compatible receiver.

​
openai

const openai = margovia.openai(client);

await openai.chat.completions.create({
  name: "support_reply",
  customerId: "workspace_123",
  request: {
    model: "gpt-5-mini",
    messages
  }
});
Creates a tracked OpenAI client. The tracked client starts a run, calls client.chat.completions.create(request), records cost from the response usage, and completes or fails the run. Use this for the simplest one-call OpenAI integration.

​
anthropic

const anthropic = margovia.anthropic(client);

await anthropic.messages.create({
  name: "score_tweet",
  customerId: "workspace_123",
  request: {
    model: "claude-sonnet-4-20250514",
    max_tokens: 800,
    messages
  }
});
Creates a tracked Anthropic client. The tracked client starts a run, calls client.messages.create(request), records cost from the response usage, and completes or fails the run. Use this for the simplest one-call Anthropic integration.

​
wrapOpenAI

const openai = margovia.wrapOpenAI(client, options);
Wraps client.chat.completions.create. With autoTrack: true, the wrapper starts a run, records the provider cost event, and completes the run after the provider call succeeds.

​
wrapAnthropic

const anthropic = margovia.wrapAnthropic(client, options);
Wraps client.messages.create. With autoTrack: true, the wrapper starts a run, records the provider cost event, and completes the run after the provider call succeeds.

​
trackOpenAI

await margovia.trackOpenAI({
  name: "support_reply",
  customerId: "workspace_123",
  request: { model: "gpt-5-mini" },
  fn: () => openai.chat.completions.create({ model: "gpt-5-mini", messages })
});
Starts a run, calls your function, reads OpenAI response usage, records a cost event, then completes or fails the run. Use this when you prefer an explicit helper around one provider call.

​
trackAnthropic

await margovia.trackAnthropic({
  name: "score_tweet",
  customerId: "workspace_123",
  request: params,
  fn: () => anthropic.messages.create(params)
});
Starts a run, calls your function, reads Anthropic response usage, records a cost event, then completes or fails the run. Use this when you prefer an explicit helper around one provider call.

​
track

await margovia.track({
  name: "weekly_report",
  customerId: "workspace_123",
  outcome: "report_generated",
  fn: async () => doWork()
});
Wraps a function in a run. The run is completed on success and failed on error. track does not extract provider token usage by itself. Use tracked or wrapped provider clients inside fn, call trackOpenAI(...) or trackAnthropic(...), or manually report cost.

​
canRun

await margovia.canRun({
  name: "support_reply",
  customerId: "workspace_123",
  estimatedCostUsd: 0.05
});
Checks active Margovia budgets before running expensive work. This is advisory until hard/soft stop enforcement is enabled in your product.

​
flush

await margovia.flush();
Waits for in-flight SDK requests to settle. Most SDK calls are awaited already, but flush is useful before a short-lived process exits.

​
startRun

await margovia.startRun(input: StartRunInput)
Starts a run and returns a MargoviaRun. Manual runs stay running until run.complete(...) or run.fail(...) is called.

​
trackCost

await margovia.trackCost(input: TrackCostInput)
Records a cost event for an existing run. Cost events do not close manual runs unless completeRun: true is explicitly sent. In normal manual workflows, call run.complete(...) after all work is finished.

​
trackOutcome

await margovia.trackOutcome(input: TrackOutcomeInput)
Records an outcome for an existing run.

​
Helpers

import { customer, user } from "@margovia/sdk";

await margovia.track({
  name: "support_reply",
  ...customer({
    id: workspace.id,
    prefix: "workspace",
    name: workspace.name,
    plan: { name: "pro", monthlyUsd: 99 }
  }),
  ...user({ id: actor.id }),
  fn: () => doWork()
});
customer(...) and user(...) help create stable namespaced IDs such as workspace_123 and user_456.