@lastbrain/module-ai 2.0.26 → 2.0.30

package/supabase/migrations/20260123100002_user_token_quota_monthly copy.sql

@@ -0,0 +1,173 @@
+-- ===========================================================================
+-- Module: @lastbrain/module-ai
+-- Migration: 20251217120000_user_token_quota_monthly.sql
+-- Description: Monthly token quota for Pro plan (non-cumulative)
+-- ===========================================================================
+
+-- ===========================================================================
+-- Table: public.user_token_quota_monthly
+-- Manages monthly included tokens for subscription plans (Pro, Premium, etc.)
+-- Separate from purchased tokens (user_token_ledger)
+-- ===========================================================================
+CREATE TABLE IF NOT EXISTS public.user_token_quota_monthly (
+  owner_id uuid PRIMARY KEY REFERENCES auth.users(id) ON DELETE CASCADE,
+  
+  -- Plan information
+  plan text NOT NULL DEFAULT 'free', -- 'free', 'pro', 'premium', etc.
+  
+  -- Quota configuration
+  default_included_tokens bigint NOT NULL DEFAULT 0, -- Default tokens for plan
+  custom_included_tokens bigint NULL, -- Admin override (nullable)
+  effective_included_tokens bigint NOT NULL DEFAULT 0, -- Actual quota for period
+  
+  -- Usage tracking
+  used_included_tokens bigint NOT NULL DEFAULT 0, -- Tokens consumed this period
+  
+  -- Period management (from Stripe subscription)
+  period_start timestamptz NULL,
+  period_end timestamptz NULL,
+  
+  -- Metadata
+  subscription_id text NULL, -- Stripe subscription ID
+  source text NOT NULL DEFAULT 'stripe', -- 'stripe', 'manual', etc.
+  
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  
+  -- Constraints
+  CHECK (used_included_tokens >= 0),
+  CHECK (used_included_tokens <= effective_included_tokens),
+  CHECK (default_included_tokens >= 0),
+  CHECK (custom_included_tokens IS NULL OR custom_included_tokens >= 0),
+  CHECK (effective_included_tokens >= 0)
+);
+
+-- ===========================================================================
+-- Indexes
+-- ===========================================================================
+CREATE INDEX IF NOT EXISTS idx_user_token_quota_monthly_owner ON public.user_token_quota_monthly(owner_id);
+CREATE INDEX IF NOT EXISTS idx_user_token_quota_monthly_plan ON public.user_token_quota_monthly(plan);
+CREATE INDEX IF NOT EXISTS idx_user_token_quota_monthly_period ON public.user_token_quota_monthly(period_start, period_end);
+CREATE INDEX IF NOT EXISTS idx_user_token_quota_monthly_subscription ON public.user_token_quota_monthly(subscription_id) WHERE subscription_id IS NOT NULL;
+
+-- ===========================================================================
+-- Table: public.user_token_quota_ledger
+-- Audit log for quota usage (separate from purchased tokens)
+-- ===========================================================================
+CREATE TABLE IF NOT EXISTS public.user_token_quota_ledger (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  owner_id uuid NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
+  
+  -- Usage details
+  tokens_used bigint NOT NULL CHECK (tokens_used > 0), -- Always positive
+  model text NULL, -- AI model used
+  prompt text NULL, -- Prompt used
+  
+  -- Context
+  period_start timestamptz NOT NULL, -- Period this usage belongs to
+  period_end timestamptz NOT NULL,
+  
+  -- Metadata
+  meta jsonb NOT NULL DEFAULT '{}'::jsonb,
+  
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+-- ===========================================================================
+-- Indexes for ledger
+-- ===========================================================================
+CREATE INDEX IF NOT EXISTS idx_user_token_quota_ledger_owner ON public.user_token_quota_ledger(owner_id);
+CREATE INDEX IF NOT EXISTS idx_user_token_quota_ledger_owner_created ON public.user_token_quota_ledger(owner_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_user_token_quota_ledger_period ON public.user_token_quota_ledger(period_start, period_end);
+
+-- ===========================================================================
+-- RLS (Row Level Security) - user_token_quota_monthly
+-- ===========================================================================
+ALTER TABLE public.user_token_quota_monthly ENABLE ROW LEVEL SECURITY;
+
+-- Users can view their own quota
+DROP POLICY IF EXISTS user_token_quota_monthly_select_own ON public.user_token_quota_monthly;
+CREATE POLICY user_token_quota_monthly_select_own
+  ON public.user_token_quota_monthly
+  FOR SELECT
+  USING (
+    owner_id = (SELECT auth.uid())
+    OR is_superadmin((SELECT auth.uid()))
+  );
+
+-- Only superadmins can insert/update/delete
+DROP POLICY IF EXISTS user_token_quota_monthly_admin_all ON public.user_token_quota_monthly;
+CREATE POLICY user_token_quota_monthly_admin_all
+  ON public.user_token_quota_monthly
+  FOR ALL
+  USING (is_superadmin((SELECT auth.uid())));
+
+-- ===========================================================================
+-- RLS (Row Level Security) - user_token_quota_ledger
+-- ===========================================================================
+ALTER TABLE public.user_token_quota_ledger ENABLE ROW LEVEL SECURITY;
+
+-- Users can view their own quota usage history
+DROP POLICY IF EXISTS user_token_quota_ledger_select_own ON public.user_token_quota_ledger;
+CREATE POLICY user_token_quota_ledger_select_own
+  ON public.user_token_quota_ledger
+  FOR SELECT
+  USING (
+    owner_id = (SELECT auth.uid())
+    OR is_superadmin((SELECT auth.uid()))
+  );
+
+-- Service role can insert (via API)
+-- No direct user insert allowed
+
+-- Only superadmins can update/delete
+DROP POLICY IF EXISTS user_token_quota_ledger_admin_all ON public.user_token_quota_ledger;
+CREATE POLICY user_token_quota_ledger_admin_all
+  ON public.user_token_quota_ledger
+  FOR ALL
+  USING (is_superadmin((SELECT auth.uid())));
+
+-- ===========================================================================
+-- Trigger for updated_at
+-- ===========================================================================
+DROP TRIGGER IF EXISTS set_user_token_quota_monthly_updated_at ON public.user_token_quota_monthly;
+CREATE TRIGGER set_user_token_quota_monthly_updated_at
+  BEFORE UPDATE ON public.user_token_quota_monthly
+  FOR EACH ROW
+  EXECUTE FUNCTION public.set_updated_at();
+
+-- ===========================================================================
+-- Helper function: Get plan default quota
+-- ===========================================================================
+CREATE OR REPLACE FUNCTION public.get_plan_default_tokens(plan_name text)
+RETURNS bigint
+LANGUAGE plpgsql
+STABLE
+AS $$
+BEGIN
+  RETURN CASE plan_name
+    WHEN 'pro' THEN 100000
+    WHEN 'premium' THEN 500000
+    WHEN 'enterprise' THEN 2000000
+    ELSE 0
+  END;
+END;
+$$;
+
+-- ===========================================================================
+-- Grants
+-- ===========================================================================
+GRANT SELECT ON public.user_token_quota_monthly TO authenticated;
+GRANT SELECT ON public.user_token_quota_ledger TO authenticated;
+GRANT ALL ON public.user_token_quota_monthly TO service_role;
+GRANT ALL ON public.user_token_quota_ledger TO service_role;
+
+-- ===========================================================================
+-- Comments
+-- ===========================================================================
+COMMENT ON TABLE public.user_token_quota_monthly IS 'Monthly token quota for subscription plans (non-cumulative, resets each period)';
+COMMENT ON TABLE public.user_token_quota_ledger IS 'Audit log for monthly quota usage (separate from purchased tokens)';
+COMMENT ON COLUMN public.user_token_quota_monthly.default_included_tokens IS 'Default tokens for the plan (100K for Pro, 500K for Premium)';
+COMMENT ON COLUMN public.user_token_quota_monthly.custom_included_tokens IS 'Admin override for custom quota per owner';
+COMMENT ON COLUMN public.user_token_quota_monthly.effective_included_tokens IS 'Actual quota for current period (custom or default)';
+COMMENT ON COLUMN public.user_token_quota_monthly.used_included_tokens IS 'Tokens consumed from quota this period';

package/supabase/migrations/20260128100003_update_and_add_table.sql

@@ -0,0 +1,368 @@
+-- module-ai: add external API primitives (api keys, AI settings, call logs)
+-- and extend token ledgers for multi-provider usage.
+
+begin;
+
+-- -----------------------------------------------------------------------------
+-- 1) Fix user_token_ledger type check (allow signup_bonus)
+-- -----------------------------------------------------------------------------
+alter table public.user_token_ledger
+  drop constraint if exists user_token_ledger_type_check;
+
+alter table public.user_token_ledger
+  add constraint user_token_ledger_type_check
+  check (
+    type = any (
+      array[
+        'purchase'::text,
+        'gift'::text,
+        'use'::text,
+        'adjust'::text,
+        'signup_bonus'::text
+      ]
+    )
+  );
+
+-- -----------------------------------------------------------------------------
+-- 2) Add provider columns to ledgers (for multi-provider routing)
+-- -----------------------------------------------------------------------------
+alter table public.user_token_ledger
+  add column if not exists provider text null;
+
+alter table public.user_token_quota_ledger
+  add column if not exists provider text null;
+
+-- Helpful indexes for provider/model breakdowns
+create index if not exists idx_user_token_ledger_owner_provider_ts
+  on public.user_token_ledger (owner_id, provider, ts desc);
+
+create index if not exists idx_user_token_quota_ledger_owner_provider_created
+  on public.user_token_quota_ledger (owner_id, provider, created_at desc);
+
+-- -----------------------------------------------------------------------------
+-- 3) API Keys table (external access)
+-- -----------------------------------------------------------------------------
+create table if not exists public.api_keys (
+  id uuid primary key default gen_random_uuid(),
+  owner_id uuid not null references auth.users(id) on delete cascade,
+
+  -- Display name for dashboard
+  name text not null,
+
+  -- Never store the raw key. Store only a hash + a small prefix for UI.
+  key_hash text not null,
+  prefix text not null,
+
+  -- dev/prod segregation
+  env text not null default 'prod',
+
+  -- scopes like ["text","image","status","metrics"]
+  scopes jsonb not null default '[]'::jsonb,
+
+  -- safety limits (enforced server-side)
+  rate_limit_rpm integer not null default 60,
+  daily_token_limit bigint null,
+
+  is_active boolean not null default true,
+  last_used_at timestamptz null,
+
+  created_at timestamptz not null default now()
+);
+
+create unique index if not exists idx_api_keys_key_hash_unique
+  on public.api_keys (key_hash);
+
+create index if not exists idx_api_keys_owner
+  on public.api_keys (owner_id);
+
+create index if not exists idx_api_keys_owner_created
+  on public.api_keys (owner_id, created_at desc);
+
+create index if not exists idx_api_keys_prefix
+  on public.api_keys (prefix);
+
+-- -----------------------------------------------------------------------------
+-- 4) User AI settings (default provider/model + limits)
+-- -----------------------------------------------------------------------------
+create table if not exists public.user_ai_settings (
+  owner_id uuid primary key references auth.users(id) on delete cascade,
+
+  mode text not null default 'auto',
+
+  default_text_provider text null,
+  default_text_model text null,
+
+  default_image_provider text null,
+  default_image_model text null,
+
+  max_tokens_per_call integer null,
+
+  -- optional allowlist: [{"provider":"openai","models":[...]}]
+  allowed_models jsonb not null default '[]'::jsonb,
+
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now()
+);
+
+create index if not exists idx_user_ai_settings_mode
+  on public.user_ai_settings (mode);
+
+-- -----------------------------------------------------------------------------
+-- 5) AI call log (observability + usage breakdown)
+--    Note: do NOT store raw prompts/payloads here.
+-- -----------------------------------------------------------------------------
+create table if not exists public.ai_call_log (
+  id uuid primary key default gen_random_uuid(),
+  owner_id uuid not null references auth.users(id) on delete cascade,
+  api_key_id uuid null references public.api_keys(id) on delete set null,
+
+  endpoint text not null, -- text|image|status|metrics
+  provider text null,
+  model text null,
+
+  tokens_in integer null,
+  tokens_out integer null,
+  tokens_total integer null,
+
+  latency_ms integer null,
+  status_code integer not null default 200,
+  error_code text null,
+
+  -- safe metadata only (request_id, sizes, etc.)
+  meta jsonb not null default '{}'::jsonb,
+
+  created_at timestamptz not null default now()
+);
+
+create index if not exists idx_ai_call_log_owner_created
+  on public.ai_call_log (owner_id, created_at desc);
+
+create index if not exists idx_ai_call_log_owner_model
+  on public.ai_call_log (owner_id, provider, model);
+
+create index if not exists idx_ai_call_log_api_key
+  on public.ai_call_log (api_key_id);
+
+-- -----------------------------------------------------------------------------
+-- 6) RLS
+-- -----------------------------------------------------------------------------
+alter table public.api_keys enable row level security;
+alter table public.user_ai_settings enable row level security;
+alter table public.ai_call_log enable row level security;
+
+-- api_keys: owners can manage their keys
+drop policy if exists api_keys_select_own on public.api_keys;
+create policy api_keys_select_own
+  on public.api_keys for select
+  using (
+    owner_id = auth.uid() OR is_superadmin(auth.uid())
+  );
+
+drop policy if exists api_keys_insert_own on public.api_keys;
+create policy api_keys_insert_own
+  on public.api_keys for insert
+  with check (
+    owner_id = auth.uid() OR is_superadmin(auth.uid())
+  );
+
+drop policy if exists api_keys_update_own on public.api_keys;
+create policy api_keys_update_own
+  on public.api_keys for update
+  using (
+    owner_id = auth.uid() OR is_superadmin(auth.uid())
+  )
+  with check (
+    owner_id = auth.uid() OR is_superadmin(auth.uid())
+  );
+
+drop policy if exists api_keys_delete_own on public.api_keys;
+create policy api_keys_delete_own
+  on public.api_keys for delete
+  using (
+    owner_id = auth.uid() OR is_superadmin(auth.uid())
+  );
+
+-- user_ai_settings: owners can read/write their settings row
+drop policy if exists user_ai_settings_select_own on public.user_ai_settings;
+create policy user_ai_settings_select_own
+  on public.user_ai_settings for select
+  using (
+    owner_id = auth.uid() OR is_superadmin(auth.uid())
+  );
+
+drop policy if exists user_ai_settings_insert_own on public.user_ai_settings;
+create policy user_ai_settings_insert_own
+  on public.user_ai_settings for insert
+  with check (
+    owner_id = auth.uid() OR is_superadmin(auth.uid())
+  );
+
+drop policy if exists user_ai_settings_update_own on public.user_ai_settings;
+create policy user_ai_settings_update_own
+  on public.user_ai_settings for update
+  using (
+    owner_id = auth.uid() OR is_superadmin(auth.uid())
+  )
+  with check (
+    owner_id = auth.uid() OR is_superadmin(auth.uid())
+  );
+
+-- ai_call_log: owners can read their logs. Inserts are expected from server/service role.
+drop policy if exists ai_call_log_select_own on public.ai_call_log;
+create policy ai_call_log_select_own
+  on public.ai_call_log for select
+  using (
+    owner_id = auth.uid() OR is_superadmin(auth.uid())
+  );
+
+-- Optional: allow authenticated inserts (useful for internal calls without service role)
+drop policy if exists ai_call_log_insert_own on public.ai_call_log;
+create policy ai_call_log_insert_own
+  on public.ai_call_log for insert
+  with check (
+    owner_id = auth.uid() OR is_superadmin(auth.uid())
+  );
+
+-- -----------------------------------------------------------------------------
+-- 7) updated_at maintenance for user_ai_settings
+-- -----------------------------------------------------------------------------
+create or replace function public.set_updated_at()
+returns trigger
+language plpgsql
+as $$
+begin
+  new.updated_at = now();
+  return new;
+end;
+$$;
+
+drop trigger if exists trg_user_ai_settings_updated_at on public.user_ai_settings;
+create trigger trg_user_ai_settings_updated_at
+before update on public.user_ai_settings
+for each row execute function public.set_updated_at();
+
+-- -----------------------------------------------------------------------------
+-- 8) Providers & models catalog (what LastBrain exposes to clients)
+-- -----------------------------------------------------------------------------
+create table if not exists public.ai_providers (
+  key text primary key, -- e.g. openai, anthropic, mistral, groq
+  name text not null,
+
+  is_active boolean not null default true,
+
+  supports_text boolean not null default true,
+  supports_image boolean not null default false,
+
+  meta jsonb not null default '{}'::jsonb,
+
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now()
+);
+
+create index if not exists idx_ai_providers_active
+  on public.ai_providers (is_active);
+
+create table if not exists public.ai_provider_models (
+  id uuid primary key default gen_random_uuid(),
+  provider_key text not null references public.ai_providers(key) on delete cascade,
+
+  model text not null,
+  kind text not null, -- text|image
+
+  is_active boolean not null default true,
+
+  -- pricing conversion: how many LastBrain tokens to charge per provider token
+  input_token_factor numeric null,
+  output_token_factor numeric null,
+
+  -- for image models, you may charge a fixed cost per generation
+  image_cost_tokens bigint null,
+
+  max_output_tokens integer null,
+
+  meta jsonb not null default '{}'::jsonb,
+
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now(),
+
+  constraint ai_provider_models_kind_check check (kind = any (array['text'::text,'image'::text]))
+);
+
+create unique index if not exists idx_ai_provider_models_unique
+  on public.ai_provider_models (provider_key, model, kind);
+
+create index if not exists idx_ai_provider_models_active
+  on public.ai_provider_models (is_active, kind);
+
+create index if not exists idx_ai_provider_models_provider
+  on public.ai_provider_models (provider_key);
+
+-- RLS
+alter table public.ai_providers enable row level security;
+alter table public.ai_provider_models enable row level security;
+
+-- Public read (authenticated) for discovery endpoints; superadmin can manage.
+drop policy if exists ai_providers_select on public.ai_providers;
+create policy ai_providers_select
+  on public.ai_providers for select
+  using (true);
+
+-- Only superadmin can write
+
+drop policy if exists ai_providers_insert on public.ai_providers;
+create policy ai_providers_insert
+  on public.ai_providers for insert
+  with check (is_superadmin(auth.uid()));
+
+
+drop policy if exists ai_providers_update on public.ai_providers;
+create policy ai_providers_update
+  on public.ai_providers for update
+  using (is_superadmin(auth.uid()))
+  with check (is_superadmin(auth.uid()));
+
+
+drop policy if exists ai_providers_delete on public.ai_providers;
+create policy ai_providers_delete
+  on public.ai_providers for delete
+  using (is_superadmin(auth.uid()));
+
+
+drop policy if exists ai_provider_models_select on public.ai_provider_models;
+create policy ai_provider_models_select
+  on public.ai_provider_models for select
+  using (true);
+
+
+drop policy if exists ai_provider_models_insert on public.ai_provider_models;
+create policy ai_provider_models_insert
+  on public.ai_provider_models for insert
+  with check (is_superadmin(auth.uid()));
+
+
+drop policy if exists ai_provider_models_update on public.ai_provider_models;
+create policy ai_provider_models_update
+  on public.ai_provider_models for update
+  using (is_superadmin(auth.uid()))
+  with check (is_superadmin(auth.uid()));
+
+
+drop policy if exists ai_provider_models_delete on public.ai_provider_models;
+create policy ai_provider_models_delete
+  on public.ai_provider_models for delete
+  using (is_superadmin(auth.uid()));
+
+-- updated_at triggers
+
+drop trigger if exists trg_ai_providers_updated_at on public.ai_providers;
+create trigger trg_ai_providers_updated_at
+before update on public.ai_providers
+for each row execute function public.set_updated_at();
+
+
+drop trigger if exists trg_ai_provider_models_updated_at on public.ai_provider_models;
+create trigger trg_ai_provider_models_updated_at
+before update on public.ai_provider_models
+for each row execute function public.set_updated_at();
+
+commit;

package/supabase/migrations/20260128120000_seed_providers_models.sql

@@ -0,0 +1,78 @@
+-- Seed initial AI providers and models for public API v1
+-- This script should be run after the main migration (20260128100003_update_and_add_table.sql)
+-- Updated to support Vercel AI Gateway provider/model notation
+
+begin;
+
+-- Insert OpenAI provider (if not exists)
+insert into public.ai_providers (key, name, is_active, supports_text, supports_image)
+values ('openai', 'OpenAI', true, true, true)
+on conflict (key) do update
+set name = excluded.name,
+    is_active = excluded.is_active,
+    supports_text = excluded.supports_text,
+    supports_image = excluded.supports_image;
+
+-- Insert OpenAI text models
+-- Note: Vercel AI uses provider/model format like "openai/gpt-4o-mini"
+-- We store just the model name here and construct the full ID at runtime
+insert into public.ai_provider_models (provider_key, model, kind, is_active, input_token_factor, output_token_factor, max_output_tokens)
+values 
+  ('openai', 'gpt-4o-mini', 'text', true, 1.0, 1.0, 16384),
+  ('openai', 'gpt-4o', 'text', true, 2.5, 10.0, 16384),
+  ('openai', 'gpt-4-turbo', 'text', true, 10.0, 30.0, 4096),
+  ('openai', 'gpt-3.5-turbo', 'text', true, 0.5, 1.5, 4096)
+on conflict (provider_key, model, kind) do update
+set is_active = excluded.is_active,
+    input_token_factor = excluded.input_token_factor,
+    output_token_factor = excluded.output_token_factor,
+    max_output_tokens = excluded.max_output_tokens;
+
+-- Insert OpenAI image models
+insert into public.ai_provider_models (provider_key, model, kind, is_active, image_cost_tokens)
+values 
+  ('openai', 'dall-e-3', 'image', true, 6000),
+  ('openai', 'dall-e-2', 'image', true, 5000),
+  ('openai', 'gpt-image-1', 'image', true, 6000)
+on conflict (provider_key, model, kind) do update
+set is_active = excluded.is_active,
+    image_cost_tokens = excluded.image_cost_tokens;
+
+-- Insert Anthropic provider (for future use with Vercel AI)
+insert into public.ai_providers (key, name, is_active, supports_text, supports_image)
+values ('anthropic', 'Anthropic (Claude)', false, true, false)
+on conflict (key) do nothing;
+
+-- Insert Mistral provider (for future use with Vercel AI)
+insert into public.ai_providers (key, name, is_active, supports_text, supports_image)
+values ('mistral', 'Mistral AI', false, true, false)
+on conflict (key) do nothing;
+
+-- Insert Google provider (Gemini models)
+insert into public.ai_providers (key, name, is_active, supports_text, supports_image)
+values ('google', 'Google (Gemini)', true, true, true)
+on conflict (key) do update
+set name = excluded.name,
+    is_active = excluded.is_active,
+    supports_text = excluded.supports_text,
+    supports_image = excluded.supports_image;
+
+-- Insert Google image model for Gemini
+insert into public.ai_provider_models (provider_key, model, kind, is_active, image_cost_tokens)
+values 
+  ('google', 'gemini-2.5-flash-image', 'image', true, 3000)
+on conflict (provider_key, model, kind) do update
+set is_active = excluded.is_active,
+    image_cost_tokens = excluded.image_cost_tokens;
+
+-- Add gpt-4.1-mini to OpenAI models
+insert into public.ai_provider_models (provider_key, model, kind, is_active, input_token_factor, output_token_factor, max_output_tokens)
+values 
+  ('openai', 'gpt-4.1-mini', 'text', true, 1.0, 1.0, 16384)
+on conflict (provider_key, model, kind) do update
+set is_active = excluded.is_active,
+    input_token_factor = excluded.input_token_factor,
+    output_token_factor = excluded.output_token_factor,
+    max_output_tokens = excluded.max_output_tokens;
+
+commit;

package/supabase/migrations/20260128131405_add_api_key_id_to_ledgers.sql

@@ -0,0 +1,41 @@
+-- module-ai: add api_key_id to ledger tables for tracking API key usage
+
+begin;
+
+-- -----------------------------------------------------------------------------
+-- Add api_key_id column to user_token_ledger
+-- -----------------------------------------------------------------------------
+alter table public.user_token_ledger
+  add column if not exists api_key_id uuid null
+  references public.api_keys(id) on delete set null;
+
+comment on column public.user_token_ledger.api_key_id is
+  'Reference to the API key used for this transaction (null for manual/admin operations)';
+
+-- Index for filtering by API key
+create index if not exists idx_user_token_ledger_api_key_id
+  on public.user_token_ledger (api_key_id, ts desc);
+
+-- Composite index for owner + api_key filtering
+create index if not exists idx_user_token_ledger_owner_api_key
+  on public.user_token_ledger (owner_id, api_key_id, ts desc);
+
+-- -----------------------------------------------------------------------------
+-- Add api_key_id column to user_token_quota_ledger
+-- -----------------------------------------------------------------------------
+alter table public.user_token_quota_ledger
+  add column if not exists api_key_id uuid null
+  references public.api_keys(id) on delete set null;
+
+comment on column public.user_token_quota_ledger.api_key_id is
+  'Reference to the API key used for this quota transaction (null for manual/admin operations)';
+
+-- Index for filtering by API key
+create index if not exists idx_user_token_quota_ledger_api_key_id
+  on public.user_token_quota_ledger (api_key_id, created_at desc);
+
+-- Composite index for owner + api_key filtering
+create index if not exists idx_user_token_quota_ledger_owner_api_key
+  on public.user_token_quota_ledger (owner_id, api_key_id, created_at desc);
+
+commit;