apptvty 0.1.2

package/dist/index.d.ts

@@ -0,0 +1,170 @@
+import { A as ApptvtyConfig, R as RequestLogEntry, Q as QueryRequest, B as BackendQueryResponse, P as PageAdsResponse, I as ImpressionLog, S as SiteOverviewStats, D as DailyStat, C as CrawlerBreakdown, a as RecentActivityItem, b as RecentQueryItem, c as SiteWalletInfo, d as CrawlerInfo, e as AgentQueryResponse, f as QueryEndpointDiscovery, g as AgentErrorResponse } from './types-C1oUTCsT.js';
+export { h as PageAd, i as QuerySource, j as SponsoredAd } from './types-C1oUTCsT.js';
+export { createNextjsQueryHandler, withApptvty } from './middleware/nextjs.js';
+export { createExpressMiddleware, createExpressQueryHandler } from './middleware/express.js';
+import 'next/server';
+import 'node:http';
+
+/**
+ * HTTP client for the Apptvty API.
+ *
+ * Handles:
+ *   - Batch log ingestion (/v1/logs/batch)
+ *   - Query processing (/v1/query) — returns answer + optional ad
+ *   - Impression logging (/v1/impressions) — triggers billing for ads
+ */
+
+declare class ApptvtyClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly siteId;
+    private readonly debug;
+    constructor(config: ApptvtyConfig);
+    /**
+     * Send a batch of request log entries to the Apptvty ingestion API.
+     * Called by the logger's auto-flush — not called directly by user code.
+     */
+    sendLogs(logs: RequestLogEntry[]): Promise<void>;
+    /**
+     * Send a query to the Apptvty backend.
+     * The backend runs RAG against the site's indexed content and,
+     * if ads are enabled for the site, attaches a relevant sponsored ad.
+     *
+     * @throws on non-retryable errors (network errors, 5xx) — callers should catch
+     */
+    query(req: QueryRequest): Promise<BackendQueryResponse>;
+    /**
+     * Get relevant ads for a page (for HTML injection when crawler is detected).
+     * Used by middleware to inject ads into HTML responses.
+     */
+    getAdsForPage(req: {
+        site_id: string;
+        page_path: string;
+    }): Promise<PageAdsResponse>;
+    /**
+     * Log an ad impression back to Apptvty.
+     *
+     * Called after returning a query response that contains a `sponsored` block.
+     * This is what triggers the billing cycle:
+     *   - Advertiser gets charged (debited from their USDC ad budget)
+     *   - Publisher (the website) gets credited in USDC
+     *
+     * This call is fire-and-forget. The SDK logs a warning on failure
+     * but does not throw — a missed impression log is better than
+     * breaking the query response.
+     */
+    logImpression(impression: ImpressionLog): Promise<void>;
+    /** Get 30-day traffic overview (requests, AI %, crawlers, queries). */
+    getSiteStats(): Promise<SiteOverviewStats>;
+    /** Get day-by-day stats (default 30 days, max 90). */
+    getSiteDailyStats(days?: number): Promise<{
+        days: number;
+        stats: DailyStat[];
+    }>;
+    /** Get crawler breakdown by type (default 30 days). */
+    getSiteCrawlers(days?: number): Promise<{
+        days: number;
+        crawlers: CrawlerBreakdown[];
+    }>;
+    /** Get recent activity feed (last hour, default 50 items, max 200). */
+    getSiteActivity(limit?: number): Promise<{
+        activity: RecentActivityItem[];
+    }>;
+    /** Get recent agent queries (default 50, max 200). */
+    getSiteQueries(limit?: number): Promise<{
+        queries: RecentQueryItem[];
+    }>;
+    /** Get wallet balance and earnings. */
+    getSiteWallet(): Promise<SiteWalletInfo>;
+    private get;
+    private post;
+    private log;
+    private warn;
+}
+declare class ApptvtyApiError extends Error {
+    readonly statusCode: number;
+    readonly path: string;
+    readonly body: string;
+    constructor(statusCode: number, path: string, body: string);
+}
+
+/**
+ * Batched request logger.
+ *
+ * Queues RequestLogEntry objects in memory and flushes them in batches
+ * to the Apptvty API. This keeps per-request overhead near zero.
+ *
+ * Flush triggers:
+ *   1. Queue reaches batchSize (default 50)
+ *   2. flushInterval elapses (default 5s)
+ *   3. process.exit / SIGTERM (best-effort sync flush)
+ */
+
+declare class RequestLogger {
+    private readonly client;
+    private queue;
+    private timer;
+    private flushing;
+    private readonly batchSize;
+    private readonly debug;
+    constructor(client: ApptvtyClient, config: ApptvtyConfig);
+    /** Enqueue a single log entry. Non-blocking. */
+    enqueue(entry: RequestLogEntry): void;
+    /** Flush the current queue to the API. */
+    flush(): Promise<void>;
+    /**
+     * Synchronous-ish flush for process shutdown.
+     * Fires the fetch and doesn't await to avoid blocking exit handlers.
+     */
+    private flushSync;
+    /** Stop the interval timer. Call when you want to fully tear down the SDK. */
+    destroy(): void;
+    private log;
+}
+
+/**
+ * Lightweight AI crawler detection.
+ *
+ * This is the single source of truth for crawler classification in the SDK.
+ * The backend (Python analytics API and TypeScript handlers) should eventually
+ * consume this same list rather than maintaining separate copies.
+ */
+
+declare function detectCrawler(userAgent: string): CrawlerInfo;
+/** Returns the list of all known crawlers for reference (e.g. for agents.txt generation) */
+declare function getKnownCrawlerNames(): string[];
+
+/**
+ * Framework-agnostic query endpoint handler.
+ *
+ * Serves the site's AEO (Agent Experience Optimization) query page.
+ *
+ * GET /query              → Returns a self-describing discovery JSON
+ * GET /query?q=<question> → Returns an AI-generated answer from the site's
+ *                           indexed content, plus a sponsored ad if ads are
+ *                           enabled and a matching ad exists.
+ *
+ * When an ad is included in the response, this handler fires an async
+ * impression log back to Apptvty to trigger billing:
+ *   - Advertiser is charged (debited from their USDC ad budget)
+ *   - Publisher earns USDC (credited to their Crossmint wallet)
+ */
+
+interface QueryHandlerRequest {
+    query: string | null;
+    lang: string | null;
+    surface_ads?: boolean;
+    ai_crawler?: boolean;
+    userAgent: string;
+    ipAddress: string;
+    /** Full URL of the request, used to build the example in the discovery response */
+    requestUrl: string;
+}
+interface QueryHandlerResponse {
+    status: number;
+    body: AgentQueryResponse | QueryEndpointDiscovery | AgentErrorResponse;
+    headers: Record<string, string>;
+}
+declare function createQueryHandler(client: ApptvtyClient, config: ApptvtyConfig): (req: QueryHandlerRequest) => Promise<QueryHandlerResponse>;
+
+export { AgentErrorResponse, AgentQueryResponse, ApptvtyApiError, ApptvtyClient, ApptvtyConfig, CrawlerBreakdown, CrawlerInfo, DailyStat, ImpressionLog, PageAdsResponse, QueryEndpointDiscovery, RecentActivityItem, RecentQueryItem, RequestLogEntry, RequestLogger, SiteOverviewStats, SiteWalletInfo, createQueryHandler, detectCrawler, getKnownCrawlerNames };