cap-copilot-sdk 0.1.1 → 0.2.2

package/src/Registrar.js

@@ -1,74 +1,253 @@
 "use strict";
 const https = require("https");
-const http = require("http");
+const http  = require("http");
 const { URL } = require("url");
 
-/**
- * Register (or update) the app context documents with the BTP Copilot backend.
- *
- * POST /api/apps/register
- * Body: { app_id, app_name, documents, replace }
- *
- * @param {{ backendUrl: string, appId: string, appName: string,
- *           documents: {title:string, content:string}[],
- *           token?: string }} opts
- * @returns {Promise<boolean>}
- */
-async function register(opts) {
-  const { backendUrl, appId, appName, documents, token } = opts;
+const SDK_VERSION = (() => {
+  try { return require("../package.json").version; } catch { return "unknown"; }
+})();
+// Timeout for every outbound HTTP request to the backend.
+// Override via BTP_COPILOT_REQUEST_TIMEOUT_MS env var if needed.
+const REQUEST_TIMEOUT_MS = Number(process.env.BTP_COPILOT_REQUEST_TIMEOUT_MS) || 15_000;
 
-  // Backend allows max 50 documents — trim if needed
-  const docs = documents.slice(0, 50);
+// ── Logging helpers ───────────────────────────────────────────────────────────
+const _log  = (...a) => console.log ("\x1b[36m[btp-copilot]\x1b[0m", ...a);
+const _warn = (...a) => console.warn("\x1b[33m[btp-copilot]\x1b[0m", ...a);
 
-  const url = new URL("/api/apps/register", backendUrl);
-  const body = JSON.stringify({
-    app_id: appId,
-    app_name: appName ?? appId,
-    documents: docs,
-    replace: true,
-  });
+// ── Concurrency limiter ───────────────────────────────────────────────────────
+// At most MAX_CONCURRENT outbound HTTP requests to the Python backend at one
+// time (per Node.js process / CAP app instance).  When a startup sync or a
+// burst of watchEntity mutations fires many simultaneous requests, the excess
+// wait here rather than landing all at once on the backend.
+const MAX_CONCURRENT = 3;
+let _active = 0;
+const _waitQueue = [];
 
+function _acquire() {
   return new Promise((resolve) => {
-    const lib = url.protocol === "https:" ? https : http;
-    const headers = {
-      "Content-Type": "application/json",
-      "Content-Length": Buffer.byteLength(body),
-    };
-    if (token) headers["Authorization"] = `Bearer ${token}`;
+    if (_active < MAX_CONCURRENT) { _active++; resolve(); }
+    else _waitQueue.push(resolve);
+  });
+}
+
+function _release() {
+  // Hand the slot to the next waiter without changing _active; only decrement
+  // when there is truly nobody waiting.
+  if (_waitQueue.length > 0) _waitQueue.shift()();
+  else _active--;
+}
+
+// ── Circuit breaker ───────────────────────────────────────────────────────────
+// Protects the backend when it is down or overloaded.
+// CLOSED  → normal operation.
+// After CB_THRESHOLD consecutive failures → OPEN: all requests are dropped for
+//   CB_RESET_MS ms so the backend gets breathing room.
+// After CB_RESET_MS → HALF_OPEN: one probe request is allowed through.
+//   Success → CLOSED.  Failure → OPEN again (timer resets).
+const CB_THRESHOLD = 5;
+const CB_RESET_MS  = 60_000; // 1 minute
+
+const _cb = { state: "CLOSED", failures: 0, openedAt: 0 };
+
+function _cbAllow() {
+  if (_cb.state === "CLOSED" || _cb.state === "HALF_OPEN") return true;
+  if (Date.now() - _cb.openedAt >= CB_RESET_MS) { _cb.state = "HALF_OPEN"; return true; }
+  return false;
+}
+function _cbSuccess() { _cb.state = "CLOSED"; _cb.failures = 0; }
+function _cbFailure() {
+  _cb.failures++;
+  if (_cb.state === "HALF_OPEN" || _cb.failures >= CB_THRESHOLD) {
+    _cb.state   = "OPEN";
+    _cb.openedAt = Date.now();
+    _warn(`Circuit breaker OPEN — backend unreachable. Pausing all SDK requests for ${CB_RESET_MS / 1000}s.`);
+  }
+}
+
+// ── Retry with exponential backoff + jitter ───────────────────────────────────
+// 5xx / network errors → RetryableError (up to MAX_RETRIES attempts).
+// 4xx errors (auth, bad request) → return false immediately; no retry needed.
+const MAX_RETRIES  = 3;
+const BASE_WAIT_MS = 1000;
+
+class RetryableError extends Error {}
+
+function _sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
+
+async function _withRetry(fn) {
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    if (!_cbAllow()) {
+      _warn("Circuit breaker OPEN — request skipped to protect backend.");
+      return false;
+    }
+    await _acquire();
+    try {
+      const ok = await fn();
+      _cbSuccess();
+      return ok; // false = non-retryable 4xx; true = success
+    } catch (e) {
+      _cbFailure();
+      if (e instanceof RetryableError && attempt < MAX_RETRIES) {
+        const delay = BASE_WAIT_MS * Math.pow(2, attempt) + Math.random() * 600;
+        _warn(`Retry ${attempt + 1}/${MAX_RETRIES} in ${Math.round(delay)}ms — ${e.message}`);
+        await _sleep(delay);
+      } else {
+        _warn("Request failed:", e.message);
+        return false;
+      }
+    } finally {
+      _release();
+    }
+  }
+  return false;
+}
+
+// ── Reusable TCP agents ───────────────────────────────────────────────────────
+const _agents = {
+  http:  new http.Agent ({ keepAlive: true, maxSockets: 4 }),
+  https: new https.Agent({ keepAlive: true, maxSockets: 4 }),
+};
+
+// ── Low-level HTTP POST ───────────────────────────────────────────────────────
+// Resolves:  true    → 2xx success
+//            false   → 4xx (config/auth error; caller should not retry)
+// Throws:    RetryableError → 5xx or network error; caller should retry
+function _post(backendUrl, apiPath, payload, token, label) {
+  const url     = new URL(apiPath, backendUrl);
+  const body    = JSON.stringify(payload);
+  const isHttps = url.protocol === "https:";
+  const lib     = isHttps ? https : http;
+  const agent   = isHttps ? _agents.https : _agents.http;
+
+  const headers = {
+    "Content-Type":              "application/json",
+    "Content-Length":            Buffer.byteLength(body),
+    "X-BTP-Copilot-SDK-Version": SDK_VERSION,
+  };
+  if (token) headers["Authorization"] = `Bearer ${token}`;
+
+  _log(`POST ${url.href}`);
 
+  return new Promise((resolve, reject) => {
     const req = lib.request(
       {
         hostname: url.hostname,
-        port: url.port || (url.protocol === "https:" ? 443 : 80),
-        path: url.pathname + url.search,
-        method: "POST",
+        port:     url.port || (isHttps ? 443 : 80),
+        path:     url.pathname + url.search,
+        method:   "POST",
         headers,
-        // Accept self-signed certs in dev environments
-        rejectUnauthorized: process.env.NODE_ENV !== "production",
+        agent,
+        // Always verify TLS certificates. Set BTP_COPILOT_TLS_INSECURE=1 ONLY for
+        // local dev with self-signed certs. Never disable in production.
+        rejectUnauthorized: process.env.BTP_COPILOT_TLS_INSECURE !== "1",
+        timeout: REQUEST_TIMEOUT_MS,
       },
       (res) => {
-        let body = "";
-        res.on("data", (chunk) => (body += chunk));
+        let data = "";
+        res.on("data", (c) => (data += c));
         res.on("end", () => {
-          const ok = res.statusCode >= 200 && res.statusCode < 300;
-          if (!ok) {
-            console.warn(
-              `[btp-copilot] Registration HTTP ${res.statusCode}: ${body.slice(0, 200)}`,
-            );
+          if (res.statusCode >= 200 && res.statusCode < 300) {
+            resolve(true);
+          } else if (res.statusCode >= 500) {
+            reject(new RetryableError(`HTTP ${res.statusCode}`));
+          } else if (res.statusCode === 404 && label === "service-tool") {
+            // Backend does not yet support live-query tool registration — not an error
+            _log("Backend does not yet support OData service tool registration (404) — using vector store only.");
+            resolve(false);
+          } else {
+            _warn(`Backend responded ${res.statusCode}: ${data.slice(0, 300)}`);
+            resolve(false);
           }
-          resolve(ok);
         });
       },
     );
-
-    req.on("error", (err) => {
-      console.warn("[btp-copilot] Registration network error:", err.message);
-      resolve(false);
+    req.on("timeout", () => {
+      req.destroy(new RetryableError(`Request timed out after ${REQUEST_TIMEOUT_MS}ms`));
     });
-
+    req.on("error", (e) => reject(new RetryableError(e.message)));
     req.write(body);
     req.end();
   });
 }
 
-module.exports = { register };
+// ── Public API ────────────────────────────────────────────────────────────────
+
+async function register(opts) {
+  const { backendUrl, appId, appName, documents, token, appBaseUrl, serviceUrl } = opts;
+  const replace = opts.replace !== false;
+
+  _log(`Sending ${documents.length} doc(s) to backend (appId="${appId}")…`);
+
+  const ok = await _withRetry(() =>
+    _post(backendUrl, "/api/apps/register", {
+      app_id:       appId,
+      app_name:     appName ?? appId,
+      // Always include base URL and service path so the backend stores them in
+      // the app registry. When the backend restarts it loses service-tool
+      // registrations but still has these values from the most recent register
+      // call, allowing live OData queries to work without a CAP restart.
+      app_base_url: appBaseUrl ?? "",
+      service_url:  serviceUrl ?? "",
+      documents,
+      replace,
+    }, token, "register")
+  );
+
+  if (ok) _log(`✔ Backend accepted ${documents.length} docs — indexing in background.`);
+  return ok;
+}
+
+/**
+ * Register one CAP OData service as a live query tool with the chatbot backend.
+ * Call once per service URL (use registerAllServiceTools for multi-service apps).
+ *
+ * Flow WITHOUT this:  user asks → search vector store → LLM answers from cached text
+ * Flow WITH this:     user asks → LLM calls OData tool → gets live rows → LLM answers
+ *
+ * @param {{ backendUrl, appId, appName, serviceUrl, entities: string[], token }} opts
+ */
+async function registerServiceTool(opts) {
+  const { backendUrl, appId, appName, serviceUrl, entities, entityFields, token, appBaseUrl } = opts;
+  if (!serviceUrl) return false;
+
+  _log(`Registering OData tool — appId="${appId}" service="${serviceUrl}" entities=${(entities ?? []).length}`);
+
+  const ok = await _withRetry(() =>
+    _post(backendUrl, "/api/apps/register-service-tool", {
+      app_id:        appId,
+      app_name:      appName ?? appId,
+      service_url:   serviceUrl,
+      entities:      entities ?? [],
+      entity_fields: entityFields ?? {},
+      app_base_url:  appBaseUrl ?? "",
+    }, token, "service-tool")
+  );
+
+  if (ok) _log(`✔ OData service tool registered — chatbot can now query live data directly.`);
+  return ok;
+}
+
+/**
+ * Register multiple OData service URLs for a multi-service CAP app.
+ * Each service is registered as a separate live query tool on the backend.
+ *
+ * Config example (package.json):
+ *   "serviceUrls": ["/odata/v4/SalesService", "/odata/v4/PurchaseService"]
+ *
+ * @param {{ backendUrl, appId, appName, serviceUrls: string[], entities: string[], token }} opts
+ * @returns {Promise<boolean[]>} one result per URL
+ */
+async function registerAllServiceTools(opts) {
+  const { serviceUrls = [], entityFieldsMap = {}, ...rest } = opts;
+  if (!serviceUrls.length) return [];
+  // Run registrations sequentially to respect the concurrency limiter
+  const results = [];
+  for (const serviceUrl of serviceUrls) {
+    // entityFieldsMap is keyed by serviceUrl; fall back to the top-level entityFields if present
+    const entityFields = entityFieldsMap[serviceUrl] ?? rest.entityFields ?? {};
+    results.push(await registerServiceTool({ ...rest, serviceUrl, entityFields }));
+  }
+  return results;
+}
+
+module.exports = { register, registerServiceTool, registerAllServiceTools };

package/src/SchemaExtractor.js

@@ -13,7 +13,7 @@
 
 /**
  * @param {import('@sap/cds')} cds
- * @param {{ serviceUrl?: string }} [options]
+ * @param {{ serviceUrl?: string, serviceList?: object[] }} [options]
  * @returns {{ title: string, content: string }[]}
  */
 function extract(cds, options = {}) {
@@ -22,16 +22,39 @@ function extract(cds, options = {}) {
 
   const docs = [];
   const serviceUrl = options.serviceUrl ?? "";
+  const serviceList = options.serviceList ?? [];
   const defs = model.definitions ?? {};
 
+
+  const entityServicePath = {};
+  for (const srv of serviceList) {
+    const srvPath = srv.path ?? srv.options?.path ?? "";
+    if (!srvPath) continue;
+    for (const entityName of Object.keys(srv.entities ?? {})) {
+      const shortName = entityName.split(".").pop();
+      if (!entityServicePath[shortName]) {
+        entityServicePath[shortName] = srvPath;
+      }
+    }
+  }
+
   // ── Collect entity definitions (skip SAP framework entities, deduplicate by short name) ──
+  // External SAP API imports (.csn / .edmx) add 300+ irrelevant docs and slow
+  // down registration. Filter by source file: only keep entities whose definition
+  // originates from a .cds file (the app's own code). Entities loaded from
+  // .csn or .edmx files are external service proxies and are skipped.
   const seenShortNames = new Set();
   const entityDefs = Object.entries(defs).filter(([fqName, d]) => {
     if (d.kind !== "entity") return false;
-    // Skip SAP common / framework entities
+    // Skip SAP framework namespaces regardless of source file
     if (fqName.startsWith("sap.common.") || fqName.startsWith("cds.")) return false;
-    // Deduplicate: keep only the first occurrence of each short entity name
+    // Skip entities whose source file is an external import (.csn / .edmx)
+    const srcFile = d.$location?.file ?? d["@src"] ?? "";
+    if (srcFile && !/\.cds$/i.test(srcFile)) return false;
     const shortName = fqName.split(".").pop();
+    // Skip localisation text shadow-entities (*_texts)
+    if (shortName.endsWith("_texts")) return false;
+    // Deduplicate: keep only the first occurrence of each short entity name
     if (seenShortNames.has(shortName)) return false;
     seenShortNames.add(shortName);
     return true;
@@ -41,6 +64,8 @@ function extract(cds, options = {}) {
     const shortName = fqName.split(".").pop();
     const elements = def.elements ?? {};
 
+    const entityPath = entityServicePath[shortName] ?? serviceUrl ?? "";
+
     const keys = [];
     const fields = [];
     const associations = [];
@@ -55,17 +80,32 @@ function extract(cds, options = {}) {
       if (el.type === "cds.Composition") {
         const target = _shortName(el.target ?? "");
         const card = el.cardinality?.max === "*" ? "many" : "one";
-        compositions.push(`${elName} → ${target} (composition of ${card})`);
+        const targetPath = entityServicePath[target] ?? entityPath;
+        // The FK on the child entity is named to_<ParentEntity>_<keyField>.
+        // Use the first key of the CURRENT entity as the parent key field.
+        const parentKeyField = keys.length > 0
+          ? `to_${shortName}_${keys[0].split(" ")[0]}`
+          : null;
+        const queryHint =
+          card === "many" && targetPath && parentKeyField
+            ? ` — query children: GET ${targetPath}/${target}?$filter=${parentKeyField}%20eq%20<value>`
+            : "";
+        compositions.push(`${elName} → ${target} (composition of ${card}${queryHint})`);
       } else if (el.type === "cds.Association") {
         const target = _shortName(el.target ?? "");
         const card = el.cardinality?.max === "*" ? "many" : "one";
-        const fk = el.keys
+        const fkKeys = el.keys
           ?.map((k) => k.ref?.join(".") ?? "")
-          .filter(Boolean)
-          .join(", ");
+          .filter(Boolean) ?? [];
+        const fk = fkKeys.join(", ");
         const fkStr = fk ? `, FK: ${fk}` : "";
+        const targetPath = entityServicePath[target] ?? entityPath;
+        const filterHint =
+          fkKeys.length > 0 && targetPath
+            ? ` — to get related ${target} records: GET ${targetPath}/${target}?$filter=${fkKeys[0]} eq <value>`
+            : "";
         associations.push(
-          `${elName} → ${target} (association to ${card}${fkStr})`,
+          `${elName} → ${target} (association to ${card}${fkStr}${filterHint})`,
         );
       } else if (el.key) {
         keys.push(`${elName} (${typeName}, key)`);
@@ -86,15 +126,74 @@ function extract(cds, options = {}) {
 
     const lines = [`Entity: ${shortName}`, `Fully qualified name: ${fqName}`];
 
-    if (serviceUrl) {
-      lines.push(`OData path: ${serviceUrl}/${shortName}`);
-      lines.push(`Count records: GET ${serviceUrl}/${shortName}/$count`);
-      lines.push(
-        `Filter example: GET ${serviceUrl}/${shortName}?$filter=ID eq 1`,
-      );
-      lines.push(
-        `Expand example: GET ${serviceUrl}/${shortName}?$expand=${associations[0]?.split(" ")[0] ?? "navProp"}`,
-      );
+    // ── Build FK filter guidance FIRST so it appears at the top of the doc ──
+    // The agent retrieves the first part of the schema doc from the vector store.
+    // If filter guidance is at the bottom it gets truncated/ignored, causing the
+    // agent to query a parent entity (e.g. SalesOrder) instead of the child
+    // (e.g. SalesOrderItem). Putting guidance first ensures the agent reads it.
+    const fkFilters = [];
+    // 1. Association-derived FK guidance: walk each association and find its FK keys.
+    //    NOTE: el.keys gives the TARGET entity's PK names, not the FK field on THIS
+    //    entity. For unmanaged associations (defined with `on` clauses) or when the FK
+    //    is an explicit key field (common in SAP CAP patterns), this loop may produce
+    //    nothing — which is why key-field guidance (step 2) is also needed.
+    for (const [, el] of Object.entries(elements)) {
+      if (el.type !== "cds.Association") continue;
+      const fkKeys = el.keys?.map((k) => k.ref?.join(".") ?? "").filter(Boolean) ?? [];
+      const target = _shortName(el.target ?? "");
+      for (const fkField of fkKeys) {
+        // Detect integer FK fields — OData integer filters must NOT use quotes.
+        const fkEl = elements[fkField];
+        const isInt = fkEl?.type === "cds.Integer" || fkEl?.type === "cds.Int64"
+          || fkEl?.type === "cds.Int32" || fkEl?.type === "cds.Int16";
+        const valueTemplate = isInt ? "<numericValue>" : "'<stringValue>'";
+        if (entityPath) {
+          fkFilters.push(
+            `To get ${shortName} records for a specific ${target}: GET ${entityPath}/${shortName}?$filter=${fkField}%20eq%20${valueTemplate}`,
+          );
+        } else {
+          fkFilters.push(`To filter ${shortName} by ${target}: $filter=${fkField}%20eq%20${valueTemplate}`);
+        }
+      }
+    }
+
+    // 2. Key-field filter guidance: for entities with COMPOSITE KEYS (e.g. SalesOrderItem
+    //    with keys salesOrderID + itemNumber), generate a filter example for each key.
+    //    This is critical for entities whose FK is an explicit key field rather than a
+    //    CDS managed association FK — without this the agent gets NO filter guidance and
+    //    falls back to querying a wrong entity (e.g. SalesOrder instead of SalesOrderItem).
+    const keyElements = Object.entries(elements).filter(
+      ([name, el]) =>
+        el.key && !el.virtual && !el.target &&
+        !name.startsWith("_") &&
+        el.type !== "cds.Association" && el.type !== "cds.Composition",
+    );
+    if (keyElements.length > 1 && entityPath) {
+      for (const [name, el] of keyElements) {
+        const isInt = [
+          "cds.Integer", "cds.Int64", "cds.Int32", "cds.Int16",
+          "cds.Double", "cds.Decimal",
+        ].includes(el.type ?? "");
+        const valueTemplate = isInt ? "<numericValue>" : "'<value>'";
+        // Only add if not already covered by association FK guidance above
+        if (!fkFilters.some((f) => f.includes(`${name}%20eq`))) {
+          fkFilters.push(
+            `To filter ${shortName} by ${name}: GET ${entityPath}/${shortName}?$filter=${name}%20eq%20${valueTemplate}`,
+          );
+        }
+      }
+    }
+
+    if (fkFilters.length) {
+      lines.push(`*** QUERY GUIDANCE — use ${shortName} (NOT a parent entity) to find these records ***`);
+      lines.push(`Filter guidance (spaces MUST be %20, never +):`);
+      for (const f of fkFilters) lines.push(`  ${f}`);
+    }
+
+    if (entityPath) {
+      lines.push(`OData path: ${entityPath}/${shortName}`);
+      lines.push(`Count records: GET ${entityPath}/${shortName}/$count`);
+      lines.push(`IMPORTANT: In OData filter URLs always encode spaces as %20, never as + (+ causes a parse error).`);
     }
 
     if (keys.length) lines.push(`Key fields: ${keys.join(", ")}`);
@@ -138,21 +237,33 @@ function extract(cds, options = {}) {
     });
   }
 
-  // ── Services ────────────────────────────────────────────────────────────────
+  // ── Actions and Functions ──────────────────────────────────────────────────
+  const actionDocs = _extractActionsAndFunctions(defs);
+  docs.push(...actionDocs);
+
+  // ── Service definitions with correct OData paths ──────────────────────────
+  // Emit one entry per service showing its actual OData path (from runtime
+  // service list if available, otherwise derive from the model definition name).
   const serviceEntries = [];
   for (const [fqName, def] of Object.entries(defs)) {
     if (def.kind !== "service") continue;
     const svcName = fqName.split(".").pop();
     const exposed = Object.keys(def.elements ?? {});
+    // Look up the real runtime path from the service list
+    const runtimeSrv = serviceList.find(
+      (s) => (s.name ?? "").endsWith(svcName),
+    );
+    const svcPath = runtimeSrv?.path ?? runtimeSrv?.options?.path ?? "";
+    const pathNote = svcPath ? ` (OData path: ${svcPath})` : "";
     if (exposed.length) {
-      serviceEntries.push(`${svcName}: ${exposed.join(", ")}`);
+      serviceEntries.push(`${svcName}${pathNote}: ${exposed.join(", ")}`);
     }
   }
   if (serviceEntries.length) {
     docs.push({
       title: "Service definitions",
       content: [
-        "CAP services and the entities/projections they expose:",
+        "CAP services, their OData paths, and the entities/projections they expose:",
         ...serviceEntries,
       ].join("\n"),
     });
@@ -164,30 +275,36 @@ function extract(cds, options = {}) {
     const summaryLines = [
       `This CAP application defines ${entityNames.length} entities: ${entityNames.join(", ")}.`,
     ];
-    if (serviceUrl) {
-      summaryLines.push(`OData service base URL: ${serviceUrl}`);
-      summaryLines.push("Query patterns:");
-      summaryLines.push("  GET {serviceUrl}/{Entity} — list all records");
-      summaryLines.push(
-        "  GET {serviceUrl}/{Entity}/{key} — single record by key",
-      );
-      summaryLines.push("  GET {serviceUrl}/{Entity}/$count — total count");
-      summaryLines.push(
-        "  GET {serviceUrl}/{Entity}?$filter=field eq value — filter",
-      );
-      summaryLines.push(
-        "  GET {serviceUrl}/{Entity}?$select=f1,f2 — specific fields",
-      );
-      summaryLines.push(
-        "  GET {serviceUrl}/{Entity}?$top=10&$skip=0 — pagination",
-      );
-      summaryLines.push(
-        "  GET {serviceUrl}/{Entity}?$orderby=field desc — sorting",
-      );
+    // Use the entity-to-service map to show each entity's real path
+    const uniquePaths = [...new Set(Object.values(entityServicePath))];
+    if (uniquePaths.length > 0) {
       summaryLines.push(
-        "  GET {serviceUrl}/{Entity}?$expand=navProp — related entities",
+        `OData service paths: ${uniquePaths.join(", ")}`,
       );
+    } else if (serviceUrl) {
+      summaryLines.push(`OData service base URL: ${serviceUrl}`);
     }
+    summaryLines.push("Query patterns (replace {servicePath} and {Entity} with values from 'OData path' in each entity's schema doc):");
+    summaryLines.push("  GET {servicePath}/{Entity} — list all records");
+    summaryLines.push(
+      "  GET {servicePath}/{Entity}/{key} — single record by key",
+    );
+    summaryLines.push("  GET {servicePath}/{Entity}/$count — total count");
+    summaryLines.push(
+      "  GET {servicePath}/{Entity}?$filter=field eq value — filter",
+    );
+    summaryLines.push(
+      "  GET {servicePath}/{Entity}?$select=f1,f2 — specific fields",
+    );
+    summaryLines.push(
+      "  GET {servicePath}/{Entity}?$top=10&$skip=0 — pagination",
+    );
+    summaryLines.push(
+      "  GET {servicePath}/{Entity}?$orderby=field desc — sorting",
+    );
+    summaryLines.push(
+      "  GET {servicePath}/{Entity}?$expand=navProp — related entities",
+    );
     docs.push({
       title: "Application schema summary",
       content: summaryLines.join("\n"),
@@ -263,4 +380,68 @@ function _shortName(fqn) {
   return fqn.split(".").pop() ?? fqn;
 }
 
+function _returnTypeStr(ret) {
+  if (!ret) return null;
+  if (ret.items) {
+    const inner = ret.items.type ?? ret.items.ref?.[0] ?? "unknown";
+    return `Array of ${_shortName(inner)}`;
+  }
+  return _shortType(ret.type ?? "");
+}
+
+function _paramListStr(params) {
+  return Object.entries(params ?? {})
+    .map(([name, p]) => `${name}: ${_shortType(p.type ?? "")}`)
+    .join(", ");
+}
+
+/** Extract unbound CDS actions and functions. */
+function _extractUnbound(defs) {
+  const docs = [];
+  for (const [fqName, def] of Object.entries(defs)) {
+    if (def.kind !== "action" && def.kind !== "function") continue;
+    const shortName = fqName.split(".").pop();
+    const kind = def.kind === "action" ? "Action" : "Function";
+    const lines = [`${kind}: ${shortName}`, `Fully qualified name: ${fqName}`];
+    const params = _paramListStr(def.params);
+    if (params) lines.push(`Parameters: ${params}`);
+    const ret = _returnTypeStr(def.returns);
+    if (ret) lines.push(`Returns: ${ret}`);
+    if (def["@description"]) lines.push(`Description: ${def["@description"]}`);
+    if (def["@requires"]) lines.push(`Requires role: ${def["@requires"]}`);
+    docs.push({ title: `${kind}: ${shortName}`, content: lines.join("\n") });
+  }
+  return docs;
+}
+
+/** Extract bound actions/functions declared as service-level elements. */
+function _extractBound(defs) {
+  const docs = [];
+  for (const [fqName, def] of Object.entries(defs)) {
+    if (def.kind !== "service") continue;
+    const svcName = fqName.split(".").pop();
+    for (const [elName, el] of Object.entries(def.elements ?? {})) {
+      if (el.kind !== "action" && el.kind !== "function") continue;
+      const kind = el.kind === "action" ? "Bound Action" : "Bound Function";
+      const lines = [
+        `${kind}: ${elName}`,
+        `Service: ${svcName}`,
+        `Call path: POST ${svcName}/${elName}`,
+      ];
+      const params = _paramListStr(el.params);
+      if (params) lines.push(`Parameters: ${params}`);
+      docs.push({ title: `${kind}: ${elName}`, content: lines.join("\n") });
+    }
+  }
+  return docs;
+}
+
+/**
+ * Extract unbound and bound CDS actions/functions from the model definitions.
+ * These describe what operations the service exposes beyond plain CRUD.
+ */
+function _extractActionsAndFunctions(defs) {
+  return [..._extractUnbound(defs), ..._extractBound(defs)];
+}
+
 module.exports = { extract, extractFromServices };