@sungen/driver-api 3.2.7 → 3.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sungen/driver-api",
-  "version": "3.2.7",
+  "version": "3.2.8",
   "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.7",
+    "@sun-asterisk/sungen": "3.2.8",
     "commander": "^14.0.2",
     "yaml": "^2.8.2"
   },

package/src/api-catalog.ts

@@ -33,7 +33,7 @@ export interface ApiEntry {
   path: string;
   body?: unknown;
   encoding?: 'json' | 'form' | 'multipart'; // request-body wire format (default json); form = application/x-www-form-urlencoded
-  files?: Record<string, FileFieldSpec>; // multipart/form-data file fields (file as a form part) — presence forces multipart
+  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")
   params: string[];
@@ -170,7 +170,9 @@ export function validateApiEntry(entry: ApiEntry, datasourceNames: string[] | nu
   for (const r of refs) if (!declared.has(r)) errs.push(`api "${entry.name}": uses :${r} but it is not in params:.`);
   for (const d of declared) if (!refs.has(d)) errs.push(`api "${entry.name}": param "${d}" is declared but never used in path/body.`);
   if (entry.files) {
-    for (const [field, spec] of Object.entries(entry.files)) if (!spec.path) errs.push(`api "${entry.name}": file field "${field}" has no path.`);
+    for (const [field, raw] of Object.entries(entry.files)) {
+      for (const spec of Array.isArray(raw) ? raw : [raw]) if (!spec.path) errs.push(`api "${entry.name}": file field "${field}" has no path.`);
+    }
     // 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).`);
   }

package/src/api-file-fields.ts

@@ -31,12 +31,28 @@ export function parseFileSpec(v: any): FileFieldSpec | undefined {
   return undefined;
 }
 
-/** Normalize the `files:` block — each value via parseFileSpec. Undefined when no valid fields. */
-export function parseFiles(raw: any): Record<string, FileFieldSpec> | undefined {
+/**
+ * Normalize one field's value — a single spec, OR an array of specs to send MULTIPLE files under the
+ * SAME field name (e.g. `gift_image: [":a", ":b"]`). A single file stays a single spec (object), so
+ * existing single-file catalogs are byte-unchanged. An array with no valid element → undefined.
+ */
+export function parseFilesValue(v: any): FileFieldSpec | FileFieldSpec[] | undefined {
+  if (Array.isArray(v)) {
+    if (!v.length) return undefined;
+    // Preserve a malformed element as an empty-path spec instead of silently dropping it: a typo'd
+    // entry (e.g. missing `path`) must surface as a validation error ("file field has no path"), not
+    // quietly shrink the upload to fewer files than the author declared.
+    return v.map((el) => parseFileSpec(el) ?? { path: '' });
+  }
+  return parseFileSpec(v);
+}
+
+/** Normalize the `files:` block — each value via parseFilesValue. Undefined when no valid fields. */
+export function parseFiles(raw: any): Record<string, FileFieldSpec | FileFieldSpec[]> | undefined {
   if (!raw || typeof raw !== 'object') return undefined;
-  const out: Record<string, FileFieldSpec> = {};
+  const out: Record<string, FileFieldSpec | FileFieldSpec[]> = {};
   for (const [field, v] of Object.entries(raw as Record<string, any>)) {
-    const spec = parseFileSpec(v);
+    const spec = parseFilesValue(v);
     if (spec) out[field] = spec;
   }
   return Object.keys(out).length ? out : undefined;

package/src/index.ts

@@ -94,6 +94,7 @@ function apiPreconditionCodegen(input: { tags: string[]; screenName: string; cwd
     const enc = entry.encoding ? `, encoding: ${JSON.stringify(entry.encoding)}` : '';
     // 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).
     const files = entry.files && Object.keys(entry.files).length ? `, files: ${JSON.stringify(entry.files)}` : '';
     // raw-binary body upload: the request body IS the fixture's bytes (e.g. application/octet-stream).
     const bodyFile = entry.bodyFile ? `, bodyFile: ${JSON.stringify(entry.bodyFile)}` : '';

package/src/openapi-import.ts

@@ -18,7 +18,7 @@ export interface ImportedApiEntry {
   path: string;
   params?: string[];
   body?: Record<string, string>;
-  files?: Record<string, { path: string; mimeType?: string; filename?: string; name?: string }>; // multipart/form-data binary props → file form fields
+  files?: Record<string, { path: string; mimeType?: string; filename?: string; name?: string } | { path: string; mimeType?: string; filename?: string; name?: string }[]>; // multipart/form-data binary props → file form fields (array = multiple files under one field)
   bodyFile?: { path: string; mimeType?: string; filename?: string; name?: string }; // raw-binary request body (application/octet-stream) → the body IS the file
   encoding?: 'form' | 'multipart'; // set when the requestBody is form/multipart (json omitted = default)
   headers?: Record<string, string>; // per-endpoint header templates (inferred auth, e.g. authorization: "Bearer :token")
@@ -111,7 +111,7 @@ function resolveBodySchema(schema: any, components: Record<string, any>, seen: S
  *  and any `files` (multipart binary props), best-effort from the requestBody content-type (#345).
  *  JSON is the default (encoding omitted). Also returns the picked request schema (for field metadata),
  *  resolving a `$ref`/`allOf` body against the doc's component schemas. */
-function bodyTemplate(op: any, components: Record<string, any> = {}): { body?: Record<string, string>; files?: Record<string, { path: string }>; bodyFile?: { path: string; mimeType?: string }; props: string[]; encoding?: 'form' | 'multipart'; schema?: any } {
+function bodyTemplate(op: any, components: Record<string, any> = {}): { body?: Record<string, string>; files?: Record<string, { path: string } | { path: string }[]>; bodyFile?: { path: string; mimeType?: string }; props: string[]; encoding?: 'form' | 'multipart'; schema?: any } {
   const content = op?.requestBody?.content ?? {};
   // A raw binary body → the request body IS the file's bytes, NOT a multipart part (multipart would
   // be rejected 415). This is `application/octet-stream` (Petstore `uploadImage`) OR a concrete media
@@ -135,12 +135,16 @@ function bodyTemplate(op: any, components: Record<string, any> = {}): { body?: R
   const properties = schema && typeof schema === 'object' && schema.properties && typeof schema.properties === 'object' ? schema.properties : {};
   const propNames = Object.keys(properties);
   if (!propNames.length) return { props: [], encoding: pick.encoding, schema };
-  // multipart: split binary (file) props into `files`, the rest stay text `body`.
+  // multipart: split binary (file) props into `files`, the rest stay text `body`. An array-of-binary
+  // prop (`type: array, items.format: binary`) → an array file value, signalling "multiple files under
+  // one field": the importer seeds one templated entry; the author adds more `:param` paths as needed.
   const body: Record<string, string> = {};
-  const files: Record<string, { path: string }> = {};
+  const files: Record<string, { path: string } | { path: string }[]> = {};
   for (const p of propNames) {
-    if (pick.encoding === 'multipart' && isBinaryProp(properties[p])) files[p] = { path: `:${p}` };
-    else body[p] = `:${p}`;
+    if (pick.encoding === 'multipart' && isBinaryProp(properties[p])) {
+      const prop = properties[p];
+      files[p] = prop?.type === 'array' ? [{ path: `:${p}` }] : { path: `:${p}` };
+    } else body[p] = `:${p}`;
   }
   return {
     ...(Object.keys(body).length ? { body } : {}),