requestshield 0.1.3 → 0.1.5

package/src/api-client.mjs

@@ -2,6 +2,14 @@
 
 import { CliError } from "./errors.mjs";
 
+const API_ENDPOINTS = {
+  SIGNIN: "/v1/cli/signin",
+  SIGNIN_TOKEN: "/v1/cli/signin/token",
+  KEYS_ROTATE: "/v1/cli/keys/rotate",
+  INTEGRATION_CONTRACT: "/v1/integration-contract",
+  APPLICATIONS: "/v1/applications",
+};
+
 export class ManagementApiClient {
   /** @param {{ baseUrl: string, fetchImpl?: typeof fetch }} options */
   constructor({ baseUrl, fetchImpl = fetch }) {
@@ -21,7 +29,7 @@ export class ManagementApiClient {
   }
 
   async startSignin() {
-    return this.#request("/v1/cli/signin", {
+    return this.#request(API_ENDPOINTS.SIGNIN, {
       method: "POST",
       body: JSON.stringify({ client: "requestshield-cli" }),
     });
@@ -30,7 +38,7 @@ export class ManagementApiClient {
   /** @param {string} deviceCode */
   async pollSignin(deviceCode) {
     return this.#request(
-      "/v1/cli/signin/token",
+      API_ENDPOINTS.SIGNIN_TOKEN,
       { method: "POST", body: JSON.stringify({ deviceCode }) },
       true,
     );
@@ -38,13 +46,97 @@ export class ManagementApiClient {
 
   /** @param {string} accessToken */
   async rotateKeys(accessToken) {
-    return this.#request("/v1/cli/keys/rotate", {
+    return this.#request(API_ENDPOINTS.KEYS_ROTATE, {
       method: "POST",
       headers: { Authorization: `Bearer ${accessToken}` },
       body: "{}",
     });
   }
 
+  /** @param {string} accessToken */
+  async integrationContract(accessToken) {
+    return this.#request(API_ENDPOINTS.INTEGRATION_CONTRACT, {
+      method: "GET",
+      headers: {
+        Accept: "application/json",
+        Authorization: `Bearer ${accessToken}`,
+      },
+    });
+  }
+
+  /** @param {string} accessToken */
+  async listApps(accessToken) {
+    return this.#request(API_ENDPOINTS.APPLICATIONS, {
+      method: "GET",
+      headers: {
+        Accept: "application/json",
+        Authorization: `Bearer ${accessToken}`,
+      },
+    });
+  }
+
+  /** @param {string} accessToken @param {string} appKey */
+  async getApp(accessToken, appKey) {
+    return this.#request(
+      `${API_ENDPOINTS.APPLICATIONS}/${encodeURIComponent(appKey)}`,
+      {
+        method: "GET",
+        headers: {
+          Accept: "application/json",
+          Authorization: `Bearer ${accessToken}`,
+        },
+      },
+    );
+  }
+
+  /**
+   * @param {string} accessToken
+   * @param {string} appKey
+   * @param {{ from?: string, to?: string, granularity?: string }} options
+   */
+  async challengeVolume(accessToken, appKey, options) {
+    const query = new URLSearchParams();
+
+    if (options.from)
+      query.set("from", options.from);
+
+    if (options.to)
+      query.set("to", options.to);
+
+    if (options.granularity)
+      query.set("granularity", options.granularity);
+
+    const suffix = query.size > 0 ? `?${query}` : "";
+
+    const endpoint =
+      `${API_ENDPOINTS.APPLICATIONS}/` +
+      `${encodeURIComponent(appKey)}/challenge-volume` +
+      suffix;
+
+    return this.#request(endpoint, {
+      method: "GET",
+      headers: {
+        Accept: "application/json",
+        Authorization: `Bearer ${accessToken}`,
+      },
+    });
+  }
+
+
+  /** @param {string} accessToken @param {string} appKey */
+  async getBilling(accessToken, appKey) {
+    return this.#request(
+      `${API_ENDPOINTS.APPLICATIONS}/${encodeURIComponent(appKey)}/billing`,
+      {
+        method: "GET",
+        headers: {
+          Accept: "application/json",
+          Authorization: `Bearer ${accessToken}`,
+        },
+      },
+    );
+  }
+
   /**
    * @param {string} path
    * @param {RequestInit} init
@@ -77,10 +169,13 @@ export class ManagementApiClient {
       }
     }
     if (!response.ok && !allowErrorBody) {
-      const detail = objectString(body, "message") ?? `HTTP ${response.status}`;
+      const nestedError = body && typeof body === "object" ? Reflect.get(body, "error") : undefined;
+      const detail = objectString(nestedError, "message")
+        ?? objectString(body, "message")
+        ?? `HTTP ${response.status}`;
       const exitCode = response.status === 401 || response.status === 403 ? 3 : 1;
       throw new CliError(`RequestShield API error: ${detail}`, {
-        code: objectString(body, "code") ?? "API_ERROR",
+        code: objectString(nestedError, "code") ?? objectString(body, "code") ?? "API_ERROR",
         exitCode,
       });
     }

package/src/args.mjs

@@ -2,22 +2,34 @@
 
 import { CliError } from "./errors.mjs";
 
-const HELP = `RequestShield customer CLI
+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: "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
  */
 
@@ -26,9 +38,13 @@ 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")) {
+  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" };
@@ -37,6 +53,29 @@ export function parseArgs(argv) {
     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} */
@@ -76,4 +115,74 @@ function assertOnly(args, allowed) {
   }
 }
 
+/** @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

@@ -4,37 +4,252 @@
 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> }} [deps]
+ * @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(packageJson.version);
 
-  if (parsed.command === "agent-setup") {
-    return setupAgent(parsed, { log, ...deps });
+  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)}`
+    );
   }
 
-  const env = deps.env ?? process.env;
+  /*
+  * 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 ??
-        "https://api.intellifend.ai",
-  });
+    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
+    );
+  }
 
-  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 });
+  /*
+   * Execute commands that do not need an API session.
+   */
+  return command.handler(
+    parsed,
+    context
+  );
 }

package/src/commands/apps-get.mjs

@@ -0,0 +1,64 @@
+// @ts-check
+
+import { CliError } from "../errors.mjs";
+import { objectString } from "../api-client.mjs";
+
+const APPLICATION_STATUSES = new Set(["ready", "active", "deactivated"]);
+
+/**
+ * @param {{ appKey: string }} options
+ * @param {{ api: { getApp(accessToken: string, appKey: string): Promise<{body: unknown}> }, sessions: { loadToken(): Promise<string> }, log: (message: string) => void }} deps
+ */
+export async function getApp(options, deps) {
+  const accessToken =
+    await deps.sessions.loadToken();
+  
+  const result =
+    await deps.api.getApp(accessToken, options.appKey);
+  
+  const app =
+    parseApp(result.body, options.appKey);
+  
+  deps.log(JSON.stringify({ ok: true, data: app }, null, 2));
+}
+
+/** @param {unknown} body @param {string} requestedAppKey */
+function parseApp(body, requestedAppKey) {
+  const ok = body && typeof body === "object" ?
+    Reflect.get(body, "ok") : undefined;
+  
+  const data = body && typeof body === "object" ?
+    Reflect.get(body, "data") : undefined;
+  
+  if (ok !== true || !data || typeof data !== "object" || Array.isArray(data)) {
+    throw invalidResponse(
+      "The application response did not contain ok=true and data"
+    );
+  }
+
+  const appKey = objectString(data, "app_key");
+  const appName = objectString(data, "name");
+  const status = objectString(data, "status");
+
+  if (appKey !== requestedAppKey) {
+    throw invalidResponse("The application response did not match the requested App Key");
+  }
+
+  if (!appName) {
+    throw invalidResponse("The application response did not contain name");
+  }
+
+  if (!status || !APPLICATION_STATUSES.has(status)) {
+    throw invalidResponse(
+      "The application response status must be ready, active, or deactivated",
+    );
+  }
+
+  // Construct a new object so unexpected response fields, especially secrets, cannot be printed.
+  return { app_key: appKey, name: appName, status };
+}
+
+/** @param {string} message */
+function invalidResponse(message) {
+  return new CliError(message, { code: "INVALID_RESPONSE" });
+}