apptvty 0.1.4 → 0.2.0

package/dist/index.d.ts

@@ -1,25 +1,47 @@
-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';
+import { C as CrawlerInfo, A as ApptvtyConfig, R as RequestLogEntry, Q as QueryRequest, B as BackendQueryResponse, P as PageAdsResponse, I as ImpressionLog, S as SiteOverviewStats, D as DailyStat, a as RecentActivityItem, b as RecentQueryItem, c as CrawlerBreakdown, d as SiteWalletInfo, e as CreateCampaignParams, f as CampaignRecord, U as UpdateCampaignParams, g as InsufficientBalanceError, h as AgentQueryResponse, i as QueryEndpointDiscovery, j as AgentErrorResponse } from './types-D2A_0sPm.js';
+export { k as CampaignStatus, l as PageAd, m as QuerySource, n as SponsoredAd } from './types-D2A_0sPm.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.
+ * Lightweight AI crawler detection.
  *
- * Handles:
- *   - Batch log ingestion (/v1/logs/batch)
- *   - Query processing (/v1/query) — returns answer + optional ad
- *   - Impression logging (/v1/impressions) — triggers billing for ads
+ * 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[];
+interface ScraperServiceInfo {
+    isScraperService: boolean;
+    /** Identifier of the matched service, or null if not a scraper service. */
+    name: string | null;
+}
+/**
+ * Detect whether the request comes from a known content-extraction scraper service
+ * (Jina, FireCrawl, Cloudflare Browser Rendering, etc.) rather than a direct AI crawler.
+ *
+ * Use this alongside detectCrawler() — scraper services are a distinct category:
+ * they proxy on behalf of an AI consumer but apply their own readability transform.
+ */
+declare function detectScraperService(userAgent: string): ScraperServiceInfo;
+
 declare class ApptvtyClient {
     private readonly baseUrl;
     private readonly apiKey;
     private readonly siteId;
     private readonly debug;
+    private x402Token?;
     constructor(config: ApptvtyConfig);
+    /**
+     * Set the X402 (LSAT) token for subsequent requests.
+     * This is called after the agent has successfully paid an X402 challenge.
+     */
+    setX402Token(macaroon: string, preimage: string): void;
     /**
      * 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.
@@ -61,6 +83,10 @@ declare class ApptvtyClient {
         days: number;
         stats: DailyStat[];
     }>;
+    /** Get recent activity logs (last 48h). */
+    getRecentActivity(siteId: string, limit?: number, offset?: number): Promise<RecentActivityItem[]>;
+    /** Get recent agent queries. */
+    getRecentQueries(siteId: string, limit?: number, offset?: number): Promise<RecentQueryItem[]>;
     /** Get crawler breakdown by type (default 30 days). */
     getSiteCrawlers(days?: number): Promise<{
         days: number;
@@ -76,7 +102,87 @@ declare class ApptvtyClient {
     }>;
     /** Get wallet balance and earnings. */
     getSiteWallet(): Promise<SiteWalletInfo>;
+    /**
+     * Create an ad campaign. The campaign goes live immediately once the wallet
+     * has sufficient balance.
+     *
+     * If the wallet balance is too low, throws `ApptvtyInsufficientBalanceError`
+     * which includes deposit instructions so the agent can fund the wallet and retry.
+     *
+     * @example
+     * // Site-based: ad copy derived from your site's crawled content
+     * const campaign = await client.createCampaign({
+     *   name: 'My Kubernetes Blog',
+     *   advertiser_site_id: 'site_abc123',
+     *   keywords: ['kubernetes', 'devops', 'containers'],
+     *   categories: ['technology'],
+     *   bid_per_view_usdc: 0.001,
+     *   daily_budget_usdc: 1.0,
+     *   total_budget_usdc: 20.0,
+     * });
+     *
+     * // Static: manually written ad copy
+     * const campaign = await client.createCampaign({
+     *   name: 'My Blog — Static',
+     *   ad_text: 'Deep dives on Kubernetes, written by practitioners.',
+     *   landing_url: 'https://myblog.com',
+     *   keywords: ['kubernetes', 'devops'],
+     *   categories: ['technology'],
+     *   bid_per_view_usdc: 0.001,
+     *   daily_budget_usdc: 1.0,
+     *   total_budget_usdc: 10.0,
+     * });
+     */
+    createCampaign(params: CreateCampaignParams): Promise<CampaignRecord>;
+    /**
+     * List all campaigns for this account.
+     * Also returns the schema (valid categories, minimum bid) so the agent
+     * knows valid field values without guessing.
+     */
+    listCampaigns(): Promise<{
+        campaigns: CampaignRecord[];
+        total: number;
+        schema: {
+            valid_categories: string[];
+            valid_statuses: string[];
+            bid_per_view_usdc_minimum: number;
+        };
+    }>;
+    /**
+     * Get a single campaign by ID, including current spend and impression count.
+     * `budget_remaining_usdc` tells the agent how much budget is left before
+     * the campaign auto-pauses.
+     */
+    getCampaign(campaignId: string): Promise<CampaignRecord>;
+    /**
+     * Partially update a campaign. Only fields present in `params` are changed.
+     *
+     * @example
+     * // Pause a campaign
+     * await client.updateCampaign(id, { status: 'paused' });
+     *
+     * // Increase bid and daily budget
+     * await client.updateCampaign(id, { bid_per_view_usdc: 0.002, daily_budget_usdc: 5.0 });
+     */
+    updateCampaign(campaignId: string, params: UpdateCampaignParams): Promise<CampaignRecord>;
+    /**
+     * Pause a campaign immediately. Equivalent to updateCampaign(id, { status: 'paused' }).
+     * Campaigns are never deleted — billing history is retained.
+     */
+    pauseCampaign(campaignId: string): Promise<void>;
+    /**
+     * Resume a paused campaign.
+     */
+    resumeCampaign(campaignId: string): Promise<void>;
     private get;
+    private patch;
+    private delete;
+    /**
+     * Settle an X402 challenge from the site's own USDC wallet balance.
+     * Called automatically when `post()` receives a 402 with an X402 header.
+     * Returns the preimage on success, or throws if the wallet balance is too low.
+     */
+    private payX402Challenge;
     private post;
     private log;
     private warn;
@@ -87,6 +193,30 @@ declare class ApptvtyApiError extends Error {
     readonly body: string;
     constructor(statusCode: number, path: string, body: string);
 }
+/**
+ * Thrown by createCampaign() when the wallet balance is too low.
+ *
+ * The `details` property contains everything needed to fund the wallet
+ * autonomously and retry — the agent can inspect `details.deposit.address`
+ * and send USDC on Base without human intervention.
+ *
+ * @example
+ * import { ApptvtyInsufficientBalanceError } from 'apptvty';
+ *
+ * try {
+ *   await client.createCampaign(params);
+ * } catch (err) {
+ *   if (err instanceof ApptvtyInsufficientBalanceError) {
+ *     const { shortfall_usdc, deposit } = err.details;
+ *     // Agent can now: send shortfall_usdc USDC to deposit.address on deposit.chain
+ *     // Then retry createCampaign
+ *   }
+ * }
+ */
+declare class ApptvtyInsufficientBalanceError extends Error {
+    readonly details: InsufficientBalanceError | undefined;
+    constructor(details: InsufficientBalanceError | undefined);
+}
 
 /**
  * Batched request logger.
@@ -122,18 +252,6 @@ declare class RequestLogger {
     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.
  *
@@ -167,4 +285,4 @@ interface QueryHandlerResponse {
 }
 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 };
+export { AgentErrorResponse, AgentQueryResponse, ApptvtyApiError, ApptvtyClient, ApptvtyConfig, ApptvtyInsufficientBalanceError, CampaignRecord, CrawlerBreakdown, CrawlerInfo, CreateCampaignParams, DailyStat, ImpressionLog, InsufficientBalanceError, PageAdsResponse, QueryEndpointDiscovery, RecentActivityItem, RecentQueryItem, RequestLogEntry, RequestLogger, type ScraperServiceInfo, SiteOverviewStats, SiteWalletInfo, UpdateCampaignParams, createQueryHandler, detectCrawler, detectScraperService, getKnownCrawlerNames };