@faable/faable 4.47.0 → 4.49.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -70,7 +70,8 @@ claude mcp add faable -- npx -y @faable/faable mcp
70
70
  By default it exposes reads plus `deploy_app` (build the latest commit server-side).
71
71
  `faable mcp --writes` adds the reversible writes: create an app from a repository,
72
72
  set environment variables, add a domain, retry or cancel a build, change deploy
73
- settings. Nothing destructive is exposed. Secret values are never returned, and
73
+ settings, rotate a Challenge secret. `delete_app` and `delete_challenge_site`
74
+ are the local server's only deletions. Secret values are never returned, and
74
75
  logs come back marked as data, not instructions.
75
76
 
76
77
  ### Scripting and agents
@@ -0,0 +1,50 @@
1
+ import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
2
+ import { log } from '../../../log.js';
3
+ import { tenant_options } from '../options.js';
4
+ import { json_option, print_json } from '../../../lib/listing.js';
5
+ import { EMAIL_EVENTS, assertRecipients, assertEmailEvents } from './shared.js';
6
+
7
+ const email_subscriptions_create = {
8
+ command: 'create',
9
+ describe: 'Email these addresses on tenant events (e.g. a new user)',
10
+ builder: yargs => json_option(tenant_options(yargs))
11
+ .option('to', {
12
+ type: 'string',
13
+ array: true,
14
+ demandOption: true,
15
+ description: 'Recipient email address — repeatable'
16
+ })
17
+ .option('event', {
18
+ alias: 'e',
19
+ type: 'string',
20
+ array: true,
21
+ demandOption: true,
22
+ description: `Event to email about — repeatable. One of: ${EMAIL_EVENTS.join(', ')}`
23
+ })
24
+ .option('disabled', {
25
+ type: 'boolean',
26
+ default: false,
27
+ description: 'Create it inactive: nothing is sent until enabled'
28
+ })
29
+ .example('$0 auth email-subscriptions create --to ops@example.com -e user.created -e user.updated', 'Get an email (with the form fields) every time a user is created or updated')
30
+ .showHelpOnFail(false),
31
+ handler: withAuthHints(async (args) => {
32
+ assertRecipients(args.to);
33
+ assertEmailEvents(args.event);
34
+ const api = await requireAuthAdmin(args);
35
+ const created = (await api.notificationsubscriptionCreate({
36
+ channel: 'email',
37
+ events: args.event,
38
+ active: !args.disabled,
39
+ config: { recipients: args.to }
40
+ }));
41
+ if (args.json)
42
+ return print_json(created);
43
+ log.info(`✅ Created email subscription ${created.id}`);
44
+ log.info(` To: ${(created.config?.recipients ?? []).join(', ')}`);
45
+ log.info(` Events: ${(created.events ?? []).join(', ')}`);
46
+ log.info(` Active: ${created.active ? 'yes' : 'no'}`);
47
+ })
48
+ };
49
+
50
+ export { email_subscriptions_create };
@@ -0,0 +1,23 @@
1
+ import { email_subscriptions_create } from './create.js';
2
+ import { email_subscriptions_list } from './list.js';
3
+ import { email_subscriptions_rm } from './rm.js';
4
+ import { email_subscriptions_update } from './update.js';
5
+
6
+ // Emails to the tenant's own people on its events (user.created,
7
+ // user.updated, credentials.exported), e.g. to hear about every form that
8
+ // lands as a user. Same resource as webhooks, `channel: 'email'`.
9
+ const email_subscriptions = {
10
+ command: 'email-subscriptions',
11
+ aliases: ['emails'],
12
+ describe: 'Manage email subscriptions (emails to your team on tenant events)',
13
+ builder: yargs => yargs
14
+ .command(email_subscriptions_list)
15
+ .command(email_subscriptions_create)
16
+ .command(email_subscriptions_update)
17
+ .command(email_subscriptions_rm)
18
+ .demandCommand(1)
19
+ .showHelpOnFail(false),
20
+ handler: () => { }
21
+ };
22
+
23
+ export { email_subscriptions };
@@ -0,0 +1,39 @@
1
+ import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
2
+ import { list_options, fetch_page, from_paginator, print_json, table_lines, print, more_hint } from '../../../lib/listing.js';
3
+ import { log } from '../../../log.js';
4
+ import { tenant_options } from '../options.js';
5
+ import { yes_no } from '../render.js';
6
+ import { isEmail } from './shared.js';
7
+
8
+ const email_subscriptions_list = {
9
+ command: 'list',
10
+ describe: 'List email subscriptions',
11
+ builder: yargs => list_options(tenant_options(yargs)).showHelpOnFail(false),
12
+ handler: withAuthHints(async (args) => {
13
+ const api = await requireAuthAdmin(args);
14
+ const page = await fetch_page(from_paginator(api.notificationsubscriptionList({})), args);
15
+ // The resource also holds webhooks; this command is email.
16
+ const data = page.data.filter(isEmail);
17
+ if (args.json)
18
+ return print_json({ ...page, data });
19
+ if (data.length === 0) {
20
+ log.info('📭 No email subscriptions. Create one with `faable auth email-subscriptions create`.');
21
+ return;
22
+ }
23
+ log.info(`📧 ${data.length} email subscription(s):`);
24
+ const rows = data.map(s => [
25
+ s.id,
26
+ (s.config?.recipients ?? []).join(','),
27
+ s.events.join(','),
28
+ yes_no(s.active)
29
+ ]);
30
+ for (const line of table_lines(['ID', 'RECIPIENTS', 'EVENTS', 'ACTIVE'], rows)) {
31
+ print(line);
32
+ }
33
+ const hint = more_hint(page);
34
+ if (hint)
35
+ log.info(hint);
36
+ })
37
+ };
38
+
39
+ export { email_subscriptions_list };
@@ -0,0 +1,45 @@
1
+ import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
2
+ import { confirm } from '../../../lib/interactive.js';
3
+ import { log } from '../../../log.js';
4
+ import { tenant_options } from '../options.js';
5
+ import { json_option, print_json } from '../../../lib/listing.js';
6
+ import { isEmail } from './shared.js';
7
+
8
+ const email_subscriptions_rm = {
9
+ command: 'rm <subscription_id>',
10
+ describe: 'Delete an email subscription',
11
+ builder: yargs => json_option(tenant_options(yargs))
12
+ .positional('subscription_id', {
13
+ type: 'string',
14
+ demandOption: true,
15
+ description: 'Subscription id (notificationsubscription_…)'
16
+ })
17
+ .option('yes', {
18
+ alias: 'y',
19
+ type: 'boolean',
20
+ default: false,
21
+ description: 'Skip the confirmation prompt'
22
+ })
23
+ .showHelpOnFail(false),
24
+ handler: withAuthHints(async (args) => {
25
+ const api = await requireAuthAdmin(args);
26
+ const s = (await api.notificationsubscriptionGet(args.subscription_id));
27
+ if (!isEmail(s)) {
28
+ throw new Error(`${s.id} is a webhook, not an email subscription: use \`faable auth webhooks rm\`.`);
29
+ }
30
+ const go = await confirm({
31
+ message: `Delete email subscription ${s.id} → ${(s.config?.recipients ?? []).join(', ')}? Those emails stop.`,
32
+ yes: args.yes
33
+ });
34
+ if (!go) {
35
+ log.info('Cancelled.');
36
+ return;
37
+ }
38
+ await api.notificationsubscriptionDelete(s.id);
39
+ if (args.json)
40
+ return print_json({ deleted: true, id: s.id });
41
+ log.info(`🗑️ Deleted email subscription ${s.id}.`);
42
+ })
43
+ };
44
+
45
+ export { email_subscriptions_rm };
@@ -0,0 +1,29 @@
1
+ // Pieces shared by the `faable auth email-subscriptions` commands.
2
+ //
3
+ // An email subscription is a notification subscription with `channel: 'email'`
4
+ // (the same resource as webhooks): Faable Auth emails the tenant's own people
5
+ // on an event — e.g. every time a form creates or updates a user, the
6
+ // recipients get an email with the user's `faable.com/fields`.
7
+ const isEmail = (s) => s.channel === 'email';
8
+ // The only events with an email template in Faable Auth
9
+ // (auth: EMAIL_SUBSCRIPTION_EVENTS). Any other event would be stored and never
10
+ // sent, so it is refused here, before the request.
11
+ const EMAIL_EVENTS = [
12
+ 'user.created',
13
+ 'user.updated',
14
+ 'credentials.exported'
15
+ ];
16
+ const assertEmailEvents = (events) => {
17
+ const unknown = events.filter(e => !EMAIL_EVENTS.includes(e));
18
+ if (unknown.length) {
19
+ throw new Error(`Email subscriptions can only send ${EMAIL_EVENTS.join(', ')} (no email template for: ${unknown.join(', ')}). For other events use \`faable auth webhooks\`.`);
20
+ }
21
+ };
22
+ const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
23
+ const assertRecipients = (to) => {
24
+ const bad = to.filter(r => !EMAIL.test(r));
25
+ if (bad.length)
26
+ throw new Error(`Not an email address: ${bad.join(', ')}`);
27
+ };
28
+
29
+ export { EMAIL_EVENTS, assertEmailEvents, assertRecipients, isEmail };
@@ -0,0 +1,54 @@
1
+ import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
2
+ import { log } from '../../../log.js';
3
+ import { tenant_options } from '../options.js';
4
+ import { yes_no } from '../render.js';
5
+ import { assertRecipients, assertEmailEvents } from './shared.js';
6
+ import { json_option, print_json } from '../../../lib/listing.js';
7
+
8
+ const email_subscriptions_update = {
9
+ command: 'update <subscription_id>',
10
+ describe: 'Change an email subscription (recipients, events, enabled)',
11
+ builder: yargs => json_option(tenant_options(yargs))
12
+ .positional('subscription_id', {
13
+ type: 'string',
14
+ demandOption: true,
15
+ description: 'Subscription id (notificationsubscription_…)'
16
+ })
17
+ .option('to', {
18
+ type: 'string',
19
+ array: true,
20
+ description: 'Replace the recipients — repeatable'
21
+ })
22
+ .option('event', {
23
+ alias: 'e',
24
+ type: 'string',
25
+ array: true,
26
+ description: 'Replace the events — repeatable'
27
+ })
28
+ .option('enabled', {
29
+ type: 'boolean',
30
+ description: 'Enable (--enabled) or pause (--no-enabled) the emails'
31
+ })
32
+ .showHelpOnFail(false),
33
+ handler: withAuthHints(async (args) => {
34
+ if (args.to?.length)
35
+ assertRecipients(args.to);
36
+ if (args.event?.length)
37
+ assertEmailEvents(args.event);
38
+ const patch = {
39
+ ...(args.to?.length ? { config: { recipients: args.to } } : {}),
40
+ ...(args.event?.length ? { events: args.event } : {}),
41
+ ...(args.enabled !== undefined ? { active: args.enabled } : {})
42
+ };
43
+ if (Object.keys(patch).length === 0) {
44
+ throw new Error('Nothing to update — pass at least one of --to, --event, --enabled');
45
+ }
46
+ const api = await requireAuthAdmin(args);
47
+ const s = (await api.notificationsubscriptionUpdate(args.subscription_id, patch));
48
+ if (args.json)
49
+ return print_json(s);
50
+ log.info(`✅ Updated email subscription ${s.id} (${(s.config?.recipients ?? []).join(', ')}, ${(s.events ?? []).join(', ')}, active ${yes_no(s.active)})`);
51
+ })
52
+ };
53
+
54
+ export { email_subscriptions_update };
@@ -8,6 +8,7 @@ import { roles } from './roles/index.js';
8
8
  import { sessions } from './sessions/index.js';
9
9
  import { users } from './users/index.js';
10
10
  import { webhooks } from './webhooks/index.js';
11
+ import { email_subscriptions } from './email_subscriptions/index.js';
11
12
 
12
13
  // `faable auth` — management commands for a Faable Auth tenant. Auth: reuses
13
14
  // the `faable login` session (or FAABLE_TOKEN); tenant: --account /
@@ -15,7 +16,7 @@ import { webhooks } from './webhooks/index.js';
15
16
  // resolveTenant in src/api/auth_admin.ts.
16
17
  const auth = {
17
18
  command: 'auth',
18
- describe: 'Manage Faable Auth (users, roles, APIs, sessions, logins, actions, clients, webhooks, audit logs)',
19
+ describe: 'Manage Faable Auth (users, roles, APIs, sessions, logins, actions, clients, webhooks, email subscriptions, audit logs)',
19
20
  builder: yargs => yargs
20
21
  .command(users)
21
22
  .command(roles)
@@ -26,6 +27,7 @@ const auth = {
26
27
  .command(sessions)
27
28
  .command(connections)
28
29
  .command(webhooks)
30
+ .command(email_subscriptions)
29
31
  .command(accounts)
30
32
  .command(auth_use)
31
33
  .demandCommand(1)
package/dist/mcp/http.js CHANGED
@@ -190,7 +190,7 @@ const llms_txt = (base = PUBLIC_URL) => [
190
190
  : `Endpoint: ${base}/mcp (Streamable HTTP). Authenticate with a Faable API key: \`Authorization: Bearer <key>\` (create one in the dashboard, project settings → API keys). The key belongs to one project and only acts there.`,
191
191
  '',
192
192
  `- \`${base}/mcp/<project>\` pins every call to one project.`,
193
- '- `?mode=write` adds the reversible writes (create apps, set secrets, add domains, retry or cancel builds, change deploy settings). Nothing destructive is exposed.',
193
+ '- `?mode=write` adds the reversible writes (create apps, set secrets, add domains, retry or cancel builds, change deploy settings, rotate a Challenge secret). Nothing is ever deleted.',
194
194
  '- `?readonly=1` exposes reads only.',
195
195
  '- Local alternative, no key: `npx -y @faable/faable mcp` (uses `faable login`).',
196
196
  '',
@@ -6,7 +6,8 @@ import { TOOLS } from './tools.js';
6
6
 
7
7
  // `faable mcp` — the Faable MCP server over stdio (Fase 1 of
8
8
  // arch/deploy/mcp-server-faable.md). Reads plus `deploy_app` by default;
9
- // the reversible writes only with --writes. Nothing destructive, ever, here.
9
+ // the reversible writes only with --writes. The destructive tools are writes,
10
+ // and all but rotate_challenge_secret are local only.
10
11
  const INSTRUCTIONS = `Faable Deploy (apps, deployments, logs, domains, secrets) and Faable Auth (the users who log in to the user's apps) of the user's Faable projects.
11
12
  - Orient with list_apps (or list_projects when the user has several projects); pass \`project\` to scope a call.
12
13
  - "Why did my deploy fail?": list_deployments → get_deployment (full failure reason, and \`fault\`: \`user\` = their code or config, \`platform\` = Faable's side) → get_build_logs (the cause is at the end).
@@ -43,7 +44,7 @@ const NEXT_STEP = {
43
44
  apikey_session: 'The user is logged in with an API key; this needs `faable login` without --apikey.',
44
45
  apikey_invalid: 'The API key this server was given is invalid or was revoked. The user needs a new one from the dashboard (project settings → API Keys).',
45
46
  not_found: 'Check the id or name — list_apps / list_deployments show what exists.',
46
- forbidden: 'This session has no access there — check the project (list_projects). With an API key, Auth tools only reach the tenants of the key\'s own project.',
47
+ forbidden: "This session has no access there — check the project (list_projects). With an API key, Auth tools only reach the tenants of the key's own project.",
47
48
  github_installation_missing: 'The Faable GitHub App is not installed on that repository. Give the user the install link (list_github_repos returns it as install_url); it is a step in their browser.',
48
49
  github_identity_missing: 'The user has not connected GitHub to Faable yet: they connect it once in the dashboard (https://dashboard.faable.com), then retry.',
49
50
  repository_already_linked: 'That repository already has an app: use deploy_app on it (list_apps finds it).',
package/dist/mcp/tools.js CHANGED
@@ -1427,16 +1427,16 @@ const TOOLS = [
1427
1427
  {
1428
1428
  name: 'rotate_challenge_secret',
1429
1429
  title: 'Rotate a Challenge secret',
1430
- description: "Issue a new secret for a Faable Challenge site, e.g. when the old one leaked. The old secret stops working AT ONCE: until the user's server has the new one, its verifications fail. Confirm with the user first. Returns the new `secret`, only this once. Only on the local server with `faable mcp --writes`.",
1430
+ description: "Issue a new secret for a Faable Challenge site, e.g. when the old one leaked. The old secret stops working AT ONCE: until the user's server has the new one, its verifications fail. Confirm with the user first. Returns the new `secret`, only this once.",
1431
1431
  input: { project, site: challenge_site },
1432
1432
  command: ['challenge', 'sites', 'rotate-secret'],
1433
1433
  // --yes: the model was asked to rotate; the CLI prompt has no one to ask.
1434
1434
  flags: a => [a.site, '--yes', ...scope(a)],
1435
1435
  shape: with_secret_note,
1436
1436
  write: true,
1437
- // It breaks the user's verify until their server has the new secret: not
1438
- // on the hosted server, which promises nothing destructive.
1439
- local_only: true,
1437
+ // The one destructive tool on the hosted server (Marc, 18-11): a leaked
1438
+ // secret is urgent and deletes nothing. It breaks the user's verify until
1439
+ // their server has the new one, so destructiveHint makes the client ask.
1440
1440
  annotations: {
1441
1441
  readOnlyHint: false,
1442
1442
  destructiveHint: true,
@@ -1453,7 +1453,7 @@ const TOOLS = [
1453
1453
  command: ['challenge', 'sites', 'delete'],
1454
1454
  flags: a => [a.site, '--yes', ...scope(a)],
1455
1455
  write: true,
1456
- // Like delete_app: the hosted server promises nothing destructive.
1456
+ // Like delete_app: the hosted server deletes nothing.
1457
1457
  local_only: true,
1458
1458
  annotations: {
1459
1459
  readOnlyHint: false,
@@ -1525,9 +1525,9 @@ const TOOLS = [
1525
1525
  command: ['deploy', 'apps', 'rm'],
1526
1526
  flags: a => ['--yes', ...target(a)],
1527
1527
  write: true,
1528
- // The hosted server promises its users nothing destructive (the consent
1529
- // screen and docs/cli.md say so): deleting stays with whoever runs the
1530
- // MCP on their own machine and passed --writes.
1528
+ // The hosted server deletes nothing (docs/cli.md and the landing say so):
1529
+ // deleting stays with whoever runs the MCP on their own machine and
1530
+ // passed --writes.
1531
1531
  local_only: true,
1532
1532
  annotations: {
1533
1533
  readOnlyHint: false,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@faable/faable",
3
- "version": "4.47.0",
3
+ "version": "4.49.0",
4
4
  "main": "dist/index.js",
5
5
  "license": "MIT",
6
6
  "author": "Marc Pomar <marc@faable.com>",