AI SDK

better-supabase/ai-sdk connects the AI SDK to the AI chat block. The block stores messages in its own format and never imports an SDK; this adapter converts AI SDK messages to that format and back, and adds the AI Gateway helpers the assistant uses. It owns no tables.

pnpm add ai @ai-sdk/react

ai (7), @ai-sdk/react (4) and @ai-sdk/mcp (2) are optional peers: install them only in the apps that use these subpaths.

MessagesCopy Anchor Link

import { fromUIMessage, toUIMessages } from "better-supabase/ai-sdk";

const stored = fromUIMessage(uiMessage); // an AiMessage for the block
const path = await aiChat.messages.path(chatId, { native: true }).orThrow();
const messages = toUIMessages(path); // UIMessage[] for useChat

toUIMessage returns the stored AI SDK copy (native) when the adapter wrote the message, so nothing is lost on the round trip. A message another SDK wrote is converted from its parts:

A tool message's results join the tool parts of the assistant message before it, the way useChat expects them. A UI part with no canonical counterpart is stored as a data part (ui.custom or ui.reasoning-file) and comes back unchanged.

AI GatewayCopy Anchor Link

Models are provider/model strings for the AI Gateway. gatewayOptions attributes spend to the user, the tenant and the chat:

import { streamText } from "ai";
import { gatewayOptions, usageOf } from "better-supabase/ai-sdk";

const result = streamText({
  model: "anthropic/claude-sonnet-4.5",
  messages,
  providerOptions: gatewayOptions({
    userId,
    organizationId,
    chatId,
    feature: "chat",
  }),
});

const usage = usageOf({
  totalUsage: await result.totalUsage,
  providerMetadata: await result.providerMetadata,
});

usageOf returns the token counts, the gateway's generationId and the cost in micro-dollars when the gateway reported it. usageEntries(usage) turns it into entries for the usage block (ai.input_tokens and ai.output_tokens by default), and usageQuota(usage, meter) is the quota check createAssistant takes: it returns a quota_exceeded error with retryAfter when the meter is used up. problem429(error) is the RFC 9457 response for it, with Retry-After.

JobsCopy Anchor Link

Two job handlers keep the block current:

import { gateway } from "ai";
import { costBackfill, modelCatalogRefresh } from "better-supabase/ai-sdk";

export const handlers = {
  "ai.cost_backfill": costBackfill({
    chats: aiChat,
    gateway,
    usage,
    meter: "ai.cost",
  }),
  "ai.model_catalog": modelCatalogRefresh({
    chats: aiChat,
    gateway,
    prune: true,
  }),
};

costBackfill reads the exact cost from gateway.getGenerationInfo once the gateway has it, writes it to the run (runs.setCost) and, with usage, records it once per generation. createAssistant enqueues it when the answer arrives without a cost. modelCatalogRefresh copies gateway.getAvailableModels() into ai_model_catalog, language models by default, with plans deciding which entitlements may use each model. Run it on a schedule.