requestshield 0.1.4 → 0.1.5

package/src/args.mjs

@@ -1,85 +1,188 @@
-// @ts-check
-
-import { CliError } from "./errors.mjs";
-
-const HELP = `RequestShield CLI
-
-Usage:
-  requestshield signin
-  requestshield keys create [--yes]
+// @ts-check
+
+import { CliError } from "./errors.mjs";
+
+const HELP = `RequestShield CLI
+
+Usage:
+  requestshield signin
+  requestshield keys create [--yes]
+  requestshield contract
+  requestshield apps list [--json]
+  requestshield apps get <app-key>
+  requestshield challenge volume <app-key> [--from <time>] [--to <time>] [--granularity <value>]
+  requestshield get billing <app-key>
   requestshield agent setup [--force]
   requestshield agent setup --codex [--force]
   requestshield agent setup --claude [--force]
   requestshield update check
   requestshield --help
   requestshield --version`;
-
-/**
- * @typedef {{ command: "help", help: string }
- * | { command: "version" }
- * | { command: "update-check" }
- * | { command: "signin" }
- * | { command: "keys-create", yes: boolean }
- * | { command: "agent-setup", agent?: "codex" | "claude", force: boolean }} ParsedArgs
- */
-
-/** @param {string[]} argv @returns {ParsedArgs} */
-export function parseArgs(argv) {
-  if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
-    return { command: "help", help: HELP };
-  }
-  if (argv.length === 1 && (argv[0] === "--version" || argv[0] === "-v" || argv[0] === "-V")) {
-    return { command: "version" };
-  }
-  if (argv[0] === "update" && argv[1] === "check") {
-    assertOnly(argv.slice(2), new Set());
-    return { command: "update-check" };
-  }
-  if (argv[0] === "signin") {
-    assertOnly(argv.slice(1), new Set());
-    return { command: "signin" };
-  }
-  if (argv[0] === "keys" && argv[1] === "create") {
-    assertOnly(argv.slice(2), new Set(["--yes"]));
-    return { command: "keys-create", yes: argv.includes("--yes") };
-  }
-  if (argv[0] === "agent" && argv[1] === "setup") {
-    const rest = argv.slice(2);
-    /** @type {"codex" | "claude" | undefined} */
-    let agent;
-    let force = false;
-    for (let index = 0; index < rest.length; index++) {
-      const arg = rest[index];
-      if (arg === "--force") {
-        force = true;
-      } else if (arg === "--codex" || arg === "--claude") {
-        if (agent !== undefined) {
-          throw new CliError("Only one of --codex or --claude may be provided", {
-            code: "INVALID_AGENT",
-            exitCode: 2,
-          });
-        }
-        agent = arg === "--codex" ? "codex" : "claude";
-      } else {
-        throw new CliError(`Unknown option: ${arg}`, { exitCode: 2 });
-      }
-    }
-    return {
-      command: "agent-setup",
-      ...(agent ? { agent } : {}),
-      force,
-    };
-  }
-  throw new CliError(`Unknown command.\n\n${HELP}`, { exitCode: 2 });
-}
-
-/** @param {string[]} args @param {Set<string>} allowed */
-function assertOnly(args, allowed) {
-  for (const arg of args) {
-    if (!allowed.has(arg)) {
-      throw new CliError(`Unknown option: ${arg}`, { exitCode: 2 });
-    }
-  }
-}
-
-export { HELP };
+
+/**
+ * @typedef {{ command: "help", help: string }
+ * | { command: "version" }
+ * | { command: "update-check" }
+ * | { command: "signin" }
+ * | { command: "keys-create", yes: boolean }
+ * | { command: "contract" }
+ * | { command: "apps-list", json: boolean }
+ * | { command: "apps-get", appKey: string }
+ * | { command: "challenge-volume", appKey: string, from?: string, to?: string, granularity?: string }
+ * | { command: "billing-get", appKey: string }
+ * | { command: "agent-setup", agent?: "codex" | "claude", force: boolean }} ParsedArgs
+ */
+
+/** @param {string[]} argv @returns {ParsedArgs} */
+export function parseArgs(argv) {
+  if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
+    return { command: "help", help: HELP };
+  }
+  if (argv.length === 1 && (argv[0] === "--version" || argv[0] === "-v" || argv[0] === "-V")) {
+    return { command: "version" };
+  }
+  if (argv[0] === "update" && argv[1] === "check") {
+    assertOnly(argv.slice(2), new Set());
+    return { command: "update-check" };
+  }
+  if (argv[0] === "signin") {
+    assertOnly(argv.slice(1), new Set());
+    return { command: "signin" };
+  }
+  if (argv[0] === "keys" && argv[1] === "create") {
+    assertOnly(argv.slice(2), new Set(["--yes"]));
+    return { command: "keys-create", yes: argv.includes("--yes") };
+  }
+  if (argv[0] === "contract") {
+    assertOnly(argv.slice(1), new Set());
+    return { command: "contract" };
+  }
+  if (argv[0] === "apps" && argv[1] === "list") {
+    assertOnly(argv.slice(2), new Set(["--json"]));
+    return { command: "apps-list", json: argv.includes("--json") };
+  }
+  if (argv[0] === "apps" && argv[1] === "get") {
+    return {
+      command: "apps-get",
+      appKey: parseAppKey(argv, "Usage: requestshield apps get <app-key>"),
+    };
+  }
+  if (argv[0] === "challenge" && argv[1] === "volume") {
+    return parseChallengeVolume(argv);
+  }
+  if (argv[0] === "get" && argv[1] === "billing") {
+    return {
+      command: "billing-get",
+      appKey: parseAppKey(argv, "Usage: requestshield get billing <app-key>"),
+    };
+  }
+  if (argv[0] === "agent" && argv[1] === "setup") {
+    const rest = argv.slice(2);
+    /** @type {"codex" | "claude" | undefined} */
+    let agent;
+    let force = false;
+    for (let index = 0; index < rest.length; index++) {
+      const arg = rest[index];
+      if (arg === "--force") {
+        force = true;
+      } else if (arg === "--codex" || arg === "--claude") {
+        if (agent !== undefined) {
+          throw new CliError("Only one of --codex or --claude may be provided", {
+            code: "INVALID_AGENT",
+            exitCode: 2,
+          });
+        }
+        agent = arg === "--codex" ? "codex" : "claude";
+      } else {
+        throw new CliError(`Unknown option: ${arg}`, { exitCode: 2 });
+      }
+    }
+    return {
+      command: "agent-setup",
+      ...(agent ? { agent } : {}),
+      force,
+    };
+  }
+  throw new CliError(`Unknown command.\n\n${HELP}`, { exitCode: 2 });
+}
+
+/** @param {string[]} args @param {Set<string>} allowed */
+function assertOnly(args, allowed) {
+  for (const arg of args) {
+    if (!allowed.has(arg)) {
+      throw new CliError(`Unknown option: ${arg}`, { exitCode: 2 });
+    }
+  }
+}
+
+/** @param {string[]} argv @param {string} usage */
+function parseAppKey(argv, usage) {
+  if (argv.length !== 3) throw new CliError(usage, { exitCode: 2 });
+  return validateAppKey(argv[2]);
+}
+
+/** @param {string[]} argv @returns {Extract<ParsedArgs, {command: "challenge-volume"}>} */
+function parseChallengeVolume(argv) {
+  const usage = "Usage: requestshield challenge volume <app-key> [--from <time>] [--to <time>] [--granularity <value>]";
+  if (argv.length < 3) throw new CliError(usage, { exitCode: 2 });
+  const appKey = validateAppKey(argv[2]);
+  /** @type {{ from?: string, to?: string, granularity?: string }} */
+  const options = {};
+  /** @type {Map<string, "from" | "to" | "granularity">} */
+  const optionNames = new Map([
+    ["--from", "from"],
+    ["--to", "to"],
+    ["--granularity", "granularity"],
+  ]);
+  for (let index = 3; index < argv.length; index += 2) {
+    const option = argv[index];
+    const property = optionNames.get(option);
+    if (!property) throw new CliError(`Unknown option: ${option}`, { exitCode: 2 });
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--")) {
+      throw new CliError(`${option} requires a value`, { exitCode: 2 });
+    }
+    if (options[property] !== undefined) {
+      throw new CliError(`${option} may only be provided once`, { exitCode: 2 });
+    }
+    if ((property === "from" || property === "to") && !isIsoTime(value)) {
+      throw new CliError(`${option} must be an ISO-8601 timestamp`, {
+        code: "INVALID_TIME",
+        exitCode: 2,
+      });
+    }
+    if (property === "granularity" && !/^[a-z][a-z0-9_-]{0,31}$/.test(value)) {
+      throw new CliError(
+        "--granularity must be 1-32 lowercase letters, numbers, '_' or '-'",
+        { code: "INVALID_GRANULARITY", exitCode: 2 },
+      );
+    }
+    options[property] = value;
+  }
+  if (options.from && options.to && Date.parse(options.from) > Date.parse(options.to)) {
+    throw new CliError("--from must not be later than --to", {
+      code: "INVALID_TIME_RANGE",
+      exitCode: 2,
+    });
+  }
+  return { command: "challenge-volume", appKey, ...options };
+}
+
+/** @param {string} appKey */
+function validateAppKey(appKey) {
+  if (!/^[A-Za-z0-9._~-]{1,128}$/.test(appKey)) {
+    throw new CliError(
+      "App Key must be 1-128 characters using letters, numbers, '.', '_', '~', or '-'",
+      { code: "INVALID_APP_KEY", exitCode: 2 },
+    );
+  }
+  return appKey;
+}
+
+/** @param {string} value */
+function isIsoTime(value) {
+  return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:\d{2})$/.test(value)
+    && Number.isFinite(Date.parse(value));
+}
+
+export { HELP };

package/src/cli.mjs

@@ -1,51 +1,255 @@
-#!/usr/bin/env node
-// @ts-check
-
-import { parseArgs } from "./args.mjs";
-import { ManagementApiClient } from "./api-client.mjs";
-import { SessionStore } from "./session-store.mjs";
-import { signin } from "./commands/signin.mjs";
-import { createKeys } from "./commands/keys-create.mjs";
-import { setupAgent } from "./commands/agent-setup.mjs";
-import { checkForUpdate } from "./commands/update-check.mjs";
-import packageJson from "../package.json" with { type: "json" };
-
-/**
- * @param {string[]} argv
- * @param {{ log?: (message: string) => void, api?: ManagementApiClient, sessions?: SessionStore, env?: NodeJS.ProcessEnv, homeDir?: string, sourceDir?: string, executablePath?: string, detectAgents?: () => Promise<Array<"codex" | "claude">>, selectAgent?: (detected: Array<"codex" | "claude">) => Promise<"codex" | "claude">, wait?: (milliseconds: number) => Promise<unknown>, confirm?: () => Promise<boolean>, fetchImpl?: typeof fetch, confirmUpdate?: () => Promise<boolean>, installLatest?: (packageName: string, version: string) => Promise<void> }} [deps]
- */
-export async function run(argv, deps = {}) {
-  const parsed = parseArgs(argv);
-  const log = deps.log ?? ((message) => console.log(message));
-  if (parsed.command === "help") return log(parsed.help);
-  if (parsed.command === "version") return log("requestshield " + packageJson.version);
-  if (parsed.command === "update-check") {
-    return checkForUpdate({
-      currentVersion: packageJson.version,
-      packageName: packageJson.name,
-      log,
-      fetchImpl: deps.fetchImpl,
-      confirm: deps.confirmUpdate,
-      install: deps.installLatest,
-    });
-  }
-
-  if (parsed.command === "agent-setup") {
-    return setupAgent(parsed, { log, ...deps });
-  }
-
-  const env = deps.env ?? process.env;
-
-  const api = deps.api ?? new ManagementApiClient({
-    baseUrl:
-        env.REQUESTSHIELD_API_URL ??
-        "https://api.intellifend.ai",
-  });
-
-  const sessions = deps.sessions ?? new SessionStore({
-    env,
-    homeDir: deps.homeDir,
-  });
-  if (parsed.command === "signin") return signin({ api, sessions, log, ...deps });
-  if (parsed.command === "keys-create") return createKeys(parsed, { api, sessions, log, ...deps });
-}
+#!/usr/bin/env node
+// @ts-check
+
+import { parseArgs } from "./args.mjs";
+import { ManagementApiClient } from "./api-client.mjs";
+import { SessionStore } from "./session-store.mjs";
+
+import { signin } from "./commands/signin.mjs";
+import { createKeys } from "./commands/keys-create.mjs";
+import { showIntegrationContract } from "./commands/contract.mjs";
+import { listApps } from "./commands/apps-list.mjs";
+import { getApp } from "./commands/apps-get.mjs";
+import { showChallengeVolume } from "./commands/challenge-volume.mjs";
+import { showBilling } from "./commands/billing-get.mjs";
+import { setupAgent } from "./commands/agent-setup.mjs";
+import { checkForUpdate } from "./commands/update-check.mjs";
+
+import packageJson from "../package.json" with { type: "json" };
+import { DEFAULT_MANAGEMENT_API_URL } from "./config.mjs";
+
+/**
+ * @typedef {{
+ *   log: (message: string) => void,
+ *   api?: ManagementApiClient,
+ *   sessions?: SessionStore,
+ *   env?: NodeJS.ProcessEnv,
+ *   homeDir?: string,
+ *   sourceDir?: string,
+ *   executablePath?: string,
+ *   detectAgents?: () => Promise<Array<"codex" | "claude">>,
+ *   selectAgent?: (
+ *     detected: Array<"codex" | "claude">
+ *   ) => Promise<"codex" | "claude">,
+ *   wait?: (milliseconds: number) => Promise<unknown>,
+ *   confirm?: () => Promise<boolean>,
+ *   fetchImpl?: typeof fetch,
+ *   confirmUpdate?: () => Promise<boolean>,
+ *   installLatest?: (
+ *     packageName: string,
+ *     version: string
+ *   ) => Promise<void>
+ * }} CommandContext
+ */
+
+/**
+ * @typedef {CommandContext & {
+ *   api: ManagementApiClient,
+ *   sessions: SessionStore
+ * }} AuthenticatedCommandContext
+ */
+
+/**
+ * @typedef {{
+ *   requiresApiSession: boolean,
+ *   handler: (
+ *     parsed: any,
+ *     context: CommandContext
+ *   ) => unknown | Promise<unknown>
+ * }} CommandHandler
+ */
+
+/**
+ * Put every CLI command handler here.
+ *
+ * @type {Record<string, CommandHandler>}
+ */
+const COMMAND_HANDLERS = {
+  "help": {
+    requiresApiSession: false,
+    handler: (parsed, context) =>
+      context.log(parsed.help),
+  },
+
+  "version": {
+    requiresApiSession: false,
+    handler: (_parsed, context) =>
+      context.log(`requestshield ${packageJson.version}`),
+  },
+
+  "update-check": {
+    requiresApiSession: false,
+    handler: (_parsed, context) =>
+      checkForUpdate({
+        currentVersion: packageJson.version,
+        packageName: packageJson.name,
+        log: context.log,
+        fetchImpl: context.fetchImpl,
+        confirm: context.confirmUpdate,
+        install: context.installLatest,
+      }),
+  },
+
+  "agent-setup": {
+    requiresApiSession: false,
+    handler: (parsed, context) =>
+      setupAgent(parsed, context),
+  },
+
+  "signin": {
+    requiresApiSession: true,
+    handler: (_parsed, context) =>
+      signin(requireApiSession(context)),
+  },
+
+  "keys-create": {
+    requiresApiSession: true,
+    handler: (parsed, context) =>
+      createKeys(parsed, requireApiSession(context)),
+  },
+
+  "contract": {
+    requiresApiSession: true,
+    handler: (_parsed, context) =>
+      showIntegrationContract(requireApiSession(context)),
+  },
+
+  "apps-list": {
+    requiresApiSession: true,
+    handler: (parsed, context) =>
+      listApps(parsed, requireApiSession(context)),
+  },
+
+  "apps-get": {
+    requiresApiSession: true,
+    handler: (parsed, context) =>
+      getApp(parsed, requireApiSession(context)),
+  },
+
+  "challenge-volume": {
+    requiresApiSession: true,
+    handler: (parsed, context) =>
+      showChallengeVolume(parsed, requireApiSession(context)),
+  },
+
+  "billing-get": {
+    requiresApiSession: true,
+    handler: (parsed, context) =>
+      showBilling(parsed, requireApiSession(context)),
+  },
+};
+
+/**
+ * Narrow the shared context before an authenticated handler can use it.
+ *
+ * @param {CommandContext} context
+ * @returns {AuthenticatedCommandContext}
+ */
+function requireApiSession(context) {
+  if (!context.api || !context.sessions) {
+    throw new Error("Authenticated command context was not initialized");
+  }
+
+  return {
+    ...context,
+    api: context.api,
+    sessions: context.sessions,
+  };
+}
+
+/**
+ * @param {string[]} argv
+ * @param {{
+ *   log?: (message: string) => void,
+ *   api?: ManagementApiClient,
+ *   sessions?: SessionStore,
+ *   env?: NodeJS.ProcessEnv,
+ *   homeDir?: string,
+ *   sourceDir?: string,
+ *   executablePath?: string,
+ *   detectAgents?: () => Promise<Array<"codex" | "claude">>,
+ *   selectAgent?: (
+ *     detected: Array<"codex" | "claude">
+ *   ) => Promise<"codex" | "claude">,
+ *   wait?: (milliseconds: number) => Promise<unknown>,
+ *   confirm?: () => Promise<boolean>,
+ *   fetchImpl?: typeof fetch,
+ *   confirmUpdate?: () => Promise<boolean>,
+ *   installLatest?: (
+ *     packageName: string,
+ *     version: string
+ *   ) => Promise<void>
+ * }} [deps]
+ */
+export async function run(argv, deps = {}) {
+  const parsed = parseArgs(argv);
+
+  const log =
+    deps.log ??
+    ((message) => console.log(message));
+
+  /*
+   * Find the requested command.
+   */
+  const command = COMMAND_HANDLERS[parsed.command];
+
+  if (!command) {
+    throw new Error(
+      `Unsupported command: ${String(parsed.command)}`
+    );
+  }
+
+  /*
+  * Dependencies available to every command.
+  */
+  /** @type {CommandContext} */
+  const context = {
+    ...deps,
+    log,
+  };
+
+  /*
+   * Only initialize the Management API and session
+   * for commands that require them.
+   */
+  if (command.requiresApiSession) {
+    const env =
+      deps.env ??
+      process.env;
+
+    const api =
+      deps.api ??
+      new ManagementApiClient({
+        baseUrl:
+          env.REQUESTSHIELD_API_URL ??
+          DEFAULT_MANAGEMENT_API_URL,
+      });
+
+    const sessions =
+      deps.sessions ??
+      new SessionStore({
+        env,
+        homeDir: deps.homeDir,
+      });
+
+    const authenticatedContext = {
+      ...context,
+      env,
+      api,
+      sessions,
+    };
+
+    return command.handler(
+      parsed,
+      authenticatedContext
+    );
+  }
+
+  /*
+   * Execute commands that do not need an API session.
+   */
+  return command.handler(
+    parsed,
+    context
+  );
+}