@frontera-sdk/functions 1.51.0 → 1.51.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/functions",
-  "version": "1.51.0",
+  "version": "1.51.1",
   "description": "Author Frontera functions: manifest, triggers and the typed handler contract.",
   "keywords": [
     "frontera",
@@ -42,7 +42,7 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@frontera-sdk/blueprint": "1.51.0",
+    "@frontera-sdk/blueprint": "1.51.1",
     "cron-parser": "^5.0.6"
   }
 }

package/src/index.ts

@@ -12,8 +12,12 @@ export {
 export { createTestContext } from './testing'
 export type { TestCall, TestContext, TestContextOptions } from './testing'
 export {
+  DEFAULT_MAX_FILES,
+  MAX_FILES_CAP,
   MAX_INPUT_BYTES,
   checkInputFieldSpec,
+  isFileInputType,
+  maxFilesOf,
   redactedInputKeys,
   sanitizeInputsSchema,
   validateInputValue,

package/src/inputs.ts

@@ -27,20 +27,39 @@ export type InputValidation =
  * naming a non-empty string `fileId`). It deliberately does NOT authorize the id
  * or check mime/size — those need the DB and the caller's workspace scope, so the
  * SERVER (`run-service` via `resolveFile`) authorizes and resolves the reference
- * after this passes.
+ * after this passes. `files` is a list of the same reference; its count is
+ * checked in `validateInputValue`, which knows the field's `maxFiles`.
  */
+const isFileRef = (v: unknown): boolean =>
+  typeof v === 'object' &&
+  v !== null &&
+  !Array.isArray(v) &&
+  typeof (v as { fileId?: unknown }).fileId === 'string' &&
+  (v as { fileId: string }).fileId.length > 0
+
 export const TYPE_CHECK: Record<InputFieldSpec['type'], (v: unknown) => boolean> = {
   string: (v) => typeof v === 'string',
   number: (v) => typeof v === 'number' && Number.isFinite(v),
   boolean: (v) => typeof v === 'boolean',
   object: (v) => typeof v === 'object' && v !== null && !Array.isArray(v),
   array: Array.isArray,
-  file: (v) =>
-    typeof v === 'object' &&
-    v !== null &&
-    !Array.isArray(v) &&
-    typeof (v as { fileId?: unknown }).fileId === 'string' &&
-    (v as { fileId: string }).fileId.length > 0,
+  file: isFileRef,
+  files: (v) => Array.isArray(v) && v.every(isFileRef),
+}
+
+/** The most files a `files` input holds when its spec names no `maxFiles`. */
+export const DEFAULT_MAX_FILES = 20
+/** The highest `maxFiles` a `files` input may declare. */
+export const MAX_FILES_CAP = 50
+
+/** Whether an input of this type holds file references: one, or a list. */
+export function isFileInputType(type: unknown): type is 'file' | 'files' {
+  return type === 'file' || type === 'files'
+}
+
+/** The most files a `files` input holds. */
+export function maxFilesOf(spec: Pick<InputFieldSpec, 'maxFiles'>): number {
+  return spec.maxFiles ?? DEFAULT_MAX_FILES
 }
 
 /** Lowercase kebab, matching `validateManifest`'s automation-`name` grammar. */
@@ -48,7 +67,7 @@ const INPUT_NAME_KEBAB_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/
 /** Lowercase snake — the one allowance kebab doesn't cover. */
 const INPUT_NAME_SNAKE_RE = /^[a-z][a-z0-9_]*$/
 
-const INPUT_TYPES = new Set<InputFieldSpec['type']>(['string', 'number', 'boolean', 'object', 'array', 'file'])
+const INPUT_TYPES = new Set<InputFieldSpec['type']>(['string', 'number', 'boolean', 'object', 'array', 'file', 'files'])
 
 /** Keys `checkInputFieldSpec` understands on ONE input spec (`inputs.<name>`).
  *  Anything else there is a warning, same philosophy as `manifest.ts`'s
@@ -63,6 +82,7 @@ const INPUT_SPEC_KEYS = new Set([
   'redact',
   'accept',
   'maxBytes',
+  'maxFiles',
 ])
 
 /**
@@ -129,6 +149,7 @@ export function checkInputFieldSpec(key: string, raw: unknown): InputFieldCheck
     redact?: unknown
     accept?: unknown
     maxBytes?: unknown
+    maxFiles?: unknown
   }
 
   if (spec.description !== undefined && typeof spec.description !== 'string') {
@@ -136,7 +157,7 @@ export function checkInputFieldSpec(key: string, raw: unknown): InputFieldCheck
   }
 
   if (typeof spec.type !== 'string' || !INPUT_TYPES.has(spec.type as InputFieldSpec['type'])) {
-    errors.push(`input "${key}": type must be one of string, number, boolean, object, array, file`)
+    errors.push(`input "${key}": type must be one of string, number, boolean, object, array, file, files`)
     return { errors, warnings }
   }
   const t = spec.type as InputFieldSpec['type']
@@ -196,12 +217,12 @@ export function checkInputFieldSpec(key: string, raw: unknown): InputFieldCheck
     }
   }
 
-  // `accept`/`maxBytes` are the file-only constraints — refused on any other
-  // type so a typo like `accept` on a string field is loud, not silently
-  // ignored. They constrain the UPLOAD, not the value on the run row (which is
+  // `accept`/`maxBytes` are the file-only constraints, for one file or a list
+  // of them — refused on any other type so a typo like `accept` on a string
+  // field is loud, not silently ignored. They constrain the UPLOAD, not the value on the run row (which is
   // only a reference), so the server enforces them; here we check well-formedness.
   if (spec.accept !== undefined) {
-    if (t !== 'file') {
+    if (!isFileInputType(t)) {
       errors.push(`input "${key}": accept is only valid for file inputs`)
     } else if (
       !Array.isArray(spec.accept)
@@ -212,18 +233,30 @@ export function checkInputFieldSpec(key: string, raw: unknown): InputFieldCheck
     }
   }
   if (spec.maxBytes !== undefined) {
-    if (t !== 'file') {
+    if (!isFileInputType(t)) {
       errors.push(`input "${key}": maxBytes is only valid for file inputs`)
     } else if (typeof spec.maxBytes !== 'number' || !Number.isFinite(spec.maxBytes) || spec.maxBytes <= 0) {
       errors.push(`input "${key}": maxBytes must be a positive number`)
     }
   }
+  if (spec.maxFiles !== undefined) {
+    if (t !== 'files') {
+      errors.push(`input "${key}": maxFiles is only valid for files inputs`)
+    } else if (
+      typeof spec.maxFiles !== 'number'
+      || !Number.isInteger(spec.maxFiles)
+      || spec.maxFiles < 1
+      || spec.maxFiles > MAX_FILES_CAP
+    ) {
+      errors.push(`input "${key}": maxFiles must be a whole number from 1 to ${MAX_FILES_CAP}`)
+    }
+  }
 
   let defaultOk = true
   if (spec.default !== undefined) {
-    // A `file` carries a reference to an uploaded item, so a fixed literal
-    // default is meaningless — refused rather than type-checked.
-    if (t === 'file') {
+    // A `file` or `files` input carries references to uploaded items, so a
+    // fixed literal default is meaningless — refused rather than type-checked.
+    if (isFileInputType(t)) {
       errors.push(`input "${key}": a file input cannot have a default`)
       defaultOk = false
     } else if (!TYPE_CHECK[t](spec.default)) {
@@ -290,9 +323,23 @@ export function validateInputValue(
       continue
     }
     if (!check(v)) {
-      errors.push(`"${key}" must be of type ${spec.type}`)
+      errors.push(
+        spec.type === 'files' ? `"${key}" must be a list of files` : `"${key}" must be of type ${spec.type}`,
+      )
       continue
     }
+    if (spec.type === 'files') {
+      const count = (v as unknown[]).length
+      // An empty list says "no files", which a required input does not accept.
+      if (count === 0 && spec.required === true) {
+        errors.push(`"${key}" is required — add at least one file`)
+        continue
+      }
+      if (count > maxFilesOf(spec)) {
+        errors.push(`"${key}" holds ${count} files — the most it takes is ${maxFilesOf(spec)}`)
+        continue
+      }
+    }
     if (spec.enum && !spec.enum.includes(v as string | number)) {
       errors.push(`"${key}" must be one of ${spec.enum.join(', ')}`)
       continue

package/src/manifest.ts

@@ -1,5 +1,5 @@
 import { CronExpressionParser } from 'cron-parser'
-import { MAX_INPUT_BYTES, checkInputFieldSpec } from './inputs'
+import { MAX_INPUT_BYTES, checkInputFieldSpec, isFileInputType } from './inputs'
 
 const SEGMENT = '[a-z][a-z0-9]*(?:-[a-z0-9]+)*'
 const NAME_RE = new RegExp(`^${SEGMENT}$`)
@@ -246,10 +246,11 @@ export function validateManifest(input: unknown): ValidationResult {
         for (const [key, raw] of Object.entries(inputs as Record<string, unknown>)) {
           const spec = raw as { type?: unknown; required?: unknown; default?: unknown }
           if (spec?.required === true && spec.default === undefined) {
-            // A `file` input can never carry a default (refused above), so the
-            // "add a default" remedy would send the author straight into the
-            // next validation error — name the two remedies that actually work.
-            const remedy = spec.type === 'file'
+            // A `file` or `files` input can never carry a default (refused
+            // above), so the "add a default" remedy would send the author
+            // straight into the next validation error — name the two remedies
+            // that actually work.
+            const remedy = isFileInputType(spec.type)
               ? 'A file input cannot have a default — make the input optional or the trigger manual.'
               : 'Add a default or make the trigger manual.'
             errors.push(

package/src/runtime-context.ts

@@ -1069,8 +1069,9 @@ export function buildContext(deps: Deps): AutomationContext {
     file: (ref: { fileId: string }) =>
       step('file', `file:${ref.fileId.slice(0, 8)}`, async () => {
         // No grant: this only reads a file the run was GIVEN — the route
-        // refuses any fileId that is not among this run's own inputs. In a dry
-        // dev run it returns null, like every other ctx call.
+        // refuses any fileId that is not among this run's own inputs (a `file`
+        // input, or one item of a `files` input). In a dry dev run it returns
+        // null, like every other ctx call.
         const res = await scoped('/ctx/file-resolve', {
           method: 'POST',
           body: JSON.stringify({ fileId: ref.fileId }),

package/src/types.ts

@@ -78,21 +78,26 @@ export type Grant =
  *  philosophy as the grant grammar: small enough that a wrong shape is
  *  refusable with a sentence, wide enough for real parameters. */
 export interface InputFieldSpec {
-  type: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'file'
+  type: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'file' | 'files'
   /** Refused at run start when absent. Mutually exclusive with `default`. */
   required?: boolean
   /** Applied at run start when the field is absent. Cron runs rely on these.
-   *  Not permitted on a `file` field — a file has no meaningful literal default. */
+   *  Not permitted on a `file` or `files` field — a file has no meaningful literal default. */
   default?: unknown
   description?: string
   /** Allowed values — string and number types only. */
   enum?: readonly (string | number)[]
-  /** `file` type only. Allowed MIME patterns, e.g. `['image/*', 'application/pdf']`.
+  /** `file` and `files` types only. Allowed MIME patterns, e.g. `['image/*', 'application/pdf']`.
+   *  On a `files` field it applies to each file.
    *  A declaration aid: the value on the run row is only a reference, so this is
    *  enforced server-side at upload and at run start, never against the value here. */
   accept?: readonly string[]
-  /** `file` type only. Maximum upload size in bytes, enforced server-side. */
+  /** `file` and `files` types only. Maximum upload size in bytes, enforced server-side.
+   *  On a `files` field it applies to each file. */
   maxBytes?: number
+  /** `files` type only. The most files the field holds: a whole number from 1
+   *  to 50, 20 when absent. */
+  maxFiles?: number
   /**
    * Mask this field's VALUE wherever a person reads the run.
    *
@@ -488,9 +493,10 @@ export interface AutomationContext {
   log(message: string, data?: Record<string, unknown>): Promise<void>
   agent(slug: string): AgentHandle
   /**
-   * Resolve one of THIS run's `file` inputs to a readable form (signed URL +
-   * authoritative mime/size). No grant — it only reads files the run was given;
-   * any other fileId is refused. `null` in a dry dev run.
+   * Resolve one of THIS run's files to a readable form (signed URL +
+   * authoritative mime/size): the value of a `file` input, or one item of a
+   * `files` input. No grant — it only reads files the run was given; any other
+   * fileId is refused. `null` in a dry dev run.
    */
   file(ref: FileRef): Promise<ResolvedFileHandle | null>
   /** One Plugin install, by the name `frontera plugin list` shows. Needs `plugin:<install>:<capability>` per call. */