@bigcommerce/catalyst 1.1.1 → 1.2.0

package/dist/cli.js

@@ -25,7 +25,7 @@ import { randomBytes, randomUUID } from "crypto";
 // package.json
 var package_default = {
   name: "@bigcommerce/catalyst",
-  version: "1.1.1",
+  version: "1.2.0",
   type: "module",
   repository: {
     type: "git",
@@ -119,6 +119,8 @@ function getUserConfig() {
 // src/cli/lib/telemetry.ts
 var TELEMETRY_KEY_ENABLED = "telemetry.enabled";
 var TELEMETRY_KEY_ID = `telemetry.anonymousId`;
+var TELEMETRY_FLUSH_INTERVAL_MS = 200;
+var TELEMETRY_HTTP_REQUEST_TIMEOUT_MS = 200;
 var Telemetry = class {
   constructor() {
     this.commandName = "unknown";
@@ -133,7 +135,10 @@ var Telemetry = class {
     this.correlationId = randomUUID();
     this.startTime = Date.now();
     this.analytics = new Analytics({
-      writeKey: "OCkxLj3KTc1N3ebEbnFBqbhxfE3tVb3Z"
+      writeKey: "OCkxLj3KTc1N3ebEbnFBqbhxfE3tVb3Z",
+      flushInterval: TELEMETRY_FLUSH_INTERVAL_MS,
+      httpRequestTimeout: TELEMETRY_HTTP_REQUEST_TIMEOUT_MS,
+      maxRetries: 0
     });
   }
   durationMs() {
@@ -2712,7 +2717,7 @@ function collectDiagnostics({
   env: env2 = process.env
 } = {}) {
   const state = getProjectState(cwd);
-  const telemetry3 = getTelemetry();
+  const telemetry2 = getTelemetry();
   const projectJson = readProjectJson(cwd);
   const storefront = readStorefrontInfo(cwd);
   const cliEnv = [{ source: "process.env", values: env2 }];
@@ -2764,8 +2769,8 @@ function collectDiagnostics({
       buildEnvVars: resolveEnvVars(buildEnv, BUILD_ENV_VARS)
     },
     telemetry: {
-      enabled: telemetry3.isEnabled(),
-      correlationId: telemetry3.correlationId
+      enabled: telemetry2.isEnabled(),
+      correlationId: telemetry2.correlationId
     },
     files: {
       ".env.local": existsSync5(join11(cwd, ".env.local")),
@@ -3147,8 +3152,8 @@ Example:
   const config2 = getProjectConfig();
   const apiHost = resolveApiHost(options, config2);
   const { storeHash, accessToken } = resolveCredentials(options, config2);
-  const telemetry3 = getTelemetry();
-  await telemetry3.identify(storeHash);
+  const telemetry2 = getTelemetry();
+  await telemetry2.identify(storeHash);
   const linkedProjectUuid = options.projectUuid ?? config2.get("projectUuid");
   let projectUuid;
   const promptForProject = async () => {
@@ -3301,7 +3306,22 @@ var logEntrySchema = z14.object({
   }).nullable().optional()
 });
 var queryLogsSchema = z14.object({
-  data: z14.array(logEntrySchema)
+  data: z14.array(logEntrySchema),
+  meta: z14.object({
+    cursor_pagination: z14.object({
+      // The REST proxy exposes page availability via links, while the
+      // gRPC response uses has_next_page/has_prev_page. Accept both while
+      // the API contract is transitioning.
+      has_next_page: z14.boolean().optional(),
+      has_prev_page: z14.boolean().optional(),
+      start_cursor: z14.string().nullable().optional(),
+      end_cursor: z14.string().nullable().optional(),
+      links: z14.object({
+        next: z14.string().optional(),
+        previous: z14.string().optional()
+      }).optional()
+    }).optional()
+  }).optional()
 });
 var v3ErrorSchema = z14.object({
   title: z14.string().optional(),
@@ -3416,6 +3436,8 @@ async function queryLogs(projectUuid, storeHash, accessToken, apiHost, params) {
   if (params.urlLike) search.set("url:like", params.urlLike);
   if (params.levelMin) search.set("level:min", params.levelMin);
   if (params.limit != null) search.set("limit", String(params.limit));
+  if (params.after) search.set("after", params.after);
+  if (params.before) search.set("before", params.before);
   const response = await fetch(
     `https://${apiHost}/stores/${storeHash}/v3/infrastructure/logs/${projectUuid}?${search.toString()}`,
     {
@@ -3434,7 +3456,9 @@ async function queryLogs(projectUuid, storeHash, accessToken, apiHost, params) {
     );
   }
   if (response.status === 404) {
-    throw new UserActionableError("Project not found. Check the project UUID.");
+    throw new UserActionableError(
+      "Project not found. Check the project UUID, and that --store-hash and --access-token belong to the store that owns the project."
+    );
   }
   if (response.status === 400 || response.status === 422) {
     const body = await response.json().catch(() => null);
@@ -4083,7 +4107,6 @@ var env = new Command8("env").configureHelp({ showGlobalOptions: true }).descrip
 import { Command as Command9, InvalidArgumentError as InvalidArgumentError4, Option as Option8 } from "commander";
 import { colorize as colorize10 } from "consola/utils";
 import { z as z16 } from "zod";
-var telemetry = new Telemetry();
 var DEFAULT_CONNECTION_TTL_MS = 1 * 60 * 1e3;
 var MAX_RETRIES = 5;
 var isFatalStatusCode = (status) => status >= 400 && status < 500;
@@ -4282,7 +4305,7 @@ Examples:
     const config2 = getProjectConfig();
     const apiHost = resolveApiHost(options, config2);
     const { storeHash, accessToken } = resolveCredentials(options, config2);
-    await telemetry.identify(storeHash);
+    await getTelemetry().identify(storeHash);
     const projectUuid = resolveProjectUuid(options);
     await tailLogs(projectUuid, storeHash, accessToken, apiHost, options.format);
   } catch (error) {
@@ -4297,17 +4320,68 @@ var parseIntInRange = (flag, min, max) => (value) => {
   }
   return parsed;
 };
+function invocationPrefix() {
+  const packageManager = process.env.npm_config_user_agent?.split("/")[0];
+  switch (packageManager) {
+    case "pnpm":
+    case "yarn":
+      return `${packageManager} catalyst`;
+    case "bun":
+      return "bunx catalyst";
+    case "npm":
+      return "npx catalyst";
+    default:
+      return "catalyst";
+  }
+}
+function printPaginationHints(pagination, start2, end, options) {
+  const hasNextPage = Boolean(pagination?.links?.next) || pagination?.has_next_page === true;
+  const hasPrevPage = Boolean(pagination?.links?.previous) || pagination?.has_prev_page === true;
+  const endCursor = pagination?.end_cursor;
+  const startCursor = pagination?.start_cursor;
+  if (!(hasNextPage && endCursor) && !(hasPrevPage && startCursor)) return;
+  const quoteArg = (value) => /\s/.test(value) ? `'${value}'` : value;
+  const baseFlags = [
+    `--start ${quoteArg(start2)}`,
+    `--end ${quoteArg(end)}`,
+    ...options.method ? [`--method ${quoteArg(options.method)}`] : [],
+    ...options.statusCode != null ? [`--status-code ${options.statusCode}`] : [],
+    ...options.urlLike ? [`--url-like ${quoteArg(options.urlLike)}`] : [],
+    ...options.levelMin ? [`--level-min ${options.levelMin}`] : [],
+    ...options.limit != null ? [`--limit ${options.limit}`] : [],
+    ...options.format !== "default" ? [`--format ${options.format}`] : []
+  ];
+  const command = `${invocationPrefix()} logs query ${baseFlags.join(" ")}`;
+  if (hasNextPage && endCursor) {
+    consola.info(`More results available. Next page:
+  ${command} --after ${quoteArg(endCursor)}`);
+  }
+  if (hasPrevPage && startCursor) {
+    consola.info(
+      `Newer results available. Previous page:
+  ${command} --before ${quoteArg(startCursor)}`
+    );
+  }
+}
 var query = new Command9("query").configureHelp({ showGlobalOptions: true }).description("Query historical logs from your deployed application.").addHelpText(
   "after",
   `
 Specify a time window with \`--since\` (relative to now) or \`--start\`/\`--end\`
 (ISO-8601 timestamps or Unix epoch seconds, UTC). The window may not exceed
-7 days. Entries print oldest-first; timestamps are UTC.
+7 days. Entries print oldest-first; timestamps are UTC. Page toward older
+entries by passing a previous page's end cursor to \`--after\` (the CLI prints
+a ready-to-run command when more entries are available), or toward newer
+entries with \`--before\`. Cursors are only valid with the same window and
+filters they came from. With \`--format json\`, the pagination cursors are
+emitted as a final \`{"meta": ...}\` line after the entries.
 
 Examples:
   # Last hour of logs
   $ catalyst logs query --since 1h
 
+  # Newest 20 errors in the window (follow the printed --after hint for more)
+  $ catalyst logs query --since 24h --level-min error --limit 20
+
   # Everything from today (UTC)
   $ catalyst logs query --start 2026-06-11T00:00:00Z
 
@@ -4334,7 +4408,20 @@ Examples:
 ).option("--url-like <substring>", "Filter by URL substring (case-sensitive).").addOption(
   new Option8("--level-min <level>", "Minimum log level.").choices(Array.from(LOG_LEVELS))
 ).addOption(
-  new Option8("--limit <n>", "Maximum number of entries to return (1-500).").argParser(parseIntInRange("--limit", 1, 500)).default(100)
+  new Option8(
+    "--limit <count>",
+    "Maximum entries per page (1-500). Defaults to the API default (100)."
+  ).argParser(parseIntInRange("--limit", 1, 500))
+).addOption(
+  new Option8(
+    "--after <cursor>",
+    "Return the page after (older than) this cursor, from a previous page's end_cursor."
+  ).conflicts("before")
+).addOption(
+  new Option8(
+    "--before <cursor>",
+    "Return the page before (newer than) this cursor, from a previous page's start_cursor."
+  )
 ).addOption(
   new Option8("--format <format>", "Output format for log entries.").choices(["json", "pretty", "default", "short", "request"]).default("default")
 ).action(async (options) => {
@@ -4342,7 +4429,7 @@ Examples:
     const config2 = getProjectConfig();
     const apiHost = resolveApiHost(options, config2);
     const { storeHash, accessToken } = resolveCredentials(options, config2);
-    await telemetry.identify(storeHash);
+    await getTelemetry().identify(storeHash);
     const projectUuid = resolveProjectUuid(options);
     const { start: start2, end } = resolveTimeWindow(options);
     const result = await queryLogs(projectUuid, storeHash, accessToken, apiHost, {
@@ -4352,13 +4439,22 @@ Examples:
       statusCode: options.statusCode,
       urlLike: options.urlLike,
       levelMin: options.levelMin,
-      limit: options.limit
+      limit: options.limit,
+      after: options.after,
+      before: options.before
     });
     const entries = result.data;
     const ordered = [...entries].reverse();
     if (options.format === "json") {
       ordered.forEach((entry) => process.stdout.write(`${JSON.stringify(entry)}
 `));
+      const cursorPagination = result.meta?.cursor_pagination;
+      if (cursorPagination) {
+        process.stdout.write(
+          `${JSON.stringify({ meta: { cursor_pagination: cursorPagination } })}
+`
+        );
+      }
       return;
     }
     if (options.format === "pretty") {
@@ -4374,11 +4470,7 @@ Examples:
     consola.info(
       `${entries.length} ${entries.length === 1 ? "entry" : "entries"} shown (oldest first, times in UTC).`
     );
-    if (entries.length === options.limit) {
-      consola.info(
-        `Limit of ${options.limit} reached; older entries may exist. Narrow the time window or raise --limit (max 500) to see more.`
-      );
-    }
+    printPaginationHints(result.meta?.cursor_pagination, start2, end, options);
   } catch (error) {
     consola.error(error instanceof Error ? error.message : error);
     process.exit(1);
@@ -4673,7 +4765,7 @@ import { Argument, Command as Command12, Option as Option9 } from "commander";
 import { colorize as colorize12 } from "consola/utils";
 var telemetryService = getTelemetry();
 var isEnabled = telemetryService.isEnabled();
-var telemetry2 = new Command12("telemetry").configureHelp({ showGlobalOptions: true }).description(
+var telemetry = new Command12("telemetry").configureHelp({ showGlobalOptions: true }).description(
   "View or change CLI telemetry collection status. Enabling telemetry helps BigCommerce support diagnose and troubleshoot errors you encounter when using the CLI."
 ).addHelpText(
   "after",
@@ -5402,17 +5494,17 @@ function getCommandPath(cmd) {
   return parts.join(" ");
 }
 var telemetryPreHook = async (thisCommand, actionCommand) => {
-  const telemetry3 = getTelemetry();
+  const telemetry2 = getTelemetry();
   const commandName = getCommandPath(actionCommand);
-  telemetry3.commandName = commandName;
-  return await telemetry3.track(commandName, {
+  telemetry2.commandName = commandName;
+  return await telemetry2.track(commandName, {
     ...parseArguments(thisCommand.args)
   });
 };
 var telemetryPostHook = async () => {
-  const telemetry3 = getTelemetry();
-  await telemetry3.track("command_completed", { durationMs: telemetry3.durationMs() });
-  await telemetry3.analytics.closeAndFlush();
+  const telemetry2 = getTelemetry();
+  await telemetry2.track("command_completed", { durationMs: telemetry2.durationMs() });
+  await telemetry2.analytics.closeAndFlush();
 };
 
 // src/cli/program.ts
@@ -5424,21 +5516,21 @@ consola.log(colorize13("cyanBright", `\u25E2 ${package_default.name} v${package_
 `));
 program.name(package_default.name).version(package_default.version).summary("CLI tool for Catalyst development").description(
   "CLI tool for Catalyst development.\n\nConfiguration priority: flags > process.env > .bigcommerce/project.json. `build` and `deploy` additionally load env files (--env-path, or an auto-loaded .env.local/.env) for the build.\n\nCATALYST_STORE_HASH falls back to BIGCOMMERCE_STORE_HASH if unset.\n\nRun `catalyst <command> --help` for details on a specific command."
-).configureHelp({ showGlobalOptions: true }).addCommand(version).addCommand(create2).addCommand(start).addCommand(build).addCommand(deploy).addCommand(domains).addCommand(logs).addCommand(project).addCommand(env).addCommand(channel).addCommand(auth).addCommand(upgrade).addCommand(telemetry2).addCommand(debug).hook("preAction", telemetryPreHook).hook("postAction", telemetryPostHook);
+).configureHelp({ showGlobalOptions: true }).addCommand(version).addCommand(create2).addCommand(start).addCommand(build).addCommand(deploy).addCommand(domains).addCommand(logs).addCommand(project).addCommand(env).addCommand(channel).addCommand(auth).addCommand(upgrade).addCommand(telemetry).addCommand(debug).hook("preAction", telemetryPreHook).hook("postAction", telemetryPostHook);
 
 // src/cli/index.ts
 var handleFatalError = async (error) => {
-  const telemetry3 = getTelemetry();
+  const telemetry2 = getTelemetry();
   const errorMessage = error instanceof Error ? error.message : String(error);
   const errorStack = error instanceof Error ? error.stack : void 0;
   try {
-    await telemetry3.track("error", {
-      commandName: telemetry3.commandName,
+    await telemetry2.track("error", {
+      commandName: telemetry2.commandName,
       errorMessage,
       errorStack,
-      durationMs: telemetry3.durationMs()
+      durationMs: telemetry2.durationMs()
     });
-    await telemetry3.analytics.closeAndFlush();
+    await telemetry2.analytics.closeAndFlush();
   } catch {
   }
   if (error instanceof UserActionableError) {
@@ -5446,9 +5538,9 @@ var handleFatalError = async (error) => {
     process.exit(1);
   }
   consola.error(errorMessage);
-  if (telemetry3.isEnabled()) {
+  if (telemetry2.isEnabled()) {
     consola.info(
-      `Correlation ID: ${telemetry3.correlationId}
+      `Correlation ID: ${telemetry2.correlationId}
 Share this Correlation ID with BigCommerce support.`
     );
   } else {