✨ feat(costs): add provider billing type (pay-per-use / subscription / free)

Core:
- New BillingType = 'pay-per-use' | 'subscription' | 'free'
- New ProviderBillingConfig interface (monthlyCostUsd, planName, notes)
- calculateCost() returns 0 for subscription/free (no per-token cost)
- UsageRecord gains billingType field for filtering

Gateway:
- CustomProvider gains billingType, subscriptionCostUsd, subscriptionPlan, billingNotes
- CreateProviderInput + UpdateProviderInput include billing fields
- UserProviderConfig inputs include billing fields
- Migration 024: adds billing columns to custom_providers, auto-sets 'free' for local providers
- 001_initial_schema.sql updated for fresh installs

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ersinkoc

packages/core/src/costs/calculator.ts

@@ -4,7 +4,7 @@
  * Functions for calculating and estimating LLM API costs.
  */
 
-import type { AIProvider, CostEstimate, ModelPricing } from './types.js';
+import type { AIProvider, BillingType, CostEstimate, ModelPricing } from './types.js';
 import { MODEL_PRICING } from './model-pricing.js';
 
 // Pre-built lookup maps for O(1) exact-match pricing (built once at module load)
@@ -36,14 +36,23 @@ export function getModelPricing(provider: AIProvider, modelId: string): ModelPri
 }
 
 /**
- * Calculate cost for a request
+ * Calculate cost for a request.
+ *
+ * If `billingType` is 'subscription' or 'free', returns 0 (no per-token cost).
+ * Subscription costs are tracked separately via provider billing config.
  */
 export function calculateCost(
   provider: AIProvider,
   modelId: string,
   inputTokens: number,
-  outputTokens: number
+  outputTokens: number,
+  billingType?: BillingType
 ): number {
+  // Subscription and free providers have no per-token cost
+  if (billingType === 'subscription' || billingType === 'free') {
+    return 0;
+  }
+
   const pricing = getModelPricing(provider, modelId);
 
   if (!pricing) {

packages/core/src/costs/index.ts

@@ -18,6 +18,8 @@
 // Types
 export type {
   AIProvider,
+  BillingType,
+  ProviderBillingConfig,
   ModelPricing,
   UsageRecord,
   UsageSummary,

packages/core/src/costs/types.ts

@@ -2,6 +2,29 @@
  * Cost Tracking Types
  */
 
+/**
+ * Billing type for AI providers
+ *
+ * - `pay-per-use`: Standard API billing per token (OpenAI, Anthropic, etc.)
+ * - `subscription`: Fixed monthly fee, no per-token cost (ChatGPT Plus, Claude Pro, etc.)
+ * - `free`: No cost (local models, free tiers like Groq, Ollama, etc.)
+ */
+export type BillingType = 'pay-per-use' | 'subscription' | 'free';
+
+/**
+ * Provider billing configuration
+ */
+export interface ProviderBillingConfig {
+  /** Billing model */
+  billingType: BillingType;
+  /** Monthly subscription cost in USD (only for subscription type) */
+  monthlyCostUsd?: number;
+  /** Subscription plan name (e.g., "ChatGPT Plus", "Claude Pro") */
+  planName?: string;
+  /** Notes (e.g., "Includes 5M tokens/month") */
+  notes?: string;
+}
+
 /**
  * AI Provider
  */
@@ -76,6 +99,8 @@ export interface UsageRecord {
   latencyMs: number;
   /** Request type */
   requestType: 'chat' | 'completion' | 'embedding' | 'image' | 'audio' | 'tool';
+  /** Billing type for this request */
+  billingType?: BillingType;
   /** Was cached */
   cached?: boolean;
   /** Error if failed */

packages/gateway/src/db/migrations/postgres/001_initial_schema.sql

@@ -614,6 +614,10 @@ CREATE TABLE IF NOT EXISTS custom_providers (
   api_key_setting TEXT,
   provider_type TEXT NOT NULL DEFAULT 'openai_compatible' CHECK(provider_type IN ('openai_compatible', 'custom')),
   is_enabled BOOLEAN NOT NULL DEFAULT TRUE,
+  billing_type TEXT NOT NULL DEFAULT 'pay-per-use',
+  subscription_cost_usd REAL,
+  subscription_plan TEXT,
+  billing_notes TEXT,
   config JSONB DEFAULT '{}',
   created_at TIMESTAMP NOT NULL DEFAULT NOW(),
   updated_at TIMESTAMP NOT NULL DEFAULT NOW(),

packages/gateway/src/db/migrations/postgres/024_provider_billing.sql

@@ -0,0 +1,13 @@
+-- Provider billing type migration
+-- Adds billing type distinction: pay-per-use (API), subscription (flat fee), free (local/free tier)
+
+-- Add billing columns to custom_providers
+ALTER TABLE custom_providers ADD COLUMN IF NOT EXISTS billing_type TEXT NOT NULL DEFAULT 'pay-per-use';
+ALTER TABLE custom_providers ADD COLUMN IF NOT EXISTS subscription_cost_usd REAL;
+ALTER TABLE custom_providers ADD COLUMN IF NOT EXISTS subscription_plan TEXT;
+ALTER TABLE custom_providers ADD COLUMN IF NOT EXISTS billing_notes TEXT;
+
+-- Set known free providers
+UPDATE custom_providers SET billing_type = 'free'
+WHERE provider_id IN ('local', 'ollama', 'lmstudio', 'localai', 'vllm')
+  AND billing_type = 'pay-per-use';

packages/gateway/src/db/repositories/model-configs.test.ts

@@ -717,7 +717,7 @@ describe('ModelConfigsRepository', () => {
       });
 
       const params = mockAdapter.execute.mock.calls[0]![1] as unknown[];
-      expect(params[8]).toBe('{"key":"value"}');
+      expect(params[12]).toBe('{"key":"value"}');
     });
   });
 

packages/gateway/src/db/repositories/model-configs.ts

@@ -40,6 +40,10 @@ export interface CustomProvider {
   apiKeySetting?: string;
   providerType: 'openai_compatible' | 'custom';
   isEnabled: boolean;
+  billingType: 'pay-per-use' | 'subscription' | 'free';
+  subscriptionCostUsd?: number;
+  subscriptionPlan?: string;
+  billingNotes?: string;
   config: Record<string, unknown>;
   createdAt: Date;
   updatedAt: Date;
@@ -79,6 +83,10 @@ export interface CreateProviderInput {
   apiKeySetting?: string;
   providerType?: 'openai_compatible' | 'custom';
   isEnabled?: boolean;
+  billingType?: 'pay-per-use' | 'subscription' | 'free';
+  subscriptionCostUsd?: number;
+  subscriptionPlan?: string;
+  billingNotes?: string;
   config?: Record<string, unknown>;
 }
 
@@ -105,6 +113,9 @@ export interface CreateUserProviderConfigInput {
   isEnabled?: boolean;
   apiKeyEnv?: string;
   notes?: string;
+  billingType?: 'pay-per-use' | 'subscription' | 'free';
+  subscriptionCostUsd?: number;
+  subscriptionPlan?: string;
   config?: Record<string, unknown>;
 }
 
@@ -114,6 +125,9 @@ export interface UpdateUserProviderConfigInput {
   isEnabled?: boolean;
   apiKeyEnv?: string;
   notes?: string;
+  billingType?: 'pay-per-use' | 'subscription' | 'free';
+  subscriptionCostUsd?: number;
+  subscriptionPlan?: string;
   config?: Record<string, unknown>;
 }
 
@@ -123,6 +137,10 @@ export interface UpdateProviderInput {
   apiKeySetting?: string;
   providerType?: 'openai_compatible' | 'custom';
   isEnabled?: boolean;
+  billingType?: 'pay-per-use' | 'subscription' | 'free';
+  subscriptionCostUsd?: number;
+  subscriptionPlan?: string;
+  billingNotes?: string;
   config?: Record<string, unknown>;
 }
 
@@ -159,6 +177,10 @@ interface CustomProviderRow {
   api_key_setting: string | null;
   provider_type: string;
   is_enabled: boolean;
+  billing_type: string | null;
+  subscription_cost_usd: number | null;
+  subscription_plan: string | null;
+  billing_notes: string | null;
   config: string;
   created_at: string;
   updated_at: string;
@@ -204,6 +226,7 @@ function rowToModelConfig(row: ModelConfigRow): UserModelConfig {
 }
 
 function rowToProvider(row: CustomProviderRow): CustomProvider {
+  const billingType = row.billing_type as CustomProvider['billingType'] | null;
   return {
     id: row.id,
     userId: row.user_id,
@@ -213,6 +236,10 @@ function rowToProvider(row: CustomProviderRow): CustomProvider {
     apiKeySetting: row.api_key_setting || undefined,
     providerType: row.provider_type as 'openai_compatible' | 'custom',
     isEnabled: row.is_enabled,
+    billingType: billingType ?? 'pay-per-use',
+    subscriptionCostUsd: row.subscription_cost_usd ?? undefined,
+    subscriptionPlan: row.subscription_plan ?? undefined,
+    billingNotes: row.billing_notes ?? undefined,
     config: parseJsonField(row.config, {}),
     createdAt: new Date(row.created_at),
     updatedAt: new Date(row.updated_at),
@@ -518,6 +545,10 @@ export class ModelConfigsRepository extends BaseRepository {
           provider_type = COALESCE($4, provider_type),
           is_enabled = COALESCE($5, is_enabled),
           config = COALESCE($6, config),
+          billing_type = COALESCE($10, billing_type),
+          subscription_cost_usd = COALESCE($11, subscription_cost_usd),
+          subscription_plan = COALESCE($12, subscription_plan),
+          billing_notes = COALESCE($13, billing_notes),
           updated_at = $7
         WHERE user_id = $8 AND provider_id = $9`,
         [
@@ -530,6 +561,10 @@ export class ModelConfigsRepository extends BaseRepository {
           now,
           userId,
           input.providerId,
+          input.billingType ?? null,
+          input.subscriptionCostUsd ?? null,
+          input.subscriptionPlan ?? null,
+          input.billingNotes ?? null,
         ]
       );
 
@@ -542,8 +577,10 @@ export class ModelConfigsRepository extends BaseRepository {
       await this.execute(
         `INSERT INTO custom_providers (
           id, user_id, provider_id, display_name,
-          api_base_url, api_key_setting, provider_type, is_enabled, config, created_at, updated_at
-        ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)`,
+          api_base_url, api_key_setting, provider_type, is_enabled,
+          billing_type, subscription_cost_usd, subscription_plan, billing_notes,
+          config, created_at, updated_at
+        ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15)`,
         [
           id,
           userId,
@@ -553,6 +590,10 @@ export class ModelConfigsRepository extends BaseRepository {
           input.apiKeySetting || null,
           input.providerType || 'openai_compatible',
           input.isEnabled !== false,
+          input.billingType || 'pay-per-use',
+          input.subscriptionCostUsd ?? null,
+          input.subscriptionPlan ?? null,
+          input.billingNotes ?? null,
           JSON.stringify(input.config || {}),
           now,
           now,