@ainyc/canonry 1.0.0

package/src/commands/settings.ts

@@ -0,0 +1,45 @@
+import { loadConfig } from '../config.js'
+import { ApiClient } from '../client.js'
+
+function getClient(): ApiClient {
+  const config = loadConfig()
+  return new ApiClient(config.apiUrl, config.apiKey)
+}
+
+export async function setProvider(name: string, opts: { apiKey?: string; baseUrl?: string; model?: string }): Promise<void> {
+  const client = getClient()
+  const result = await client.updateProvider(name, opts) as {
+    name: string
+    model?: string
+    configured: boolean
+  }
+  console.log(`Provider ${result.name} updated successfully.`)
+  if (result.model) {
+    console.log(`  Model: ${result.model}`)
+  }
+}
+
+export async function showSettings(): Promise<void> {
+  const client = getClient()
+  const settings = await client.getSettings() as {
+    providers: Array<{
+      name: string
+      model?: string
+      configured: boolean
+      quota?: { maxConcurrency: number; maxRequestsPerMinute: number; maxRequestsPerDay: number }
+    }>
+  }
+
+  console.log('Provider settings:\n')
+
+  for (const provider of settings.providers) {
+    const status = provider.configured ? 'configured' : 'not configured'
+    console.log(`  ${provider.name.padEnd(10)} ${status}`)
+    if (provider.configured) {
+      console.log(`    Model:     ${provider.model ?? '(default)'}`)
+      if (provider.quota) {
+        console.log(`    Quota:     ${provider.quota.maxConcurrency} concurrent · ${provider.quota.maxRequestsPerMinute}/min · ${provider.quota.maxRequestsPerDay}/day`)
+      }
+    }
+  }
+}

package/src/commands/status.ts

@@ -0,0 +1,52 @@
+import { loadConfig } from '../config.js'
+import { ApiClient } from '../client.js'
+
+function getClient(): ApiClient {
+  const config = loadConfig()
+  return new ApiClient(config.apiUrl, config.apiKey)
+}
+
+export async function showStatus(project: string): Promise<void> {
+  const client = getClient()
+  const projectData = await client.getProject(project) as {
+    id: string
+    name: string
+    displayName: string
+    canonicalDomain: string
+    country: string
+    language: string
+  }
+
+  console.log(`Status: ${projectData.displayName} (${projectData.name})\n`)
+  console.log(`  Domain:   ${projectData.canonicalDomain}`)
+  console.log(`  Country:  ${projectData.country}`)
+  console.log(`  Language: ${projectData.language}`)
+
+  // Try to get latest run info
+  try {
+    const runs = await client.listRuns(project) as Array<{
+      id: string
+      status: string
+      kind: string
+      createdAt: string
+      finishedAt: string | null
+    }>
+
+    if (runs.length > 0) {
+      const latest = runs[runs.length - 1]!
+      console.log(`\n  Latest run:`)
+      console.log(`    ID:       ${latest.id}`)
+      console.log(`    Status:   ${latest.status}`)
+      console.log(`    Created:  ${latest.createdAt}`)
+      if (latest.finishedAt) {
+        console.log(`    Finished: ${latest.finishedAt}`)
+      }
+      console.log(`\n  Total runs: ${runs.length}`)
+    } else {
+      console.log('\n  No runs yet. Use "canonry run" to trigger one.')
+    }
+  } catch {
+    // Runs endpoint may not be available
+    console.log('\n  Run info unavailable.')
+  }
+}

package/src/config.ts

@@ -0,0 +1,90 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import { parse, stringify } from 'yaml'
+import type { ProviderQuotaPolicy } from '@ainyc/canonry-contracts'
+
+export interface ProviderConfigEntry {
+  apiKey?: string
+  baseUrl?: string
+  model?: string
+  quota?: ProviderQuotaPolicy
+}
+
+export interface CanonryConfig {
+  apiUrl: string
+  database: string
+  apiKey: string
+  port?: number
+  // Legacy single-provider fields (backward compat)
+  geminiApiKey?: string
+  geminiModel?: string
+  geminiQuota?: ProviderQuotaPolicy
+  // Multi-provider config
+  providers?: {
+    gemini?: ProviderConfigEntry
+    openai?: ProviderConfigEntry
+    claude?: ProviderConfigEntry
+    local?: ProviderConfigEntry
+  }
+}
+
+export function getConfigDir(): string {
+  return path.join(os.homedir(), '.canonry')
+}
+
+export function getConfigPath(): string {
+  return path.join(getConfigDir(), 'config.yaml')
+}
+
+export function loadConfig(): CanonryConfig {
+  const configPath = getConfigPath()
+  if (!fs.existsSync(configPath)) {
+    throw new Error(
+      `Config not found at ${configPath}. Run "canonry init" to create one.`,
+    )
+  }
+  const raw = fs.readFileSync(configPath, 'utf-8')
+  const parsed = parse(raw) as CanonryConfig
+  if (!parsed.apiUrl || !parsed.database || !parsed.apiKey) {
+    throw new Error(
+      `Invalid config at ${configPath}. Required fields: apiUrl, database, apiKey`,
+    )
+  }
+
+  // Migrate legacy geminiApiKey to providers map
+  if (parsed.geminiApiKey && !parsed.providers?.gemini) {
+    parsed.providers = {
+      ...parsed.providers,
+      gemini: {
+        apiKey: parsed.geminiApiKey,
+        model: parsed.geminiModel,
+        quota: parsed.geminiQuota,
+      },
+    }
+  }
+
+  // Must have at least one provider configured
+  const hasProvider = parsed.providers &&
+    (parsed.providers.gemini?.apiKey || parsed.providers.openai?.apiKey || parsed.providers.claude?.apiKey || parsed.providers.local?.baseUrl)
+  if (!hasProvider) {
+    throw new Error(
+      `No providers configured at ${configPath}. At least one provider is required.`,
+    )
+  }
+
+  return parsed
+}
+
+export function saveConfig(config: CanonryConfig): void {
+  const configDir = getConfigDir()
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true })
+  }
+  const yaml = stringify(config)
+  fs.writeFileSync(getConfigPath(), yaml, { encoding: 'utf-8', mode: 0o600 })
+}
+
+export function configExists(): boolean {
+  return fs.existsSync(getConfigPath())
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { createServer } from './server.js'
+export { loadConfig, type CanonryConfig } from './config.js'

package/src/job-runner.ts

@@ -0,0 +1,368 @@
+import crypto from 'node:crypto'
+import { eq } from 'drizzle-orm'
+import type { DatabaseClient } from '@ainyc/canonry-db'
+import { runs, keywords, competitors, projects, querySnapshots, usageCounters } from '@ainyc/canonry-db'
+import type { ProviderName, NormalizedQueryResult } from '@ainyc/canonry-contracts'
+import type { ProviderRegistry, RegisteredProvider } from './provider-registry.js'
+
+export class JobRunner {
+  private db: DatabaseClient
+  private registry: ProviderRegistry
+  onRunCompleted?: (runId: string, projectId: string) => Promise<void>
+
+  constructor(db: DatabaseClient, registry: ProviderRegistry) {
+    this.db = db
+    this.registry = registry
+  }
+
+  async executeRun(runId: string, projectId: string, providerOverride?: ProviderName[]): Promise<void> {
+    const now = new Date().toISOString()
+
+    try {
+      // Mark run as running
+      this.db
+        .update(runs)
+        .set({ status: 'running', startedAt: now })
+        .where(eq(runs.id, runId))
+        .run()
+
+      // Fetch project
+      const project = this.db
+        .select()
+        .from(projects)
+        .where(eq(projects.id, projectId))
+        .get()
+
+      if (!project) {
+        throw new Error(`Project ${projectId} not found`)
+      }
+
+      // Resolve which providers to use — honour per-run override, then project config
+      const projectProviders = providerOverride ?? (JSON.parse(project.providers || '[]') as ProviderName[])
+      const activeProviders = this.registry.getForProject(projectProviders)
+
+      if (activeProviders.length === 0) {
+        throw new Error('No providers configured. Add at least one provider API key.')
+      }
+
+      console.log(`[JobRunner] Run ${runId}: dispatching to ${activeProviders.length} providers: ${activeProviders.map(p => p.adapter.name).join(', ')}`)
+
+      // Fetch keywords for the project
+      const projectKeywords = this.db
+        .select()
+        .from(keywords)
+        .where(eq(keywords.projectId, projectId))
+        .all()
+
+      // Fetch competitors for the project
+      const projectCompetitors = this.db
+        .select()
+        .from(competitors)
+        .where(eq(competitors.projectId, projectId))
+        .all()
+
+      const competitorDomains = projectCompetitors.map(c => c.domain)
+
+      // Enforce daily quota per provider — each provider receives one query per keyword.
+      // Track and check usage per (projectId, providerName) so that a provider that has
+      // never been used isn't blocked by another provider's past usage.
+      const queriesPerProvider = projectKeywords.length
+      const todayPeriod = getCurrentPeriod()
+
+      for (const p of activeProviders) {
+        const providerScope = `${projectId}:${p.adapter.name}`
+        const providerUsage = this.db
+          .select()
+          .from(usageCounters)
+          .where(eq(usageCounters.scope, providerScope))
+          .all()
+          .filter(r => r.period === todayPeriod && r.metric === 'queries')
+          .reduce((sum, r) => sum + r.count, 0)
+        const limit = p.config.quotaPolicy.maxRequestsPerDay
+        if (providerUsage + queriesPerProvider > limit) {
+          throw new Error(
+            `Daily quota exceeded for ${p.adapter.name}: ${providerUsage} queries used today, ` +
+            `limit is ${limit}. This run needs ${queriesPerProvider} more.`,
+          )
+        }
+      }
+
+      // Per-provider rate limiting: separate sliding windows
+      const minuteWindows = new Map<ProviderName, number[]>()
+      for (const p of activeProviders) {
+        minuteWindows.set(p.adapter.name, [])
+      }
+
+      // Track per-provider errors for partial completion
+      const providerErrors = new Map<ProviderName, string>()
+      let totalSnapshotsInserted = 0
+
+      // Process each keyword across all providers
+      for (const kw of projectKeywords) {
+        // Fan out across providers for this keyword
+        const providerPromises = activeProviders.map(async (registeredProvider) => {
+          const { adapter, config } = registeredProvider
+          const providerName = adapter.name
+
+          try {
+            // Enforce per-minute rate limit
+            await this.waitForRateLimit(
+              minuteWindows.get(providerName)!,
+              config.quotaPolicy.maxRequestsPerMinute,
+            )
+
+            const raw = await adapter.executeTrackedQuery(
+              {
+                keyword: kw.keyword,
+                canonicalDomains: [project.canonicalDomain],
+                competitorDomains,
+              },
+              config,
+            )
+
+            const normalized = adapter.normalizeResult(raw)
+
+            console.log(`[JobRunner] ${providerName}: "${kw.keyword}" citedDomains=${JSON.stringify(normalized.citedDomains)}, groundingSources=${JSON.stringify(normalized.groundingSources.map(s => s.uri))}, canonical="${project.canonicalDomain}"`)
+            const citationState = determineCitationState(normalized, project.canonicalDomain)
+            const overlap = computeCompetitorOverlap(normalized, competitorDomains)
+
+            this.db.insert(querySnapshots).values({
+              id: crypto.randomUUID(),
+              runId,
+              keywordId: kw.id,
+              provider: providerName,
+              citationState,
+              answerText: normalized.answerText,
+              citedDomains: JSON.stringify(normalized.citedDomains),
+              competitorOverlap: JSON.stringify(overlap),
+              rawResponse: JSON.stringify({
+                model: raw.model,
+                groundingSources: normalized.groundingSources,
+                searchQueries: normalized.searchQueries,
+                apiResponse: raw.rawResponse,
+              }),
+              createdAt: new Date().toISOString(),
+            }).run()
+
+            totalSnapshotsInserted++
+            console.log(`[JobRunner] ${providerName}: keyword "${kw.keyword}" → ${citationState}`)
+          } catch (err: unknown) {
+            const msg = err instanceof Error ? err.message : String(err)
+            console.error(`[JobRunner] ${providerName}: keyword "${kw.keyword}" FAILED: ${msg}`)
+            providerErrors.set(providerName, msg)
+          }
+        })
+
+        await Promise.all(providerPromises)
+      }
+
+      // Determine final run status
+      const allFailed = totalSnapshotsInserted === 0 && providerErrors.size > 0
+      const someFailed = providerErrors.size > 0
+
+      if (allFailed) {
+        const errorDetail = JSON.stringify(Object.fromEntries(providerErrors))
+        this.db
+          .update(runs)
+          .set({ status: 'failed', finishedAt: new Date().toISOString(), error: errorDetail })
+          .where(eq(runs.id, runId))
+          .run()
+      } else if (someFailed) {
+        const errorDetail = JSON.stringify(Object.fromEntries(providerErrors))
+        this.db
+          .update(runs)
+          .set({ status: 'partial', finishedAt: new Date().toISOString(), error: errorDetail })
+          .where(eq(runs.id, runId))
+          .run()
+      } else {
+        this.db
+          .update(runs)
+          .set({ status: 'completed', finishedAt: new Date().toISOString() })
+          .where(eq(runs.id, runId))
+          .run()
+      }
+
+      // Increment per-provider usage counters to keep quota checks accurate
+      for (const p of activeProviders) {
+        this.incrementUsage(`${projectId}:${p.adapter.name}`, 'queries', queriesPerProvider)
+      }
+      this.incrementUsage(projectId, 'runs', 1)
+
+      // Notify after run completion
+      if (this.onRunCompleted) {
+        this.onRunCompleted(runId, projectId).catch((err: unknown) => {
+          console.error('[JobRunner] Notification callback failed:', err)
+        })
+      }
+    } catch (err: unknown) {
+      // Mark run as failed
+      const errorMessage = err instanceof Error ? err.message : String(err)
+      this.db
+        .update(runs)
+        .set({
+          status: 'failed',
+          finishedAt: new Date().toISOString(),
+          error: errorMessage,
+        })
+        .where(eq(runs.id, runId))
+        .run()
+
+      // Notify on failure too
+      if (this.onRunCompleted) {
+        this.onRunCompleted(runId, projectId).catch((notifErr: unknown) => {
+          console.error('[JobRunner] Notification callback failed:', notifErr)
+        })
+      }
+    }
+  }
+
+  private async waitForRateLimit(window: number[], maxPerMinute: number): Promise<void> {
+    const now = Date.now()
+    const windowStart = now - 60_000
+    while (window.length > 0 && window[0]! < windowStart) {
+      window.shift()
+    }
+    if (window.length >= maxPerMinute) {
+      const oldestInWindow = window[0]!
+      const waitMs = oldestInWindow + 60_000 - now + 50
+      await new Promise(resolve => setTimeout(resolve, waitMs))
+      const nowAfterWait = Date.now()
+      const newWindowStart = nowAfterWait - 60_000
+      while (window.length > 0 && window[0]! < newWindowStart) {
+        window.shift()
+      }
+    }
+    window.push(Date.now())
+  }
+
+  private incrementUsage(scope: string, metric: string, count: number): void {
+    const now = new Date()
+    const period = `${now.getUTCFullYear()}-${String(now.getUTCMonth() + 1).padStart(2, '0')}`
+    const id = crypto.randomUUID()
+
+    const existing = this.db
+      .select()
+      .from(usageCounters)
+      .where(eq(usageCounters.scope, scope))
+      .all()
+      .find(r => r.period === period && r.metric === metric)
+
+    if (existing) {
+      this.db
+        .update(usageCounters)
+        .set({ count: existing.count + count, updatedAt: now.toISOString() })
+        .where(eq(usageCounters.id, existing.id))
+        .run()
+    } else {
+      this.db.insert(usageCounters).values({
+        id,
+        scope,
+        period,
+        metric,
+        count,
+        updatedAt: now.toISOString(),
+      }).run()
+    }
+  }
+}
+
+function getCurrentPeriod(): string {
+  const d = new Date()
+  return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, '0')}`
+}
+
+/** Normalize a canonical domain that may be stored as a full URL (e.g. "https://www.ainyc.ai") to a bare domain ("ainyc.ai") */
+function normalizeDomain(input: string): string {
+  let domain = input
+  try {
+    if (domain.includes('://')) {
+      domain = new URL(domain).hostname
+    }
+  } catch {
+    // not a URL, use as-is
+  }
+  return domain.replace(/^www\./, '')
+}
+
+function domainMatches(domain: string, canonicalDomain: string): boolean {
+  const normalized = normalizeDomain(canonicalDomain)
+  const d = normalizeDomain(domain)
+  return d === normalized || d.endsWith(`.${normalized}`)
+}
+
+function determineCitationState(
+  normalized: NormalizedQueryResult,
+  canonicalDomain: string,
+): 'cited' | 'not-cited' {
+  const bareDomain = normalizeDomain(canonicalDomain)
+
+  // Check extracted cited domains
+  if (normalized.citedDomains.some(d => domainMatches(d, bareDomain))) {
+    return 'cited'
+  }
+
+  // Also check grounding source URIs and titles directly
+  const lowerDomain = bareDomain.toLowerCase()
+  for (const source of normalized.groundingSources) {
+    try {
+      const uri = source.uri.toLowerCase()
+      if (uri.includes(lowerDomain)) {
+        return 'cited'
+      }
+    } catch {
+      // ignore
+    }
+    // Gemini proxy URLs use base64 encoding, so the domain won't appear in the URI.
+    // The title field often contains the bare domain (e.g. "ainyc.ai").
+    if (source.title) {
+      const titleLower = source.title.toLowerCase().replace(/^www\./, '')
+      if (titleLower === lowerDomain || titleLower.endsWith(`.${lowerDomain}`)) {
+        return 'cited'
+      }
+    }
+  }
+
+  return 'not-cited'
+}
+
+function computeCompetitorOverlap(
+  normalized: NormalizedQueryResult,
+  competitorDomains: string[],
+): string[] {
+  const overlapSet = new Set<string>()
+
+  // Check extracted cited domains
+  for (const d of normalized.citedDomains) {
+    for (const cd of competitorDomains) {
+      if (domainMatches(d, cd)) {
+        overlapSet.add(cd)
+      }
+    }
+  }
+
+  // Check grounding source URIs (handles proxy URLs)
+  for (const source of normalized.groundingSources) {
+    const uri = source.uri.toLowerCase()
+    for (const cd of competitorDomains) {
+      if (uri.includes(cd.toLowerCase())) {
+        overlapSet.add(cd)
+      }
+    }
+  }
+
+  // Check answer text for competitor domain mentions
+  if (normalized.answerText) {
+    const lowerAnswer = normalized.answerText.toLowerCase()
+    for (const cd of competitorDomains) {
+      if (lowerAnswer.includes(cd.toLowerCase())) {
+        overlapSet.add(cd)
+      }
+      const brand = cd.split('.')[0]
+      if (brand && brand.length >= 4 && new RegExp(`\\b${brand}\\b`, 'i').test(lowerAnswer)) {
+        overlapSet.add(cd)
+      }
+    }
+  }
+
+  return [...overlapSet]
+}