@commercetools/processors

Output processors for MCP-style tool payloads and similar JSON: declarative field filtering (drop keys) and redaction (mask values, including query strings inside URL-shaped strings), plus transform helpers that turn structured tool results into tabular or JSON text for LLMs.

The library is domain-agnostic: you pass plain objects/arrays/primitives (anything you would normally JSON.parse). Rules use dot paths from the root of the value you pass into filterFields.

Install

npm add @commercetools/processors

or

yarn add @commercetools/processors

You can also use npm or yarn with the same package name.

Runtime: Node ≥ 18.

Package layout (what each area does)

Usage overview

import {
  FieldFilteringHandler,
  type FieldFilteringManagerConfig,
  type FieldFilteringRule,
  type FieldFilteringManager,
  isFieldFilteringManager,
  defaultFilteringRules,
  defaultJsonRedactionText,
  defaultUrlRedactionText,
  transformToolOutput,
  transformPropertyName,
  isValidUrl,
  generateQueryString,
  normaliseUrl,
} from '@commercetools/processors';

Typical flow: clone (or parse fresh JSON) → new FieldFilteringHandler(config).filterFields(data) → optionally transformToolOutput({ data: safe, ... }) before sending to a model, agent or client.

Field filtering and redaction

Why cloning matters

filterFields mutates object graphs in place (delete keys, replace values). If the same object is referenced elsewhere (cache, logger, retry), those views change too. Always structuredClone, JSON.parse(JSON.stringify(x)), or another deep copy before filtering when you need isolation.

How rules are evaluated (mental model)

For each object key, the handler builds a path like parent.child.leaf. Then, for filter or redact separately:

1. Whitelist — if the current path matches a whitelist entry, no filter/redact on that path from the declarative lists (exact / case rules as in tests).
2. paths — full path match; filter removes that property; redact replaces the entire value at that path with jsonRedactionText (the subtree is not traversed further for path-redact in the same way as nested keys—see handler tests for edge cases).
3. properties — compares the last segment of the path (the key name) to each rule.
4. includes — substring match on that last segment (e.g. secret matches clientSecret when case-insensitive).

Arrays: elements are processed with the same currentPath as the parent array (no .0, .1 in the path). Rules keyed on property names or includes still apply inside objects inside arrays; full paths rules that assume items.0.field will not match the stock handler—use properties/includes or a custom FieldFilteringManager.

FieldFilteringManagerConfig (reference)

Every top-level field is optional; supply only what you need.

FieldFilteringRule

FieldFilteringManager and isFieldFilteringManager

Use a custom class that implements filterFields / filterUrlFields when you need logging, remote policy, or different path semantics than FieldFilteringHandler. isFieldFilteringManager(x) returns true when x has both methods (duck typing), so you can accept either plain config or a ready-made manager from configuration:

import {
  FieldFilteringHandler,
  isFieldFilteringManager,
  type FieldFilteringManager,
  type FieldFilteringManagerConfig,
} from '@commercetools/processors';

function getHandler(
  input: FieldFilteringManagerConfig | FieldFilteringManager
): FieldFilteringManager {
  if (isFieldFilteringManager(input)) {
    return input;
  }
  return new FieldFilteringHandler(input);
}

const handler = getHandler({
  properties: [{value: 'x', caseSensitive: true, type: 'filter'}],
});
const out = handler.filterFields({x: 1, y: 2});

// Expected `out`:
// { y: 2 }

Examples: FieldFilteringHandler on JSON

import {
  FieldFilteringHandler,
  type FieldFilteringManagerConfig,
} from '@commercetools/processors';

const config: FieldFilteringManagerConfig = {
  // Full path: redact only this branch's value (here the string becomes "[REDACTED]")
  paths: [
    {value: 'credentials.accessToken', caseSensitive: true, type: 'redact'},
  ],
  // Any key named apiKey (any casing): remove entirely
  properties: [{value: 'apiKey', caseSensitive: false, type: 'filter'}],
  // Any leaf name containing "secret": redact value, keep key
  includes: [{value: 'secret', caseSensitive: false, type: 'redact'}],
};

const toolResult = {
  credentials: {accessToken: 'tok', refresh: 'r'},
  apiKey: 'k',
  clientSecret: 's',
};

const safe = structuredClone(toolResult);
new FieldFilteringHandler(config).filterFields(safe);

// Expected `safe` (JSON-serialized for clarity):
// {"credentials":{"accessToken":"[REDACTED]","refresh":"r"},"clientSecret":"[REDACTED]"}
// - paths: credentials.accessToken value replaced; refresh unchanged
// - properties: apiKey key removed
// - includes: clientSecret value redacted (leaf name contains "secret")

Examples: filterUrlFields (query string)

Rules use the same machinery: filter drops a query pair; redact keeps the name and sets the value to urlRedactionText.

import {FieldFilteringHandler} from '@commercetools/processors';

const redacted = new FieldFilteringHandler({
  properties: [{value: 'sig', caseSensitive: false, type: 'redact'}],
}).filterUrlFields('https://x.example/y?sig=abc123&ok=1');

// Expected `redacted`:
// "https://x.example/y?sig=REDACTED&ok=1"

const stripped = new FieldFilteringHandler({
  properties: [{value: 'token', caseSensitive: false, type: 'filter'}],
}).filterUrlFields('https://api.example.com/callback?token=abc&ok=1');

// Expected `stripped`:
// "https://api.example.com/callback?ok=1"

Examples: transformToolOutput

format defaults to 'tabular'. With a title, the title is uppercased (after transformPropertyName) and used as a heading. Booleans become Yes/No; nested objects get indented lines; empty plain objects yield no properties (with optional title prefix—see below).

Tabular, with title

import {transformToolOutput} from '@commercetools/processors';

const text = transformToolOutput({
  data: {orderId: '123', total: {currency: 'EUR', centAmount: 4200}},
  title: 'Order summary',
  format: 'tabular',
});

// Expected `text` (string; newlines shown as \n here):
// "ORDER SUMMARY\nOrder Id: 123\nTotal:\n\tCurrency: EUR\n\tCent Amount: 4200"

Tabular, no title

const plain = transformToolOutput({
  data: {a: 1},
  format: 'tabular',
});

// Expected `plain`:
// "A: 1"

Tabular, empty object

const empty = transformToolOutput({data: {}, format: 'tabular'});

// Expected `empty`:
// "no properties"

Tabular, boolean

const stock = transformToolOutput({
  data: {inStock: true},
  format: 'tabular',
});

// Expected `stock`:
// "In Stock: Yes"

JSON format

With format: 'json', output is JSON.stringify of the data (or a single-key object whose key is the transformed title when title is set).

const json = transformToolOutput({
  data: {orderId: '123', total: {currency: 'EUR', centAmount: 4200}},
  title: 'Order summary',
  format: 'json',
});

// Expected `json` (parsed shape):
// {"ORDER SUMMARY":{"orderId":"123","total":{"currency":"EUR","centAmount":4200}}}
// Exact string spacing follows JSON.stringify.

Examples: transformPropertyName

Splits camelCase, PascalCase, snake_case, and kebab-case into words and applies light title-style casing (see unit tests for acronym edge cases).

import {transformPropertyName} from '@commercetools/processors';

transformPropertyName('customerId');
// Expected: "Customer Id"

transformPropertyName('order_line_id');
// Expected: "Order Line Id"

transformPropertyName('propertyNameSDK');
// Expected: "Property Name SDK"

Examples: URL helpers

import {
  isValidUrl,
  normaliseUrl,
  generateQueryString,
} from '@commercetools/processors';

isValidUrl('https://example.com/path?q=1');
// Expected: true

isValidUrl('not a url');
// Expected: false

normaliseUrl('https://a.com//b/../c?x=1');
// Example output (string; normalises slashes/host segment style — see tests for full matrix):
// "https://a.com/b/../c?x=1"

generateQueryString({a: 1, b: [2, 3]});
// Expected (qs indices format; leading `?`):
// "?a=1&b[0]=2&b[1]=3"

More cases: processors/test/field-filtering/urlHelpers.test.ts.

Defaults export

import {
  defaultFilteringRules,
  defaultJsonRedactionText,
  defaultUrlRedactionText,
} from '@commercetools/processors';

// `defaultFilteringRules` is a FieldFilteringManagerConfig-shaped object with only the default redaction strings set.
// `defaultJsonRedactionText` === '[REDACTED]'
// `defaultUrlRedactionText` === 'REDACTED'

Build from source (monorepo)

pnpm --filter @commercetools/processors install
pnpm --filter @commercetools/processors run build
pnpm --filter @commercetools/processors run test

Further reading

Behavioural details (whitelist vs paths, URL bracket keys, empty-rule short-circuit, etc.) are covered here and here