Flow scripts

Browser scripts that run inside a Descope flow, on the end user's page. Each file in src is bundled to dist/<name>.js and published as @descope/flow-scripts, which the web component loads on demand.

A connector opts into one by naming it in its metadata.json, either as a top-level clientScripts entry (loaded on any screen that references the connector) or under a command's sdkScripts (loaded once at flow start when a flow uses that command). See connectors/README.md for the metadata shape.

Adding a script

Drop a <name>.ts in src - the rollup config discovers it automatically - and add a <name>.spec.ts beside it. The id in the connector metadata must match the file name.

The default export is a factory, called with the connector's initArgs, the flow context, an onTokenReady callback and a logger:

(initArgs, { baseUrl, ref }, onTokenReady, logger) => ScriptModule | void

onTokenReady must be called, otherwise the SDK waits on the script until it times out. Call it with the value the flow should receive, or null when the script produces nothing. A script that has no result to report should call it up front rather than after loading a third-party library, so a slow or blocked vendor CDN cannot delay the first screen.

See src/types.ts for ScriptModule and its optional start / stop / present / refresh hooks.

Logging

Everything a flow script logs reaches the end user's browser console. The SDK applies no level filtering, and browsers hide only console.debug by default. src/types.ts documents which level to pick; the short version:

• debug for anything useful while troubleshooting
• warn for a misconfiguration whoever set up the connector can fix
• error only for a broken state the user would notice anyway
• nothing at all for expected states that need no attention

Never log a token, key, or other credential. Log its length instead when the size matters.

That last one is enforced, not trusted: no-restricted-syntax in the repo's eslint config fails lint when a credential-looking value is passed to logger here or to console in a connector. It matches on the name, so configuration.writeKey and response.token are rejected while token.length, publicWriteKey and siteKey pass. Add the value you actually need rather than disabling the rule.

Working on one

npm test          # jest
npm run lint      # eslint
npm run build     # rollup, emits dist/<name>.js

A released version has to be picked up by the web component, which pins the @descope/flow-scripts version it loads, so a new script only resolves once that pin moves.