cap-copilot-sdk 0.1.0 → 0.2.2

package/cds-plugin.js

@@ -1,67 +1,630 @@
-'use strict';
+"use strict";
 // Resolve @sap/cds from the project root (process.cwd()) to get the same
 // singleton instance that cds watch uses — not a duplicate from this package's location.
-const cdsPath = require.resolve('@sap/cds', { paths: [process.cwd()] });
+const cdsPath = require.resolve("@sap/cds", { paths: [process.cwd()] });
 const cds = require(cdsPath);
-const { extract, extractFromServices } = require('./src/SchemaExtractor');
-const { scan } = require('./src/ProjectScanner');
-const { register } = require('./src/Registrar');
+const path = require("path");
+const fs = require("fs");
+const { extract, extractFromServices } = require("./src/SchemaExtractor");
+const { scan } = require("./src/ProjectScanner");
+const {
+  register,
+  registerServiceTool,
+  registerAllServiceTools,
+} = require("./src/Registrar");
+
+// Read consuming app's package.json for zero-config defaults (name → appId, description → appName)
+let _appPkg = {};
+try {
+  _appPkg = JSON.parse(
+    fs.readFileSync(path.join(process.cwd(), "package.json"), "utf8"),
+  );
+} catch {}
 
-const cfg = cds.env.requires?.['btp-copilot'] ?? {};
+const cfg = cds.env.requires?.["btp-copilot"] ?? {};
 const {
-  backendUrl = process.env.BTP_COPILOT_URL,
-  appId     = process.env.BTP_COPILOT_APP_ID,
-  appName,
-  serviceUrl,
-  token             = process.env.BTP_COPILOT_TOKEN,
+  // Zero-config defaults — works out of the box without any cds.requires config
+  backendUrl = process.env.BTP_COPILOT_URL ?? "http://localhost:8000",
+  appId = process.env.BTP_COPILOT_APP_ID ??
+    (_appPkg.name ?? "cap-app").replace(/[^a-zA-Z0-9_-]/g, "-"),
+  appName = _appPkg.description ?? cfg.appId ?? _appPkg.name ?? "CAP App",
+  serviceUrl, // single service URL (legacy / simple apps)
+  serviceUrls, // array of service URLs for multi-service CAP apps
+  iframeUrl = process.env.BTP_COPILOT_IFRAME_URL ?? "http://localhost:5173",
+  token = process.env.BTP_COPILOT_TOKEN,
   includeProjectFiles = true,
-  includeHandlers     = true,
-  includeViews        = true,
+  includeHandlers = true,
+  includeViews = true,
+  injectWidget = true,
+  widgetPosition = "bottom-right",
+  autoWatch = false, // auto-register READ + mutation hooks on all entities (opt-in for enterprise)
+  autoSync = false, // background paginated sync of all entities on startup (opt-in for enterprise)
+  syncPageSize = 100, // rows per sync page
+  syncJitter = true, // random 0-30 s delay before startup sync (staggers multi-app restarts)
+  maxDocs = 200,    // max documents sent to backend per startup (increase if your app has many entities)
+  // multiTenant=true  → the app has many end-users; raw record data MUST NOT go into
+  //                     the shared vector store (User A would see User B's records).
+  //                     In this mode autoWatch + autoSync push only entity stats (count +
+  //                     field list).  Per-user live data is fetched at query time via OData
+  //                     using each user's own JWT — the CAP auth layer enforces isolation.
+  // multiTenant=false → single-user or dev; raw records are pushed to the vector store
+  //                     so the AI can answer questions even without an OData token.
+  multiTenant = process.env.BTP_COPILOT_MULTI_TENANT === "true"
+    ? true
+    : process.env.BTP_COPILOT_MULTI_TENANT === "false"
+      ? false
+      : false, // default: safe for single-user / dev; set true for production
 } = cfg;
 
-const log = (...args) => console.log('\x1b[36m[btp-copilot]\x1b[0m', ...args);
-const warn = (...args) => console.warn('\x1b[33m[btp-copilot]\x1b[0m', ...args);
-const err  = (...args) => console.error('\x1b[31m[btp-copilot]\x1b[0m', ...args);
+// Normalize service URLs: accept both `serviceUrl` (single, backward-compat) and
+// `serviceUrls` (array, for apps with multiple OData services).
+// When NEITHER is configured the plugin auto-discovers all internal service paths
+// from the running CDS services at startup — zero config needed for any app size.
+//
+// Auto-discovery rules (applied inside cds.on('served')):
+//   - Include only services that have a .path starting with /odata
+//   - Exclude services backed by external .csn/.edmx imports (proxy services)
+//     because those forward to external systems not reachable via localhost
+//   - Exclude pure value-help / reference services with no writable entities
+//     (they are still indexed in the vector store via autoWatch)
+const _configuredUrls = Array.isArray(serviceUrls)
+  ? serviceUrls.filter(Boolean)
+  : serviceUrl
+    ? [serviceUrl]
+    : null; // null = auto-discover at served time
+
+// Resolved after 'served' fires; used for widget attribute + schema docs.
+// Initialised to the first configured URL (or null) so the widget snippet
+// built during 'bootstrap' has a value even before 'served' fires.
+let _serviceUrls = _configuredUrls ?? [];
+let _primarySvcUrl = _serviceUrls[0] ?? null;
+
+// Base URL of this CAP server (e.g. http://localhost:4004).
+// Sent to the chatbot backend so it can resolve relative OData paths to full URLs.
+// Resolved from the CDS server address after 'served' fires.
+// Can be overridden via BTP_COPILOT_BASE_URL env var for non-standard setups.
+let _appBaseUrl = process.env.BTP_COPILOT_BASE_URL ?? null;
+
+const log = (...args) => console.log("\x1b[36m[btp-copilot]\x1b[0m", ...args);
+const warn = (...args) => console.warn("\x1b[33m[btp-copilot]\x1b[0m", ...args);
+const err = (...args) => console.error("\x1b[31m[btp-copilot]\x1b[0m", ...args);
+
+// ── HTML attribute escaping ───────────────────────────────────────────────────
+// Prevents XSS if appName or other config values contain special characters.
+function _escHtml(str) {
+  return String(str ?? "")
+    .replace(/&/g, "&")
+    .replace(/"/g, """)
+    .replace(/'/g, "'")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+// ── Widget auto-injection middleware ─────────────────────────────────────────
+// Intercepts every HTML response from CAP and appends the <btp-copilot> tag
+// + the widget script. Works for ALL Fiori/UI5 apps served by this CAP server
+// without any manual changes to their index.html files.
+function _buildWidgetSnippet() {
+  // Serve the widget JS bundle from node_modules so no CDN dependency
+  const widgetBundlePath = (() => {
+    try {
+      return require.resolve("cap-copilot-widget/dist/btp-copilot.js", {
+        paths: [process.cwd()],
+      });
+    } catch {
+      return null;
+    }
+  })();
+
+  if (!widgetBundlePath) {
+    warn(
+      "cap-copilot-widget not found in node_modules — falling back to unpkg.com CDN. " +
+      "Add cap-copilot-widget to your dependencies for offline/air-gapped deployments.",
+    );
+  }
+  const scriptTag = widgetBundlePath
+    ? `<script src="/__btp-copilot-widget/btp-copilot.js"></script>`
+    : `<script src="https://unpkg.com/cap-copilot-widget/dist/btp-copilot.js"></script>`;
+
+  const attrs = [
+    `app-id="${_escHtml(appId)}"`,
+    `position="${_escHtml(widgetPosition)}"`,
+    iframeUrl ? `iframe-url="${_escHtml(iframeUrl)}"` : "",
+    backendUrl ? `backend-url="${_escHtml(backendUrl)}"` : "",
+    _primarySvcUrl ? `service-url="${_escHtml(_primarySvcUrl)}"` : "",
+    appName ? `app-name="${_escHtml(appName)}"` : "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  return {
+    snippet: `\n${scriptTag}\n<btp-copilot ${attrs}></btp-copilot>\n</body>`,
+    widgetBundlePath,
+  };
+}
+
+function _registerWidgetMiddleware(app) {
+  // Always serve the widget bundle — even when iframeUrl is not configured
+  // so that apps that manually embed <btp-copilot> in their index.html can
+  // load the script from /__btp-copilot-widget/btp-copilot.js.
+  const { snippet, widgetBundlePath } = _buildWidgetSnippet();
+
+  if (widgetBundlePath) {
+    app.get("/__btp-copilot-widget/btp-copilot.js", (_req, res) => {
+      res.setHeader("Content-Type", "application/javascript");
+      res.setHeader("Cache-Control", "public, max-age=3600");
+      res.sendFile(widgetBundlePath);
+    });
+    log("Serving widget bundle at /__btp-copilot-widget/btp-copilot.js");
+  }
+
+  // Auto-inject widget into HTML responses only when iframeUrl is configured
+  if (!injectWidget || !iframeUrl) {
+    if (!iframeUrl)
+      warn(
+        'No iframeUrl configured — widget auto-injection skipped. Add "iframeUrl" to cds.requires["btp-copilot"] or embed <btp-copilot> manually in your index.html.',
+      );
+    return;
+  }
+
+  // Intercept HTML responses and inject the widget before </body>
+  app.use((req, res, next) => {
+    const _write = res.write.bind(res);
+    const _end = res.end.bind(res);
+    let _buffer = "";
+    let _isHtml = false;
+    let _intercepted = false;
+
+    res.on("pipe", () => {});
+
+    const _intercept = () => {
+      const ct = res.getHeader("content-type") || "";
+      _isHtml = ct.includes("text/html");
+    };
+
+    const _inject = (chunk) => {
+      if (!_isHtml) return chunk;
+      const str = Buffer.isBuffer(chunk) ? chunk.toString("utf8") : chunk || "";
+      if (str.includes("</body>")) {
+        _intercepted = true;
+        return str.replace("</body>", snippet);
+      }
+      return str;
+    };
+
+    // Wrap write
+    res.write = function (chunk, encoding, callback) {
+      _intercept();
+      const patched = _inject(chunk);
+      return _write(patched, encoding, callback);
+    };
+
+    // Wrap end
+    res.end = function (chunk, encoding, callback) {
+      _intercept();
+      if (chunk) {
+        const patched = _inject(chunk);
+        return _end(patched, encoding, callback);
+      }
+      return _end(chunk, encoding, callback);
+    };
+
+    next();
+  });
+
+  log(
+    `Widget auto-injection active — <btp-copilot> will appear in all HTML pages.`,
+  );
+}
+
+// ── Graceful shutdown: flush debounce queue ───────────────────────────────────
+// Ensures any queued entity data is sent before the process exits so no records
+// are silently lost when cds watch restarts or the container is killed.
+const _gracefulShutdown = async () => {
+  try {
+    const { flushAll } = require("./src/DataSender");
+    log("Flushing pending data before shutdown…");
+    await flushAll();
+  } catch {}
+};
+// cds.on("shutdown") is the preferred CDS lifecycle hook; SIGTERM is the fallback
+// for Docker/Kubernetes environments where the CDS hook may not fire.
+try { cds.on("shutdown", _gracefulShutdown); } catch {}
+process.once("SIGTERM", _gracefulShutdown);
 
 if (!backendUrl || !appId) {
-  log('No backendUrl/appId in cds.requires["btp-copilot"] — skipping registration.');
+  log(
+    'No backendUrl/appId in cds.requires["btp-copilot"] — skipping registration.',
+  );
 } else if (!/^[a-zA-Z0-9_-]+$/.test(appId)) {
-  warn(`appId "${appId}" contains invalid characters. Use only letters, digits, _ and -.`);
+  warn(
+    `appId "${appId}" contains invalid characters. Use only letters, digits, _ and -.`,
+  );
 } else {
-  cds.on('served', async (services) => {
-    try {
-      log(`Collecting context for app "${appId}"…`);
-      const allDocs = [];
-
-      const schemaDocs = extract(cds, { serviceUrl });
-      allDocs.push(...schemaDocs);
-      log(`  + ${schemaDocs.length} schema documents`);
-
-      const serviceList = Array.isArray(services) ? services : Object.values(services ?? {});
-      const runtimeDocs = extractFromServices(serviceList);
-      allDocs.push(...runtimeDocs);
-      if (runtimeDocs.length) log(`  + ${runtimeDocs.length} runtime service documents`);
-
-      if (includeProjectFiles) {
-        const projectRoot = cds.env.root ?? process.cwd();
-        const fileDocs = scan(projectRoot, { includeHandlers, includeViews });
-        allDocs.push(...fileDocs);
-        log(`  + ${fileDocs.length} project file documents`);
+  // Register the middleware as early as possible so it wraps all HTML routes
+  cds.on("bootstrap", (app) => {
+    _registerWidgetMiddleware(app);
+  });
+
+  cds.on("served", (services) => {
+    // Resolve the CAP server's own listening URL so relative service paths can be
+    // reconstructed into full URLs by the chatbot backend.
+    if (!_appBaseUrl) {
+      try {
+        // Cloud Foundry / BTP: external URL from VCAP_APPLICATION
+        const vcap = process.env.VCAP_APPLICATION;
+        if (vcap) {
+          const vcapData = JSON.parse(vcap);
+          const externalUri = vcapData.application_uris?.[0];
+          if (externalUri) {
+            _appBaseUrl = `https://${externalUri}`;
+            log(`Detected BTP/CF external URL: ${_appBaseUrl}`);
+          }
+        }
+        // Local development: use the actual listening port
+        if (!_appBaseUrl) {
+          const addr = cds.server?.address?.();
+          const port = addr?.port || cds.env?.server?.port || 4004;
+          _appBaseUrl = `http://localhost:${port}`;
+        }
+      } catch {
+        _appBaseUrl = "http://localhost:4004";
+      }
+    }
+
+    // ── Layer 1: Auto-register READ + mutation hooks on all entities ──────────
+    // Every OData read AND every create/update is captured automatically.
+    // In multiTenant mode: hooks still fire but the data is NOT sent to the
+    // vector store — the SDK silently skips push since each user's OData data
+    // must stay private and is fetched live at query time instead.
+    if (autoWatch && !multiTenant) {
+      const { watchEntity: _autoWatch } = require("./src/DataSender");
+      const svcList = Array.isArray(services)
+        ? services
+        : Object.values(services ?? {});
+      let watchCount = 0;
+      for (const svc of svcList) {
+        if (typeof svc.after !== "function" || !svc.entities) continue;
+        for (const [, entity] of Object.entries(svc.entities)) {
+          _autoWatch(svc, entity, { backendUrl, appId, token, appName });
+          watchCount++;
+        }
+      }
+      if (watchCount > 0)
+        log(
+          `Auto-watching ${watchCount} entit${watchCount === 1 ? "y" : "ies"} (READ + mutations) across all services.`,
+        );
+    } else if (autoWatch && multiTenant) {
+      log(
+        "multiTenant=true — skipping autoWatch (raw record push). Live user data is fetched via OData at query time.",
+      );
+    }
+
+    // ── Layer 2: Background startup sync ─────────────────────────────────────
+    // Catches all historical data in the DB — not just records visited today.
+    // Incremental on restart: only re-syncs rows changed since last sync.
+    if (autoSync) {
+      const { syncAllEntities } = require("./src/DataSender");
+      // Use os.tmpdir() so cds watch never sees this file and doesn't restart
+      const cacheFile = path.join(
+        require("os").tmpdir(),
+        `.btp-copilot-${appId}.json`,
+      );
+
+      let modifiedSince = null;
+      try {
+        const cached = JSON.parse(fs.readFileSync(cacheFile, "utf8"));
+        modifiedSince = cached.lastSyncedAt ?? null;
+      } catch {}
+
+      const svcList = Array.isArray(services)
+        ? services
+        : Object.values(services ?? {});
+      const syncStart = new Date().toISOString();
+
+      setImmediate(async () => {
+        try {
+          // Startup jitter: delay by a random amount so that when 100+ apps
+          // restart simultaneously they don't all hammer the backend at once.
+          if (syncJitter) {
+            const jitterMs = Math.floor(Math.random() * 30_000);
+            log(
+              `Startup sync delayed ${Math.round(jitterMs / 1000)}s (jitter) to spread backend load.`,
+            );
+            await new Promise((r) => setTimeout(r, jitterMs));
+          }
+          log(
+            modifiedSince
+              ? `Starting incremental sync (changes since ${modifiedSince})…`
+              : `Starting full background sync — all entity data will be indexed…`,
+          );
+          const total = await syncAllEntities(
+            cds,
+            svcList,
+            { backendUrl, appId, token, appName },
+            {
+              pageSize: syncPageSize,
+              modifiedSince,
+              multiTenant,
+            },
+          );
+          log(
+            `\x1b[32m✔ Background sync complete — ${total} row(s) indexed.\x1b[0m`,
+          );
+          try {
+            let cached = {};
+            try {
+              cached = JSON.parse(fs.readFileSync(cacheFile, "utf8"));
+            } catch {}
+            fs.writeFileSync(
+              cacheFile,
+              JSON.stringify({ ...cached, lastSyncedAt: syncStart }),
+            );
+          } catch {}
+        } catch (e) {
+          warn("Background sync error —", e.message);
+        }
+      });
+    }
+
+    // ── Layer 3: Auto-discover + register OData service(s) as live query tools ─
+    // When the user has not configured serviceUrl(s) we build the list automatically
+    // from every CDS service that has an /odata path and real (non-external) entities.
+    // This means zero config for any app, regardless of how many services it has.
+    {
+      const svcList = Array.isArray(services)
+        ? services
+        : Object.values(services ?? {});
+
+      // ── Identify external/proxy services (backed by .csn/.edmx imports) ───
+      // CDS marks external service definitions with a "from" pointing to an
+      // external file. We detect them by checking the model definitions.
+      const _externalServiceNames = new Set();
+      try {
+        const defs = cds.model?.definitions ?? {};
+        for (const [name, def] of Object.entries(defs)) {
+          if (def.kind === "service") {
+            const src = def.$location?.file ?? def["@src"] ?? "";
+            if (src && !/\.cds$/i.test(src)) _externalServiceNames.add(name);
+          }
+        }
+      } catch {
+        /* ignore */
       }
 
-      if (!allDocs.length) { log('No documents to register.'); return; }
+      // ── Auto-discover: build URL list from running services ───────────────
+      if (_configuredUrls === null) {
+        _serviceUrls = svcList
+          .filter((svc) => {
+            // Must have an /odata path
+            if (!svc.path?.startsWith("/odata")) return false;
+            // Skip CDS-internal services: the database service (cds.db) is
+            // accessible via svc.path="/odata/v4/db" but is NOT a real OData
+            // endpoint — it is the internal persistence layer. Same for any
+            // service whose name is exactly "db" or is a DatabaseService instance.
+            if (svc.name === "db" || svc.path === "/odata/v4/db") return false;
+            if (cds.DatabaseService && svc instanceof cds.DatabaseService)
+              return false;
+            // Skip external proxy services (backed by .csn/.edmx imports)
+            if (_externalServiceNames.has(svc.name)) return false;
+            // Must expose at least one entity
+            if (!svc.entities || Object.keys(svc.entities).length === 0)
+              return false;
+            return true;
+          })
+          .map((svc) => svc.path);
 
-      const toSend = Math.min(allDocs.length, 50);
-      log(`Registering ${toSend} of ${allDocs.length} documents with backend…`);
+        _primarySvcUrl = _serviceUrls[0] ?? null;
+        if (_serviceUrls.length) {
+          log(
+            `Auto-discovered ${_serviceUrls.length} OData service(s) for live-query tool registration.`,
+          );
+        }
+      }
+
+      if (_serviceUrls.length) {
+        setImmediate(() => {
+          const registrations = _serviceUrls.map((svcUrl) => {
+            // Match the service whose path equals this URL.
+            const matchedSvc = svcList.find((svc) => svc.path === svcUrl);
 
-      const ok = await register({ backendUrl, appId, appName: appName ?? appId, serviceUrl, documents: allDocs, token });
-      if (ok) {
-        log(`\x1b[32m✔ App "${appId}" registered — chatbot is now context-aware!\x1b[0m`);
-      } else {
-        warn(`✘ Registration failed. Backend: ${backendUrl} — start your chatbot backend to enable AI answers.`);
+            // Only pass entities that belong to THIS service.
+            const entityNames = matchedSvc?.entities
+              ? Object.keys(matchedSvc.entities)
+              : [];
+
+            return registerServiceTool({
+              backendUrl,
+              appId,
+              appName,
+              serviceUrl: svcUrl,
+              entities: entityNames,
+              token,
+              appBaseUrl: _appBaseUrl,
+            });
+          });
+          Promise.all(registrations).catch(() => {});
+        });
       }
-    } catch (e) {
-      err('Registration error —', e.message);
     }
+    // ─────────────────────────────────────────────────────────────────────────
+
+    setImmediate(async () => {
+      try {
+        log(`Collecting context for app "${appId}"…`);
+        const allDocs = [];
+
+
+        const serviceList = Array.isArray(services)
+          ? services
+          : Object.values(services ?? {});
+
+        const schemaDocs = extract(cds, {
+          serviceUrl: _primarySvcUrl,
+          serviceList,
+        });
+        allDocs.push(...schemaDocs);
+        log(`  + ${schemaDocs.length} schema documents`);
+
+        const runtimeDocs = extractFromServices(serviceList);
+        allDocs.push(...runtimeDocs);
+        if (runtimeDocs.length)
+          log(`  + ${runtimeDocs.length} runtime service documents`);
+
+        if (includeProjectFiles) {
+          const projectRoot = cds.env.root ?? process.cwd();
+          const fileDocs = scan(projectRoot, { includeHandlers, includeViews });
+          allDocs.push(...fileDocs);
+          log(`  + ${fileDocs.length} project file documents`);
+        }
+
+        if (!allDocs.length) {
+          log("No documents to register.");
+          return;
+        }
+
+        // ── Hash-based cache: skip re-registration if docs haven't changed ──
+        const crypto = require("crypto");
+        // Use os.tmpdir() so cds watch never sees this file and doesn't restart
+        const cacheFile = path.join(
+          require("os").tmpdir(),
+          `.btp-copilot-${appId}.json`,
+        );
+        const contentHash = crypto
+          .createHash("sha256")
+          .update(allDocs.map((d) => d.title + d.content).join("|"))
+          .digest("hex");
+
+        try {
+          const cached = JSON.parse(fs.readFileSync(cacheFile, "utf8"));
+          if (cached.appId === appId && cached.hash === contentHash) {
+            log(
+              `\x1b[32m✔ Schema unchanged — skipping re-registration (cached). Live data will still be seeded on first READ.\x1b[0m`,
+            );
+            return;
+          }
+        } catch {
+          // No cache file yet — proceed with registration
+        }
+        // ────────────────────────────────────────────────────────────────────
+
+        const toSend = Math.min(allDocs.length, maxDocs);
+        if (toSend < allDocs.length) {
+          warn(
+            `Sending ${toSend} of ${allDocs.length} documents (maxDocs=${maxDocs}). ` +
+            `Increase via cds.requires["btp-copilot"].maxDocs to index all documents.`,
+          );
+        }
+        log(
+          `Registering ${toSend} of ${allDocs.length} documents with backend…`,
+        );
+
+        const ok = await register({
+          backendUrl,
+          appId,
+          appName: appName ?? appId,
+          serviceUrl,
+          documents: allDocs,
+          token,
+        });
+        if (ok) {
+          // Save cache so next restart skips re-registration
+          try {
+            fs.writeFileSync(
+              cacheFile,
+              JSON.stringify({ appId, hash: contentHash, ts: Date.now() }),
+            );
+          } catch {
+            /* ignore cache write errors */
+          }
+          log(
+            `\x1b[32m✔ App "${appId}" registered — chatbot is now context-aware!\x1b[0m`,
+          );
+        } else {
+          warn(
+            `✘ Registration failed. Backend: ${backendUrl} — start your chatbot backend to enable AI answers.`,
+          );
+        }
+      } catch (e) {
+        err("Registration error —", e.message);
+      }
+    }); // end setImmediate
   });
 }
+
+// ── Public API ────────────────────────────────────────────────────────────────
+const {
+  sendEntityData,
+  watchEntity: _watchEntity,
+  syncAllEntities: _syncAll,
+} = require("./src/DataSender");
+
+/**
+ * Push live DB query results to the BTP Copilot backend from any CAP
+ * service handler or action — minimum code, no extra config needed.
+ *
+ * The plugin already has backendUrl / appId / token from cds.env so you
+ * only pass the entity name and the data you just queried.
+ *
+ * @example
+ *   const { sendData } = require('cap-copilot-sdk');
+ *
+ *   // inside any srv.on / srv.before / srv.after handler:
+ *   const data = await tx.run(SELECT.from(Orders).where({ ID: orderID }));
+ *   await sendData('Orders', data);
+ *
+ * @param {string}           entityName  - entity name, e.g. 'Orders'
+ * @param {object[]|object}  data        - result of tx.run(SELECT.from(...))
+ * @param {string}           [label]     - optional custom document title
+ * @returns {Promise<boolean>}
+ */
+module.exports.sendData = (entityName, data, label) =>
+  sendEntityData(
+    { backendUrl, appId, token, appName },
+    entityName,
+    data,
+    label,
+  );
+
+/**
+ * Register an after-READ hook so this entity's read results are pushed to the
+ * BTP Copilot chatbot automatically — no manual sendData calls needed.
+ *
+ * This is the recommended pattern for CAP apps. Only data that the user
+ * actually reads is sent, so it scales to large tables without bulk dumps.
+ *
+ * @example
+ *   const { watchEntity } = require('cap-copilot-sdk');
+ *
+ *   // In module.exports = (srv) => { ... }:
+ *   const { FertilizerBlend, AssignMaterialToBlend, UnitsOfMeasuresV1 } = srv.entities;
+ *
+ *   // Transactional: group by key so each order is a separate titled document
+ *   watchEntity(srv, FertilizerBlend,       { groupByKey: 'orderID' });
+ *   watchEntity(srv, AssignMaterialToBlend, { groupByKey: 'to_FertilizerBlend_orderID' });
+ *
+ *   // Reference/lookup: send only on the first READ, then cache
+ *   watchEntity(srv, UnitsOfMeasuresV1, { once: true });
+ *
+ * @param {object}  srv
+ * @param {object}  entity               CDS entity from srv.entities
+ * @param {object}  [options]
+ * @param {string}  [options.groupByKey]  Field to group rows by (one doc per unique value)
+ * @param {string}  [options.labelPrefix] Custom document title prefix (default: entity name)
+ * @param {boolean} [options.once]        Only send on the first READ
+ */
+module.exports.watchEntity = (srv, entity, options) =>
+  _watchEntity(srv, entity, { backendUrl, appId, token, appName }, options);
+
+/**
+ * Manually trigger a paginated background sync of all entities across all services.
+ * Useful for triggering a re-sync after bulk imports or migrations.
+ *
+ * @param {object}  cds       - @sap/cds instance
+ * @param {object[]} services - array of CDS service instances
+ * @param {object}  [options]
+ * @param {number}  [options.pageSize]       rows per page (default: 100)
+ * @param {string}  [options.modifiedSince]  ISO timestamp — only sync rows newer than this
+ */
+module.exports.syncAll = (cds, services, options) =>
+  _syncAll(cds, services, { backendUrl, appId, token, appName }, options);