@alia.onl/sdk 15.7.0 → 19.0.0

package/src/runtime/thread/tool-cards.ts

@@ -0,0 +1,383 @@
+import type { AutomationTrigger, ToolInvocation } from '../types';
+
+/**
+ * The cards a tool result draws inside the assistant turn, as data.
+ *
+ * Everything here is pure: the snapshot the tool stored with the message goes
+ * in, and what Bloom's `LineChartCard`, `Card` and `Item` are handed comes
+ * out. A thread reopened next month shows the numbers it was answered with,
+ * because nothing is fetched — every range the card offers is already in the
+ * snapshot. The producers are `packages/api/src/lib/tools/{weather,market,
+ * faircoin}.ts` and the scheduling tool.
+ */
+
+type Translate = (key: string, params?: Record<string, string>) => string;
+
+/** The tool results that are a card rather than a step of the turn's work. */
+const CARD_TYPES = new Set(['weather', 'market', 'faircoin', 'scheduled-task']);
+
+export type ToolCard =
+  | { type: 'weather'; data: WeatherCardData }
+  | { type: 'market'; data: MarketCardData }
+  | { type: 'faircoin'; data: FairCoinCardData }
+  | { type: 'scheduled-task'; data: ScheduledTaskCardData };
+
+/**
+ * The card a finished call returned, if it is one this conversation draws.
+ *
+ * It checks the card's NAME, not the shape of its `data`, which is then cast
+ * unchecked — so each card renders inside its own error boundary, and the
+ * builders below guard every field they read.
+ */
+export function cardOf(t: ToolInvocation): ToolCard | null {
+  if (t.state !== 'result') return null;
+  const card = (t.result as { card?: { type?: string; data?: unknown } } | undefined)?.card;
+  if (card?.type === undefined || !CARD_TYPES.has(card.type) || !card.data) return null;
+  return { type: card.type, data: card.data } as ToolCard;
+}
+
+// ---------------------------------------------------------------------------
+//  Shared formatting
+// ---------------------------------------------------------------------------
+
+/** `[msSinceEpoch, price]`, exactly as the tool stored it. */
+export type PricePoint = [number, number];
+
+/** A coin worth 0.000023 is not "0.00", and one worth 60000 is not "60000.000000". */
+const priceDigits = (value: number) => (Math.abs(value) < 1 ? 6 : 2);
+
+/**
+ * ISO 4217 is three letters and `Intl` throws a `RangeError` on anything that
+ * is not. The currency arrives from whatever the reader typed, so a typo must
+ * not take the whole card down.
+ */
+const isCurrencyCode = (code: string) => /^[A-Za-z]{3}$/.test(code);
+
+export function formatPrice(value: number, currency: string, locale: string): string {
+  const options: Intl.NumberFormatOptions = {
+    minimumFractionDigits: 2,
+    maximumFractionDigits: priceDigits(value),
+  };
+  if (!isCurrencyCode(currency)) {
+    return `${value.toLocaleString(locale, options)} ${currency.toUpperCase()}`;
+  }
+  return value.toLocaleString(locale, {
+    ...options,
+    style: 'currency',
+    currency: currency.toUpperCase(),
+  });
+}
+
+/**
+ * The axis labels a price scale, not a currency: no symbol, compact, and three
+ * significant digits — the chart's axis is 44px wide, and "60,000" does not fit
+ * in it where "60K" does.
+ */
+const formatAxis = (value: number, locale: string) =>
+  value.toLocaleString(locale, { notation: 'compact', maximumSignificantDigits: 3 });
+
+/**
+ * The scale names go through a translation whole — Spanish "billón" is 10¹²,
+ * not 10⁹ — so a suffix is never appended in one language and reused in the
+ * next.
+ */
+const SCALES = [
+  { at: 1e12, key: 'trillion' },
+  { at: 1e9, key: 'billion' },
+  { at: 1e6, key: 'million' },
+  { at: 1e3, key: 'thousand' },
+] as const;
+
+function formatCompact(
+  value: number,
+  namespace: string,
+  locale: string,
+  t: Translate,
+  fallback: string,
+): string {
+  const scale = SCALES.find((s) => Math.abs(value) >= s.at);
+  if (!scale) return fallback;
+  return t(`${namespace}.scale.${scale.key}`, {
+    value: (value / scale.at).toLocaleString(locale, { maximumFractionDigits: 2 }),
+  });
+}
+
+/**
+ * A field the row did not carry reads the same as one that could not be
+ * priced: `null` from the tool, `undefined` from an older row and a `NaN` that
+ * survived a parse are all "no number".
+ */
+const quoted = (value: number | null | undefined): value is number =>
+  typeof value === 'number' && Number.isFinite(value);
+
+/** A series point as the chart reads it, labelled with its moment. */
+function toPoints(series: readonly PricePoint[], intraday: boolean, locale: string) {
+  return series.map(([at, value]) => ({
+    label: new Date(at).toLocaleString(
+      locale,
+      intraday
+        ? { hour: 'numeric', minute: '2-digit' }
+        : { day: 'numeric', month: 'short', year: 'numeric' },
+    ),
+    value,
+  }));
+}
+
+/** First-to-last change as a ratio, or none for a run that started at nothing. */
+function runDelta(series: readonly PricePoint[]): number | undefined {
+  const first = series[0][1];
+  const last = series[series.length - 1][1];
+  return first === 0 ? undefined : (last - first) / first;
+}
+
+export interface PriceChartRange {
+  id: string;
+  label: string;
+  data: { label: string; value: number }[];
+  headline: number;
+  delta?: number;
+}
+
+/** What `LineChartCard` is handed, plus the lines the card cannot draw itself. */
+export interface PriceChart {
+  title: string;
+  ranges: PriceChartRange[];
+  defaultRange: string;
+  format: (value: number) => string;
+  formatAxisValue: (value: number) => string;
+  /** Secondary lines under the chart, in reading order. */
+  notes: string[];
+}
+
+// ---------------------------------------------------------------------------
+//  Market
+// ---------------------------------------------------------------------------
+
+export interface MarketCardData {
+  id: string;
+  name: string;
+  symbol: string;
+  currency: string;
+  price?: number;
+  changePct?: number;
+  changeAbs?: number;
+  marketCap?: number;
+  volume24h?: number;
+  /** Optional per key: a row stored by an older version of the tool is not a crash. */
+  series: Record<string, PricePoint[] | undefined>;
+}
+
+/** The order the switcher offers, not the order the tool happens to store. */
+const MARKET_RANGES = ['1D', '5D', '1M', '6M', 'YTD', '1Y', '5Y', 'MAX'] as const;
+
+/**
+ * A quote as a line chart, or `null` when no range has two points to draw —
+ * the card then says the price in words.
+ *
+ * A range with one point cannot be drawn and a range with none was never
+ * stored, so neither is offered (YTD in the first days of January is the real
+ * case). 1D reports the tool's own change rather than the ends of the series,
+ * which starts whenever the window opened.
+ */
+export function marketChart(data: MarketCardData, t: Translate, locale: string): PriceChart | null {
+  const series = data.series ?? {};
+  const ranges: PriceChartRange[] = [];
+  for (const id of MARKET_RANGES) {
+    const run = series[id];
+    if (!run || run.length < 2) continue;
+    ranges.push({
+      id,
+      label: t(`market.range.${id}`),
+      data: toPoints(run, id === '1D', locale),
+      headline: quoted(data.price) ? data.price : run[run.length - 1][1],
+      delta: id === '1D' && quoted(data.changePct) ? data.changePct / 100 : runDelta(run),
+    });
+  }
+  if (ranges.length === 0) return null;
+
+  const format = (value: number) => formatPrice(value, data.currency, locale);
+  const compact = (value: number) => {
+    const scaled = formatCompact(value, 'market', locale, t, '');
+    return scaled === '' ? format(value) : `${scaled} ${data.currency.toUpperCase()}`;
+  };
+  const notes: string[] = [];
+  const intraday = (series['1D'] ?? []).map(([, price]) => price);
+  if (intraday.length >= 2) {
+    notes.push(
+      [
+        `${t('market.open')} ${format(intraday[0])}`,
+        `${t('market.dayHigh')} ${format(Math.max(...intraday))}`,
+        `${t('market.dayLow')} ${format(Math.min(...intraday))}`,
+      ].join(' · '),
+    );
+  }
+  const totals = [
+    quoted(data.volume24h) ? `${t('market.volume')} ${compact(data.volume24h)}` : null,
+    quoted(data.marketCap) ? `${t('market.marketCap')} ${compact(data.marketCap)}` : null,
+  ].filter((part): part is string => part !== null);
+  if (totals.length > 0) notes.push(totals.join(' · '));
+
+  return {
+    title: `${data.name} · ${data.symbol}`,
+    ranges,
+    defaultRange: ranges.some((r) => r.id === '1D') ? '1D' : ranges[0].id,
+    format,
+    formatAxisValue: (value) => formatAxis(value, locale),
+    notes,
+  };
+}
+
+// ---------------------------------------------------------------------------
+//  FairCoin
+// ---------------------------------------------------------------------------
+
+export interface FairCoinCardData {
+  /** `null` is a real answer: the pool had no indexed price when asked. */
+  price: number | null;
+  changePct: number | null;
+  volume24h: number | null;
+  liquidityUsd: number | null;
+  marketCapUsd: number | null;
+  /** Where the number came from, which is the one thing this card cannot drop. */
+  source: string;
+  updatedAt: string;
+  /**
+   * Absent key and empty array mean different things: the tool omits a period
+   * whose fetch failed, and stores `[]` for one with no samples yet.
+   */
+  series: Record<string, PricePoint[] | undefined>;
+}
+
+/** Exactly what the explorer retains, in the order the switcher offers them. */
+const FAIRCOIN_RANGES = ['24h', '7d', '30d', '1y', 'all'] as const;
+
+/**
+ * FairCoin's price as a line chart, with its provenance ALWAYS in the notes.
+ *
+ * FairCoin has no exchange listing: the price is GeckoTerminal's indexed price
+ * for a thin pool, so where it came from and when is printed in the reading
+ * order — a number off a thin pool that looks exactly like an exchange quote
+ * is the one thing this card must not ship. `chart` is `null` when no period
+ * has two samples; the notes still say why.
+ */
+export function faircoinChart(
+  data: FairCoinCardData,
+  t: Translate,
+  locale: string,
+): { chart: PriceChart | null; notes: string[] } {
+  const series = data.series ?? {};
+  const format = (value: number) => formatPrice(value, 'USD', locale);
+  const ranges: PriceChartRange[] = [];
+  for (const id of FAIRCOIN_RANGES) {
+    const run = series[id];
+    if (!run || run.length < 2) continue;
+    ranges.push({
+      id,
+      label: t(`faircoin.range.${id}`),
+      data: toPoints(run, id === '24h', locale),
+      headline: quoted(data.price) ? data.price : run[run.length - 1][1],
+      delta: id === '24h' && quoted(data.changePct) ? data.changePct / 100 : runDelta(run),
+    });
+  }
+
+  const notes: string[] = [t('faircoin.indexed')];
+  const at = Date.parse(data.updatedAt);
+  // An unparseable stamp is left out rather than printed raw: the source alone
+  // is still true.
+  notes.push(
+    [
+      t('faircoin.source', { source: data.source }),
+      Number.isNaN(at)
+        ? null
+        : t('faircoin.updated', {
+            time: new Date(at).toLocaleString(locale, { dateStyle: 'medium', timeStyle: 'short' }),
+          }),
+    ]
+      .filter((part): part is string => part !== null)
+      .join(' · '),
+  );
+  if (!quoted(data.price)) notes.push(t('faircoin.noPriceHint'));
+  // A period the explorer never answered for is named; one it answered with too
+  // few samples is said out loud, so neither reads as a period nobody asked about.
+  const missing = FAIRCOIN_RANGES.filter((id) => series[id] === undefined);
+  if (missing.length > 0) {
+    notes.push(
+      t('faircoin.unavailable', {
+        ranges: missing.map((id) => t(`faircoin.range.${id}`)).join(', '),
+      }),
+    );
+  }
+  if (ranges.length === 0 && missing.length < FAIRCOIN_RANGES.length) {
+    const anySample = FAIRCOIN_RANGES.some((id) => (series[id]?.length ?? 0) === 1);
+    notes.push(t(anySample ? 'faircoin.noChart' : 'faircoin.noSamples'));
+  }
+  // FairCoin's scale strings are SUFFIXES ("K", " mil"), unlike the market's
+  // templates, so the number is written here and the word appended.
+  const compact = (value: number) => {
+    const scale = SCALES.find((s) => Math.abs(value) >= s.at);
+    if (!scale) return format(value);
+    const short = (value / scale.at).toLocaleString(locale, { maximumFractionDigits: 2 });
+    return `$${short}${t(`faircoin.scale.${scale.key}`)}`;
+  };
+  const totals = [
+    quoted(data.volume24h) ? `${t('faircoin.volume')} ${compact(data.volume24h)}` : null,
+    quoted(data.liquidityUsd) ? `${t('faircoin.liquidity')} ${compact(data.liquidityUsd)}` : null,
+    quoted(data.marketCapUsd) ? `${t('faircoin.marketCap')} ${compact(data.marketCapUsd)}` : null,
+  ].filter((part): part is string => part !== null);
+  if (totals.length > 0) notes.push(totals.join(' · '));
+
+  if (ranges.length === 0) return { chart: null, notes };
+  return {
+    chart: {
+      title: `${t('faircoin.name')} · ${t('faircoin.symbol')}`,
+      ranges,
+      defaultRange: ranges.some((r) => r.id === '24h') ? '24h' : ranges[0].id,
+      format,
+      formatAxisValue: (value) => formatAxis(value, locale),
+      notes: [],
+    },
+    notes,
+  };
+}
+
+// ---------------------------------------------------------------------------
+//  Weather
+// ---------------------------------------------------------------------------
+
+export interface WeatherCardData {
+  place: string;
+  timezone: string;
+  current: { temperature: number; humidity: number; windSpeed: number; condition: string };
+  hourly: { time: string; temperature: number; precipitationChance: number }[];
+  daily: { date: string; condition: string; high: number; low: number }[];
+}
+
+/** Celsius on the wire; what the reader sees is their choice, not the answer's. */
+export type TemperatureUnit = 'C' | 'F';
+
+export const degrees = (celsius: number, unit: TemperatureUnit) =>
+  `${Math.round(unit === 'C' ? celsius : (celsius * 9) / 5 + 32)}°`;
+
+/**
+ * The weekday a forecast date names, in the reader's language.
+ *
+ * `YYYY-MM-DD` parses as UTC midnight, which is the previous evening west of
+ * Greenwich — so the day is read at noon UTC, which is the same calendar day
+ * everywhere a person lives.
+ */
+export function forecastWeekday(date: string, locale: string): string {
+  const at = Date.parse(`${date}T12:00:00Z`);
+  if (Number.isNaN(at)) return date;
+  return new Date(at).toLocaleDateString(locale, { weekday: 'short', timeZone: 'UTC' });
+}
+
+// ---------------------------------------------------------------------------
+//  Scheduled task
+// ---------------------------------------------------------------------------
+
+export interface ScheduledTaskCardData {
+  id: string;
+  objective: string;
+  enabled: boolean;
+  trigger: AutomationTrigger;
+}

package/src/runtime/turn-failure.ts

@@ -0,0 +1,108 @@
+/**
+ * A turn that did not get its answer, and what the thread shows for it.
+ *
+ * ## Why this is a thing at all
+ *
+ * A hosted-inference failure reaches the client as a typed error, never as
+ * an answer: on the open stream, an `{"error": {code, retryable, reference}}`
+ * frame and no stop chunk; before the stream opened, an HTTP 503/500 with the
+ * same envelope (`packages/api/src/routes/v1/chat-completions.ts`,
+ * `failTurn`). Older servers answered a failure BEFORE any output with HTTP
+ * 200 and an ordinary content delta — "all models are busy, try again in a few
+ * seconds" — flagged only by `alia_meta: { synthetic: true, retryable: true }`
+ * on the chunk; that flag is still read, so a stand-in is never rendered.
+ * Rendered as prose a stand-in reads as Alia declining; rolled back either
+ * vanishes with a toast, and once the toast is gone there is nothing on screen
+ * that says what happened or offers to try again.
+ *
+ * So a failed send keeps the person's turn in the thread and hangs this on it:
+ * a persistent error the row is drawn with, and the material a retry needs.
+ *
+ * ## What the server persists when the reply is synthetic — measured, not assumed
+ *
+ * Nothing. `saveConversationResult` is called from `lib/chat/provider-loop.ts`
+ * only after a stream COMPLETES (`:331`); every other exit returns
+ * `{ status: 'exhausted' }` (`:458`) or throws, and both the route's synthetic
+ * branch and its outer `catch` write the stand-in chunk without ever reaching
+ * the saver. So the user message of a failed turn is not in the database, and
+ * a retry can simply re-send it through the same path — no second user row is
+ * created because no first one was. (Were a turn ever saved before its tail
+ * failed, `saveConversation` converges storage on the client's history anyway,
+ * by full rewrite on divergence.)
+ */
+export interface FailedTurn {
+  /** The person's message the missing answer belonged to. */
+  userMessageId: string;
+  /**
+   * The row the error is drawn UNDER: the user message when nothing came
+   * back, or the assistant message when real output arrived before the tail
+   * failed — in which case the output is kept and the error sits after it.
+   */
+  anchorMessageId: string;
+  /** Whether trying again is offered. `false` when the server said so. */
+  retryable: boolean;
+  /** Real output arrived before the failure; the error is a tail, not the answer. */
+  partial: boolean;
+  /** The server's own words, when it sent any worth repeating. */
+  detail?: string;
+}
+
+/** What a chunk's `alia_meta` says about itself. */
+export interface AliaMeta {
+  /** The content is a stand-in the server wrote, not something the model said. */
+  synthetic: boolean;
+  /** Sending the same turn again is worth a try. Defaults to `true`. */
+  retryable: boolean;
+  /** Stable product error code; never an upstream/provider message. */
+  code?: string;
+  /** Safe Alia run identifier support can use to trace the failed turn. */
+  reference?: string;
+  retryAfter?: number;
+}
+
+/**
+ * Read `alia_meta` off a parsed stream chunk.
+ *
+ * Tolerant of every shape a chunk can have — no meta, meta with only one of
+ * the flags, a non-object where an object was expected — because this runs
+ * on every content delta and a throw here would take the whole stream down.
+ */
+export function readAliaMeta(chunk: unknown): AliaMeta {
+  const meta = (chunk as { alia_meta?: unknown } | null | undefined)?.alia_meta;
+  if (meta === null || typeof meta !== 'object') {
+    return { synthetic: false, retryable: true };
+  }
+  const { synthetic, retryable, error } = meta as {
+    synthetic?: unknown;
+    retryable?: unknown;
+    error?: unknown;
+  };
+  const failure =
+    error !== null && typeof error === 'object'
+      ? (error as { code?: unknown; reference?: unknown; retryAfter?: unknown })
+      : null;
+  return {
+    synthetic: synthetic === true,
+    retryable: retryable !== false,
+    ...(typeof failure?.code === 'string' ? { code: failure.code } : {}),
+    ...(typeof failure?.reference === 'string' ? { reference: failure.reference } : {}),
+    ...(typeof failure?.retryAfter === 'number' ? { retryAfter: failure.retryAfter } : {}),
+  };
+}
+
+/**
+ * The line under a failed turn's card: the stable code and the run reference.
+ *
+ * Never the server's prose. The card's own line is the app's, in the reader's
+ * language; this is what support needs, and both halves are language-free.
+ * Empty when the server sent neither.
+ */
+export function failureDetail(failure: { code?: string; reference?: string }): string | undefined {
+  const detail = [
+    failure.code,
+    failure.reference === undefined ? undefined : `Ref ${failure.reference}`,
+  ]
+    .filter((value): value is string => typeof value === 'string' && value !== '')
+    .join(' · ');
+  return detail === '' ? undefined : detail;
+}

package/src/runtime/types.ts

@@ -0,0 +1,148 @@
+import type { MessagePlan, ResearchProgress } from '../types';
+
+/**
+ * The canonical tool invocation: streaming, the conversation hooks and the
+ * thread UI all read this one shape.
+ */
+export interface ToolInvocation {
+  toolCallId: string;
+  toolName: string;
+  state: 'partial-call' | 'call' | 'result';
+  args?: Record<string, unknown>;
+  // Tool output is dynamically shaped per tool and consumed structurally
+  // (e.g. `result.results`, `result.url`) by the thread UI; typing it more
+  // narrowly would require validating every tool's output shape.
+  // biome-ignore lint/suspicious/noExplicitAny: structural per-tool output, see above
+  result?: any;
+}
+
+/** What a message carries to the model: plain text, or multi-part once images are attached. */
+export type MessageContent = string | Array<{ type: string; [key: string]: unknown }>;
+
+export interface Message {
+  id: string;
+  role: 'user' | 'assistant' | 'system';
+  content: MessageContent;
+  /** Extended thinking content (when thinking mode is enabled). */
+  thinking?: string;
+  toolInvocations?: ToolInvocation[];
+  /** Voice fields (optional, only present for voice-originated messages). */
+  source?: 'text' | 'voice';
+  /** Speaker identity in voice mode. */
+  speaker?: 'primary';
+  /**
+   * The turn is being streamed into this message right now.
+   *
+   * Set by `useConversationStream` on the assistant placeholder it appends and
+   * cleared by it when the stream ends, whichever way it ends; voice sets it
+   * on its own rows. Absent on a message read back from the server.
+   */
+  isStreaming?: boolean;
+  /**
+   * How the turn that wrote this message ended, once it has: on its own
+   * (`completed`), on an error (`failed`), or because the person stopped it
+   * (`cancelled`). Stamped by `useConversationStream` alongside clearing
+   * `isStreaming`, and absent on a message the server sent.
+   */
+  turnOutcome?: 'completed' | 'failed' | 'cancelled';
+  /**
+   * The server does not hold this message yet, so nothing can be addressed to
+   * it by id — a vote, a read-aloud clip stored on it.
+   *
+   * Set on every message of a turn the stream sends (the question, the reply,
+   * a delegated agent's answer) and cleared when that turn completes, which is
+   * when the server has stored it under these same ids. A turn that failed or
+   * was stopped keeps it.
+   */
+  unsaved?: true;
+  /**
+   * The consulted agent that wrote this message (`consultAgent`, ADR 0020 §5): one message per
+   * consultation, drawn under the agent's own identity.
+   *
+   * `character` is the agent's look as the server stores it (JSON), parsed
+   * where it is drawn; absent, the default look.
+   */
+  agentInfo?: {
+    id: string;
+    name: string;
+    character?: unknown;
+    handle?: string;
+    color?: string;
+  };
+  /**
+   * When the message was written, ISO — what the date separators are derived
+   * from, in the reader's own timezone. Absent means the turn has not been
+   * persisted yet and carries no stamp of its own.
+   */
+  createdAt?: string;
+  // Streaming UI metadata (deep research, plan preview)
+  researchProgress?: ResearchProgress;
+  plan?: MessagePlan;
+}
+
+export interface Conversation {
+  id: string;
+  title: string;
+  lastMessage?: string;
+  source?: string;
+  /**
+   * The agent this conversation is a stretch of, or none.
+   *
+   * NULLABLE, not optional-absent: the column is `agent_id text` and the list
+   * route sends `c.agentId` straight through, so an ordinary conversation
+   * arrives carrying an explicit `null`.
+   */
+  agentId?: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+  messages: Message[];
+}
+
+/** The run a delegated agent started for a turn: its session is `turnId`, in the agent's own room. */
+export interface AgentRun {
+  turnId: string;
+  agentId: string;
+}
+
+/** One page of the paginated conversation list. */
+export interface ConversationsPage {
+  conversations: Conversation[];
+  nextCursor: string | null;
+  hasMore: boolean;
+}
+
+/** React Query infinite-query cache shape for the conversation list. */
+export interface ConversationsInfiniteData {
+  pages: ConversationsPage[];
+  pageParams: unknown[];
+}
+
+/** What a chat turn is sent with. */
+export interface SendOptions {
+  /** `null` explicitly withholds MCP tools; omission preserves legacy callers. */
+  mcpServerId?: string | null;
+  /**
+   * The skills chosen for THIS message, by name. Per turn rather than per
+   * session; omitted means the person chose none.
+   */
+  skillNames?: string[];
+}
+
+/** A resource an automation acts on or listens to. */
+export interface AutomationResource {
+  appId: string;
+  effectiveAccountId: string;
+  resourceType: string;
+  resourceId: string;
+}
+
+/** What starts a scheduled task. */
+export type AutomationTrigger =
+  | { type: 'manual' }
+  | {
+      type: 'event';
+      appId: string | null;
+      eventType: string | null;
+      resource?: AutomationResource | null;
+    }
+  | { type: 'schedule'; cron: string | null; timezone: string | null };

package/src/runtime/usage-limit-error.ts

@@ -0,0 +1,44 @@
+export type UsageLimitType = 'credits' | 'rate_limit' | 'model_access';
+
+export interface UsageLimitDetails {
+  type: UsageLimitType;
+  code: string;
+  message: string;
+  retryable: boolean;
+  retryAfterSeconds?: number;
+  suggestedAction?: 'upgrade' | 'wait';
+  limitType?: string;
+  current?: number;
+  limit?: number;
+  tier?: string;
+}
+
+export class UsageLimitError extends Error {
+  public details: UsageLimitDetails;
+
+  constructor(details: UsageLimitDetails) {
+    super(details.message);
+    this.name = 'UsageLimitError';
+    this.details = details;
+  }
+
+  get isCreditsError(): boolean {
+    return this.details.type === 'credits';
+  }
+
+  get isRateLimitError(): boolean {
+    return this.details.type === 'rate_limit';
+  }
+
+  get isModelAccessError(): boolean {
+    return this.details.type === 'model_access';
+  }
+
+  get shouldShowUpgrade(): boolean {
+    return (
+      this.details.suggestedAction === 'upgrade' ||
+      this.details.type === 'credits' ||
+      this.details.type === 'model_access'
+    );
+  }
+}