Full Type Reference

interface ApptvtyConfig {
  apiKey: string;         // Required — your API key (ak_live_...)
  siteId: string;         // Required — your site ID (site_...)
  baseUrl?: string;       // Default: 'https://api.apptvty.com'
  batchSize?: number;     // Default: 50   — log entries per flush
  flushInterval?: number; // Default: 5000 — ms between auto-flushes
  debug?: boolean;        // Default: false — print errors to console
  queryPath?: string;     // Default: '/query' — AEO endpoint path
}

interface CrawlerInfo {
  isAi: boolean;                           // Is this AI/LLM traffic?
  name: string | null;                     // e.g. 'GPTBot', 'ClaudeBot', null
  organization: string | null;             // e.g. 'OpenAI', 'Anthropic', null
  confidence: number;                      // 0.0 – 1.0
  detectionMethod:
    | 'exact_match'    // matched a known crawler string
    | 'pattern_match'  // matched an AI-related pattern
    | 'heuristic'      // inferred from bot-like signals
    | 'none';          // unknown / no signal
}

interface RequestLogEntry {
  site_id: string;                  // From ApptvtyConfig.siteId
  timestamp: string;                // ISO 8601 UTC
  request_method: string;           // HTTP method, e.g. 'GET'
  request_path: string;             // URL path, e.g. '/blog/post-1'
  response_status: number;          // HTTP response status
  response_time_ms: number;         // ms from request start to response
  ip_address: string;               // Client IP
  user_agent: string;               // Raw User-Agent string
  referer: string | null;           // Referer header (or null)
  is_ai_crawler: boolean;           // From CrawlerInfo.isAi
  crawler_type: string | null;      // From CrawlerInfo.name
  crawler_organization: string | null; // From CrawlerInfo.organization
  confidence_score: number;         // From CrawlerInfo.confidence
  scraper_service: string | null;   // e.g. 'JinaReader' or null
}

interface QuerySource {
  url: string;       // Canonical URL of the source page
  title: string;     // Page title
  snippet: string;   // Relevant excerpt from the page
  relevance: number; // 0.0 – 1.0 — how relevant this source was to the query
}

interface SponsoredAd {
  label: 'Sponsored';      // Always exactly 'Sponsored' — use to label the ad
  text: string;            // Ad copy to show the user
  url: string;             // Attribution URL for the advertiser
  advertiser: string;      // Advertiser name
  impression_id: string;   // Unique ID — SDK logs this automatically for billing
}

interface AgentQueryResponse {
  success: true;
  version: '1.0';
  query: string;              // The question as received
  answer: string;             // RAG-generated answer
  sources: QuerySource[];     // Source pages used to generate the answer
  confidence: number;         // 0.0 – 1.0
  sponsored?: SponsoredAd | SponsoredAd[]; // matched ads (optional)
  metadata: {
    request_id: string;
    response_time_ms: number;
    tokens_used: number;
    site_id: string;
    timestamp: string;        // ISO 8601
  };
}

interface QueryEndpointDiscovery {
  version: '1.0';
  endpoint: string;            // Full URL of this endpoint
  description: string;
  usage: {
    method: 'GET';
    parameters: {
      q:    { type: 'string'; required: true;  description: string };
      lang: { type: 'string'; required: false; description: string };
    };
    example: string;           // Example URL with ?q=
    response_format: 'application/json';
  };
  capabilities: string[];      // e.g. ['rag', 'sponsored_ads']
  rate_limit: string;          // e.g. '60 requests per minute'
}

interface AgentErrorResponse {
  success: false;
  error: {
    code: string;          // e.g. 'QUERY_TOO_LONG', 'UPSTREAM_ERROR'
    message: string;       // Human-readable description
    request_id: string;
    timestamp: string;     // ISO 8601
  };
}

interface ImpressionLog {
  impression_id: string;   // From SponsoredAd.impression_id
  site_id: string;
  query: string;           // The question that triggered the ad
  agent_ua: string;        // User-agent of the calling agent
  agent_ip: string;
  timestamp: string;       // ISO 8601
}

interface RegisterOptions {
  domain: string;                              // e.g. 'mysite.com'
  framework?: 'nextjs' | 'express' | 'other'; // default: 'other'
  agentId?: string;                            // identifies the registering agent
  apiUrl?: string;                             // override API base URL
}

interface RegisterResult {
  siteId: string;                   // Use in ApptvtyConfig
  apiKey: string;                   // Use in ApptvtyConfig
  companyId: string;
  walletAddress: string | null;     // Crossmint USDC wallet, or null
  dashboardUrl: string;             // Claim link — valid for 30 days
  claimTokenExpiresAt: string;      // ISO 8601
  trialEndsAt: string;              // ISO 8601
  email: string | null;             // Linked email
  setup: {
    envVars: {
      APPTVTY_SITE_ID: string;
      APPTVTY_API_KEY: string;
    };
    files?: Record<string, string>; // path → file content
    x402?: {
      chain: string;
      currency: string;
    };
  };
}