apptvty 0.1.5 → 0.2.0

package/dist/index.js

@@ -22,12 +22,14 @@ var src_exports = {};
 __export(src_exports, {
   ApptvtyApiError: () => ApptvtyApiError,
   ApptvtyClient: () => ApptvtyClient,
+  ApptvtyInsufficientBalanceError: () => ApptvtyInsufficientBalanceError,
   RequestLogger: () => RequestLogger,
   createExpressMiddleware: () => createExpressMiddleware,
   createExpressQueryHandler: () => createExpressQueryHandler,
   createNextjsQueryHandler: () => createNextjsQueryHandler,
   createQueryHandler: () => createQueryHandler,
   detectCrawler: () => detectCrawler,
+  detectScraperService: () => detectScraperService,
   getKnownCrawlerNames: () => getKnownCrawlerNames,
   withApptvty: () => withApptvty
 });
@@ -46,6 +48,13 @@ var ApptvtyClient = class {
     this.siteId = config.siteId;
     this.debug = config.debug ?? false;
   }
+  /**
+   * Set the X402 (LSAT) token for subsequent requests.
+   * This is called after the agent has successfully paid an X402 challenge.
+   */
+  setX402Token(macaroon, preimage) {
+    this.x402Token = `LSAT ${macaroon}:${preimage}`;
+  }
   /**
    * 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.
@@ -118,6 +127,20 @@ var ApptvtyClient = class {
   async getSiteDailyStats(days = 30) {
     return this.get(`/v1/sites/${this.siteId}/stats/daily`, { days: String(days) });
   }
+  /** Get recent activity logs (last 48h). */
+  async getRecentActivity(siteId, limit = 50, offset = 0) {
+    return this.get(`/v1/sites/${siteId}/activity`, {
+      limit: String(limit),
+      offset: String(offset)
+    });
+  }
+  /** Get recent agent queries. */
+  async getRecentQueries(siteId, limit = 20, offset = 0) {
+    return this.get(`/v1/sites/${siteId}/queries`, {
+      limit: String(limit),
+      offset: String(offset)
+    });
+  }
   /** Get crawler breakdown by type (default 30 days). */
   async getSiteCrawlers(days = 30) {
     return this.get(`/v1/sites/${this.siteId}/crawlers`, { days: String(days) });
@@ -134,6 +157,106 @@ var ApptvtyClient = class {
   async getSiteWallet() {
     return this.get(`/v1/sites/${this.siteId}/wallet`);
   }
+  // ─── Campaign management (for coding agents) ────────────────────────────────
+  //
+  // A coding agent that installed the SDK can create and manage ad campaigns
+  // programmatically — no human dashboard login required.
+  //
+  // Typical agentic advertiser flow:
+  //   1. Check wallet balance:  const w = await client.getSiteWallet()
+  //   2. Fund wallet if needed: send USDC to w.wallet_address on Base chain
+  //   3. Create campaign:       await client.createCampaign({ ... })
+  //   4. Monitor performance:   await client.getCampaign(id)
+  //   5. Adjust or pause:       await client.updateCampaign(id, { status: 'paused' })
+  /**
+   * 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,
+   * });
+   */
+  async createCampaign(params) {
+    try {
+      return await this.post("/v1/campaigns", params);
+    } catch (err) {
+      if (err instanceof ApptvtyApiError && err.statusCode === 402) {
+        let details;
+        try {
+          const body = JSON.parse(err.body);
+          details = body?.error;
+        } catch {
+        }
+        throw new ApptvtyInsufficientBalanceError(details);
+      }
+      throw err;
+    }
+  }
+  /**
+   * List all campaigns for this account.
+   * Also returns the schema (valid categories, minimum bid) so the agent
+   * knows valid field values without guessing.
+   */
+  async listCampaigns() {
+    return this.get("/v1/campaigns");
+  }
+  /**
+   * 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.
+   */
+  async getCampaign(campaignId) {
+    return this.get(`/v1/campaigns/${campaignId}`);
+  }
+  /**
+   * 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 });
+   */
+  async updateCampaign(campaignId, params) {
+    return this.patch(`/v1/campaigns/${campaignId}`, params);
+  }
+  /**
+   * Pause a campaign immediately. Equivalent to updateCampaign(id, { status: 'paused' }).
+   * Campaigns are never deleted — billing history is retained.
+   */
+  async pauseCampaign(campaignId) {
+    await this.delete(`/v1/campaigns/${campaignId}`);
+  }
+  /**
+   * Resume a paused campaign.
+   */
+  async resumeCampaign(campaignId) {
+    await this.patch(`/v1/campaigns/${campaignId}`, { status: "active" });
+  }
   async get(path, params) {
     const url = new URL(`${this.baseUrl}${path}`);
     if (params) {
@@ -142,7 +265,7 @@ var ApptvtyClient = class {
     const response = await fetch(url.toString(), {
       method: "GET",
       headers: {
-        Authorization: `Bearer ${this.apiKey}`,
+        Authorization: this.x402Token ?? `Bearer ${this.apiKey}`,
         "User-Agent": "apptvty-sdk/0.1.0"
       },
       signal: AbortSignal.timeout(1e4)
@@ -153,22 +276,91 @@ var ApptvtyClient = class {
     }
     return response.json();
   }
+  async patch(path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const response = await fetch(url, {
+      method: "PATCH",
+      headers: {
+        "Authorization": this.x402Token ?? `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json",
+        "User-Agent": "apptvty-sdk/0.1.0"
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(1e4)
+    });
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      throw new ApptvtyApiError(response.status, path, text);
+    }
+    return response.json();
+  }
+  async delete(path) {
+    const url = `${this.baseUrl}${path}`;
+    const response = await fetch(url, {
+      method: "DELETE",
+      headers: {
+        "Authorization": this.x402Token ?? `Bearer ${this.apiKey}`,
+        "User-Agent": "apptvty-sdk/0.1.0"
+      },
+      signal: AbortSignal.timeout(1e4)
+    });
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      throw new ApptvtyApiError(response.status, path, text);
+    }
+  }
+  /**
+   * 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.
+   */
+  async payX402Challenge(macaroon) {
+    const url = `${this.baseUrl}/v1/x402/pay`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json",
+        "User-Agent": "apptvty-sdk/0.1.0"
+      },
+      body: JSON.stringify({ macaroon }),
+      signal: AbortSignal.timeout(1e4)
+    });
+    const text = await response.text().catch(() => "");
+    if (!response.ok) {
+      let details;
+      try {
+        details = JSON.parse(text)?.error?.details;
+      } catch {
+      }
+      throw new ApptvtyInsufficientBalanceError(details);
+    }
+    const json = JSON.parse(text);
+    return json.preimage;
+  }
   async post(path, body) {
     const url = `${this.baseUrl}${path}`;
     const response = await fetch(url, {
       method: "POST",
       headers: {
-        "Authorization": `Bearer ${this.apiKey}`,
+        "Authorization": this.x402Token ?? `Bearer ${this.apiKey}`,
         "Content-Type": "application/json",
         "User-Agent": "apptvty-sdk/0.1.0"
       },
       body: JSON.stringify(body),
-      // Node 18+ fetch: set a reasonable timeout via AbortSignal
       signal: AbortSignal.timeout(1e4)
     });
     if (!response.ok) {
       const text = await response.text().catch(() => "");
       if (response.status === 402) {
+        const authHeader = response.headers.get("WWW-Authenticate");
+        if (authHeader?.includes("X402") || authHeader?.includes("LSAT")) {
+          const macaroon = authHeader.match(/macaroon="([^"]+)"/)?.[1] || "";
+          const preimage = await this.payX402Challenge(macaroon);
+          this.setX402Token(macaroon, preimage);
+          this.log("X402 challenge auto-paid from wallet, retrying request");
+          return this.post(path, body);
+        }
         let dashboardUrl = "https://dashboard.apptvty.com/login";
         try {
           const json = JSON.parse(text);
@@ -204,6 +396,16 @@ var ApptvtyTrialExpiredError = class extends Error {
     this.name = "ApptvtyTrialExpiredError";
   }
 };
+var ApptvtyInsufficientBalanceError = class extends Error {
+  constructor(details) {
+    const shortfall = details?.shortfall_usdc ?? "?";
+    super(
+      `Wallet balance too low to create campaign. Send ${shortfall} USDC to ${details?.deposit?.address ?? "your wallet"} on Base and retry.`
+    );
+    this.details = details;
+    this.name = "ApptvtyInsufficientBalanceError";
+  }
+};
 
 // src/logger.ts
 var RequestLogger = class {
@@ -393,6 +595,27 @@ function extractBotName(userAgent) {
 function getKnownCrawlerNames() {
   return KNOWN_CRAWLERS.map((c) => c.name);
 }
+var SCRAPER_SERVICES = [
+  // Jina AI Reader — r.jina.ai/URL — converts any page to clean Markdown
+  { name: "JinaReader", patterns: [/JinaReader/i] },
+  // Cloudflare Browser Rendering /crawl endpoint (open beta, announced March 2026)
+  { name: "Cloudflare-BrowserRendering", patterns: [/CloudflareBrowserRenderingCrawler/i] },
+  // FireCrawl — LLM-ready content extraction service
+  { name: "FireCrawl", patterns: [/FireCrawlAgent/i, /firecrawl/i] },
+  // Apify web scraping platform
+  { name: "Apify", patterns: [/ApifyBot/i] }
+];
+function detectScraperService(userAgent) {
+  if (!userAgent) return { isScraperService: false, name: null };
+  for (const service of SCRAPER_SERVICES) {
+    for (const pattern of service.patterns) {
+      if (pattern.test(userAgent)) {
+        return { isScraperService: true, name: service.name };
+      }
+    }
+  }
+  return { isScraperService: false, name: null };
+}
 
 // src/query-handler.ts
 var RESPONSE_HEADERS = {
@@ -534,6 +757,65 @@ function getOrigin(url) {
 
 // src/middleware/nextjs.ts
 var import_server = require("next/server");
+
+// src/ad-injection.ts
+var AD_INJECTION_MARKER = "<!-- apptvty-sponsored -->";
+function injectIntoHtml(html, ads, isScraperService) {
+  if (!html || ads.length === 0) return html;
+  if (html.includes(AD_INJECTION_MARKER)) return html;
+  let modified = html;
+  const contentBlock = buildContentStreamBlock(ads);
+  if (modified.includes("</article>")) {
+    modified = modified.replace("</article>", `${contentBlock}
+</article>`);
+  } else if (modified.includes("</main>")) {
+    modified = modified.replace("</main>", `${contentBlock}
+</main>`);
+  } else if (!isScraperService && modified.includes("</body>")) {
+    modified = modified.replace("</body>", `${contentBlock}
+</body>`);
+  }
+  if (!isScraperService && modified.includes("</head>")) {
+    const jsonLdBlock = buildJsonLdBlock(ads);
+    modified = modified.replace("</head>", `${jsonLdBlock}
+</head>`);
+  }
+  return modified;
+}
+function buildSponsoredHeader(ads) {
+  return JSON.stringify(
+    ads.map((ad) => ({ text: ad.text, url: ad.url, advertiser: ad.advertiser }))
+  );
+}
+function buildContentStreamBlock(ads) {
+  const paragraphs = ads.map(
+    (ad) => `<p data-apptvty-sponsored="${escapeAttr(ad.impression_id)}"><strong>[Sponsored]</strong> <a href="${escapeAttr(ad.url)}" rel="sponsored noopener">${escapeHtml(ad.text)}</a> \u2014 <span>${escapeHtml(ad.advertiser)}</span></p>`
+  ).join("\n");
+  return `${AD_INJECTION_MARKER}
+${paragraphs}`;
+}
+function buildJsonLdBlock(ads) {
+  const entries = ads.map((ad) => ({
+    "@context": "https://schema.org",
+    "@type": "WPAdBlock",
+    sponsor: {
+      "@type": "Organization",
+      name: ad.advertiser,
+      url: ad.url
+    },
+    description: ad.text
+  }));
+  const ld = entries.length === 1 ? entries[0] : entries;
+  return `<script type="application/ld+json">${JSON.stringify(ld)}</script>`;
+}
+function escapeHtml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function escapeAttr(s) {
+  return s.replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+
+// src/middleware/nextjs.ts
 function headersToRecord(h) {
   const entries = h.entries();
   return Object.fromEntries(Array.from(entries));
@@ -555,8 +837,9 @@ function withApptvty(config, next) {
     const startMs = Date.now();
     const userAgent = request.headers.get("user-agent") ?? "";
     const crawlerInfo = detectCrawler(userAgent);
+    const scraperService = detectScraperService(userAgent);
     const aiCrawlerParam = parseBoolParam(request.nextUrl.searchParams.get("ai_crawler"), false);
-    const isCrawler = crawlerInfo.isAi || aiCrawlerParam;
+    const isCrawler = crawlerInfo.isAi || aiCrawlerParam || scraperService.isScraperService;
     let response;
     try {
       response = next ? await next(request) : import_server.NextResponse.next();
@@ -582,14 +865,23 @@ function withApptvty(config, next) {
       is_ai_crawler: crawlerInfo.isAi,
       crawler_type: crawlerInfo.name,
       crawler_organization: crawlerInfo.organization,
-      confidence_score: crawlerInfo.confidence
+      confidence_score: crawlerInfo.confidence,
+      scraper_service: scraperService.name
     };
     logger.enqueue(entry);
     if (isCrawler && response.ok && !pathname.startsWith(queryPath)) {
       const contentType = response.headers.get("content-type") ?? "";
       if (contentType.includes("text/html")) {
         try {
-          const modified = await injectAdsIntoHtml(response, client, config.siteId, pathname);
+          const modified = await injectAdsIntoResponse(
+            response,
+            client,
+            config,
+            pathname,
+            userAgent,
+            getClientIp(headers),
+            scraperService.isScraperService
+          );
           if (modified) return modified;
         } catch (err) {
           if (config.debug) console.warn("[apptvty] Ad injection failed:", err);
@@ -625,40 +917,31 @@ function createNextjsQueryHandler(config) {
     });
   };
 }
-var AD_INJECTION_MARKER = "<!-- apptvty-sponsored -->";
-function buildAdBlock(ads) {
-  const items = ads.map(
-    (ad) => `<li><a href="${escapeHtml(ad.url)}" rel="nofollow">${escapeHtml(ad.text)}</a> <small>\u2014 ${escapeHtml(ad.advertiser)}</small></li>`
-  ).join("\n");
-  return `
-<section aria-label="Sponsored" data-sponsored ${AD_INJECTION_MARKER}>
-  <h3>Sponsored</h3>
-  <ul>${items}</ul>
-</section>`;
-}
-function escapeHtml(s) {
-  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
-}
-async function injectAdsIntoHtml(response, client, siteId, pathname) {
+async function injectAdsIntoResponse(response, client, config, pathname, userAgent, ipAddress, isScraperService) {
   const html = await response.text();
-  if (!html || html.includes(AD_INJECTION_MARKER)) return null;
-  const pageAds = await client.getAdsForPage({ site_id: siteId, page_path: pathname });
+  if (!html) return null;
+  const pageAds = await client.getAdsForPage({ site_id: config.siteId, page_path: pathname });
   if (!pageAds.ads || pageAds.ads.length === 0) return null;
-  const adBlock = buildAdBlock(pageAds.ads);
-  let modified;
-  if (html.includes("</body>")) {
-    modified = html.replace("</body>", `${adBlock}
-</body>`);
-  } else if (html.includes("</html>")) {
-    modified = html.replace("</html>", `${adBlock}
-</html>`);
-  } else {
-    modified = html + adBlock;
+  const modified = injectIntoHtml(html, pageAds.ads, isScraperService);
+  if (modified === html) return null;
+  const newHeaders = new Headers(response.headers);
+  newHeaders.set("X-Sponsored-Content", buildSponsoredHeader(pageAds.ads));
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  for (const ad of pageAds.ads) {
+    client.logImpression({
+      impression_id: ad.impression_id,
+      site_id: config.siteId,
+      page_path: pathname,
+      agent_ua: userAgent,
+      agent_ip: ipAddress,
+      timestamp
+    }).catch(() => {
+    });
   }
   return new import_server.NextResponse(modified, {
     status: response.status,
     statusText: response.statusText,
-    headers: new Headers(response.headers)
+    headers: newHeaders
   });
 }
 function parseBoolParam(value, defaultValue) {
@@ -681,12 +964,77 @@ function getInstance2(config) {
   return instances2.get(key);
 }
 function createExpressMiddleware(config) {
-  const { logger } = getInstance2(config);
-  return function apptvtyLogger(req, res, next) {
+  const { client, logger } = getInstance2(config);
+  return function apptvtyMiddleware(req, res, next) {
     const startMs = Date.now();
     const userAgent = req.headers["user-agent"] ?? "";
     const crawlerInfo = detectCrawler(userAgent);
+    const scraperService = detectScraperService(userAgent);
     const path = req.url ?? "/";
+    const isCrawler = crawlerInfo.isAi || scraperService.isScraperService;
+    const ipAddress = getClientIp(req.headers);
+    const adsPromise = isCrawler && !shouldSkip2(path) ? client.getAdsForPage({ site_id: config.siteId, page_path: path }).catch(() => ({ ads: [] })) : Promise.resolve({ ads: [] });
+    if (isCrawler && !shouldSkip2(path)) {
+      const chunks = [];
+      const originalWrite = res.write.bind(res);
+      const originalEnd = res.end.bind(res);
+      res.write = function(chunk, encodingOrCallback, callback) {
+        if (chunk != null) {
+          chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        }
+        if (typeof encodingOrCallback === "function") encodingOrCallback();
+        else if (typeof callback === "function") callback();
+        return true;
+      };
+      res.end = function(chunk, encodingOrCallback, callback) {
+        if (chunk != null) {
+          chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        }
+        const contentType = res.getHeader("content-type") ?? "";
+        const isHtml = contentType.includes("text/html");
+        if (!isHtml || chunks.length === 0) {
+          res.write = originalWrite;
+          res.end = originalEnd;
+          return originalEnd(Buffer.concat(chunks), encodingOrCallback, callback);
+        }
+        const html = Buffer.concat(chunks).toString("utf-8");
+        if (html.includes(AD_INJECTION_MARKER)) {
+          res.write = originalWrite;
+          res.end = originalEnd;
+          return originalEnd(html, encodingOrCallback, callback);
+        }
+        adsPromise.then((pageAds) => {
+          res.write = originalWrite;
+          res.end = originalEnd;
+          if (!pageAds.ads || pageAds.ads.length === 0) {
+            originalEnd(html, encodingOrCallback, callback);
+            return;
+          }
+          const modified = injectIntoHtml(html, pageAds.ads, scraperService.isScraperService);
+          res.setHeader("X-Sponsored-Content", buildSponsoredHeader(pageAds.ads));
+          const buf = Buffer.from(modified, "utf-8");
+          res.setHeader("Content-Length", buf.length);
+          const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+          for (const ad of pageAds.ads) {
+            client.logImpression({
+              impression_id: ad.impression_id,
+              site_id: config.siteId,
+              page_path: path,
+              agent_ua: userAgent,
+              agent_ip: ipAddress,
+              timestamp
+            }).catch(() => {
+            });
+          }
+          originalEnd(buf, encodingOrCallback, callback);
+        }).catch(() => {
+          res.write = originalWrite;
+          res.end = originalEnd;
+          originalEnd(html, encodingOrCallback, callback);
+        });
+        return res;
+      };
+    }
     res.on("finish", () => {
       if (shouldSkip2(path)) return;
       const entry = {
@@ -696,13 +1044,14 @@ function createExpressMiddleware(config) {
         path,
         status_code: res.statusCode,
         response_time_ms: Date.now() - startMs,
-        ip_address: getClientIp(req.headers),
+        ip_address: ipAddress,
         user_agent: userAgent,
         referer: req.headers["referer"] ?? null,
         is_ai_crawler: crawlerInfo.isAi,
         crawler_type: crawlerInfo.name,
         crawler_organization: crawlerInfo.organization,
-        confidence_score: crawlerInfo.confidence
+        confidence_score: crawlerInfo.confidence,
+        scraper_service: scraperService.name
       };
       logger.enqueue(entry);
     });
@@ -746,12 +1095,14 @@ function shouldSkip2(path) {
 0 && (module.exports = {
   ApptvtyApiError,
   ApptvtyClient,
+  ApptvtyInsufficientBalanceError,
   RequestLogger,
   createExpressMiddleware,
   createExpressQueryHandler,
   createNextjsQueryHandler,
   createQueryHandler,
   detectCrawler,
+  detectScraperService,
   getKnownCrawlerNames,
   withApptvty
 });