> ## Documentation Index
> Fetch the complete documentation index at: https://docs.margovia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Margovia client

> Constructor and methods on the Margovia SDK client.

## Constructor

```ts theme={null}
new Margovia(options?: MargoviaOptions)
```

### Options

```ts theme={null}
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`

```ts theme={null}
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`

```ts theme={null}
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`

```ts theme={null}
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`

```ts theme={null}
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`

```ts theme={null}
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`

```ts theme={null}
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`

```ts theme={null}
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`

```ts theme={null}
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`

```ts theme={null}
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`

```ts theme={null}
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`

```ts theme={null}
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`

```ts theme={null}
await margovia.trackOutcome(input: TrackOutcomeInput)
```

Records an outcome for an existing run.

## Helpers

```ts theme={null}
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`.