@sungen/driver-api 3.2.24 → 3.2.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sungen/driver-api",
-  "version": "3.2.24",
+  "version": "3.2.25",
   "description": "Sungen API capability — the @api annotation, API catalog, OpenAPI import + `sungen api import`, and the specs/api.ts runtime template. Plugs into @sun-asterisk/sungen via the capability SPI.",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -13,7 +13,7 @@
   "author": "eqe team (engineer & quality) — Sun Asterisk",
   "license": "MIT",
   "dependencies": {
-    "@sun-asterisk/sungen": "3.2.24",
+    "@sun-asterisk/sungen": "3.2.25",
     "commander": "^14.0.2",
     "yaml": "^2.8.2"
   },

package/src/api-catalog.ts

@@ -32,7 +32,8 @@ export interface ApiEntry {
   method: HttpMethod;
   path: string;
   body?: unknown;
-  encoding?: 'json' | 'form' | 'multipart'; // request-body wire format (default json); form = application/x-www-form-urlencoded
+  encoding?: 'json' | 'form' | 'multipart' | 'xml'; // request-body wire format (default json); form = application/x-www-form-urlencoded; xml = raw string template
+  arrayPaths?: string[]; // xml only: dot jpaths (incl. root element) that are ALWAYS arrays — XML can't tell one item from a list of one
   files?: Record<string, FileFieldSpec | FileFieldSpec[]>; // multipart/form-data file fields — array = multiple files under one field name; presence forces multipart
   bodyFile?: FileFieldSpec; // raw-binary body: the request body IS the file's bytes (Content-Type = mimeType, default application/octet-stream)
   headers?: Record<string, string>; // per-endpoint header templates; `:param` tokens bind at runtime (flow auth, e.g. authorization: "Bearer :token")
@@ -84,7 +85,13 @@ function refsIn(text: string): string[] {
 /** All `:param` refs an entry binds — path + JSON body + header templates + file specs. */
 function entryRefs(entry: ApiEntry): string[] {
   const fromPath = refsIn(entry.path);
-  const fromBody = entry.body != null ? refsIn(JSON.stringify(entry.body)) : [];
+  // An XML body is a raw string full of `:`-prefixed tokens that are NOT params
+  // (namespace prefixes like soapenv:Envelope) — a generic scan would force those
+  // into params:. XML params are DECLARED, so the body contributes only declared
+  // names it actually uses (word-boundary match, so :id never claims :id_2).
+  const fromBody = entry.encoding === 'xml' && typeof entry.body === 'string'
+    ? entry.params.filter((p) => new RegExp(`:${p}(?![A-Za-z0-9_])`).test(entry.body as string))
+    : entry.body != null ? refsIn(JSON.stringify(entry.body)) : [];
   const fromHeaders = entry.headers ? refsIn(JSON.stringify(entry.headers)) : [];
   const fromFiles = entry.files ? refsIn(JSON.stringify(entry.files)) : [];
   const fromBodyFile = entry.bodyFile ? refsIn(JSON.stringify(entry.bodyFile)) : [];
@@ -103,7 +110,8 @@ function parseEntries(file: string, scope: 'screen' | 'shared'): Map<string, Api
       method: String(v.method).toUpperCase() as HttpMethod,
       path: v.path,
       body: v.body,
-      encoding: v.encoding === 'form' || v.encoding === 'multipart' ? v.encoding : undefined, // default (undefined) = json
+      encoding: v.encoding === 'form' || v.encoding === 'multipart' || v.encoding === 'xml' ? v.encoding : undefined, // default (undefined) = json
+      arrayPaths: Array.isArray(v.arrayPaths) ? v.arrayPaths.map((p: any) => String(p)) : undefined,
       files: parseFiles(v.files),
       bodyFile: parseFileSpec(v.bodyFile),
       headers: v.headers && typeof v.headers === 'object' ? Object.fromEntries(Object.entries(v.headers).map(([k, hv]) => [k, String(hv)])) : undefined,
@@ -164,7 +172,23 @@ export function apiParamNames(entry: ApiEntry): string[] {
 export function validateApiEntry(entry: ApiEntry, datasourceNames: string[] | null): string[] {
   const errs: string[] = [];
   if (!METHODS.has(entry.method)) errs.push(`api "${entry.name}": method "${entry.method}" is not a valid HTTP method.`);
-  if (!entry.path.startsWith('/')) errs.push(`api "${entry.name}": path "${entry.path}" must start with "/".`);
+  // Param names feed RegExp construction (runtime whitelist bind, exporter cells) —
+  // a name like "a(b" would THROW out of the binder instead of reporting, and a "."
+  // would silently match any character. Identifier-only, checked before any regex use.
+  for (const p of entry.params) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(p)) {
+      errs.push(`api "${entry.name}": param "${p}" is not a valid name — use letters, digits and underscores, starting with a letter or underscore.`);
+    }
+  }
+  if (entry.params.some((p) => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(p))) {
+    return errs; // don't feed the invalid names into the regex-based checks below
+  }
+  // Three valid path forms: a base_url-relative path, a single ":param" token (an
+  // absolute URL bound at runtime from a prior response), or a literal http(s) URL.
+  const pathOk = entry.path.startsWith('/')
+    || /^:[A-Za-z_][A-Za-z0-9_]*$/.test(entry.path)
+    || /^https?:\/\//i.test(entry.path);
+  if (!pathOk) errs.push(`api "${entry.name}": path "${entry.path}" must start with "/", be a single ":param" token, or be an absolute http(s) URL.`);
   const refs = new Set(entryRefs(entry));
   const declared = new Set(entry.params);
   for (const r of refs) if (!declared.has(r)) errs.push(`api "${entry.name}": uses :${r} but it is not in params:.`);
@@ -176,6 +200,14 @@ export function validateApiEntry(entry: ApiEntry, datasourceNames: string[] | nu
     // files are always sent as multipart; an explicit json/form encoding contradicts that.
     if (entry.encoding && entry.encoding !== 'multipart') errs.push(`api "${entry.name}": has files: but encoding: ${entry.encoding} — a file upload must be multipart (omit encoding).`);
   }
+  // XML entries: the body is a raw string template (any shape); arrayPaths belongs to
+  // the XML response mapping only.
+  if (entry.encoding === 'xml' && entry.body !== undefined && typeof entry.body !== 'string') {
+    errs.push(`api "${entry.name}": encoding: xml requires body: to be a string template (use a YAML block scalar holding the raw XML).`);
+  }
+  if (entry.arrayPaths?.length && entry.encoding !== 'xml') {
+    errs.push(`api "${entry.name}": arrayPaths: applies only to encoding: xml responses.`);
+  }
   // A GET/HEAD request may not carry a body — fetch/undici refuses one, so the runtime would have to
   // drop it. Catch the contradiction HERE, in the catalog the author wrote, rather than let a request
   // go out silently shorter than the entry says it is.
@@ -205,6 +237,19 @@ export function lintApiCatalog(screenName: string, datasourceNames: string[] | n
   const entries = [...screen.values(), ...shared.values()];
   for (const e of entries) errors.push(...validateApiEntry(e, datasourceNames));
   for (const name of screen.keys()) if (shared.has(name)) errors.push(`api "${name}": defined in both screen and shared catalogs — names must be unambiguous.`);
+  // XML runtime needs fast-xml-parser IN THE PROJECT (the generated specs/api.ts
+  // lazy-requires it). Projects initialized before the capability existed don't have
+  // it, and generate overwrites specs/api.ts — warn HERE so the author installs the
+  // dep before the suite dies mid-run on the first XML response.
+  if (entries.some((e) => e.encoding === 'xml')) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+      const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+      if (!deps['fast-xml-parser']) {
+        console.warn('⚠ apis.yaml declares encoding: xml but "fast-xml-parser" is not in this project\'s package.json — run: npm install --save-dev fast-xml-parser');
+      }
+    } catch { /* no readable package.json — project init installs the dep */ }
+  }
   return { files, errors, entries };
 }
 

package/src/index.ts

@@ -32,6 +32,33 @@ import { apiRepair } from './api-repair';
  * `testData.raw()` (native type, still interpolates embedded refs) rather than `get()`
  * (Gherkin-text stringify) — a numeric override otherwise reaches the JSON body as a string.
  */
+/**
+ * `{{var}}` EMBEDDED in a quoted override value — a quoted value can mix static
+ * text with refs (`user_email="pre-{{id}}-x"`); shipping the braces verbatim
+ * would POST literal `{{...}}` text in a live request body. `{{$...}}` dynamic
+ * tokens have no test-data key and stay literal. Twin of the core helper —
+ * this driver deliberately has no runtime dependency on @sun-asterisk/sungen.
+ */
+const RE_EMBEDDED_VAR = /\{\{\s*([\w.[\]*-]+?)\s*\}\}/g;
+
+/** Escape static literal text for a template-literal context. */
+const escapeForTemplate = (s: string): string =>
+  s.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
+
+/** Render a quoted override value's BODY as a JS expression (string intent → get()). */
+function literalExpr(text: string): string {
+  const vars = [...text.matchAll(RE_EMBEDDED_VAR)];
+  if (vars.length === 0) return JSON.stringify(text);
+  if (vars.length === 1 && vars[0][0] === text) return `testData.get(${JSON.stringify(vars[0][1])})`;
+  let out = '';
+  let last = 0;
+  for (const m of vars) {
+    out += escapeForTemplate(text.slice(last, m.index!)) + `\${testData.get(${JSON.stringify(m[1])})}`;
+    last = m.index! + m[0].length;
+  }
+  return `\`${out + escapeForTemplate(text.slice(last))}\``;
+}
+
 function parseQueryOverrides(raw?: string): Record<string, string> {
   const out: Record<string, string> = {};
   if (!raw) return out;
@@ -44,7 +71,7 @@ function parseQueryOverrides(raw?: string): Record<string, string> {
     const v = val.match(/^\{\{\s*([^}]+?)\s*\}\}$/);
     const q = val.match(/^["'](.*)["']$/);
     if (v) out[key] = `testData.raw(${JSON.stringify(v[1])})`;
-    else if (q) out[key] = JSON.stringify(q[1]);
+    else if (q) out[key] = literalExpr(q[1]);
     else if (/^-?\d+(?:\.\d+)?$/.test(val)) out[key] = val;
     else out[key] = JSON.stringify(val);
   }
@@ -98,6 +125,9 @@ function apiPreconditionCodegen(input: { tags: string[]; screenName: string; cwd
     const hdr = entry.headers && Object.keys(entry.headers).length ? `, headers: ${JSON.stringify(entry.headers)}` : '';
     // request-body wire format (default json); `form` → x-www-form-urlencoded, `multipart` → form-data (#345).
     const enc = entry.encoding ? `, encoding: ${JSON.stringify(entry.encoding)}` : '';
+    // xml response mapping: catalog-declared paths that are ALWAYS arrays (XML can't
+    // tell one repeated element from a list of one — `[0]` access must not break).
+    const arrayPaths = entry.arrayPaths?.length ? `, arrayPaths: ${JSON.stringify(entry.arrayPaths)}` : '';
     // multipart file fields; the runtime reads each fixture and builds a Playwright file payload. Its
     // `:param` paths bind at runtime from the same params. Presence forces multipart in the runtime.
     // A field's value may be an array → multiple files under one field name (JSON.stringify carries it).
@@ -106,7 +136,7 @@ function apiPreconditionCodegen(input: { tags: string[]; screenName: string; cwd
     const bodyFile = entry.bodyFile ? `, bodyFile: ${JSON.stringify(entry.bodyFile)}` : '';
     // per-endpoint timeout override (else the datasource timeout applies at runtime).
     const timeout = entry.timeout_ms ? `, timeout: ${JSON.stringify(entry.timeout_ms)}` : '';
-    const req = `{ method: ${JSON.stringify(entry.method)}, path: ${JSON.stringify(entry.path)}${entry.body !== undefined ? `, body: ${JSON.stringify(entry.body)}` : ''}${enc}${files}${bodyFile}${hdr}${timeout}, datasource: ${ds} }`;
+    const req = `{ method: ${JSON.stringify(entry.method)}, path: ${JSON.stringify(entry.path)}${entry.body !== undefined ? `, body: ${JSON.stringify(entry.body)}` : ''}${enc}${arrayPaths}${files}${bodyFile}${hdr}${timeout}, datasource: ${ds} }`;
     // @concurrent:N → callN (N parallel calls, aggregate result); else a single call. @hybrid adds
     // the storageState opts so the request reuses the UI auth session.
     const callExpr = concurrent