> ## 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.

# Types

> Public TypeScript input types exported by the SDK.

## `StartRunInput`

```ts theme={null}
type StartRunInput = {
  name: string;
  userId?: string;
  customerId?: string;
  customerName?: string;
  customerPlan?: string | { name: string; monthlyUsd: number };
  properties?: Record<string, unknown>;
  budgetUsd?: number;
  startedAt?: string;
};
```

`customerId` is your stable customer, workspace, organization, tenant, or billing customer key. Prefer namespaced values such as `workspace_123`, `org_abc`, or `stripe_cus_123`. Margovia stores this value exactly as sent.

## `TrackCostInput`

```ts theme={null}
type TrackCostInput = {
  runId: string;
  provider: string;
  label?: string;
  model?: string;
  inputTokens?: number;
  outputTokens?: number;
  cacheCreationInputTokens?: number;
  cacheCreationInputTokens5m?: number;
  cacheCreationInputTokens1h?: number;
  cachedInputTokens?: number;
  reasoningTokens?: number;
  costUsd?: number;
  latencyMs?: number;
  status?: string;
  completeRun?: boolean;
  outcome?: string;
  metadata?: Record<string, unknown>;
  createdAt?: string;
};
```

Use `completeRun` only when a cost event is also the terminal event for the run. Tracked clients, provider helpers, and wrapped provider calls use this internally for one-call workflows. For multi-step workflows, complete the run after all steps finish.

## `TrackOutcomeInput`

```ts theme={null}
type TrackOutcomeInput = {
  runId: string;
  outcome: string;
  valueUsd?: number;
  metadata?: Record<string, unknown>;
  createdAt?: string;
};
```

## `CompleteRunInput`

```ts theme={null}
type CompleteRunInput = {
  outcome?: string;
  metadata?: Record<string, unknown>;
  completedAt?: string;
};
```

## `FailRunInput`

```ts theme={null}
type FailRunInput = {
  error?: string;
  metadata?: Record<string, unknown>;
  completedAt?: string;
};
```

## `GuardrailCheckInput`

```ts theme={null}
type GuardrailCheckInput = {
  name: string;
  userId?: string;
  customerId?: string;
  estimatedCostUsd?: number;
};
```

Used by `margovia.canRun(...)` to check active budgets before running expensive work.

## `GuardrailCheckResult`

```ts theme={null}
type GuardrailCheckResult = {
  allowed: boolean;
  status: "allow" | "warn" | "block";
  checks: Array<{
    budgetId: string;
    scopeType: "project" | "workflow" | "customer" | "user";
    scopeValue?: string;
    period: "run" | "day" | "month";
    mode: "warn" | "soft_stop" | "hard_stop";
    limitUsd: number;
    currentSpendUsd: number;
    estimatedCostUsd: number;
    projectedSpendUsd: number;
    usage: number;
    status: "allow" | "warn" | "block";
  }>;
};
```

## `TrackedProviderCallInput`

```ts theme={null}
type TrackedProviderCallInput<TRequest> = StartRunInput & {
  outcome?: string;
  request: TRequest;
};
```

Used by `margovia.openai(client)` and `margovia.anthropic(client)`.

```ts theme={null}
await anthropic.messages.create({
  name: "score_tweet",
  customerId: "workspace_123",
  outcome: "tweet_scored",
  request: {
    model: "claude-sonnet-4-20250514",
    max_tokens: 800,
    messages
  }
});
```

`request` is the real provider request. Margovia run fields, such as `name`, `customerId`, `customerName`, and `outcome`, live beside `request`.

## `TrackProviderInput`

```ts theme={null}
type TrackProviderInput<TRequest, TResponse> = StartRunInput & {
  outcome?: string;
  request?: TRequest;
  fn: () => PromiseLike<TResponse> | TResponse;
};
```

Used by `trackOpenAI(...)` and `trackAnthropic(...)`. The SDK preserves the response type returned by `fn`.

## `CustomerInput`

```ts theme={null}
type CustomerInput = {
  id: string | number;
  name?: string | null;
  plan?: string | { name: string; monthlyUsd: number };
  planName?: string | null;
  monthlyUsd?: number | null;
  prefix?: string;
};
```

Used by the `customer(...)` helper to build `customerId`, `customerName`, and `customerPlan`.

```ts theme={null}
customer({
  id: 42,
  prefix: "workspace",
  name: "Northstar Agency",
  plan: { name: "pro", monthlyUsd: 99 }
});
```

This produces:

```ts theme={null}
{
  customerId: "workspace_42",
  customerName: "Northstar Agency",
  customerPlan: { name: "pro", monthlyUsd: 99 }
}
```