@littlebearapps/platform-admin-sdk 1.4.2 → 1.5.0

package/templates/shared/scripts/ops/verify-account-completeness.ts

@@ -0,0 +1,236 @@
+#!/usr/bin/env npx tsx
+/**
+ * Verify Account Completeness Script
+ *
+ * Queries all Cloudflare GraphQL Analytics endpoints to calculate the true
+ * account-wide bill and compare against D1 records for the current month.
+ *
+ * Services audited:
+ *   - Workers (requests + CPU)
+ *   - D1 (rows read/written)
+ *   - R2 (Class A/B operations)
+ *   - KV (reads/writes)
+ *   - Vectorize (queries)
+ *   - Durable Objects (requests)
+ *   - Workers AI (neurons)
+ *
+ * Usage:
+ *   npx tsx scripts/ops/verify-account-completeness.ts
+ *   npx tsx scripts/ops/verify-account-completeness.ts --start 2026-02-01 --end 2026-02-28
+ *
+ * Environment Variables:
+ *   CLOUDFLARE_API_TOKEN  — API token with Analytics:Read permissions
+ *   CLOUDFLARE_ACCOUNT_ID — Your Cloudflare account ID
+ *   D1_DATABASE_ID        — Your platform-metrics D1 database ID
+ */
+
+const GRAPHQL_ENDPOINT = 'https://api.cloudflare.com/client/v4/graphql';
+const REST_API_BASE = 'https://api.cloudflare.com/client/v4';
+
+// Pricing constants (Workers Paid Plan)
+const PRICING = {
+  workers: { includedRequests: 10_000_000, requestCostPerMillion: 0.3, cpuCostPerMillionMs: 0.02 },
+  d1: { includedReads: 25_000_000_000, includedWrites: 50_000_000, readCostPerMillion: 0.001, writeCostPerMillion: 1.0 },
+  kv: { includedReads: 10_000_000, includedWrites: 1_000_000, readCostPerMillion: 0.5, writeCostPerMillion: 5.0 },
+  r2: { includedClassA: 1_000_000, includedClassB: 10_000_000, classACostPerMillion: 4.5, classBCostPerMillion: 0.36 },
+  vectorize: { includedDimensions: 30_000_000, queryCostPerMillionDimensions: 0.01 },
+  durableObjects: { includedRequests: 1_000_000, requestCostPerMillion: 0.15 },
+  workersAI: { neuronCostPer1000: 0.011 },
+};
+
+interface ServiceUsage {
+  name: string;
+  usage: string;
+  includedAllowance: string;
+  billableUsage: string;
+  estimatedCost: number;
+}
+
+// ---------------------------------------------------------------------------
+// GraphQL helper
+// ---------------------------------------------------------------------------
+
+async function queryGraphQL(query: string, variables: Record<string, unknown>): Promise<unknown> {
+  const apiToken = process.env.CLOUDFLARE_API_TOKEN;
+  if (!apiToken) throw new Error('CLOUDFLARE_API_TOKEN required');
+
+  const response = await fetch(GRAPHQL_ENDPOINT, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${apiToken}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ query, variables }),
+  });
+
+  const result = (await response.json()) as { data?: unknown; errors?: Array<{ message: string }> };
+  if (result.errors?.length) throw new Error(`GraphQL error: ${result.errors[0].message}`);
+  return result.data;
+}
+
+// ---------------------------------------------------------------------------
+// Service queries
+// ---------------------------------------------------------------------------
+
+async function getWorkersUsage(accountId: string, startDate: string, endDate: string): Promise<ServiceUsage> {
+  const query = `query($accountTag:String!,$startDate:Date!,$endDate:Date!){viewer{accounts(filter:{accountTag:$accountTag}){workersInvocationsAdaptive(filter:{date_geq:$startDate,date_leq:$endDate},limit:1000){sum{requests,errors}quantiles{cpuTimeP50}}}}}`;
+  const data = (await queryGraphQL(query, { accountTag: accountId, startDate, endDate })) as Record<string, unknown>;
+  const results = ((data as { viewer: { accounts: Array<{ workersInvocationsAdaptive: Array<{ sum: { requests: number }; quantiles: { cpuTimeP50: number } }> }> } }).viewer.accounts[0]?.workersInvocationsAdaptive) ?? [];
+  let totalRequests = 0;
+  let totalCpuMs = 0;
+  for (const row of results) {
+    totalRequests += row.sum.requests;
+    totalCpuMs += row.sum.requests * row.quantiles.cpuTimeP50;
+  }
+  const billable = Math.max(0, totalRequests - PRICING.workers.includedRequests);
+  const cost = (billable / 1_000_000) * PRICING.workers.requestCostPerMillion + (totalCpuMs / 1_000_000) * PRICING.workers.cpuCostPerMillionMs;
+  return { name: 'Workers', usage: `${(totalRequests / 1_000_000).toFixed(2)}M requests`, includedAllowance: '10M requests', billableUsage: `${(billable / 1_000_000).toFixed(2)}M`, estimatedCost: cost };
+}
+
+async function getD1Usage(accountId: string, startDate: string, endDate: string): Promise<ServiceUsage> {
+  const query = `query($accountTag:String!,$startDate:Date!,$endDate:Date!){viewer{accounts(filter:{accountTag:$accountTag}){d1AnalyticsAdaptiveGroups(filter:{date_geq:$startDate,date_leq:$endDate},limit:1000){sum{rowsRead,rowsWritten}}}}}`;
+  const data = (await queryGraphQL(query, { accountTag: accountId, startDate, endDate })) as Record<string, unknown>;
+  const results = ((data as { viewer: { accounts: Array<{ d1AnalyticsAdaptiveGroups: Array<{ sum: { rowsRead: number; rowsWritten: number } }> }> } }).viewer.accounts[0]?.d1AnalyticsAdaptiveGroups) ?? [];
+  let totalReads = 0, totalWrites = 0;
+  for (const row of results) { totalReads += row.sum.rowsRead; totalWrites += row.sum.rowsWritten; }
+  const billReads = Math.max(0, totalReads - PRICING.d1.includedReads);
+  const billWrites = Math.max(0, totalWrites - PRICING.d1.includedWrites);
+  const cost = (billReads / 1_000_000) * PRICING.d1.readCostPerMillion + (billWrites / 1_000_000) * PRICING.d1.writeCostPerMillion;
+  return { name: 'D1', usage: `${(totalWrites / 1_000_000).toFixed(1)}M writes, ${(totalReads / 1_000_000_000).toFixed(3)}B reads`, includedAllowance: '50M writes, 25B reads', billableUsage: `${(billWrites / 1_000_000).toFixed(1)}M writes`, estimatedCost: cost };
+}
+
+async function getKVUsage(accountId: string, startDate: string, endDate: string): Promise<ServiceUsage> {
+  const query = `query($accountTag:String!,$startDate:Date!,$endDate:Date!){viewer{accounts(filter:{accountTag:$accountTag}){kvOperationsAdaptiveGroups(filter:{date_geq:$startDate,date_leq:$endDate},limit:1000){sum{requests}dimensions{actionType}}}}}`;
+  const data = (await queryGraphQL(query, { accountTag: accountId, startDate, endDate })) as Record<string, unknown>;
+  const results = ((data as { viewer: { accounts: Array<{ kvOperationsAdaptiveGroups: Array<{ sum: { requests: number }; dimensions: { actionType: string } }> }> } }).viewer.accounts[0]?.kvOperationsAdaptiveGroups) ?? [];
+  let reads = 0, writes = 0;
+  for (const row of results) {
+    const action = row.dimensions.actionType.toLowerCase();
+    if (action === 'read' || action === 'get') reads += row.sum.requests;
+    else if (action === 'write' || action === 'put') writes += row.sum.requests;
+  }
+  const billReads = Math.max(0, reads - PRICING.kv.includedReads);
+  const cost = (billReads / 1_000_000) * PRICING.kv.readCostPerMillion + (Math.max(0, writes - PRICING.kv.includedWrites) / 1_000_000) * PRICING.kv.writeCostPerMillion;
+  return { name: 'KV', usage: `${(reads / 1_000_000).toFixed(2)}M reads, ${(writes / 1_000).toFixed(1)}K writes`, includedAllowance: '10M reads, 1M writes', billableUsage: `${(billReads / 1_000_000).toFixed(2)}M reads`, estimatedCost: cost };
+}
+
+async function getR2Usage(accountId: string, startDate: string, endDate: string): Promise<ServiceUsage> {
+  const query = `query($accountTag:String!,$startDate:Date!,$endDate:Date!){viewer{accounts(filter:{accountTag:$accountTag}){r2OperationsAdaptiveGroups(filter:{date_geq:$startDate,date_leq:$endDate},limit:1000){sum{requests}dimensions{actionType}}}}}`;
+  const data = (await queryGraphQL(query, { accountTag: accountId, startDate, endDate })) as Record<string, unknown>;
+  const results = ((data as { viewer: { accounts: Array<{ r2OperationsAdaptiveGroups: Array<{ sum: { requests: number }; dimensions: { actionType: string } }> }> } }).viewer.accounts[0]?.r2OperationsAdaptiveGroups) ?? [];
+  const classBActions = new Set(['GetObject', 'HeadObject', 'HeadBucket']);
+  let classA = 0, classB = 0;
+  for (const row of results) {
+    if (classBActions.has(row.dimensions.actionType)) classB += row.sum.requests;
+    else classA += row.sum.requests;
+  }
+  const billA = Math.max(0, classA - PRICING.r2.includedClassA);
+  const billB = Math.max(0, classB - PRICING.r2.includedClassB);
+  const cost = (billA / 1_000_000) * PRICING.r2.classACostPerMillion + (billB / 1_000_000) * PRICING.r2.classBCostPerMillion;
+  return { name: 'R2', usage: `${(classA / 1_000).toFixed(1)}K A, ${(classB / 1_000).toFixed(1)}K B`, includedAllowance: '1M A, 10M B', billableUsage: `${billA.toLocaleString()} A`, estimatedCost: cost };
+}
+
+// ---------------------------------------------------------------------------
+// D1 comparison
+// ---------------------------------------------------------------------------
+
+async function getD1RecordTotal(
+  accountId: string,
+  apiToken: string,
+  databaseId: string,
+  startDate: string,
+  endDate: string
+): Promise<number> {
+  const sql = `SELECT SUM(total_cost_usd) as total FROM daily_usage_rollups WHERE snapshot_date BETWEEN '${startDate}' AND '${endDate}'`;
+  const url = `${REST_API_BASE}/accounts/${accountId}/d1/database/${databaseId}/query`;
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${apiToken}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ sql }),
+  });
+  if (!response.ok) return 0;
+  const data = (await response.json()) as { result?: Array<{ results?: Array<{ total: number }> }> };
+  return data?.result?.[0]?.results?.[0]?.total ?? 0;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  const apiToken = process.env.CLOUDFLARE_API_TOKEN;
+  const accountId = process.env.CLOUDFLARE_ACCOUNT_ID;
+  const databaseId = process.env.D1_DATABASE_ID;
+
+  if (!apiToken || !accountId || !databaseId) {
+    console.error('Error: Required environment variables: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, D1_DATABASE_ID');
+    process.exit(1);
+  }
+
+  // Parse date range
+  const args = process.argv.slice(2);
+  const now = new Date();
+  let startDate = `${now.getUTCFullYear()}-${String(now.getUTCMonth() + 1).padStart(2, '0')}-01`;
+  let endDate = now.toISOString().split('T')[0];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--start' && args[i + 1]) startDate = args[++i];
+    else if (args[i] === '--end' && args[i + 1]) endDate = args[++i];
+  }
+
+  console.log('='.repeat(80));
+  console.log(`ACCOUNT COMPLETENESS AUDIT (${startDate} to ${endDate})`);
+  console.log('='.repeat(80));
+  console.log('');
+
+  const services: ServiceUsage[] = [];
+
+  console.log('Querying Cloudflare GraphQL…');
+  for (const [name, fn] of [
+    ['Workers', () => getWorkersUsage(accountId, startDate, endDate)],
+    ['D1', () => getD1Usage(accountId, startDate, endDate)],
+    ['KV', () => getKVUsage(accountId, startDate, endDate)],
+    ['R2', () => getR2Usage(accountId, startDate, endDate)],
+  ] as const) {
+    console.log(`  ${name}…`);
+    services.push(await fn());
+  }
+
+  console.log('');
+  console.log('Service          | Usage                           | Billable               | Est. Cost');
+  console.log('-'.repeat(80));
+
+  let totalCF = 0;
+  for (const svc of services) {
+    totalCF += svc.estimatedCost;
+    console.log(`${svc.name.padEnd(16)} | ${svc.usage.padEnd(31)} | ${svc.billableUsage.padEnd(22)} | $${svc.estimatedCost.toFixed(2).padStart(8)}`);
+  }
+  console.log('-'.repeat(80));
+  console.log(`${'CF TOTAL'.padEnd(16)} | ${' '.repeat(31)} | ${' '.repeat(22)} | $${totalCF.toFixed(2).padStart(8)}`);
+  console.log('');
+
+  // Compare against D1
+  console.log('Querying D1 records…');
+  const d1Total = await getD1RecordTotal(accountId, apiToken, databaseId, startDate, endDate);
+
+  console.log('');
+  console.log('-'.repeat(80));
+  console.log('COMPARISON');
+  console.log('-'.repeat(80));
+  console.log(`  Cloudflare Calculated: $${totalCF.toFixed(2)}`);
+  console.log(`  Our D1 Records:       $${d1Total.toFixed(2)}`);
+  console.log(`  Variance:             $${(totalCF - d1Total).toFixed(2)}`);
+  console.log('');
+
+  const variance = Math.abs(totalCF - d1Total);
+  const variancePct = (variance / Math.max(totalCF, d1Total, 0.01)) * 100;
+
+  if (variancePct < 5) {
+    console.log(`VERDICT: ACCURATE (${variancePct.toFixed(1)}% variance — within acceptable margin)`);
+  } else if (d1Total > totalCF) {
+    console.log(`VERDICT: OVER-RECORDED (D1 records exceed Cloudflare by $${(d1Total - totalCF).toFixed(2)})`);
+  } else {
+    console.log(`VERDICT: MISSING DATA (Cloudflare exceeds D1 by $${(totalCF - d1Total).toFixed(2)})`);
+  }
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/templates/shared/scripts/validate-schemas.js

@@ -0,0 +1,61 @@
+/**
+ * JSON Schema Validation Script
+ *
+ * Validates all JSON schemas in contracts/schemas/ are syntactically correct
+ * using the Ajv JSON Schema validator.
+ *
+ * Usage:
+ *   node scripts/validate-schemas.js
+ *   npm run validate:schemas
+ *
+ * Prerequisites:
+ *   npm install ajv ajv-formats --save-dev
+ */
+
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+import { readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+
+const ajv = new Ajv({ allErrors: true, strict: true });
+addFormats(ajv);
+
+const schemasDir = join(process.cwd(), 'contracts', 'schemas');
+
+let schemaFiles;
+try {
+  schemaFiles = readdirSync(schemasDir).filter((file) => file.endsWith('.schema.json'));
+} catch {
+  console.error(`No schemas directory found at ${schemasDir}`);
+  console.error('Create contracts/schemas/ with your JSON schema files.');
+  process.exit(1);
+}
+
+if (schemaFiles.length === 0) {
+  console.log('No schema files found in contracts/schemas/');
+  process.exit(0);
+}
+
+let allValid = true;
+
+for (const file of schemaFiles) {
+  const path = join(schemasDir, file);
+  const schema = JSON.parse(readFileSync(path, 'utf-8'));
+
+  try {
+    ajv.compile(schema);
+    console.log(`  PASS  ${file}`);
+  } catch (error) {
+    console.error(`  FAIL  ${file}: ${error.message}`);
+    allValid = false;
+  }
+}
+
+console.log('');
+if (allValid) {
+  console.log(`All ${schemaFiles.length} schemas are valid.`);
+  process.exit(0);
+}
+
+console.error('Some schemas are invalid.');
+process.exit(1);

package/templates/shared/workers/lib/usage/collectors/anthropic.ts

@@ -0,0 +1,114 @@
+/**
+ * Anthropic (Claude) Usage Collector
+ *
+ * Collects API usage from the Anthropic Admin Usage API.
+ * Requires an Admin API key with organization:usage:read scope.
+ *
+ * NOTE: This only tracks API usage (developer/organization consumption).
+ * Claude Max subscriptions (claude.ai consumer product) are NOT tracked here -
+ * there is no API to retrieve Claude Max conversation/usage data.
+ *
+ * This is a FLOW metric (usage that accumulates) - safe to SUM.
+ *
+ * @see https://docs.anthropic.com/en/api/admin-api
+ */
+
+import type { Env, AnthropicUsageData } from '../shared';
+import { fetchWithRetry } from '../shared';
+import { createLoggerFromEnv } from '@littlebearapps/platform-consumer-sdk';
+import type { ExternalCollector } from './index';
+
+/**
+ * Collect Anthropic (Claude) API usage from the Admin Usage API.
+ * Requires an Admin API key with organization:usage:read scope.
+ */
+export async function collectAnthropicUsage(env: Env): Promise<AnthropicUsageData | null> {
+  const log = createLoggerFromEnv(env, 'platform-usage', 'platform:usage:anthropic');
+  if (!env.ANTHROPIC_ADMIN_API_KEY) {
+    log.info('No ANTHROPIC_ADMIN_API_KEY configured, skipping usage collection');
+    return null;
+  }
+
+  try {
+    // Get usage for the last 24 hours
+    const now = new Date();
+    const yesterday = new Date(now.getTime() - 24 * 60 * 60 * 1000);
+    const startTime = yesterday.toISOString().replace(/\.\d{3}Z$/, 'Z');
+    const endTime = now.toISOString().replace(/\.\d{3}Z$/, 'Z');
+
+    const url =
+      `https://api.anthropic.com/v1/organizations/usage?` +
+      `start_time=${startTime}&end_time=${endTime}&group_by=model`;
+
+    const response = await fetchWithRetry(url, {
+      headers: {
+        'anthropic-version': '2023-06-01',
+        'x-api-key': env.ANTHROPIC_ADMIN_API_KEY,
+      },
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      log.error(`Usage API returned ${response.status}: ${errorText}`);
+      return null;
+    }
+
+    const data = (await response.json()) as {
+      data?: Array<{
+        model?: string;
+        input_tokens?: number;
+        output_tokens?: number;
+      }>;
+    };
+
+    if (!data.data || !Array.isArray(data.data)) {
+      log.info('No usage data returned');
+      return { inputTokens: 0, outputTokens: 0, totalCost: 0, modelBreakdown: {} };
+    }
+
+    const result: AnthropicUsageData = {
+      inputTokens: 0,
+      outputTokens: 0,
+      totalCost: 0,
+      modelBreakdown: {},
+    };
+
+    // Aggregate usage by model
+    for (const item of data.data) {
+      const inputTokens = item.input_tokens || 0;
+      const outputTokens = item.output_tokens || 0;
+      result.inputTokens += inputTokens;
+      result.outputTokens += outputTokens;
+
+      if (item.model) {
+        if (!result.modelBreakdown[item.model]) {
+          result.modelBreakdown[item.model] = { inputTokens: 0, outputTokens: 0 };
+        }
+        result.modelBreakdown[item.model].inputTokens += inputTokens;
+        result.modelBreakdown[item.model].outputTokens += outputTokens;
+      }
+    }
+
+    // Estimate cost (rough approximation - actual pricing varies by model)
+    // Claude Sonnet: $3/$15 per MTok, Claude Opus: $15/$75 per MTok
+    // Using average estimate of $5/$20 per MTok
+    result.totalCost = (result.inputTokens * 5 + result.outputTokens * 20) / 1_000_000;
+
+    log.info('Collected usage', {
+      inputTokens: result.inputTokens,
+      outputTokens: result.outputTokens,
+      estimatedCost: result.totalCost,
+    });
+    return result;
+  } catch (error) {
+    log.error('Failed to collect usage', error);
+    return null;
+  }
+}
+
+/** Collector registration for use in collectors/index.ts COLLECTORS array */
+export const anthropicCollector: ExternalCollector<AnthropicUsageData | null> = {
+  name: 'anthropic',
+  collect: collectAnthropicUsage,
+  defaultValue: null,
+};

package/templates/shared/workers/lib/usage/collectors/apify.ts

@@ -0,0 +1,96 @@
+/**
+ * Apify Usage Collector
+ *
+ * Collects platform usage from the Apify Monthly Usage API.
+ *
+ * This is a FLOW metric (usage that accumulates) - safe to SUM.
+ *
+ * @see https://docs.apify.com/api/v2/users-me-usage-monthly-get
+ */
+
+import type { Env, ApifyUsageData } from '../shared';
+import { fetchWithRetry } from '../shared';
+import { createLoggerFromEnv } from '@littlebearapps/platform-consumer-sdk';
+import type { ExternalCollector } from './index';
+
+/**
+ * Collect Apify platform usage from the Monthly Usage API.
+ */
+export async function collectApifyUsage(env: Env): Promise<ApifyUsageData | null> {
+  const log = createLoggerFromEnv(env, 'platform-usage', 'platform:usage:apify');
+  if (!env.APIFY_API_KEY) {
+    log.info('No APIFY_API_KEY configured, skipping usage collection');
+    return null;
+  }
+
+  try {
+    const response = await fetchWithRetry('https://api.apify.com/v2/users/me/usage/monthly', {
+      headers: {
+        Authorization: `Bearer ${env.APIFY_API_KEY}`,
+        Accept: 'application/json',
+      },
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      if (response.status === 401) {
+        log.info('API key invalid or expired');
+        return null;
+      }
+      log.error(`Usage API returned ${response.status}: ${errorText}`);
+      return null;
+    }
+
+    const data = (await response.json()) as {
+      data?: {
+        monthlyServiceUsage?: Record<
+          string,
+          {
+            quantity?: number;
+            baseAmountUsd?: number;
+          }
+        >;
+        totalUsageCreditsUsdAfterVolumeDiscount?: number;
+      };
+    };
+
+    const result: ApifyUsageData = {
+      totalUsageCreditsUsd: data.data?.totalUsageCreditsUsdAfterVolumeDiscount || 0,
+      actorComputeUnits: 0,
+      dataTransferGb: 0,
+      storageGb: 0,
+    };
+
+    const services = data.data?.monthlyServiceUsage;
+    if (services) {
+      if (services.ACTOR_COMPUTE_UNITS) {
+        result.actorComputeUnits = services.ACTOR_COMPUTE_UNITS.quantity || 0;
+      }
+      if (services.DATA_TRANSFER_EXTERNAL_GBYTES) {
+        result.dataTransferGb = services.DATA_TRANSFER_EXTERNAL_GBYTES.quantity || 0;
+      }
+      if (services.DATASET_STORAGE_GBYTES) {
+        result.storageGb += services.DATASET_STORAGE_GBYTES.quantity || 0;
+      }
+      if (services.KEY_VALUE_STORE_STORAGE_GBYTES) {
+        result.storageGb += services.KEY_VALUE_STORE_STORAGE_GBYTES.quantity || 0;
+      }
+    }
+
+    log.info('Collected usage', {
+      totalUsageCreditsUsd: result.totalUsageCreditsUsd,
+      actorComputeUnits: result.actorComputeUnits,
+    });
+    return result;
+  } catch (error) {
+    log.error('Failed to collect usage', error);
+    return null;
+  }
+}
+
+/** Collector registration for use in collectors/index.ts COLLECTORS array */
+export const apifyCollector: ExternalCollector<ApifyUsageData | null> = {
+  name: 'apify',
+  collect: collectApifyUsage,
+  defaultValue: null,
+};

package/templates/shared/workers/lib/usage/collectors/custom-http.ts

@@ -0,0 +1,151 @@
+/**
+ * Custom HTTP Collector Factory
+ *
+ * Factory function for creating collectors that fetch metrics from arbitrary
+ * REST APIs. Use when no dedicated collector exists for your provider.
+ *
+ * Supports bearer token, basic auth, and API key header authentication.
+ * Extracts multiple metrics from a single JSON response using dot-notation paths.
+ *
+ * @example
+ * ```ts
+ * import { createCustomCollector } from './custom-http';
+ *
+ * const myCollector = createCustomCollector({
+ *   name: 'my-api',
+ *   url: 'https://api.example.com/v1/usage',
+ *   auth: { type: 'bearer', envKey: 'MY_API_TOKEN' },
+ *   metrics: {
+ *     requests: { jsonPath: 'data.total_requests', unit: 'count' },
+ *     cost: { jsonPath: 'data.billing.amount', unit: 'usd', isCost: true },
+ *   },
+ * });
+ *
+ * // Register in COLLECTORS array:
+ * // const COLLECTORS = [myCollector];
+ * ```
+ */
+
+import type { Env, CustomHttpCollectorConfig } from '../shared';
+import { fetchWithRetry } from '../shared';
+import { createLoggerFromEnv } from '@littlebearapps/platform-consumer-sdk';
+import type { ExternalCollector } from './index';
+
+/** Extracted metrics result from a custom collector */
+export interface CustomMetrics {
+  /** Metric values keyed by name */
+  values: Record<string, number>;
+  /** Metadata about each metric */
+  meta: Record<string, { unit: string; isCost: boolean }>;
+  /** Source URL that was fetched */
+  source: string;
+}
+
+/**
+ * Extract a value from a nested object using dot-notation path.
+ * Returns undefined if the path doesn't exist.
+ */
+function extractJsonPath(obj: unknown, path: string): unknown {
+  const parts = path.split('.');
+  let current: unknown = obj;
+
+  for (const part of parts) {
+    if (current === null || current === undefined || typeof current !== 'object') {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[part];
+  }
+
+  return current;
+}
+
+/**
+ * Build request headers for the configured auth type.
+ */
+function buildAuthHeaders(
+  config: CustomHttpCollectorConfig,
+  env: Env
+): Record<string, string> | null {
+  const headers: Record<string, string> = { ...config.headers };
+
+  if (config.auth.type === 'bearer') {
+    const token = (env as Record<string, unknown>)[config.auth.envKey] as string | undefined;
+    if (!token) return null;
+    headers['Authorization'] = `Bearer ${token}`;
+  } else if (config.auth.type === 'basic') {
+    const username = (env as Record<string, unknown>)[config.auth.usernameEnvKey] as
+      | string
+      | undefined;
+    const password = (env as Record<string, unknown>)[config.auth.passwordEnvKey] as
+      | string
+      | undefined;
+    if (!username || !password) return null;
+    headers['Authorization'] = `Basic ${btoa(`${username}:${password}`)}`;
+  } else if (config.auth.type === 'api-key') {
+    const key = (env as Record<string, unknown>)[config.auth.envKey] as string | undefined;
+    if (!key) return null;
+    headers[config.auth.headerName] = key;
+  }
+
+  return headers;
+}
+
+/**
+ * Create a custom HTTP collector from a configuration object.
+ *
+ * The collector fetches the configured URL, parses the JSON response,
+ * and extracts metrics using the provided JSON paths.
+ */
+export function createCustomCollector(
+  config: CustomHttpCollectorConfig
+): ExternalCollector<CustomMetrics | null> {
+  return {
+    name: config.name,
+    defaultValue: null,
+    collect: async (env: Env): Promise<CustomMetrics | null> => {
+      const log = createLoggerFromEnv(env, 'platform-usage', `platform:usage:${config.name}`);
+
+      const headers = buildAuthHeaders(config, env);
+      if (!headers) {
+        log.info(`No credentials configured for ${config.name}, skipping collection`);
+        return null;
+      }
+
+      try {
+        const response = await fetchWithRetry(config.url, { headers });
+
+        if (!response.ok) {
+          const errorText = await response.text();
+          if (response.status === 401 || response.status === 403) {
+            log.info(`${config.name} API access denied`, { status: response.status });
+            return null;
+          }
+          log.error(`${config.name} API returned ${response.status}: ${errorText}`);
+          return null;
+        }
+
+        const data = (await response.json()) as unknown;
+
+        const values: Record<string, number> = {};
+        const meta: Record<string, { unit: string; isCost: boolean }> = {};
+
+        for (const [metricName, metricConfig] of Object.entries(config.metrics)) {
+          const raw = extractJsonPath(data, metricConfig.jsonPath);
+          const value = typeof raw === 'number' ? raw : parseFloat(String(raw || '0'));
+          values[metricName] = isNaN(value) ? 0 : value;
+          meta[metricName] = { unit: metricConfig.unit, isCost: metricConfig.isCost ?? false };
+        }
+
+        log.info(`Collected ${config.name} metrics`, {
+          metricCount: Object.keys(values).length,
+          values,
+        });
+
+        return { values, meta, source: config.url };
+      } catch (error) {
+        log.error(`Failed to collect ${config.name} metrics`, error);
+        return null;
+      }
+    },
+  };
+}