Margovia client - Margovia

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.

​Constructor

​Options

​openai

​anthropic

​wrapOpenAI

​wrapAnthropic

​trackOpenAI

​trackAnthropic

​track

​canRun

​flush

​startRun

​trackCost

​trackOutcome

​Helpers