Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -552,14 +552,15 @@ Receive webhooks from platforms and forward them to any connected platform via p
```bash
one relay platforms # List relay-capable platforms + event type counts
one relay event-types <platform> # List supported event types for a platform
one relay metadata <platform> # List the --metadata keys the platform needs on create
one relay create --connection-key <key> --create-webhook --event-filters '["event.type"]'
one relay activate <id> --actions '<json>' # Attach passthrough forwarding actions (agent mode: add --confirm-write for actions that write)
one relay list # List existing relay endpoints
one relay events --platform <p> # Inspect received events
one relay deliveries --endpoint-id <id> # Check delivery status
```

Start with `one relay platforms` to discover which platforms support relay at all, then drill into `event-types <platform>` for the specific events. Run `one guide relay` for the full reference including `--metadata` requirements per platform.
Start with `one relay platforms` to discover which platforms support relay at all, then drill into `event-types <platform>` for the specific events and `metadata <platform>` for the `--metadata` keys it needs. With `--create-webhook`, `relay create` refuses to create anything while a required key is missing. Run `one guide relay` for the full reference.

### `one skills`

Expand Down
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@withone/cli",
"version": "2.16.2",
"version": "2.17.0",
"description": "CLI for managing One",
"type": "module",
"files": [
Expand Down
69 changes: 14 additions & 55 deletions skills/one/references/relay.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,61 +59,17 @@ Always use `--create-webhook` — it registers the webhook URL with the source p

**One relay per source connection.** All relays on a connection share one hosted URL and one signing secret, and a second `--create-webhook` replaces the stored secret. If the connection already has a relay, add your actions to it with `relay update --actions` (pass the full list; it replaces) instead of creating another.

**Many source platforms require extra identifiers via `--metadata`** (ask the user for the values). Every platform not listed (Stripe, Linear, Attio, Google Calendar, ...) needs none. Keys are case-sensitive; a missing one doesn't fail `create`, but the webhook isn't registered and the `warning` names the key.
**Check what `--metadata` the source platform needs first:**

| Platform | Required metadata keys |
|---|---|
| `airtable` | `AIRTABLE_DATABASE_ID` |
| `apify` | `APIFY_ACTOR_ID` or `APIFY_ACTOR_TASK_ID` |
| `asana` | `ASANA_RESOURCE_GID` |
| `autodesk` | `AUTODESK_SYSTEM`, `AUTODESK_SCOPE` (an object) |
| `basin` | `BASIN_FORM_ID` (a number) |
| `bookingmood` | `BOOKINGMOOD_ORGANIZATION_ID` |
| `box` | `BOX_TARGET_ID`, `BOX_TARGET_TYPE` |
| `brevo` | `BREVO_DOMAIN`, only when `BREVO_TYPE` is `inbound` |
| `browse-ai` | `BROWSE_AI_ROBOT_ID` |
| `btcpay-server` | `BTCPAY_SERVER_STORE_ID` |
| `calendly` | `CALENDLY_ORGANIZATION`, plus `CALENDLY_USER` or `CALENDLY_GROUP` for a user or group `CALENDLY_SCOPE` |
| `chargebee` | `CHARGEBEE_WEBHOOK_NAME` |
| `click-up` | `CLICK_UP_TEAM_ID` |
| `clockify` | `CLOCKIFY_WORKSPACE_ID`, `CLOCKIFY_WEBHOOK_NAME`, `CLOCKIFY_TRIGGER_SOURCE_TYPE`, `CLOCKIFY_TRIGGER_SOURCE` (a list) |
| `cloudinary` | `CLOUDINARY_SIGNING_SECRET` |
| `contentful-content-management` | `CONTENTFUL_CONTENT_MANAGEMENT_SPACE_ID` |
| `crowdin` | `CROWDIN_PROJECT_ID` |
| `datadog` | `DATADOG_WEBHOOK_NAME` |
| `doppler-secretops` | `DOPPLER_SECRETOPS_PROJECT`, `DOPPLER_SECRETOPS_CONFIGS` (a list) |
| `fathom` | `FATHOM_TRIGGERED_FOR` |
| `figma` | `FIGMA_CONTEXT`, `FIGMA_CONTEXT_ID` |
| `files-com` | `FILES_COM_PATH` |
| `fillout` | `FILLOUT_FORM_ID` |
| `formbricks` | `FORMBRICKS_ENVIRONMENT_ID` |
| `git-lab` | `GIT_LAB_PROJECT_ID` |
| `github` | `GITHUB_OWNER`, `GITHUB_REPOSITORY` |
| `grist` | `GRIST_DOC_ID`, `GRIST_TABLE_ID` |
| `heyy` | `HEYY_TENANT_ID` |
| `hugging-face` | `HUGGING_FACE_WATCHED` |
| `jira` | `jqlFilter` |
| `launchdarkly` | `LAUNCHDARKLY_RESOURCES` (a list) |
| `loyverse` | `LOYVERSE_MERCHANT_ID` |
| `mailchimp-marketing` | `MAILCHIMP_MARKETING_LIST_ID` |
| `mailersend` | `MAILERSEND_DOMAIN_ID` |
| `monday` | `MONDAY_BOARD_ID` |
| `paradym` | `PARADYM_PROJECT_ID`, `PARADYM_WEBHOOK_NAME` |
| `parseur` | `PARSEUR_MAILBOX_ID`, `PARSEUR_WEBHOOK_NAME` |
| `posthog` | `POSTHOG_PROJECT_ID`, `POSTHOG_WEBHOOK_NAME` |
| `productive` | `PRODUCTIVE_ORGANIZATION_ID` |
| `sanity` | `SANITY_PROJECT_ID`, `SANITY_DATASET` |
| `sentry` | `SENTRY_ORGANIZATION_ID_OR_SLUG`, `SENTRY_PROJECT_ID_OR_SLUG` |
| `storyblok` | `STORYBLOK_SPACE_ID` |
| `tally` | `TALLY_FORM_ID` |
| `toggl-track` | `TOGGL_TRACK_WORKSPACE_ID` |
| `trello` | `TRELLO_MODEL_ID` |
| `typeform` | `TYPEFORM_FORM_ID` |
| `webflow` | `WEBFLOW_SITE_ID` |
| `workable` | `WORKABLE_ACCOUNT_ID`, only for `candidate_*` events |
| `workiom` | `WORKIOM_APP_ID`, `WORKIOM_LIST_ID` |

Some platforms also take optional keys (e.g. `GOOGLE_CALENDAR_CALENDAR_ID`, which defaults to the primary calendar). Example for GitHub:
```bash
one --agent relay metadata <source-platform>
```

It returns `{platform, fields: [{key, label, required, secret, placeholder?}]}`: the keys One lists for registering that platform's webhook (the same list the dashboard's setup form shows). Ask the user for the values and pass them as one JSON object in `--metadata`. Keys are case-sensitive. A `secret` field is a credential: ask the user for it, and never use the placeholder as a value. An empty `fields` list means One lists none; most such platforms need none.

With `--create-webhook`, `relay create` checks the required keys first. If any is missing it returns `"status": "metadata_required"` with the `missing` fields, exits 1 and creates nothing. A key the list doesn't name can still be missing: then the create response's `warning` names it.

Example for GitHub:

```bash
one --agent relay create \
Expand Down Expand Up @@ -274,6 +230,7 @@ The access settings from `one config` (and `.onerc`) apply to relays as well as
```bash
one --agent relay platforms # All relay-capable platforms + event type counts
one --agent relay event-types <platform> # Event types for a specific platform
one --agent relay metadata <platform> # --metadata keys the platform needs on create
```

## Management Commands
Expand Down Expand Up @@ -304,6 +261,8 @@ Agent-mode output:
| `delete` | `{deleted: true, id}` |
| `platforms` | `{platforms: [{platform, eventTypeCount}]}` |
| `event-types` | `{platform, eventTypes: [...]}` |
| `metadata` | `{platform, fields: [{key, label, required, secret, placeholder?}]}` |
| `create` refused | `{status: "metadata_required", error, platform, missing: [...]}`, exit 1 |

To page `list` or `events`, raise `--page` until `showing` is 0. With a connection allowlist, rows are filtered after the server pages them, so a page can hold fewer than `--limit` rows and `total` counts only the rows shown.

Expand All @@ -323,7 +282,7 @@ To page `list` or `events`, raise `--page` until `showing` is 0. With a connecti
- Event filters on both the endpoint and individual actions must match
- Multiple actions can be attached to a single relay endpoint
- Missing template variables resolve to empty strings — verify `{{payload.*}}` paths against the actual payload
- Many platforms require `--metadata` on create (see the table in Step 5); a `warning` in the create response means the webhook was not registered with the source platform
- Many platforms require `--metadata` on create (`relay metadata <platform>` lists the keys); a `warning` in the create response means the webhook was not registered with the source platform
- Every rendered template value is a string
- Don't pass `--webhook-secret` on activate when the endpoint was created with `--create-webhook` unless activate asks for one; a wrong secret makes One reject every webhook on that connection (no events at all)
- Keep one relay per source connection and add actions to it
Expand Down
11 changes: 10 additions & 1 deletion src/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ import {
relayDeliveriesCommand,
relayEventTypesCommand,
relayPlatformsCommand,
relayMetadataCommand,
} from './commands/relay.js';
import { connectCreateCommand, connectTypesCommand } from './commands/connect.js';

Expand Down Expand Up @@ -141,6 +142,7 @@ program
one relay activate <id> Attach forwarding actions (agent mode: --confirm-write for writes)
one relay get|update|delete <id> Inspect, change, or remove an endpoint
one relay event-types <platform> List supported event types
one relay metadata <platform> List the --metadata keys a platform needs on create
one relay events List received webhook events (relay event <id> for one)
one relay deliveries List delivery attempts

Expand Down Expand Up @@ -712,7 +714,7 @@ relay
.option('--description <desc>', 'Description of the relay endpoint')
.option('--event-filters <json>', 'JSON array of event types to filter (e.g. \'["customer.created"]\')')
.option('--tags <json>', 'JSON array of tags')
.option('--metadata <json>', 'JSON object of platform-specific values many platforms need to register the webhook (e.g. GitHub: \'{"GITHUB_OWNER":"org","GITHUB_REPOSITORY":"repo"}\', Airtable: \'{"AIRTABLE_DATABASE_ID":"app..."}\'). `one guide relay` lists every platform\'s keys; a missing one leaves the webhook unregistered and the response carries a warning')
.option('--metadata <json>', 'JSON object of platform-specific values many platforms need to register the webhook (e.g. GitHub: \'{"GITHUB_OWNER":"org","GITHUB_REPOSITORY":"repo"}\'). `one relay metadata <platform>` lists a platform\'s keys. With --create-webhook, a missing required key stops the create before anything is made')
.option('--create-webhook', 'Automatically register the webhook with the source platform')
.action(async (options: { connectionKey: string; description?: string; eventFilters?: string; tags?: string; metadata?: string; createWebhook?: boolean }) => {
await relayCreateCommand(options);
Expand Down Expand Up @@ -809,6 +811,13 @@ relay
await relayPlatformsCommand();
});

relay
.command('metadata <platform>')
.description('List the --metadata keys a platform needs on relay create to register its webhook')
.action(async (platform: string) => {
await relayMetadataCommand(platform);
});


// ── Sync Commands ──

Expand Down
172 changes: 172 additions & 0 deletions src/commands/relay-metadata.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,172 @@
import { describe, it, beforeEach, afterEach } from 'node:test';
import assert from 'node:assert/strict';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import http from 'node:http';
import type { AddressInfo } from 'node:net';
import { relayCreateCommand, relayMetadataCommand } from './relay.js';
import { setHomeTo, snapshotHomeEnv, restoreHomeEnv, type HomeEnvSnapshot } from '../test-support/home.js';

// `relay metadata` reads the setup fields One stores per platform (the list the
// dashboard's Configuration step shows), and `relay create --create-webhook`
// stops before creating anything when a required one is missing. Without the
// check the endpoint is created and the webhook never registers.

const CONNECTORS: Record<string, string> = { github: 'conn_def::GH', stripe: 'conn_def::ST' };
const CONFIGS: Record<string, unknown> = {
'conn_def::GH': {
formData: [
{ name: 'GITHUB_OWNER', type: 'input', label: 'Repository Owner', placeholder: 'acme', options: [], optional: null },
{ name: 'GITHUB_REPOSITORY', type: 'input', label: 'Repository Name', placeholder: 'api', options: [], optional: null },
{ name: 'GITHUB_SIGNING_SECRET', type: 'password', label: 'Signing secret', placeholder: 'a1b2c3-not-for-output', options: [], optional: true },
],
},
};

interface Harness { server: http.Server; port: number; requests: string[]; created: unknown[]; failConfig: boolean }

function startServer(): Promise<Harness> {
const h = { requests: [] as string[], created: [] as unknown[], failConfig: false } as Harness;
h.server = http.createServer((req, res) => {
const url = new URL(req.url ?? '/', 'http://localhost');
let raw = '';
req.on('data', chunk => { raw += chunk; });
req.on('end', () => {
h.requests.push(`${req.method} ${url.pathname}`);
res.setHeader('content-type', 'application/json');
if (url.pathname === '/v1/available-connectors') {
const platform = url.searchParams.get('platform') ?? '';
const id = CONNECTORS[platform];
res.end(JSON.stringify({ rows: id ? [{ id, platform }] : [], total: id ? 1 : 0, pages: 1, page: 1 }));
return;
}
if (url.pathname.startsWith('/v1/webhooks/relay/config/')) {
if (h.failConfig) { res.statusCode = 500; res.end('{"message":"boom"}'); return; }
const config = CONFIGS[decodeURIComponent(url.pathname.slice('/v1/webhooks/relay/config/'.length))];
if (!config) { res.statusCode = 404; res.end('{"message":"Webhook relay config not found"}'); return; }
res.end(JSON.stringify(config));
return;
}
if (url.pathname === '/v1/webhooks/relay' && req.method === 'POST') {
h.created.push(JSON.parse(raw));
res.end(JSON.stringify({ id: 'r1', url: 'https://example.test/in', active: true }));
return;
}
res.statusCode = 404;
res.end('{}');
});
});
return new Promise(resolve => h.server.listen(0, () => {
h.port = (h.server.address() as AddressInfo).port;
resolve(h);
}));
}

class Exit extends Error { constructor(public code?: number) { super(`exit(${code})`); } }

describe('relay --metadata fields', () => {
let tmp: string;
let home: HomeEnvSnapshot;
let agent: string | undefined;
let write: typeof process.stdout.write;
let exit: typeof process.exit;
let lines: string[];
let h: Harness;

beforeEach(async () => {
home = snapshotHomeEnv();
agent = process.env.ONE_AGENT;
tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'one-cli-relay-metadata-'));
setHomeTo(tmp);
process.env.ONE_AGENT = '1';
h = await startServer();
fs.mkdirSync(path.join(tmp, '.one'), { recursive: true });
fs.writeFileSync(path.join(tmp, '.one', 'config.json'),
JSON.stringify({ apiKey: 'sk_test', apiBase: `http://localhost:${h.port}` }));

lines = [];
write = process.stdout.write.bind(process.stdout);
process.stdout.write = ((chunk: any, ...rest: any[]) => {
if (typeof chunk !== 'string') return (write as any)(chunk, ...rest);
if (chunk.trim().startsWith('{')) lines.push(chunk);
return true;
}) as typeof process.stdout.write;
exit = process.exit;
process.exit = ((code?: number) => { throw new Exit(code); }) as typeof process.exit;
});

afterEach(() => {
process.stdout.write = write;
process.exit = exit;
restoreHomeEnv(home);
if (agent === undefined) delete process.env.ONE_AGENT; else process.env.ONE_AGENT = agent;
h.server.close();
fs.rmSync(tmp, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
});

const last = () => JSON.parse(lines[lines.length - 1]);

async function exitCode(fn: () => Promise<void>): Promise<number | undefined> {
try { await fn(); return undefined; } catch (e) { if (e instanceof Exit) return e.code; throw e; }
}

const GITHUB = 'live::github::default::abc123';

it('relay metadata lists the stored fields with which are required', async () => {
await relayMetadataCommand('github');
const out = last();
assert.equal(out.platform, 'github');
assert.deepEqual(out.fields.map((f: any) => [f.key, f.required, f.secret]), [
['GITHUB_OWNER', true, false],
['GITHUB_REPOSITORY', true, false],
['GITHUB_SIGNING_SECRET', false, true],
]);
assert.equal(out.fields[0].placeholder, 'acme');
assert.ok(!JSON.stringify(out).includes('not-for-output'), 'a secret field\'s placeholder is not repeated');
});

it('relay metadata says when One lists no fields for a platform', async () => {
await relayMetadataCommand('stripe');
const out = last();
assert.deepEqual(out.fields, []);
assert.match(out._hint, /lists no --metadata fields/);
});

it('relay create --create-webhook stops before creating when a required key is missing', async () => {
const code = await exitCode(() => relayCreateCommand({
connectionKey: GITHUB, createWebhook: true, metadata: '{"GITHUB_OWNER":"acme","GITHUB_REPOSITORY":" "}',
}));
assert.equal(code, 1);
const out = last();
assert.equal(out.status, 'metadata_required');
assert.deepEqual(out.missing.map((f: any) => f.key), ['GITHUB_REPOSITORY']);
assert.deepEqual(h.created, []);
assert.equal(lines.length, 1, 'prints the refusal once');
});

it('relay create goes through when the required keys are there, optional ones aside', async () => {
await relayCreateCommand({
connectionKey: GITHUB, createWebhook: true, metadata: '{"GITHUB_OWNER":"acme","GITHUB_REPOSITORY":"api"}',
});
assert.equal(h.created.length, 1);
assert.equal(last().id, 'r1');
});

it('relay create without --create-webhook does not look the fields up', async () => {
await relayCreateCommand({ connectionKey: GITHUB });
assert.equal(h.created.length, 1);
assert.ok(!h.requests.some(r => r.includes('/webhooks/relay/config/')));
});

it('relay create goes through for a platform with no stored fields', async () => {
await relayCreateCommand({ connectionKey: 'live::stripe::default::abc123', createWebhook: true });
assert.equal(h.created.length, 1);
});

it('relay create goes through when the field list cannot be read', async () => {
h.failConfig = true;
await relayCreateCommand({ connectionKey: GITHUB, createWebhook: true });
assert.equal(h.created.length, 1);
});
});
Loading
Loading