apptvty 0.3.1 → 0.4.0

package/dist/middleware/express.js

@@ -108,6 +108,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). */
@@ -355,8 +377,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);
       }
@@ -1166,13 +1192,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 && !shouldSkip(path) ? client.getAdsForPage({ site_id: config.siteId, page_path: path }).catch(() => ({ ads: [] })) : Promise.resolve({ ads: [] });
-    if (isCrawler && !shouldSkip(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 = parseBoolParam(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) && !shouldSkip(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) && !shouldSkip(path);
+    if (shouldBuffer) {
       res.write = function(chunk, encodingOrCallback, callback) {
         if (chunk != null) {
           chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
@@ -1187,17 +1218,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;
@@ -1205,14 +1231,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,
@@ -1231,7 +1276,7 @@ function createExpressMiddleware(config) {
       };
     }
     res.on("finish", () => {
-      if (shouldSkip(path)) return;
+      if (shouldSkip(path) || isInternalRequest(req)) return;
       const entry = {
         site_id: config.siteId,
         timestamp: (/* @__PURE__ */ new Date()).toISOString(),
@@ -1242,17 +1287,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 } = getInstance(config);
   const handleQuery = createQueryHandler(client, config);