apptvty 0.1.2

package/dist/types-C1oUTCsT.d.mts

@@ -0,0 +1,263 @@
+interface ApptvtyConfig {
+    /** Your site's API key from the Apptvty dashboard (ak_...) */
+    apiKey: string;
+    /** Your site ID from the Apptvty dashboard */
+    siteId: string;
+    /**
+     * Apptvty API base URL. Default: https://api.apptvty.com.
+     * Uses APPTVTY_API_URL env var if set. Override only for self-hosted backend.
+     */
+    baseUrl?: string;
+    /**
+     * How many log entries to accumulate before flushing to the API.
+     * Default: 50
+     */
+    batchSize?: number;
+    /**
+     * How often (in ms) to flush accumulated logs, even if batchSize is not reached.
+     * Default: 5000 (5 seconds)
+     */
+    flushInterval?: number;
+    /**
+     * Whether to enable debug logging to console.
+     * Default: false
+     */
+    debug?: boolean;
+    /**
+     * Path at which the query page is served on the website owner's domain.
+     * Default: '/query'
+     * This path is referenced in agents.txt and sitemaps.
+     */
+    queryPath?: string;
+}
+interface CrawlerInfo {
+    isAi: boolean;
+    name: string | null;
+    organization: string | null;
+    /** 0.0 – 1.0 */
+    confidence: number;
+    detectionMethod: 'exact_match' | 'pattern_match' | 'heuristic' | 'none';
+}
+interface RequestLogEntry {
+    site_id: string;
+    timestamp: string;
+    method: string;
+    path: string;
+    status_code: number;
+    response_time_ms: number;
+    ip_address: string;
+    user_agent: string;
+    referer: string | null;
+    is_ai_crawler: boolean;
+    crawler_type: string | null;
+    crawler_organization: string | null;
+    confidence_score: number;
+}
+/**
+ * Sent to the Apptvty backend when an agent queries the site's /query endpoint.
+ */
+interface QueryRequest {
+    site_id: string;
+    query: string;
+    agent_ua: string;
+    agent_ip: string;
+    request_id: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Include sponsored ads in response (default true). Set to false to opt out. */
+    surface_ads?: boolean;
+    /** Explicit signal: "I am an AI agent/crawler" — ensures ads are surfaced. Use ?ai_crawler=1 when crawling. */
+    ai_crawler?: boolean;
+}
+/**
+ * The raw response from the Apptvty backend for a query.
+ * The SDK passes this through to the agent unchanged,
+ * wrapping it in the standard envelope.
+ */
+interface BackendQueryResponse {
+    answer: string;
+    sources: QuerySource[];
+    confidence: number;
+    tokens_used: number;
+    /** Present only when ads are enabled for this site and a matching ad was found (1–2 ads max) */
+    sponsored?: SponsoredAd | SponsoredAd[];
+}
+interface QuerySource {
+    url: string;
+    title: string;
+    snippet: string;
+    relevance: number;
+}
+/**
+ * An ad returned from the Apptvty ad network.
+ *
+ * Advertisers pay per agentic view (impression).
+ * The website owner earns USDC for each impression served.
+ *
+ * The impression_id is used by the SDK to log the view back
+ * to Apptvty for billing. Do not modify or omit it.
+ */
+interface SponsoredAd {
+    /** Human-readable label — always "Sponsored" for transparency */
+    label: 'Sponsored';
+    /** The ad copy shown to the agent */
+    text: string;
+    /** Attribution/click URL for the advertiser */
+    url: string;
+    /** Advertiser name */
+    advertiser: string;
+    /**
+     * Unique identifier for this ad impression.
+     * The SDK sends this back to Apptvty to record the view and trigger billing.
+     */
+    impression_id: string;
+}
+/**
+ * The JSON response returned by the SDK's query endpoint to the calling agent.
+ */
+interface AgentQueryResponse {
+    success: true;
+    version: '1.0';
+    query: string;
+    answer: string;
+    sources: QuerySource[];
+    confidence: number;
+    /** Present when ads are enabled and an ad was matched (1–2 ads max) */
+    sponsored?: SponsoredAd | SponsoredAd[];
+    metadata: {
+        request_id: string;
+        response_time_ms: number;
+        tokens_used: number;
+        site_id: string;
+        timestamp: string;
+    };
+}
+/**
+ * Returned when the query endpoint is called without a ?q= parameter.
+ * Instructs agents how to use the endpoint (self-describing discovery page).
+ */
+interface QueryEndpointDiscovery {
+    version: '1.0';
+    endpoint: string;
+    description: string;
+    /** Instructs crawlers to prefer query over full-site crawl */
+    crawl_policy: string;
+    usage: {
+        method: 'GET';
+        parameters: {
+            q: {
+                type: 'string';
+                required: true;
+                description: string;
+            };
+            lang: {
+                type: 'string';
+                required: false;
+                description: string;
+            };
+            surface_ads: {
+                type: 'boolean';
+                required: false;
+                description: string;
+            };
+            ai_crawler: {
+                type: 'boolean';
+                required: false;
+                description: string;
+            };
+        };
+        example: string;
+        response_format: 'application/json';
+    };
+    capabilities: string[];
+    rate_limit: string;
+}
+interface AgentErrorResponse {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+        request_id: string;
+        timestamp: string;
+    };
+}
+/**
+ * Sent to Apptvty when an ad is shown in a query response.
+ * Triggers: advertiser billing, publisher USDC credit.
+ */
+interface PageAd {
+    text: string;
+    url: string;
+    advertiser: string;
+    impression_id: string;
+}
+interface PageAdsResponse {
+    ads: PageAd[];
+}
+interface ImpressionLog {
+    impression_id: string;
+    site_id: string;
+    query: string;
+    agent_ua: string;
+    agent_ip: string;
+    timestamp: string;
+}
+/** 30-day overview returned by getSiteStats */
+interface SiteOverviewStats {
+    total_requests_30d: number;
+    ai_requests_30d: number;
+    human_requests_30d: number;
+    ai_percentage: number;
+    unique_crawlers_30d: number;
+    queries_30d: number;
+    avg_response_ms: number;
+}
+/** Per-day stats returned by getSiteDailyStats */
+interface DailyStat {
+    date: string;
+    total_requests: number;
+    ai_requests: number;
+    human_requests: number;
+    avg_response_ms: number;
+    unique_crawlers: number;
+    unique_ips: number;
+}
+/** Crawler type breakdown */
+interface CrawlerBreakdown {
+    crawler_type: string;
+    requests: number;
+    percentage: number;
+    last_seen: string;
+}
+/** Recent request in activity feed */
+interface RecentActivityItem {
+    timestamp: string;
+    path: string;
+    crawler_type: string | null;
+    is_ai_crawler: boolean;
+    status_code: number;
+    response_time_ms: number | null;
+    user_agent: string | null;
+}
+/** Recent agent query */
+interface RecentQueryItem {
+    id: string;
+    timestamp: string;
+    question: string;
+    answer_summary: string | null;
+    tokens_used: number | null;
+    response_time_ms: number | null;
+    crawler_type: string | null;
+    success: boolean;
+}
+/** Wallet balance and earnings */
+interface SiteWalletInfo {
+    company_id: string;
+    site_id: string;
+    wallet_address: string | null;
+    balance_usdc: number;
+    total_earned_usdc: number;
+    total_spent_usdc: number;
+}
+
+export type { ApptvtyConfig as A, BackendQueryResponse as B, CrawlerBreakdown as C, DailyStat as D, ImpressionLog as I, PageAdsResponse as P, QueryRequest as Q, RequestLogEntry as R, SiteOverviewStats as S, RecentActivityItem as a, RecentQueryItem as b, SiteWalletInfo as c, CrawlerInfo as d, AgentQueryResponse as e, QueryEndpointDiscovery as f, AgentErrorResponse as g, PageAd as h, QuerySource as i, SponsoredAd as j };

package/dist/types-C1oUTCsT.d.ts

@@ -0,0 +1,263 @@
+interface ApptvtyConfig {
+    /** Your site's API key from the Apptvty dashboard (ak_...) */
+    apiKey: string;
+    /** Your site ID from the Apptvty dashboard */
+    siteId: string;
+    /**
+     * Apptvty API base URL. Default: https://api.apptvty.com.
+     * Uses APPTVTY_API_URL env var if set. Override only for self-hosted backend.
+     */
+    baseUrl?: string;
+    /**
+     * How many log entries to accumulate before flushing to the API.
+     * Default: 50
+     */
+    batchSize?: number;
+    /**
+     * How often (in ms) to flush accumulated logs, even if batchSize is not reached.
+     * Default: 5000 (5 seconds)
+     */
+    flushInterval?: number;
+    /**
+     * Whether to enable debug logging to console.
+     * Default: false
+     */
+    debug?: boolean;
+    /**
+     * Path at which the query page is served on the website owner's domain.
+     * Default: '/query'
+     * This path is referenced in agents.txt and sitemaps.
+     */
+    queryPath?: string;
+}
+interface CrawlerInfo {
+    isAi: boolean;
+    name: string | null;
+    organization: string | null;
+    /** 0.0 – 1.0 */
+    confidence: number;
+    detectionMethod: 'exact_match' | 'pattern_match' | 'heuristic' | 'none';
+}
+interface RequestLogEntry {
+    site_id: string;
+    timestamp: string;
+    method: string;
+    path: string;
+    status_code: number;
+    response_time_ms: number;
+    ip_address: string;
+    user_agent: string;
+    referer: string | null;
+    is_ai_crawler: boolean;
+    crawler_type: string | null;
+    crawler_organization: string | null;
+    confidence_score: number;
+}
+/**
+ * Sent to the Apptvty backend when an agent queries the site's /query endpoint.
+ */
+interface QueryRequest {
+    site_id: string;
+    query: string;
+    agent_ua: string;
+    agent_ip: string;
+    request_id: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Include sponsored ads in response (default true). Set to false to opt out. */
+    surface_ads?: boolean;
+    /** Explicit signal: "I am an AI agent/crawler" — ensures ads are surfaced. Use ?ai_crawler=1 when crawling. */
+    ai_crawler?: boolean;
+}
+/**
+ * The raw response from the Apptvty backend for a query.
+ * The SDK passes this through to the agent unchanged,
+ * wrapping it in the standard envelope.
+ */
+interface BackendQueryResponse {
+    answer: string;
+    sources: QuerySource[];
+    confidence: number;
+    tokens_used: number;
+    /** Present only when ads are enabled for this site and a matching ad was found (1–2 ads max) */
+    sponsored?: SponsoredAd | SponsoredAd[];
+}
+interface QuerySource {
+    url: string;
+    title: string;
+    snippet: string;
+    relevance: number;
+}
+/**
+ * An ad returned from the Apptvty ad network.
+ *
+ * Advertisers pay per agentic view (impression).
+ * The website owner earns USDC for each impression served.
+ *
+ * The impression_id is used by the SDK to log the view back
+ * to Apptvty for billing. Do not modify or omit it.
+ */
+interface SponsoredAd {
+    /** Human-readable label — always "Sponsored" for transparency */
+    label: 'Sponsored';
+    /** The ad copy shown to the agent */
+    text: string;
+    /** Attribution/click URL for the advertiser */
+    url: string;
+    /** Advertiser name */
+    advertiser: string;
+    /**
+     * Unique identifier for this ad impression.
+     * The SDK sends this back to Apptvty to record the view and trigger billing.
+     */
+    impression_id: string;
+}
+/**
+ * The JSON response returned by the SDK's query endpoint to the calling agent.
+ */
+interface AgentQueryResponse {
+    success: true;
+    version: '1.0';
+    query: string;
+    answer: string;
+    sources: QuerySource[];
+    confidence: number;
+    /** Present when ads are enabled and an ad was matched (1–2 ads max) */
+    sponsored?: SponsoredAd | SponsoredAd[];
+    metadata: {
+        request_id: string;
+        response_time_ms: number;
+        tokens_used: number;
+        site_id: string;
+        timestamp: string;
+    };
+}
+/**
+ * Returned when the query endpoint is called without a ?q= parameter.
+ * Instructs agents how to use the endpoint (self-describing discovery page).
+ */
+interface QueryEndpointDiscovery {
+    version: '1.0';
+    endpoint: string;
+    description: string;
+    /** Instructs crawlers to prefer query over full-site crawl */
+    crawl_policy: string;
+    usage: {
+        method: 'GET';
+        parameters: {
+            q: {
+                type: 'string';
+                required: true;
+                description: string;
+            };
+            lang: {
+                type: 'string';
+                required: false;
+                description: string;
+            };
+            surface_ads: {
+                type: 'boolean';
+                required: false;
+                description: string;
+            };
+            ai_crawler: {
+                type: 'boolean';
+                required: false;
+                description: string;
+            };
+        };
+        example: string;
+        response_format: 'application/json';
+    };
+    capabilities: string[];
+    rate_limit: string;
+}
+interface AgentErrorResponse {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+        request_id: string;
+        timestamp: string;
+    };
+}
+/**
+ * Sent to Apptvty when an ad is shown in a query response.
+ * Triggers: advertiser billing, publisher USDC credit.
+ */
+interface PageAd {
+    text: string;
+    url: string;
+    advertiser: string;
+    impression_id: string;
+}
+interface PageAdsResponse {
+    ads: PageAd[];
+}
+interface ImpressionLog {
+    impression_id: string;
+    site_id: string;
+    query: string;
+    agent_ua: string;
+    agent_ip: string;
+    timestamp: string;
+}
+/** 30-day overview returned by getSiteStats */
+interface SiteOverviewStats {
+    total_requests_30d: number;
+    ai_requests_30d: number;
+    human_requests_30d: number;
+    ai_percentage: number;
+    unique_crawlers_30d: number;
+    queries_30d: number;
+    avg_response_ms: number;
+}
+/** Per-day stats returned by getSiteDailyStats */
+interface DailyStat {
+    date: string;
+    total_requests: number;
+    ai_requests: number;
+    human_requests: number;
+    avg_response_ms: number;
+    unique_crawlers: number;
+    unique_ips: number;
+}
+/** Crawler type breakdown */
+interface CrawlerBreakdown {
+    crawler_type: string;
+    requests: number;
+    percentage: number;
+    last_seen: string;
+}
+/** Recent request in activity feed */
+interface RecentActivityItem {
+    timestamp: string;
+    path: string;
+    crawler_type: string | null;
+    is_ai_crawler: boolean;
+    status_code: number;
+    response_time_ms: number | null;
+    user_agent: string | null;
+}
+/** Recent agent query */
+interface RecentQueryItem {
+    id: string;
+    timestamp: string;
+    question: string;
+    answer_summary: string | null;
+    tokens_used: number | null;
+    response_time_ms: number | null;
+    crawler_type: string | null;
+    success: boolean;
+}
+/** Wallet balance and earnings */
+interface SiteWalletInfo {
+    company_id: string;
+    site_id: string;
+    wallet_address: string | null;
+    balance_usdc: number;
+    total_earned_usdc: number;
+    total_spent_usdc: number;
+}
+
+export type { ApptvtyConfig as A, BackendQueryResponse as B, CrawlerBreakdown as C, DailyStat as D, ImpressionLog as I, PageAdsResponse as P, QueryRequest as Q, RequestLogEntry as R, SiteOverviewStats as S, RecentActivityItem as a, RecentQueryItem as b, SiteWalletInfo as c, CrawlerInfo as d, AgentQueryResponse as e, QueryEndpointDiscovery as f, AgentErrorResponse as g, PageAd as h, QuerySource as i, SponsoredAd as j };

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "apptvty",
+  "version": "0.1.2",
+  "description": "Server-side analytics and AEO (Agent Experience Optimization) SDK for websites. Logs agentic traffic, exposes a structured query endpoint for AI agents, and serves relevant ads on agent queries.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "apptvty": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./setup": {
+      "types": "./dist/setup.d.ts",
+      "import": "./dist/setup.mjs",
+      "require": "./dist/setup.js"
+    },
+    "./nextjs": {
+      "types": "./dist/middleware/nextjs.d.ts",
+      "import": "./dist/middleware/nextjs.mjs",
+      "require": "./dist/middleware/nextjs.js"
+    },
+    "./express": {
+      "types": "./dist/middleware/express.d.ts",
+      "import": "./dist/middleware/express.mjs",
+      "require": "./dist/middleware/express.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "jest",
+    "test:unit": "jest --testPathIgnorePatterns=integration",
+    "test:integration": "jest --testPathPattern=integration",
+    "prepublishOnly": "npm run build && npm run typecheck"
+  },
+  "keywords": [
+    "analytics",
+    "aeo",
+    "agent-experience-optimization",
+    "ai-crawler",
+    "agentic-traffic",
+    "sitemap",
+    "rag",
+    "apptvty"
+  ],
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "next": ">=13.0.0",
+    "express": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    },
+    "express": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.12.0",
+    "jest": "^29.7.0",
+    "next": "^14.0.0",
+    "ts-jest": "^29.1.2",
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.5"
+  }
+}