trigger-autocomplete-catalog

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Trigger Autocomplete Catalog

触发器自动补全目录

Use this whenever a provider has webhook/event triggers.

The trigger catalog is owned by

@relayfile/adapter-core

and generated from adapter sources. It does not live in this (cloud) repo's

packages/core

- that's a different package.

To check coverage (is a provider already in the catalog?), import it from the installed package - no checkout needed:
```
import("@relayfile/adapter-core/triggers")
```
exposes
```
KNOWN_TRIGGER_CATALOG
```
and
```
ADAPTERS_WITHOUT_KNOWN_TRIGGERS
```
.
To add events, edit the provider's adapter source. That's the same
```
@relayfile/adapter-<provider>
```
package you already work in when wiring a provider (the relayfile-adapters checkout from the persona's adapter-package steps). Declaring events is one more edit in that package - no separate location to track.

当提供商具备webhook/事件触发器时，请使用此功能。

触发器目录由

@relayfile/adapter-core

维护，并从适配器源生成。它不存放在本（云）仓库的

packages/core

中——那是另一个不同的包。

检查覆盖范围（某个提供商是否已在目录中？）：从已安装的包中导入即可，无需检出代码：
```
import("@relayfile/adapter-core/triggers")
```
会暴露
```
KNOWN_TRIGGER_CATALOG
```
和
```
ADAPTERS_WITHOUT_KNOWN_TRIGGERS
```
。
添加事件：编辑提供商的适配器源。也就是你在对接提供商时使用的同一个
```
@relayfile/adapter-<provider>
```
包（即从角色的适配器包步骤中检出的relayfile-adapters）。只需在该包中再做一处编辑即可声明事件——无需在其他位置跟踪。

Goal

目标

Ensure persona trigger autocomplete and deploy-time lint include the provider via

KNOWN_TRIGGER_CATALOG

确保角色触发器自动补全和部署时的lint能通过

KNOWN_TRIGGER_CATALOG

识别该提供商。

Scope

范围

Only providers that actually emit webhook/event triggers belong in the catalog. Pure storage / polling providers with no event source (e.g. s3, gcs, postgres) legitimately remain in

adapters-without-known-triggers.generated.json

- do not fabricate events for them.

只有实际会发送webhook/事件触发器的提供商才需要加入目录。纯存储/轮询类、无事件源的提供商（如s3、gcs、postgres）合理归属于

adapters-without-known-triggers.generated.json

——请勿为它们虚构事件。

Required outcomes

必要结果

Provider appears in

KNOWN_TRIGGER_CATALOG

(regenerated

catalog.generated.ts

Provider is absent from
```
adapters-without-known-triggers.generated.json
```
for missing trigger metadata.
Event names are verbatim provider event names used at runtime (match the adapter webhook-normalizer's
```
eventType
```
and/or the events the cloud
```
nango-integrations/<provider>-relay
```
syncs subscribe to).

提供商出现在
```
KNOWN_TRIGGER_CATALOG
```
中（即重新生成的
```
catalog.generated.ts
```
）。
提供商不会因缺少触发器元数据而出现在
```
adapters-without-known-triggers.generated.json
```
中。
事件名称必须与运行时使用的提供商事件名称完全一致（匹配适配器webhook-normalizer的
```
eventType
```
和/或云服务
```
nango-integrations/<provider>-relay
```
同步订阅的事件）。

Implementation options (in the adapter package)

实现方案（在适配器包中）

Add
```
supportedEvents(): string[]
```
to the adapter class, or
Add a
```
<provider>.mapping.yaml
```
with a top-level
```
webhooks:
```
block whose keys are the event names (mirror
```
packages/granola/granola.mapping.yaml
```
). The generator only reads the keys.

为适配器类添加
```
supportedEvents(): string[]
```
方法，或者
添加一个
```
<provider>.mapping.yaml
```
文件，其中包含顶级
```
webhooks:
```
块，其键为事件名称（参考
```
packages/granola/granola.mapping.yaml
```
）。生成器只会读取这些键。

Validation (in your relayfile-adapters checkout)

验证（在你的relayfile-adapters检出目录中）

bash

undefined

bash

undefined

Build ALL workspaces first. The generator imports each adapter's

先构建所有工作区。生成器会导入每个适配器的

supportedEvents(); if dependencies/dist are missing, those providers fail to

supportedEvents()；如果依赖/构建产物缺失，这些提供商将无法被导入，

import and are silently dropped from the catalog into the gap list. A core-only

会被自动从目录中移除并加入缺失列表。仅构建core是不够的。

build is NOT enough.

—

npm ci npm run build node --import tsx packages/core/src/cli.ts triggers generate --repo-root . node --import tsx packages/core/src/cli.ts triggers check --repo-root . npm run build --workspace=packages/core node --import tsx --test packages/core/tests/triggers/catalog-generator.test.ts


After the change merges, publish `@relayfile/adapter-core` (the `Publish Package`
workflow, e.g. `package=core`, `version=patch`). Publishing is what makes the
catalog change take effect - the trigger-autocomplete / deploy-time lint tooling
reads it via its `@relayfile/adapter-core` dependency. Cloud's
`packages/core` also depends on `@relayfile/adapter-core` and has tests that
import `KNOWN_TRIGGER_CATALOG`; normally no cloud `package.json` edit is
required because the dependency is a caret range that accepts new patch
releases. Bump Cloud's dependency only when the catalog fix requires a new
minor/major adapter-core version or Cloud needs to pin a specific published
version for CI.


变更合并后，发布`@relayfile/adapter-core`（使用`Publish Package`工作流，例如`package=core`，`version=patch`）。发布操作会让目录变更生效——触发器自动补全/部署时lint工具会通过其`@relayfile/adapter-core`依赖读取该目录。云服务的`packages/core`同样依赖`@relayfile/adapter-core`，并且有导入`KNOWN_TRIGGER_CATALOG`的测试；通常无需修改云服务的`package.json`，因为依赖使用的是接受新补丁版本的 caret 范围。只有当目录修复需要adapter-core的新次版本/主版本，或者云服务需要为CI固定某个特定发布版本时，才需要升级云服务的依赖。

Notes

注意事项

Reference
```
relayfile-adapters#115
```
when closing missing-provider autocomplete gaps.
If a provider intentionally has no event source, document why it remains in the
```
without-known-triggers
```
list.

当填补缺失提供商的自动补全空白时，请引用
```
relayfile-adapters#115
```
。
如果某个提供商故意没有事件源，请记录其留在
```
without-known-triggers
```
列表中的原因。