@ 商业工具/ 处理器

输出处理器 用于MCP型工具有效载荷和类似JSON:声明式 字段过滤 (按键)和 编辑 (任务值,包括URL形状字符串内的查询字符串),加 转换 将结构化工具结果转化为 表格 或者说 贾森 文本.

图书馆是 域不可识别:您通过普通对象/阵列/原始对象(任何通常情况下) JSON.parse) (中文(简体) ). 规则的使用 点路径 从您输入的值的根入 filterFields。 。 。 .

安装

npm add @commercetools/processors

或者说

yarn add @commercetools/processors

您还可以使用 npm 或者说 yarn 使用相同的软件包名称.

运行时间 : 节点 第18条。 。 。 .

软件包布局( 每个区域做什么)

使用概况

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

典型流量 : 克隆 (或剖析新鲜的JSON) new FieldFilteringHandler(config).filterFields(data) ——可选 transformToolOutput({ data: safe, ... }) 在发送到模型、代理或客户之前.

实地过滤和编辑

克隆为何重要

filterFields 变异 设置对象图表(删除密钥,替换值)。 如果在别处引用同一对象(缓存、记录器、重试),这些视图也会改变。 永远 structuredClone, (中文(简体) ), JSON.parse(JSON.stringify(x)),或另一个 深层复制 在需要隔离时过滤.

如何评价规则(精神模型)

对于每个对象键,处理器会构建一个 路径 喜欢 parent.child.leaf。然后,为 过滤器 或者说 编辑 单独:

1. 白名单 如果当前路径匹配白名单条目, 没有 从声明列表中过滤/删除路径(精确/例规则如测试).
2. paths 完全路径匹配; filter 拆除该财产; redact 替换 路径的全部值 与 jsonRedactionText (子树不会像嵌入式钥匙那样在路径校正上进一步穿行——边缘情况请参见处理器测试).
3. properties 比较 最后一段 每个规则的路径(关键名称).
4. includes 下弦比对 最后一段 (例如:. secret 匹配 clientSecret 当事无因.

矩阵 : 元素与 不变 currentPath 作为母数组( 无) .0, (中文(简体) ), .1 在路径。 规则已按键 属性名称 或者说 includes 仍在对象内应用 内部 阵列; 满 paths 假设的规则 items.0.field 将 没有 匹配库存处理器 - 使用 properties编号 :includes 或习惯 FieldFilteringManager。 。 。 .

FieldFilteringManagerConfig (参考文献)

每个顶级域都是 选项;只提供你需要的东西.

FieldFilteringRule

FieldFilteringManager 财务报告和审定财务报表 isFieldFilteringManager

使用一个 自定义类 执行 filterFields 编号 : filterUrlFields 当您需要日志、远程策略或不同路径语义时 FieldFilteringHandler。 。 。 . isFieldFilteringManager(x) 当 x 具有两种方法(打字),所以可以接受 无论是 简单 配置 或现成 管理器 从配置 :

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 }

实例: FieldFilteringHandler 关于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")

实例: filterUrlFields (叫声字符串)

规则使用相同的机器: 过滤器 丢弃查询对; 编辑 保留名称并设定值为 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"

实例: transformToolOutput

format 默认为 'tabular'与一个 title,标题为大写(在 transformPropertyName)并用作标题. 布尔斯变成 Yes编号 :No; 嵌入对象得到缩进行; 空平方对象生成 no properties (带有可选标题前缀-见下文).

表格, 有标题

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"

表格, 无标题

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

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

表格, 空对象

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

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

图表,布尔

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

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

JSON 格式

与 format: 'json',输出为 JSON.stringify 数据(或单键对象,其键为转换后的标题) title 已设定).

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.

实例: transformPropertyName

分块 骆驼 Case, (中文(简体) ), 帕斯卡案件, (中文(简体) ), 蛇脚( c),以及 弹匣 以字为单位,并应用轻标题式外壳(关于缩写边框的单位测试).

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

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

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

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

示例: URL 帮助者

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"

更多案件: processors/test/field-filtering/urlHelpers.test.ts。 。 。 .

默认导出

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

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

从源建( Monorepo)

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

进一步阅读

行为细节( 白名单 vs 路径, URL 括号密钥, 空规则短路等) 被覆盖 这里 财务报告和审定财务报表 这里