Skip to main content

​
StartRunInput

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

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

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

​
CompleteRunInput

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

​
FailRunInput

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

​
GuardrailCheckInput

type GuardrailCheckInput = {
  name: string;
  userId?: string;
  customerId?: string;
  estimatedCostUsd?: number;
};
Used by margovia.canRun(...) to check active budgets before running expensive work.

​
GuardrailCheckResult

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

type TrackedProviderCallInput<TRequest> = StartRunInput & {
  outcome?: string;
  request: TRequest;
};
Used by margovia.openai(client) and margovia.anthropic(client). 
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

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

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. 
customer({
  id: 42,
  prefix: "workspace",
  name: "Northstar Agency",
  plan: { name: "pro", monthlyUsd: 99 }
});
This produces: 
{
  customerId: "workspace_42",
  customerName: "Northstar Agency",
  customerPlan: { name: "pro", monthlyUsd: 99 }
}