run402 4.7.0 → 4.9.0

package/lib/secrets.mjs

@@ -1,7 +1,7 @@
 import { readFileSync } from "fs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { assertKnownFlags, flagValue, normalizeArgv, positionalArgs, validateRegularFile } from "./argparse.mjs";
+import { assertKnownFlags, flagValue, normalizeArgv, positionalArgs, resolveProjectSelector, validateRegularFile } from "./argparse.mjs";
 import { editRequestAction } from "./next-actions.mjs";
 
 const HELP = `run402 secrets — Manage project secrets
@@ -10,18 +10,25 @@ Usage:
   run402 secrets <subcommand> [args...]
 
 Subcommands:
-  set    <id> <key> <value> [--file <path>|--stdin]  Set a secret on a project
-  list   <id>                  List all secrets for a project
-  delete <id> <key>            Delete a secret from a project
+  set    <key> (--value <v> | --file <path> | --stdin) [--project <id>]
+                               Set a secret on a project
+  list   [--project <id>]      List all secrets for a project
+  delete <key> [--project <id>]  Delete a secret from a project
+
+Legacy (still supported):
+  run402 secrets set <prj_id> <key> <value>
+  run402 secrets list <prj_id>
+  run402 secrets delete <prj_id> <key>
 
 Examples:
-  printf %s "$STRIPE_KEY" | run402 secrets set prj_abc123 STRIPE_KEY --stdin
-  run402 secrets set prj_abc123 STRIPE_KEY --file ./.secrets/stripe-key
-  run402 secrets set prj_abc123 TLS_CERT --file cert.pem
-  run402 secrets list prj_abc123
-  run402 secrets delete prj_abc123 STRIPE_KEY
+  printf %s "$STRIPE_KEY" | run402 secrets set STRIPE_KEY --stdin --project prj_abc123
+  run402 secrets set STRIPE_KEY --file ./.secrets/stripe-key --project prj_abc123
+  run402 secrets set TLS_CERT --file cert.pem
+  run402 secrets list --project prj_abc123
+  run402 secrets delete STRIPE_KEY --project prj_abc123
 
 Notes:
+  - --project defaults to the active project ('run402 projects use')
   - Secrets are injected as process.env in serverless functions
   - Values are write-only — list returns keys and timestamps only
   - Deploy manifests should declare existing keys with secrets.require; never put values in deploy specs
@@ -31,68 +38,86 @@ const SUB_HELP = {
   set: `run402 secrets set — Set a secret on a project
 
 Usage:
-  run402 secrets set <id> <key> <value>
-  run402 secrets set <id> <key> --file <path>
-  run402 secrets set <id> <key> --stdin
+  run402 secrets set <key> --value <v> [--project <id>]
+  run402 secrets set <key> --file <path> [--project <id>]
+  run402 secrets set <key> --stdin [--project <id>]
+
+Legacy (still supported):
+  run402 secrets set <prj_id> <key> <value>
+  run402 secrets set <key> <value>
 
 Arguments:
-  <id>                Project ID (from 'run402 projects list')
   <key>               Secret key name (exposed as process.env.<key>)
-  <value>             Inline secret value (omit if using --file or --stdin)
 
 Options:
+  --project <id>      Project ID (defaults to the active project)
+  --value <v>         Inline secret value (alternative to the legacy positional)
   --file <path>       Read the secret value from a file instead of inline
                       Use --file - or --file /dev/stdin to read from stdin
   --stdin             Read the secret value from stdin until EOF
 
 Notes:
+  - Provide exactly one value source: --value, --file, --stdin, or the legacy inline positional
   - Secrets are injected as process.env in serverless functions
   - Values are write-only; 'list' cannot verify values by hash
   - Prefer --stdin or --file for real secrets so values do not land in shell history
 
 Examples:
-  printf %s "$STRIPE_KEY" | run402 secrets set prj_abc123 STRIPE_KEY --stdin
-  cat ./.secrets/stripe-key | run402 secrets set prj_abc123 STRIPE_KEY --file -
-  run402 secrets set prj_abc123 STRIPE_KEY --file ./.secrets/stripe-key
-  run402 secrets set prj_abc123 TLS_CERT --file cert.pem
+  printf %s "$STRIPE_KEY" | run402 secrets set STRIPE_KEY --stdin --project prj_abc123
+  cat ./.secrets/stripe-key | run402 secrets set STRIPE_KEY --file - --project prj_abc123
+  run402 secrets set STRIPE_KEY --file ./.secrets/stripe-key
+  run402 secrets set TLS_CERT --file cert.pem --project prj_abc123
 `,
   list: `run402 secrets list — List all secrets for a project
 
 Usage:
-  run402 secrets list <id>
+  run402 secrets list [--project <id>]
 
-Arguments:
-  <id>                Project ID (from 'run402 projects list')
+Legacy (still supported):
+  run402 secrets list <prj_id>
+
+Options:
+  --project <id>      Project ID (defaults to the active project)
 
 Notes:
   - Returns secret keys and timestamps only; raw values and value-derived hashes are never returned
 
 Examples:
-  run402 secrets list prj_abc123
+  run402 secrets list --project prj_abc123
 `,
   delete: `run402 secrets delete — Delete a secret from a project
 
 Usage:
-  run402 secrets delete <id> <key>
+  run402 secrets delete <key> [--project <id>]
+
+Legacy (still supported):
+  run402 secrets delete <prj_id> <key>
 
 Arguments:
-  <id>                Project ID (from 'run402 projects list')
   <key>               Secret key name to remove
 
+Options:
+  --project <id>      Project ID (defaults to the active project)
+
 Examples:
-  run402 secrets delete prj_abc123 STRIPE_KEY
+  run402 secrets delete STRIPE_KEY --project prj_abc123
 `,
 };
 
+const SET_VALUE_FLAGS = ["--file", "--value", "--project"];
+
 export function readSecretValueForSet(parsedArgs, values, readers = {}) {
   const readStdin = readers.readStdin ?? (() => readFileSync(0, "utf-8"));
   const readFile = readers.readFile ?? ((path) => readFileSync(path, "utf-8"));
   const validateFile = readers.validateFile ?? validateRegularFile;
   const file = flagValue(parsedArgs, "--file");
+  const valueFlagPresent = parsedArgs.includes("--value");
+  const valueFlag = valueFlagPresent ? flagValue(parsedArgs, "--value") : null;
   const stdinRequested = parsedArgs.includes("--stdin");
   const stdinFile = isStdinAlias(file);
   const sources = [];
   if (values.length === 1) sources.push("inline");
+  if (valueFlagPresent) sources.push("--value");
   if (file) sources.push(stdinFile ? "--file stdin" : "--file");
   if (stdinRequested) sources.push("--stdin");
 
@@ -101,22 +126,31 @@ export function readSecretValueForSet(parsedArgs, values, readers = {}) {
       code: "BAD_USAGE",
       message: "Provide exactly one secret value source.",
       details: { sources },
-      hint: "Use one of: inline value, --file <path>, or --stdin.",
+      hint: "Use one of: --value <v>, --file <path>, --stdin, or an inline value.",
     });
   }
   if (file && !stdinFile) validateFile(file, "--file");
 
   if (stdinRequested || stdinFile) return readStdin();
+  if (valueFlagPresent) return valueFlag;
   if (file) return readFile(file);
   if (values.length === 1) return values[0];
   return undefined;
 }
 
-async function set(projectId, key, args = []) {
+async function set(projectId, args = []) {
   const parsedArgs = normalizeArgv(args);
-  const valueFlags = ["--file"];
-  assertKnownFlags(parsedArgs, [...valueFlags, "--stdin", "--help", "-h"], valueFlags);
-  const values = positionalArgs(parsedArgs, valueFlags);
+  assertKnownFlags(parsedArgs, [...SET_VALUE_FLAGS, "--stdin", "--help", "-h"], SET_VALUE_FLAGS);
+  const positionals = positionalArgs(parsedArgs, SET_VALUE_FLAGS);
+  const key = positionals[0];
+  if (!key) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <key>.",
+      hint: "run402 secrets set <key> --value <v> [--project <id>]",
+    });
+  }
+  const values = positionals.slice(1);
   if (values.length > 1) {
     fail({ code: "BAD_USAGE", message: `Unexpected argument for secrets set: ${values[1]}` });
   }
@@ -172,8 +206,8 @@ function failMissingStdin() {
 
 async function list(projectId, args = []) {
   const parsedArgs = normalizeArgv(args);
-  assertKnownFlags(parsedArgs, ["--help", "-h"]);
-  const extra = positionalArgs(parsedArgs);
+  assertKnownFlags(parsedArgs, ["--project", "--help", "-h"], ["--project"]);
+  const extra = positionalArgs(parsedArgs, ["--project"]);
   if (extra.length > 0) {
     fail({ code: "BAD_USAGE", message: `Unexpected argument for secrets list: ${extra[0]}` });
   }
@@ -192,12 +226,20 @@ async function list(projectId, args = []) {
   }
 }
 
-async function deleteSecret(projectId, key, args = []) {
+async function deleteSecret(projectId, args = []) {
   const parsedArgs = normalizeArgv(args);
-  assertKnownFlags(parsedArgs, ["--help", "-h"]);
-  const extra = positionalArgs(parsedArgs);
-  if (extra.length > 0) {
-    fail({ code: "BAD_USAGE", message: `Unexpected argument for secrets delete: ${extra[0]}` });
+  assertKnownFlags(parsedArgs, ["--project", "--help", "-h"], ["--project"]);
+  const positionals = positionalArgs(parsedArgs, ["--project"]);
+  const key = positionals[0];
+  if (!key) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <key>.",
+      hint: "run402 secrets delete <key> [--project <id>]",
+    });
+  }
+  if (positionals.length > 1) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for secrets delete: ${positionals[1]}` });
   }
   try {
     await getSdk().secrets.delete(projectId, key);
@@ -213,10 +255,26 @@ export async function run(sub, args) {
     console.log(SUB_HELP[sub] || HELP);
     process.exit(0);
   }
+  if (!["set", "list", "delete"].includes(sub)) {
+    fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown secrets subcommand: ${sub}`, hint: "Run `run402 secrets --help` for usage.", details: { command: "secrets", subcommand: sub } });
+  }
+  const parsed = normalizeArgv(Array.isArray(args) ? args : []);
   switch (sub) {
-    case "set":    await set(args[0], args[1], args.slice(2)); break;
-    case "list":   await list(args[0], args.slice(1)); break;
-    case "delete": await deleteSecret(args[0], args[1], args.slice(2)); break;
+    case "set": {
+      const { projectId, rest } = resolveProjectSelector(parsed, { valueFlags: SET_VALUE_FLAGS });
+      await set(projectId, rest);
+      break;
+    }
+    case "list": {
+      const { projectId, rest } = resolveProjectSelector(parsed, { valueFlags: ["--project"] });
+      await list(projectId, rest);
+      break;
+    }
+    case "delete": {
+      const { projectId, rest } = resolveProjectSelector(parsed, { valueFlags: ["--project"] });
+      await deleteSecret(projectId, rest);
+      break;
+    }
     default:
       fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown secrets subcommand: ${sub}`, hint: "Run `run402 secrets --help` for usage.", details: { command: "secrets", subcommand: sub } });
   }

package/lib/snapshots.mjs

@@ -8,24 +8,28 @@ import {
   normalizeArgv,
   parseIntegerFlag,
   positionalArgs,
+  resolveProjectSelector,
 } from "./argparse.mjs";
-import { resolveProjectId } from "./config.mjs";
 
 const HELP = `run402 snapshots — Project database restore points
 
 Usage:
-  run402 snapshots create [project-id] [--json]
-  run402 snapshots list [project-id] [--kind <kind>] [--limit <n>] [--after <cursor>] [--json]
-  run402 snapshots get [project-id] <snapshot-id> [--json]
-  run402 snapshots restore [project-id] <snapshot-id> [--include-auth] [--confirm <token>] [--json]
-  run402 snapshots delete [project-id] <snapshot-id> [--json]
+  run402 snapshots create [--project <id>] [--json]
+  run402 snapshots list [--project <id>] [--kind <kind>] [--limit <n>] [--after <cursor>] [--json]
+  run402 snapshots get <snapshot-id> [--project <id>] [--json]
+  run402 snapshots restore <snapshot-id> [--project <id>] [--include-auth] [--confirm <token>] [--json]
+  run402 snapshots delete <snapshot-id> [--project <id>] [--json]
+
+Legacy (still supported): a leading prj_... positional selects the project,
+e.g. run402 snapshots restore prj_abc123 <snapshot-id>. --project defaults to
+the active project.
 
 Restore is a two-step handshake. First call without --confirm to get a
 restore_plan.confirm.token, then re-run with --confirm after reviewing the
 data-loss statement.
 `;
 
-const FLAG_VALUES = ["--kind", "--limit", "--after", "--confirm"];
+const FLAG_VALUES = ["--project", "--kind", "--limit", "--after", "--confirm"];
 const FLAGS = new Set([...FLAG_VALUES, "--include-auth", "--json", "--help", "-h"]);
 const SNAPSHOT_KINDS = ["manual", "pre_migration", "pre_restore", "scheduled"];
 
@@ -54,7 +58,7 @@ export async function run(sub, args = []) {
 }
 
 async function create(args) {
-  const projectId = resolveOptionalProject(positionalArgs(args, FLAG_VALUES)[0]);
+  const { projectId } = resolveProjectSelector(args, { valueFlags: FLAG_VALUES });
   try {
     const snapshot = await getSdk().snapshots.create(projectId);
     console.log(JSON.stringify({ ok: snapshot.status === "ready", snapshot }, null, 2));
@@ -64,7 +68,7 @@ async function create(args) {
 }
 
 async function list(args) {
-  const projectId = resolveOptionalProject(positionalArgs(args, FLAG_VALUES)[0]);
+  const { projectId } = resolveProjectSelector(args, { valueFlags: FLAG_VALUES });
   const kind = flagValue(args, "--kind") ?? undefined;
   if (kind !== undefined) assertAllowedValue(kind, SNAPSHOT_KINDS, "--kind");
   const limitFlag = flagValue(args, "--limit");
@@ -124,14 +128,12 @@ async function deleteSnapshot(args) {
   }
 }
 
-function resolveOptionalProject(value) {
-  if (value && String(value).startsWith("prj_")) return value;
-  return resolveProjectId(null);
-}
-
 function resolveProjectAndSnapshot(args, usage) {
-  const pos = positionalArgs(args, FLAG_VALUES);
-  if (pos.length === 1) return { projectId: resolveProjectId(null), snapshotId: pos[0] };
-  if (pos.length === 2 && pos[0].startsWith("prj_")) return { projectId: pos[0], snapshotId: pos[1] };
-  fail({ code: "BAD_USAGE", message: `Usage: ${usage}` });
+  // Canonical: `<snapshot-id> [--project <id>]`; legacy `<prj_id> <snapshot-id>`
+  // still works (requireRestPositional keeps a lone snapshot id that happens to
+  // start with prj_ from being eaten as the project selector).
+  const { projectId, rest } = resolveProjectSelector(args, { valueFlags: FLAG_VALUES, requireRestPositional: true });
+  const pos = positionalArgs(rest, FLAG_VALUES);
+  if (pos.length !== 1) fail({ code: "BAD_USAGE", message: `Usage: ${usage}` });
+  return { projectId, snapshotId: pos[0] };
 }

package/lib/wallets.mjs

@@ -42,7 +42,7 @@ Usage:
   run402 wallets current              Show the resolved active wallet + how it was selected
   run402 wallets new <name>           Create a new named wallet (key stays local)
   run402 wallets use <name>           Set the global default wallet
-  run402 wallets rename <old> <new>   Rename a wallet (migrates the default's files when old=default)
+  run402 wallets rename <old> --to <new>   Rename a wallet (legacy: rename <old> <new>)
   run402 wallets bind [<name>]        Write ./.run402.json binding this directory to a wallet
   run402 wallets unbind               Remove ./.run402.json
   run402 wallets import <name> --key <path|->   Adopt an existing private key as a named wallet
@@ -174,9 +174,10 @@ function cmdUse(args) {
 }
 
 async function cmdRename(args) {
-  const positionals = args.filter((a) => a && !a.startsWith("-"));
+  const toFlag = flagVal(args, "--to");
+  const positionals = args.filter((a, i) => a && !a.startsWith("-") && args[i - 1] !== "--to");
   const oldName = requireName(positionals[0], "old wallet name");
-  const newName = requireName(positionals[1], "new wallet name");
+  const newName = requireName(toFlag ?? positionals[1], "new wallet name");
   if (newName === DEFAULT) {
     fail({ code: "BAD_WALLET_NAME", message: "Cannot rename a wallet to the reserved name 'default'.", details: { name: newName } });
   }

package/lib/webhook-secret.mjs

@@ -27,6 +27,12 @@ export async function run(sub, args = []) {
     console.log(HELP);
     process.exit(0);
   }
+  // --help/-h anywhere in the argv must short-circuit BEFORE auth/config side
+  // effects (the cli-help.test.mjs contract) — same check as notifications.mjs.
+  if (Array.isArray(args) && (args.includes("--help") || args.includes("-h"))) {
+    console.log(HELP);
+    process.exit(0);
+  }
   if (sub !== "rotate") {
     fail({
       code: "UNKNOWN_SUBCOMMAND",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "4.7.0",
+  "version": "4.9.0",
   "description": "CLI for Run402 — provision Postgres databases, deploy static sites, generate images, and manage wallets via x402 and MPP micropayments.",
   "type": "module",
   "bin": {

package/sdk/dist/namespaces/admin.d.ts

@@ -126,9 +126,50 @@ export type NotificationPreferencesPatch = Partial<Omit<NotificationPreferences,
     /** Cannot be changed away from "always" — server returns 400. */
     security_events?: "always";
 };
+export interface TestNotificationOptions {
+    /**
+     * Route the synthetic test event as if it came from the app lane
+     * (`project_events.source = 'app'`) or the platform. Defaults to
+     * `"platform"` on the gateway when omitted.
+     */
+    source?: "app" | "platform";
+    /**
+     * Synthetic `event_type` override (flat snake_case,
+     * `^[a-z][a-z0-9_]{2,63}$`). Use this to exercise a specific routing rule's
+     * `event_types` filter precisely. Defaults to the gateway's built-in
+     * sample event when omitted.
+     */
+    eventType?: string;
+}
+/** One Telegram destination's outcome from a `testNotification()` call —
+ *  present only when the operator has a routing rule matching the synthetic
+ *  event. Empty `telegram.destinations` is Faithful (no matching rule), not
+ *  an error. */
+export interface TestNotificationDestination {
+    binding_id: string;
+    label: string | null;
+    delivered: boolean;
+    /** Present on failures. `true` = retryable (429/5xx/timeout/rate-limited);
+     *  `false` = permanent (bad chat, bot blocked/removed). */
+    transient?: boolean;
+    description?: string;
+}
 export interface TestNotificationResult {
-    status: "queued";
+    status: "delivered" | "skipped" | "queued";
     source_event_id: string;
+    drained: {
+        claimed: number;
+        delivered: number;
+        skipped: number;
+        failed_transient: number;
+        failed_permanent: number;
+    };
+    /** Telegram delivery report for the synthetic event, routed through the
+     *  operator's normal rules — the full binding + rule + render + send
+     *  chain, not just email/webhook. */
+    telegram: {
+        destinations: TestNotificationDestination[];
+    };
     note: string;
 }
 export interface RotateWebhookSecretResult {
@@ -137,6 +178,200 @@ export interface RotateWebhookSecretResult {
     grace_window_hours: number;
     note: string;
 }
+export type TelegramBindingStatus = "pending" | "active" | "revoked";
+/**
+ * One Telegram binding as returned by `GET /agent/v1/notifications/channels`
+ * (`telegram[]`) and `r.admin.channels.list()`. Never carries the raw
+ * connect code — codes are single-use, hashed at rest, and returned only
+ * once, inline in {@link ConnectTelegramResult}.
+ */
+export interface TelegramChannelBinding {
+    id: string;
+    recipient_email: string;
+    status: TelegramBindingStatus;
+    chat_id: number | null;
+    chat_type: string | null;
+    chat_title: string | null;
+    label: string | null;
+    consecutive_failures: number;
+    /** Set once auto-disabled after 10 consecutive hard delivery failures. */
+    disabled_at: string | null;
+    /** Only set while `status === "pending"` — the connect code's 15-min TTL. */
+    code_expires_at: string | null;
+    created_at: string;
+    activated_at: string | null;
+}
+export interface ConnectTelegramOptions {
+    /** Human-readable label for the chat (e.g. `"kychon alerts"`), 1-64 chars. */
+    label?: string;
+}
+export interface ConnectTelegramNextAction {
+    type: string;
+    method?: string;
+    path?: string;
+    why?: string;
+}
+export interface ConnectTelegramResult {
+    binding_id: string;
+    status: "pending";
+    /** `t.me/<bot>?start=<code>` — tap to bind a PRIVATE chat. Single-use, 15-min TTL. */
+    connect_url: string;
+    /** `t.me/<bot>?startgroup=<code>` — tap to bind a GROUP chat. Same code/TTL as {@link connect_url} (whichever is tapped first consumes it). */
+    connect_group_url: string;
+    code_expires_at: string;
+    label: string | null;
+    next_actions: ConnectTelegramNextAction[];
+}
+export interface NotificationChannelsResult {
+    email: {
+        address: string | null;
+        verified: boolean;
+    };
+    webhook: {
+        configured: boolean;
+        url: string | null;
+        secret_configured: boolean;
+    };
+    /** Every live (non-revoked) Telegram binding for this operator, newest first. */
+    telegram: TelegramChannelBinding[];
+}
+export interface RevokeTelegramResult {
+    status: "revoked";
+    binding_id: string;
+}
+/**
+ * `"app"` = app-emitted business events (`project_events.source = 'app'`,
+ * e.g. `events.emit(...)` from `@run402/functions`); `"platform"` = every
+ * non-app platform event (deploys, lifecycle, verification, ...). Absent /
+ * `null` on a rule is a wildcard — matches both.
+ */
+export type RoutingRuleSource = "app" | "platform";
+/**
+ * Wire-shaped routing rule. Every match dimension (`project_id`, `source`,
+ * `event_types`, `classes`) is ANDed; `null` is a wildcard for that
+ * dimension. An explicit empty array (`event_types: []` / `classes: []`)
+ * matches NOTHING — Postgres `TEXT[]` semantics, deliberately different from
+ * the "`[]` means unfiltered" convention used by some read-filter query
+ * params elsewhere in this SDK. One rule always targets exactly one Telegram
+ * binding; overlapping rules that resolve to the same binding are deduped by
+ * the gateway at delivery time (one message, not one per matching rule).
+ */
+export interface RoutingRule {
+    id: string;
+    recipient_email: string;
+    project_id: string | null;
+    source: RoutingRuleSource | null;
+    event_types: string[] | null;
+    classes: string[] | null;
+    channel: "telegram";
+    telegram_binding_id: string;
+    enabled: boolean;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * `r.admin.rules.create(...)` input. Every match dimension is optional
+ * (absent = wildcard); `telegramBindingId` is the only required field. An
+ * all-wildcard rule (every event on every project routes to one chat) is
+ * legal.
+ */
+export interface CreateRoutingRuleInput {
+    telegramBindingId: string;
+    projectId?: string | null;
+    source?: RoutingRuleSource | null;
+    eventTypes?: string[] | null;
+    classes?: string[] | null;
+}
+/**
+ * `r.admin.rules.update(...)` patch. PATCH semantics: a field OMITTED from
+ * this object leaves the stored value unchanged; a field explicitly set to
+ * `null` CLEARS that dimension back to wildcard. There is no wire difference
+ * between "omitted" and "set to `undefined`" — both drop the key from the
+ * JSON request body, so the gateway sees no instruction to change it.
+ */
+export interface UpdateRoutingRulePatch {
+    projectId?: string | null;
+    source?: RoutingRuleSource | null;
+    eventTypes?: string[] | null;
+    classes?: string[] | null;
+    telegramBindingId?: string;
+    enabled?: boolean;
+}
+export interface ListRoutingRulesResult {
+    rules: RoutingRule[];
+}
+export interface CreateRoutingRuleResult extends RoutingRule {
+    next_actions: ConnectTelegramNextAction[];
+}
+export interface DeleteRoutingRuleResult {
+    deleted: true;
+    rule_id: string;
+}
+/**
+ * `r.admin.channels` — the Telegram notification-channel binding lifecycle
+ * (connect / list / revoke). Mutations (`connectTelegram`, `revokeTelegram`)
+ * require `operator_passkey` assurance; `connectTelegram` additionally
+ * requires a VERIFIED operator email (bindings are addressed to it). See
+ * `r.admin.setAgentContact` / `r.admin.verifyAgentContactEmail` and
+ * `r.admin.startOperatorPasskeyEnrollment` to reach that assurance level —
+ * same ladder as {@link Admin.rotateWebhookSecret}.
+ */
+export declare class Channels {
+    private readonly client;
+    constructor(client: Client);
+    /**
+     * Start binding a Telegram chat. Returns two single-use, 15-minute deep
+     * links — `connect_url` for a private chat, `connect_group_url` for a
+     * group — plus a `pending` binding id. A human taps ONE of the links and
+     * starts the bot; poll {@link Channels.list} until the binding's `status`
+     * flips to `"active"` (or `code_expires_at` passes and it's swept back to
+     * `"revoked"`).
+     *
+     * Throws (via the generic SDK error hierarchy — check `err.code`) HTTP 503
+     * `TELEGRAM_CHANNEL_NOT_CONFIGURED` until the platform's dedicated
+     * notification bot is provisioned, and HTTP 412
+     * `OPERATOR_EMAIL_NOT_VERIFIED` when the caller has no verified email yet.
+     */
+    connectTelegram(opts?: ConnectTelegramOptions): Promise<ConnectTelegramResult>;
+    /** List every notification channel — email, webhook, and every live
+     *  (non-revoked) Telegram binding — for the authenticated wallet. */
+    list(): Promise<NotificationChannelsResult>;
+    /**
+     * Revoke a Telegram binding. Missing / already-revoked / another
+     * operator's binding id all return the SAME not-found error
+     * (authorize-before-reveal) — no existence oracle.
+     */
+    revokeTelegram(bindingId: string): Promise<RevokeTelegramResult>;
+}
+/**
+ * `r.admin.rules` — Telegram routing rules (design D4): one match (ANDed
+ * dimensions; an omitted dimension is a wildcard) → one Telegram binding.
+ * Rules govern the Telegram channel ONLY in v1 — email/webhook keep their
+ * existing preference-toggle semantics untouched. Mutations require
+ * `operator_passkey` assurance.
+ */
+export declare class Rules {
+    private readonly client;
+    constructor(client: Client);
+    /** List the operator's routing rules, newest first. */
+    list(): Promise<ListRoutingRulesResult>;
+    /**
+     * Create a routing rule. `telegramBindingId` must reference a binding this
+     * operator owns and that is currently usable (`status: "active"`); an
+     * unusable or foreign binding id returns the same 404 as a nonexistent one
+     * (authorize-before-reveal).
+     */
+    create(input: CreateRoutingRuleInput): Promise<CreateRoutingRuleResult>;
+    /**
+     * Patch a routing rule. PATCH semantics: only fields PRESENT on `patch`
+     * are sent — `{ projectId: null }` clears that dimension back to
+     * wildcard; omitting a field leaves it unchanged (see
+     * {@link UpdateRoutingRulePatch}).
+     */
+    update(ruleId: string, patch: UpdateRoutingRulePatch): Promise<RoutingRule>;
+    /** Delete a routing rule. */
+    delete(ruleId: string): Promise<DeleteRoutingRuleResult>;
+}
 export interface SetLeasePerpetualResult {
     status: "ok";
     org_id: string;
@@ -246,6 +481,16 @@ export declare class Admin {
      * preview, accept, claim, cancel, listIncoming, listOutgoing}`.
      */
     readonly transfers: Transfers;
+    /**
+     * Telegram notification-channel binding lifecycle. Access via
+     * `r.admin.channels.{connectTelegram, list, revokeTelegram}`.
+     */
+    readonly channels: Channels;
+    /**
+     * Telegram routing rules — one match (ANDed dimensions) to one binding.
+     * Access via `r.admin.rules.{list, create, update, delete}`.
+     */
+    readonly rules: Rules;
     constructor(client: Client);
     /**
      * Operator-scoped sub-client for an org id — the operator analog of
@@ -280,10 +525,15 @@ export declare class Admin {
     setNotificationPreferences(patch: NotificationPreferencesPatch): Promise<NotificationPreferences>;
     /**
      * Trigger a real test notification. Sends a sample `project_past_due`
-     * event through the normal worker pipeline; the audit row is marked
-     * `is_test: true`. Rate-limited per wallet at 1/min.
+     * event through the normal worker pipeline (email/webhook); the audit row
+     * is marked `is_test: true`. ALSO delivers a synthetic event through the
+     * operator's Telegram routing rules end-to-end (binding + rule + render +
+     * send) and reports a per-destination outcome in `telegram.destinations`
+     * — pass `opts.source` / `opts.eventType` to target a specific rule's
+     * filters instead of the default sample event. Rate-limited per wallet at
+     * 1/min.
      */
-    testNotification(): Promise<TestNotificationResult>;
+    testNotification(opts?: TestNotificationOptions): Promise<TestNotificationResult>;
     /**
      * Rotate the operator's webhook signing secret. The new plaintext secret
      * is returned EXACTLY once. The previous secret remains valid for 24