apptvty 0.3.1 → 0.4.0

package/dist/index.js

@@ -127,6 +127,28 @@ var ApptvtyClient = class {
       this.warn("Failed to log impression (billing may be delayed):", err);
     }
   }
+  // ─── Programmatic Indexing ───────────────────────────────────────────────────
+  /**
+   * Manually push text or markdown directly into your site's RAG vector database.
+   * This instantly embeds the content for AI agents to query, bypassing the 
+   * need for a scheduled HTML crawl. This is ideal for Client-Side Rendered (CSR) 
+   * Apps or for injecting private institutional facts/databases.
+   *
+   * @example
+   * const result = await client.pushKnowledge({
+   *   title: "Capitol Technology University Profile",
+   *   content: "Here are all the detailed specs, majors, and acceptances...",
+   *   url: "https://thecollegeradar.com/institution/499" // Optional reference
+   * });
+   */
+  async pushKnowledge(params) {
+    const payload = {
+      title: params.title,
+      content: params.content,
+      url: params.url
+    };
+    return this.post(`/v1/sites/${this.siteId}/knowledge`, payload);
+  }
   // ─── Analytics (for coding agents) ───────────────────────────────────────────
   // These allow agents to check activity, logs, and errors without a human.
   /** Get 30-day traffic overview (requests, AI %, crawlers, queries). */
@@ -374,8 +396,12 @@ var ApptvtyClient = class {
         let dashboardUrl = (typeof process !== "undefined" ? process.env?.DASHBOARD_URL : void 0) ?? "https://dashboard.apptvty.com/login";
         try {
           const json = JSON.parse(text);
+          if (json?.error?.code === "INSUFFICIENT_BALANCE") {
+            throw new ApptvtyApiError(402, path, text);
+          }
           dashboardUrl = json?.error?.details?.dashboard_url ?? dashboardUrl;
-        } catch {
+        } catch (e) {
+          if (e instanceof ApptvtyApiError) throw e;
         }
         throw new ApptvtyTrialExpiredError(dashboardUrl);
       }
@@ -861,7 +887,8 @@ function withApptvty(config, next) {
     const crawlerInfo = detectCrawler(userAgent);
     const scraperService = detectScraperService(userAgent);
     const aiCrawlerParam = parseBoolParam(request.nextUrl.searchParams.get("ai_crawler"), false);
-    const isCrawler = crawlerInfo.isAi || aiCrawlerParam || scraperService.isScraperService;
+    const isAi = crawlerInfo.isAi || aiCrawlerParam;
+    const isScraper = isAi || scraperService.isScraperService || crawlerInfo.name === "unknown_bot";
     if (request.nextUrl.pathname === "/api/apptvty/verify") {
       const challenge = request.nextUrl.searchParams.get("challenge");
       if (challenge) {
@@ -906,59 +933,87 @@ function withApptvty(config, next) {
       ip_address: getClientIp(headers),
       user_agent: userAgent,
       referrer: request.headers.get("referer"),
-      is_ai_crawler: crawlerInfo.isAi,
+      is_ai_crawler: isAi,
       crawler_type: crawlerInfo.name,
       crawler_organization: crawlerInfo.organization,
       confidence_score: crawlerInfo.confidence,
-      scraper_service: scraperService.name
+      scraper_service: scraperService.name,
+      attribution_id: request.nextUrl.searchParams.get("atid")
     };
-    const isInternalRequest = request.headers.get("x-apptvty-internal") === "true";
-    if (!isInternalRequest && !pathname.startsWith(queryPath)) {
+    const isInternalRequest2 = request.headers.get("x-apptvty-internal") === "true";
+    if (!isInternalRequest2 && !pathname.startsWith(queryPath)) {
       logger.enqueue(entry);
       if (event && typeof event.waitUntil === "function") {
         event.waitUntil(logger.flush());
       }
     }
-    if (isCrawler && !isInternalRequest && !pathname.startsWith(queryPath)) {
+    if (!isInternalRequest2 && !pathname.startsWith(queryPath) && response.status === 200) {
       try {
-        const proxyReq = new Request(request.url, {
-          headers: new Headers(request.headers)
-        });
-        proxyReq.headers.set("x-apptvty-internal", "true");
-        const res = await fetch(proxyReq);
-        const contentType = res.headers.get("content-type") ?? "";
-        if (contentType.includes("text/html")) {
-          const html = await res.text();
-          let markdown = convertHtmlToMarkdown(html);
-          const pageAds = await client.getAdsForPage({ site_id: config.siteId, page_path: pathname });
-          if (pageAds.ads && pageAds.ads.length > 0) {
-            const ad = pageAds.ads[0];
-            markdown += `
+        const pageAds = await client.getAdsForPage({ site_id: config.siteId, page_path: pathname });
+        if (pageAds.ads && pageAds.ads.length > 0) {
+          const ad = pageAds.ads[0];
+          client.logImpression({
+            impression_id: ad.impression_id,
+            site_id: config.siteId,
+            page_path: pathname,
+            agent_ua: userAgent,
+            agent_ip: getClientIp(headers),
+            timestamp: (/* @__PURE__ */ new Date()).toISOString()
+          }).catch(() => {
+          });
+          if (isAi || scraperService.isScraperService) {
+            const proxyReq = new Request(request.url, { headers: new Headers(request.headers) });
+            proxyReq.headers.set("x-apptvty-internal", "true");
+            const res = await fetch(proxyReq);
+            const contentType = res.headers.get("content-type") ?? "";
+            if (contentType.includes("text/html")) {
+              const html = await res.text();
+              let markdown = convertHtmlToMarkdown(html);
+              markdown += `
 
 ---
 > **Sponsored:** [${ad.text}](${ad.url}) - ${ad.advertiser}
 `;
-            client.logImpression({
-              impression_id: ad.impression_id,
-              site_id: config.siteId,
-              page_path: pathname,
-              agent_ua: userAgent,
-              agent_ip: getClientIp(headers),
-              timestamp: (/* @__PURE__ */ new Date()).toISOString()
-            }).catch(() => {
-            });
+              return new import_server.NextResponse(markdown, {
+                status: res.status,
+                headers: {
+                  "Content-Type": "text/markdown",
+                  "X-Apptvty-AEO": "true",
+                  "X-Sponsored-Content": `${ad.text}; url=${ad.url}`
+                }
+              });
+            }
           }
-          return new import_server.NextResponse(markdown, {
-            status: res.status,
-            headers: {
-              "Content-Type": "text/markdown",
-              "X-Apptvty-AEO": "true"
+          const originalHeaders = headersToRecord(response.headers);
+          if (originalHeaders["content-type"]?.includes("text/html")) {
+            const html = await response.text();
+            const jsonLd = `
+<script type="application/ld+json">{"@context":"https://schema.org","@type":"CreativeWork","author":{"@type":"Organization","name":"${ad.advertiser}"},"mainEntityOfPage":{"@type":"WebPage","@id":"${ad.url}"},"headline":"Sponsored: ${ad.text}"}</script>
+`;
+            const stealthDiv = `
+<div style="display:none !important;visibility:hidden;height:0;width:0;overflow:hidden;" aria-hidden="true" data-apptvty-ad="${ad.impression_id}">Sponsored by ${ad.advertiser}: <a href="${ad.url}">${ad.text}</a></div>
+`;
+            let modifiedHtml = html;
+            if (html.includes("</head>")) {
+              modifiedHtml = html.replace("</head>", `${jsonLd}</head>`);
             }
-          });
+            if (modifiedHtml.includes("</body>")) {
+              modifiedHtml = modifiedHtml.replace("</body>", `${stealthDiv}</body>`);
+            } else {
+              modifiedHtml += stealthDiv;
+            }
+            return new import_server.NextResponse(modifiedHtml, {
+              status: response.status,
+              headers: {
+                ...originalHeaders,
+                "X-Sponsored-Content": `${ad.text}; url=${ad.url}`
+              }
+            });
+          }
+          response.headers.set("X-Sponsored-Content", `${ad.text}; url=${ad.url}`);
         }
-        return res;
       } catch (err) {
-        if (config.debug) console.warn("[apptvty] Markdown proxy failed:", err);
+        if (config.debug) console.warn("[apptvty] Stealth injection failed:", err);
       }
     }
     return response;
@@ -1074,13 +1129,18 @@ function createExpressMiddleware(config) {
     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);
+    const urlObj = new URL(path, `http://${req.headers.host ?? "localhost"}`);
+    const aiCrawlerParam = parseBoolParam2(urlObj.searchParams.get("ai_crawler"), false);
+    const attributionId = urlObj.searchParams.get("atid");
+    const isAi = crawlerInfo.isAi || aiCrawlerParam;
+    const isScraper = isAi || scraperService.isScraperService || crawlerInfo.name === "unknown_bot";
+    const adsPromise = !isInternalRequest(req) && !shouldSkip2(path) ? client.getAdsForPage({ site_id: config.siteId, page_path: path }).catch(() => ({ ads: [] })) : Promise.resolve({ ads: [] });
+    const chunks = [];
+    const originalWrite = res.write.bind(res);
+    const originalEnd = res.end.bind(res);
+    const shouldBuffer = !isInternalRequest(req) && !shouldSkip2(path);
+    if (shouldBuffer) {
       res.write = function(chunk, encodingOrCallback, callback) {
         if (chunk != null) {
           chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
@@ -1095,17 +1155,12 @@ function createExpressMiddleware(config) {
         }
         const contentType = res.getHeader("content-type") ?? "";
         const isHtml = contentType.includes("text/html");
-        if (!isHtml || chunks.length === 0) {
+        if (!isHtml || chunks.length === 0 || res.statusCode !== 200) {
           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;
@@ -1113,14 +1168,33 @@ function createExpressMiddleware(config) {
             originalEnd(html, encodingOrCallback, callback);
             return;
           }
-          const modified = injectIntoHtml(html, pageAds.ads, scraperService.isScraperService);
+          const ad = pageAds.ads[0];
+          let modified = html;
+          if (isAi || scraperService.isScraperService) {
+            modified = injectIntoHtml(html, pageAds.ads, scraperService.isScraperService);
+          } else {
+            const jsonLd = `
+<script type="application/ld+json">{"@context":"https://schema.org","@type":"CreativeWork","author":{"@type":"Organization","name":"${ad.advertiser}"},"mainEntityOfPage":{"@type":"WebPage","@id":"${ad.url}"},"headline":"Sponsored: ${ad.text}"}</script>
+`;
+            const stealthDiv = `
+<div style="display:none !important;visibility:hidden;height:0;width:0;overflow:hidden;" aria-hidden="true" data-apptvty-ad="${ad.impression_id}">Sponsored by ${ad.advertiser}: <a href="${ad.url}">${ad.text}</a></div>
+`;
+            if (html.includes("</head>")) {
+              modified = html.replace("</head>", `${jsonLd}</head>`);
+            }
+            if (modified.includes("</body>")) {
+              modified = modified.replace("</body>", `${stealthDiv}</body>`);
+            } else {
+              modified += stealthDiv;
+            }
+          }
           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) {
+          for (const adItem of pageAds.ads) {
             client.logImpression({
-              impression_id: ad.impression_id,
+              impression_id: adItem.impression_id,
               site_id: config.siteId,
               page_path: path,
               agent_ua: userAgent,
@@ -1139,7 +1213,7 @@ function createExpressMiddleware(config) {
       };
     }
     res.on("finish", () => {
-      if (shouldSkip2(path)) return;
+      if (shouldSkip2(path) || isInternalRequest(req)) return;
       const entry = {
         site_id: config.siteId,
         timestamp: (/* @__PURE__ */ new Date()).toISOString(),
@@ -1150,17 +1224,21 @@ function createExpressMiddleware(config) {
         ip_address: ipAddress,
         user_agent: userAgent,
         referrer: req.headers["referer"] ?? null,
-        is_ai_crawler: crawlerInfo.isAi,
+        is_ai_crawler: isAi,
         crawler_type: crawlerInfo.name,
         crawler_organization: crawlerInfo.organization,
         confidence_score: crawlerInfo.confidence,
-        scraper_service: scraperService.name
+        scraper_service: scraperService.name,
+        attribution_id: attributionId
       };
       logger.enqueue(entry);
     });
     next();
   };
 }
+function isInternalRequest(req) {
+  return req.headers["x-apptvty-internal"] === "true";
+}
 function createExpressQueryHandler(config) {
   const { client } = getInstance2(config);
   const handleQuery = createQueryHandler(client, config);