Ffcpe Custom Node Sdk

FFCPE custom actions on App Builder (@adobe/ffcpe-custom-node-core, @adobe/ffcpe-custom-node-app-builder)

Audience

Use this skill when assisting consumers of the NPM packages: teams shipping an App Builder application that Workflow Builder invokes as a `custom-action` (async submit + status polling).

For contributing to the SDK source repository (monorepo, Turbo, releases), see `README.md` (“Monorepo (contributors)”) and `CONTRIBUTING.md` next to the SDK sources (internal mirror or published repo checkout).

For scaffolding web/worker files, webpack, and `ext.config.yaml`, use `ffcpe-app-builder-actions`.

For `catalog-entry.json` authoring and `aio ffcpe catalog` (validate, register, list, update), install skills from [adobe/aio-cli-plugin-ffcpe](https://github.com/adobe/aio-cli-plugin-ffcpe): `ffcpe-catalog-entry-json` and `aio-ffcpe-cli`.

npx skills add adobe/aio-cli-plugin-ffcpe --all -y

End-to-end checklist

0. Bootstrap Console project (new projects only) — create project + workspace via aio console, run aio app init --standalone-app, download workspace config, wire with aio app use <config>.json --overwrite --no-input. Clean up web-src/, scaffolded generic actions, and web: web-src from app.config.yaml. Replace webpack-config.js with the esbuild-loader + commonjs2 shape. Console project names: alphanumeric only, ≤20 chars (no hyphens); may differ from the OpenWhisk package name in YAML. See `ffcpe-app-builder-actions` → "Starting from scratch with init-bare" for the exact sequence. 1. Install SDK packages (npm or pnpm) and implement web + worker actions. Best practice: co-locate the catalog entry as `<action-name>.entry.json` next to *`<action-name>.web.** and **<action-name>.worker.` (see `ffcpe-app-builder-actions`). 2. Deploy the App Builder app; copy web action base URLs from deploy output; set catalog `submitEndpoint` / `statusEndpoint` to `{base}/submit` and `{base}/status`. 3. Author `<action-name>.entry.json` — ports must match worker input/output names; endpoints from deploy; `authentication: { "type": "ims_service_token" }` when using default `mountFfcpeNodeRoutes` auth (not `none` unless `authenticate: null` on routes). 4. Validate and register* with the CLI — never raw curl:

    aio ffcpe catalog validate --file ./actions/my-action/my-action.entry.json
    aio ffcpe catalog register --file ./actions/my-action/my-action.entry.json

Install packages

with npm:

npm install @adobe/ffcpe-custom-node-core @adobe/ffcpe-custom-node-app-builder

or pnpm — set `auto-install-peers=true` in the app’s `.npmrc`, then:

pnpm add @adobe/ffcpe-custom-node-core @adobe/ffcpe-custom-node-app-builder

Explicit peers — if you prefer every peer in `package.json`, or your tool does not auto-install peers (e.g. Yarn Classic):

npm install @adobe/ffcpe-custom-node-core @adobe/ffcpe-custom-node-app-builder hono hono-openwhisk-adapter

pnpm add @adobe/ffcpe-custom-node-core @adobe/ffcpe-custom-node-app-builder hono hono-openwhisk-adapter

Typical peers (confirm versions against your template and Adobe docs):

• @adobe/aio-lib-core-logging, @adobe/aio-lib-state, @adobe/aio-lib-ims, openwhisk, hono, hono-openwhisk-adapter

Link a local SDK checkout

Use this when the consumer app should load `@adobe/ffcpe-custom-node-core` / `@adobe/ffcpe-custom-node-app-builder` from a nearby clone of the SDK monorepo instead of the registry.

1. In the SDK monorepo, install and build `dist/` for both packages:

    pnpm install && pnpm run build
    # or: npm install && npm run build

For tight iteration, run `pnpm run dev` (or `npm run dev`) from the SDK root so `dist/` rebuilds on change.

2. In the consumer App Builder project, link core first, then app-builder:

pnpm:

    pnpm link /path/to/ffcpe-custom-node-sdk/packages/core
    pnpm link /path/to/ffcpe-custom-node-sdk/packages/app-builder

npm:

    npm link /path/to/ffcpe-custom-node-sdk/packages/core
    npm link /path/to/ffcpe-custom-node-sdk/packages/app-builder

3. To restore registry packages:

    pnpm unlink @adobe/ffcpe-custom-node-core @adobe/ffcpe-custom-node-app-builder && pnpm install
    # or: npm unlink @adobe/ffcpe-custom-node-core @adobe/ffcpe-custom-node-app-builder && npm install

Optional global link (pnpm): register each package with `pnpm link --global` from `packages/core` and `packages/app-builder`, then in the consumer `pnpm link --global @adobe/ffcpe-custom-node-core` and `pnpm link --global @adobe/ffcpe-custom-node-app-builder`. If *`workspace:** fails to resolve for app-builder, keep using directory links or add a consumer **pnpm.overrides** pinning **@adobe/ffcpe-custom-node-core** to the **packages/core`** path.

Full wording lives in the SDK `README.md` (“Use a local SDK checkout”).

Install agent skills

Skills live in the SDK repo under `skills/` and install via the open agent skills CLI. One canonical copy is symlinked into each agent (Claude Code, Cursor, etc.) so guidance stays identical.

From GitHub (consumer repo)

# List available skills
npx skills add adobe/ffcpe-custom-node-sdk --list

# Install all FFCPE skills (project-local)
npx skills add adobe/ffcpe-custom-node-sdk --all -y

# Install only this skill
npx skills add adobe/ffcpe-custom-node-sdk --skill ffcpe-custom-node-sdk -y

# Claude Code + Cursor
npx skills add adobe/ffcpe-custom-node-sdk --all -a claude-code -a cursor -y

# Global (all projects on this machine)
npx skills add adobe/ffcpe-custom-node-sdk --all -g -y

From a local SDK checkout

npx skills add /path/to/ffcpe-custom-node-sdk/skills --all -y

See `skills/README.md` in this repo for update/remove commands and skill layout.

CLI plugin skills (separate repo):

npx skills add adobe/aio-cli-plugin-ffcpe --all -y

Reference skills by `name` in each `SKILL.md` frontmatter: `ffcpe-custom-node-sdk`, `ffcpe-app-builder-actions`, `aio-ffcpe-cli`, `ffcpe-catalog-entry-json`.

Catalog CLI (@adobe/aio-cli-plugin-ffcpe)

Install the Adobe I/O CLI plugin for catalog operations after deploy:

npm install -g @adobe/aio-cli
aio plugins:install @adobe/aio-cli-plugin-ffcpe
aio login
aio console org select

Use `--strict` on register/update to fail on validation warnings. Override API host with `AIO_FFCPE_CATALOG_BASE_URL` or `--base-url`. Prefer `aio ffcpe catalog` over hand-written HTTP — auth uses the same IMS session as `aio login`.

Align `customActionConfig.submitEndpoint` / `statusEndpoint` in catalog JSON with your deployed web action URLs and route paths from `mountFfcpeNodeRoutes`. Port `name` values in catalog `inputs` / `outputs` must match what the worker reads via `getTextInput`, `getImageInput`, etc.

Two OpenWhisk actions (recommended shape)

1. Web action — HTTP entry for FFCPE: `POST /submit`, `GET /status`. Build a Hono app, call `mountFfcpeNodeRoutes`, export `main` with `ToOpenWhiskAction` from hono-openwhisk-adapter. 2. Worker action — Long-running job: export `main` from `createFfcpeNodeWorker(handler, options)`.

Use `ext.config.yaml` (or equivalent) so the web action uses `web: "raw"` and `annotations.require-adobe-auth: false` (see `README.md` manifest example). Match `worker` / `web` package and action names to what `mountFfcpeNodeRoutes` receives.

Web route wiring (mountFfcpeNodeRoutes)

• Pass `worker: { package, name }` — target for async OpenWhisk invoke after submit.
• Pass `web: { package, name }` — required; used to build `statusUrl` returned to Workflow Builder. Omitting or empty strings throws at mount time.
• Optional `routes` — defaults `/submit` and `/status`; align with catalog `submitEndpoint` / `statusEndpoint` paths.
• Optional `authenticate` — defaults to IMS bearer + x-api-key via `createImsInboundAuth`. Pass `null` to disable auth on those routes (only if product/security allows).
• Optional `jobStore`, `loggerName`, `jobMetadata(submit)` — advanced; default store is aio-lib-state-backed.

Worker handler (createFfcpeNodeWorker)

• Implement `FfcpeNodeWorkerHandler`: async `({ jobId, inputs, params, logger, authContext, args })` — `inputs` is the validated FFCPE `input[]`; `params` is workflow parameters from run-workflow (submit `parameters`); `args` is the full worker invocation object (OpenWhisk `main(args)`).
• Return `{ status: "completed", outputs?: ActionOutput[] }` or `{ status: "failed", error: string }`.
• Use `requiredInputNames` in options to fail fast when submit payloads omit named inputs.
• Throw `FfcpeJobFailedError` only when intentionally mapping failures to the SDK’s failed-job behavior (the adapter already maps handler `failed` results).

Prefer `findInputByName`, `getTextInput`, etc., from `@adobe/ffcpe-custom-node-core`, and narrow with `TextInput`, `ImageInput`, `VideoInput`, `JsonInput`. Build outputs with `createTextOutput`, `createImageOutput`, `createVideoOutput`, `createJsonOutput` (and related helpers).

HTTP contract (what Workflow Builder expects)

Workflow Builder POSTs `{ inputs, parameters }` to `submitEndpoint` and polls status until `completed` or `failed`. Submit responses should include `jobId`, `status`, and ideally `statusUrl` for polling.

For header rules, response fields, and polling semantics, read `docs/custom-action-requests.md` from the SDK documentation bundle or source tree (same material ships beside the repo README for maintainers).

Security and robustness (custom-action authors)

• Treat `inputs` and `parameters` as untrusted; validate types, sizes, and URLs before fetching or processing assets.
• Never log tokens, API keys, or raw Authorization headers; keep `Logger` output minimal.
• Use HTTPS asset URLs where possible; fail closed on suspicious schemes or redirects if implementing custom fetch logic outside the SDK.
• Keep auth enabled on submit/status unless there is an explicit, reviewed reason to pass `authenticate: null`.

Advanced / escape hatches

• Core-only HTTP — `handleFfcpeSubmit`, `handleFfcpeStatus`, or `runWorkerJob` when not using Hono (still need `JobStore`, `JobOrchestrator`, `InboundAuth`, status URL builder).
• Custom orchestration or storage — implement core ports (`JobStore`, `JobOrchestrator`) and mirror the checklist in the upstream README section “Implementing for a different Cloud Functions Provider” (same ideas apply when forking adapter behavior).

Quick lookup

For import cheat sheets, `pnpm link`, and troubleshooting (status URL, web manifest), see references/quick-reference.md.

Quick reference — App Builder custom-action apps

Bootstrap (new project from scratch)

Console CLI flag gotchas

Commands have inconsistent flag shapes — mismatches throw NonExistentFlagsError:

Deployed endpoint URLs (catalog)

After `aio app deploy`, web actions print a base URL like:

https://3326322-myproject-stage.adobeioruntime.net/api/v1/web/my-package/my-action-web

Set catalog endpoints to:

• `submitEndpoint`: {base}/submit
• `statusEndpoint`: {base}/status

Notes:

• Path is `/api/v1/web/` (not /apis/v1/).
• Hostname namespace is lowercase (demoqrffcpe-stage), independent of Console project casing (demoQrFfcpe).
• Console project name (alphanumeric, ≤20) can differ from `runtimeManifest` package name (hyphens allowed).

---

Packages

Local SDK (pnpm / npm link)

If global `pnpm link --global` breaks on *`workspace:**, use directory **pnpm link** / **npm link** or **pnpm.overrides** for **@adobe/ffcpe-custom-node-core** → **packages/core** path. Details: SDK **README.md`**.

Custom action file layout (recommended)

Co-locate each action’s web, worker, and catalog entry with the same `<action-name>` prefix:

actions/<action-name>/
  <action-name>.web.ts
  <action-name>.worker.ts
  <action-name>.entry.json    ← run-workflow catalog entry (aio ffcpe catalog validate/register)

Example: `actions/resize-image/resize-image.entry.json` beside `resize-image.web.ts` and `resize-image.worker.ts`. See `ffcpe-app-builder-actions` and `ffcpe-catalog-entry-json`.

Catalog CLI (@adobe/aio-cli-plugin-ffcpe)

Agent skills: `aio-ffcpe-cli`, `ffcpe-catalog-entry-json` — install with `npx skills add adobe/aio-cli-plugin-ffcpe --all -y`. Plugin repo: github.com/adobe/aio-cli-plugin-ffcpe.

Imports (typical)

From `@adobe/ffcpe-custom-node-core`

• Handler types: FfcpeNodeWorkerHandler, FfcpeNodeWorkerResult, FfcpeInput, TextInput, …
• Input helpers: findInputByName, getTextInput, getImageInput, …
• Outputs: createTextOutput, createImageOutput, createVideoOutput, createJsonOutput, …
• Errors: FfcpeJobFailedError

From `@adobe/ffcpe-custom-node-app-builder`

• mountFfcpeNodeRoutes, createFfcpeNodeWorker, buildStatusUrl, createAioLogger (as needed)

From `hono` / `hono-openwhisk-adapter`

• Hono, ToOpenWhiskAction (web action export pattern)

mountFfcpeNodeRoutes(app, options) (summary)

createFfcpeNodeWorker(handler, options?) (summary)

Web action manifest (runtimeManifest)

Ensure the web action uses `web: "raw"` and `require-adobe-auth: false`:

my-web-action:
    function: actions/my-web-action.ts
    web: "raw"
    runtime: nodejs:22
    annotations:
        require-adobe-auth: false

Misconfiguration often surfaces as wrong request/response mapping or broken status URLs.

Troubleshooting

Contract details

Full submit/status schema and polling behavior: `docs/custom-action-requests.md` in the SDK repo (or published doc mirror).