apptvty 0.1.5 → 0.2.1

package/dist/cli.js

@@ -22,7 +22,8 @@ async function register(options) {
     body: JSON.stringify({
       domain: options.domain,
       framework: options.framework ?? "other",
-      agent_id: options.agentId
+      agent_id: options.agentId,
+      ...options.email && { email: options.email }
     }),
     signal: AbortSignal.timeout(2e4)
   });
@@ -39,15 +40,18 @@ async function register(options) {
     apiKey: data.api_key,
     companyId: data.company_id,
     walletAddress: data.wallet_address ?? null,
+    platformDepositAddress: data.platform_deposit_address ?? null,
     dashboardUrl: data.dashboard_url,
     claimTokenExpiresAt: data.claim_token_expires_at,
     trialEndsAt: data.trial_ends_at,
+    email: data.email ?? null,
     setup: {
       envVars: data.setup?.env_vars ?? {
         APPTVTY_SITE_ID: data.site_id,
         APPTVTY_API_KEY: data.api_key
       },
-      files: data.setup?.files
+      files: data.setup?.files,
+      x402: data.setup?.x402
     }
   };
 }
@@ -85,7 +89,8 @@ async function migrate(options) {
 var args = process.argv.slice(2);
 var rawCmd = args[0];
 var isMigrate = rawCmd === "migrate";
-var cmdArgs = isMigrate ? args.slice(1) : args;
+var isCreateSuperuser = rawCmd === "create-superuser";
+var cmdArgs = isMigrate || isCreateSuperuser ? args.slice(1) : args;
 function getFlag(name, from = cmdArgs) {
   const idx = from.indexOf(`--${name}`);
   return idx !== -1 ? from[idx + 1] : void 0;
@@ -94,6 +99,7 @@ var isNonInteractive = cmdArgs.includes("--non-interactive") || cmdArgs.includes
 var flagDomain = getFlag("domain");
 var flagFramework = getFlag("framework");
 var flagApiUrl = getFlag("api-url");
+var flagEmail = getFlag("email");
 function detectFramework() {
   try {
     const pkg = JSON.parse((0, import_fs.readFileSync)((0, import_path.join)(process.cwd(), "package.json"), "utf-8"));
@@ -186,7 +192,11 @@ function loadEnvVars() {
     const m = line.match(/^\s*([A-Z_][A-Z0-9_]*)\s*=\s*(.+?)\s*$/);
     if (m) out[m[1]] = m[2].replace(/^["']|["']$/g, "").trim();
   }
-  return { siteId: out.APPTVTY_SITE_ID, apiKey: out.APPTVTY_API_KEY };
+  return {
+    siteId: out.APPTVTY_SITE_ID,
+    apiKey: out.APPTVTY_API_KEY,
+    claimToken: out.APPTVTY_CLAIM_TOKEN
+  };
 }
 async function runInit() {
   const framework = flagFramework ?? detectFramework();
@@ -201,6 +211,10 @@ async function runInit() {
   if (!domain && !isNonInteractive) {
     domain = await prompt("  Enter your site domain (e.g. mysite.com): ");
   }
+  let email = flagEmail ?? "";
+  if (!email && !isNonInteractive) {
+    email = await prompt("  Enter your email to claim this account (optional, press Enter to skip): ");
+  }
   if (!domain) {
     if (isNonInteractive) {
       process.stdout.write(JSON.stringify({ error: "domain is required (use --domain)" }) + "\n");
@@ -218,7 +232,8 @@ async function runInit() {
       domain,
       framework,
       agentId: "apptvty-cli",
-      apiUrl: flagApiUrl
+      apiUrl: flagApiUrl,
+      ...email && { email }
     });
   } catch (err) {
     const msg = err instanceof RegistrationError ? err.message : String(err);
@@ -253,9 +268,12 @@ async function runInit() {
         company_id: result.companyId,
         wallet_address: result.walletAddress,
         dashboard_url: result.dashboardUrl,
+        claim_token_expires_at: result.claimTokenExpiresAt,
         trial_ends_at: result.trialEndsAt,
+        email: result.email ?? null,
         env_file: envFile,
-        env_vars: result.setup.envVars
+        env_vars: result.setup.envVars,
+        x402: result.setup.x402
       }) + "\n"
     );
     return;
@@ -264,6 +282,9 @@ async function runInit() {
   if (result.walletAddress) {
     console.log(`  \u2713 Wallet created:      ${result.walletAddress}`);
   }
+  if (email) {
+    console.log(`  \u2713 Email linked:        ${email}`);
+  }
   console.log(`  \u2713 Credentials written: ${envFile}`);
   if (scaffolded.length > 0) {
     for (const f of scaffolded) {
@@ -274,21 +295,83 @@ async function runInit() {
     console.log("\n  middleware.ts");
     console.log("    import { withApptvty } from 'apptvty/nextjs';");
     console.log("    export default withApptvty({ apiKey: process.env.APPTVTY_API_KEY!, siteId: process.env.APPTVTY_SITE_ID! });");
+    console.log("    export default withApptvty({ apiKey: process.env.APPTVTY_API_KEY!, siteId: process.env.APPTVTY_SITE_ID! });");
     console.log("    export const config = { matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'] };");
-    console.log("\n  app/query/route.ts");
+    console.log("\n  app/query/route.ts (Agent Interface)");
     console.log("    import { createNextjsQueryHandler } from 'apptvty/nextjs';");
     console.log("    export const GET = createNextjsQueryHandler({ apiKey: process.env.APPTVTY_API_KEY!, siteId: process.env.APPTVTY_SITE_ID! });");
+    console.log("\n  app/api/apptvty/logs/route.ts (Maintainer Dashboard)");
+    console.log("    import { createNextjsDashboardHandler } from 'apptvty/nextjs';");
+    console.log("    export const GET = createNextjsDashboardHandler({ apiKey: process.env.APPTVTY_API_KEY!, siteId: process.env.APPTVTY_SITE_ID! });");
   }
   console.log("\n  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
   console.log("  Free trial active \u2014 24 hours from now.");
-  console.log(`  Trial expires: ${result.trialEndsAt}`);
+  if (result.setup.x402) {
+    console.log(`  \u2713 Agent-native payments (X402): ${result.setup.x402.chain}/${result.setup.x402.currency}`);
+    if (result.platformDepositAddress) {
+      console.log(`  \u2713 Platform Deposit Address:    ${result.platformDepositAddress}`);
+      console.log("    (Send USDC here to fund ad campaigns autonomously)");
+    }
+  }
+  console.log(`  \u2713 Trial expires:       ${result.trialEndsAt}`);
+  console.log("");
+  if (email) {
+    console.log(`  A claim link has been sent to: ${email}`);
+    console.log("  Or open the link below to access your dashboard:");
+  } else {
+    console.log("  No email provided \u2014 click the link below to claim your account.");
+    console.log("  (This link expires in 30 days. Save it now.)");
+  }
   console.log("");
-  console.log("  Open the dashboard to log in before the trial ends:");
   console.log(`  ${result.dashboardUrl}`);
   console.log("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
   console.log("  After the trial expires, this site's API key will stop working.");
+  console.log("  Advertisers: Deposit USDC to the address above, then fund via:");
+  console.log("  GET /v1/wallet/sync?tx_hash=<your_transaction_hash>");
   console.log("  Log in once to keep your credentials and continue receiving analytics.\n");
 }
+async function runCreateSuperuser() {
+  console.log("\n  \u{1F680} Apptvty \u2014 Create Superuser\n");
+  const { claimToken } = loadEnvVars();
+  if (!claimToken) {
+    console.error("\n  \u2716 Error: APPTVTY_CLAIM_TOKEN not found in .env.local or .env");
+    console.log("  Please run `npx apptvty init` first to initialize your site.\n");
+    process.exit(1);
+  }
+  const email = await prompt("  Email: ");
+  const password = await prompt("  Password: ");
+  const name = await prompt("  Full Name (optional): ");
+  const apiUrl = flagApiUrl || "https://api.apptvty.com";
+  try {
+    const response = await fetch(`${apiUrl}/v1/auth/claim`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        claim_token: claimToken,
+        email,
+        password,
+        name
+      })
+    });
+    const result = await response.json();
+    if (!response.ok) {
+      console.error(`
+  \u2716 Error: ${result.message || result.error?.message || response.statusText}`);
+      process.exit(1);
+    }
+    console.log("\n  \u2713 Superuser created successfully!");
+    console.log(`  \u2713 Email:      ${result.user.email}`);
+    console.log(`  \u2713 Company:    ${result.company.name}
+`);
+    console.log("  You can now log in at https://dashboard.apptvty.com\n");
+  } catch (err) {
+    console.error(`
+  \u2716 Network error: ${err.message}`);
+    process.exit(1);
+  }
+}
 async function runMigrate() {
   const { siteId, apiKey } = loadEnvVars();
   if (!siteId || !apiKey) {
@@ -332,6 +415,8 @@ async function runMigrate() {
 async function main() {
   if (isMigrate) {
     await runMigrate();
+  } else if (isCreateSuperuser) {
+    await runCreateSuperuser();
   } else {
     await runInit();
   }

package/dist/index.d.mts

@@ -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.mjs';
-export { h as PageAd, i as QuerySource, j as SponsoredAd } from './types-C1oUTCsT.mjs';
+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-Zt2qHOrW.mjs';
+export { k as CampaignStatus, l as PageAd, m as QuerySource, n as SponsoredAd } from './types-Zt2qHOrW.mjs';
 export { createNextjsQueryHandler, withApptvty } from './middleware/nextjs.mjs';
 export { createExpressMiddleware, createExpressQueryHandler } from './middleware/express.mjs';
 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 };

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-Zt2qHOrW.js';
+export { k as CampaignStatus, l as PageAd, m as QuerySource, n as SponsoredAd } from './types-Zt2qHOrW.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 };