@debugbundle/cli 1.12.0 → 1.13.0

package/README.md

@@ -65,6 +65,19 @@ The CLI reads local project configuration from `.debugbundle/` and can use membe
 
 ## AnalyticsBundle
 
+Public project flows support customer-defined acquisition and activation steps across sites,
+auth pages and apps. Read definitions and aggregate reports with:
+
+```bash
+debugbundle analytics flows list --project <project-id> --json
+debugbundle analytics flows report --project <project-id> --key onboarding --window 30d --json
+```
+
+Owners/admins can use `analytics flows save --project <project-id> --definition-json '<JSON>'`
+and `analytics flows archive --project <project-id> --key onboarding`. See the
+[flow contract](https://debugbundle.com/docs/api/analytics/#public-acquisition-and-activation-flows)
+for definitions, capture, full UTC day report windows, and partial coverage.
+
 Analytics commands require connected member authentication and a project with AnalyticsBundle enabled. They query aggregate rollups or request an asynchronous analysis artifact; they do not read raw analytics events.
 
 ```sh

package/dist/main.cjs

@@ -26224,7 +26224,7 @@ var require_codegen = __commonJS({
         return `${this.lhs} ${this.op}= ${this.rhs};` + _n;
       }
     };
-    var Label = class extends Node {
+    var Label2 = class extends Node {
       constructor(label) {
         super();
         this.label = label;
@@ -26655,7 +26655,7 @@ var require_codegen = __commonJS({
       }
       // `label` statement
       label(label) {
-        return this._leafNode(new Label(label));
+        return this._leafNode(new Label2(label));
       }
       // `break` statement
       break(label) {
@@ -73259,6 +73259,91 @@ var PROJECT_COLOR_TAG_VALUES = [
 ];
 var ProjectColorTagSchema = external_exports.enum(PROJECT_COLOR_TAG_VALUES);
 
+// ../../packages/shared-types/src/analytics-flows.ts
+var AnalyticsFlowKeySchema = external_exports.string().trim().regex(/^[a-z][a-z0-9_.-]{0,63}$/);
+var AnalyticsFlowOriginSchema = external_exports.string().max(255).refine((value) => {
+  try {
+    const url = new URL(value);
+    return url.origin === value && !url.username && !url.password && (url.protocol === "https:" || url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname));
+  } catch {
+    return false;
+  }
+}, "Use an exact HTTPS origin (HTTP is allowed for localhost).");
+var AnalyticsFlowDefinitionInputSchema = external_exports.object({
+  flow_key: AnalyticsFlowKeySchema,
+  display_name: external_exports.string().trim().min(1).max(120),
+  kind: external_exports.enum(["acquisition", "activation"]),
+  timeout_minutes: external_exports.number().int().min(10).max(1440).default(60),
+  steps: external_exports.array(
+    external_exports.object({
+      step_key: AnalyticsFlowKeySchema,
+      display_name: external_exports.string().trim().min(1).max(120),
+      origin: AnalyticsFlowOriginSchema
+    }).strict()
+  ).min(2).max(8)
+}).strict().refine(
+  (value) => new Set(value.steps.map((step) => step.step_key)).size === value.steps.length,
+  "Step keys must be unique."
+);
+var AnalyticsFlowDefinitionSchema = AnalyticsFlowDefinitionInputSchema.innerType().extend({
+  id: external_exports.string().uuid(),
+  project_id: external_exports.string().uuid(),
+  version: external_exports.number().int().positive(),
+  archived_at: external_exports.string().datetime().nullable()
+}).refine(
+  (value) => new Set(value.steps.map((step) => step.step_key)).size === value.steps.length,
+  "Step keys must be unique."
+);
+var Count = external_exports.number().int().nonnegative();
+var AnalyticsFlowReportSchema = external_exports.object({
+  flow: AnalyticsFlowDefinitionSchema,
+  window: external_exports.object({
+    from: external_exports.string().datetime(),
+    to: external_exports.string().datetime(),
+    previous_from: external_exports.string().datetime()
+  }),
+  starts: Count,
+  previous_starts: Count,
+  completions: Count,
+  steps: external_exports.array(
+    external_exports.object({
+      step_key: AnalyticsFlowKeySchema,
+      display_name: external_exports.string(),
+      reached: Count,
+      previous_reached: Count,
+      unlinked: Count,
+      dropoff: Count,
+      average_seconds: external_exports.number().nonnegative().nullable()
+    })
+  ).min(2).max(8),
+  sources: external_exports.array(
+    external_exports.object({ source: external_exports.string(), campaign: external_exports.string(), starts: Count, completions: Count })
+  ).max(50),
+  coverage: external_exports.object({
+    observation: external_exports.literal("explicit_integration_signals"),
+    incomplete: external_exports.literal(true),
+    sources_truncated: external_exports.boolean()
+  })
+});
+var AnalyticsFlowsResponseSchema = external_exports.object({
+  flows: external_exports.array(AnalyticsFlowDefinitionSchema).max(100)
+});
+var AnalyticsFlowResponseSchema = external_exports.object({ flow: AnalyticsFlowDefinitionSchema });
+var Secret = external_exports.string().regex(/^[A-Za-z0-9_-]{43}$/);
+var Label = external_exports.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._~+-]{0,99}$/);
+var Context = external_exports.object({ context: Secret, consent: external_exports.boolean().optional() });
+var AnalyticsFlowCaptureSchemas = {
+  start: Context.extend({
+    step_key: AnalyticsFlowKeySchema,
+    source: Label.optional(),
+    campaign: Label.optional()
+  }).strict(),
+  step: Context.extend({ step_key: AnalyticsFlowKeySchema }).strict(),
+  handoff: Context.extend({ step_key: AnalyticsFlowKeySchema, token: Secret }).strict(),
+  arrive: Context.extend({ token: Secret }).strict(),
+  withdraw: Context.strict()
+};
+
 // ../../packages/shared-types/src/index.ts
 var SeveritySchema = external_exports.enum(["low", "medium", "high", "critical"]);
 var BundleSdkSchema = external_exports.object({
@@ -100733,8 +100818,52 @@ function defineStorageSchemaMigration(input3) {
   };
 }
 
-// ../../packages/storage/src/browser-recovery-schema.ts
+// ../../packages/storage/src/analytics-flow-schema.ts
 var statements = [
+  `CREATE TABLE IF NOT EXISTS analytics_flow_definitions (
+    id uuid PRIMARY KEY, project_id uuid NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+    flow_key text NOT NULL, version integer NOT NULL DEFAULT 1, definition jsonb NOT NULL,
+    archived_at timestamptz, created_at timestamptz NOT NULL, updated_at timestamptz NOT NULL,
+    UNIQUE(project_id, flow_key)
+  )`,
+  `CREATE TABLE IF NOT EXISTS analytics_flow_runs (
+    id uuid PRIMARY KEY, flow_id uuid NOT NULL REFERENCES analytics_flow_definitions(id) ON DELETE CASCADE,
+    version integer NOT NULL, context_hash text NOT NULL UNIQUE, origin text NOT NULL,
+    start_index integer NOT NULL, last_index integer NOT NULL,
+    source text NOT NULL DEFAULT 'unknown', campaign text NOT NULL DEFAULT '',
+    started_at timestamptz NOT NULL, last_step_at timestamptz NOT NULL, expires_at timestamptz NOT NULL,
+    CHECK (start_index BETWEEN 0 AND 7 AND last_index BETWEEN start_index AND 7),
+    CHECK (expires_at > started_at AND expires_at <= started_at + interval '24 hours')
+  )`,
+  `CREATE INDEX IF NOT EXISTS analytics_flow_runs_expiry_idx ON analytics_flow_runs(expires_at, id)`,
+  `CREATE TABLE IF NOT EXISTS analytics_flow_handoffs (
+    id uuid PRIMARY KEY, run_id uuid NOT NULL REFERENCES analytics_flow_runs(id) ON DELETE CASCADE,
+    token_hash text NOT NULL UNIQUE, step_index integer NOT NULL, expires_at timestamptz NOT NULL,
+    redeemed_context_hash text, UNIQUE(run_id, step_index)
+  )`,
+  `CREATE INDEX IF NOT EXISTS analytics_flow_handoffs_expiry_idx ON analytics_flow_handoffs(expires_at, id)`,
+  `CREATE TABLE IF NOT EXISTS analytics_flow_rollups (
+    flow_id uuid NOT NULL REFERENCES analytics_flow_definitions(id) ON DELETE CASCADE,
+    version integer NOT NULL, cohort_date date NOT NULL, step_index integer NOT NULL,
+    source text NOT NULL, campaign text NOT NULL, reached bigint NOT NULL DEFAULT 0,
+    unlinked bigint NOT NULL DEFAULT 0, elapsed_ms double precision NOT NULL DEFAULT 0,
+    elapsed_count bigint NOT NULL DEFAULT 0,
+    PRIMARY KEY(flow_id, version, cohort_date, step_index, source, campaign)
+  )`,
+  `CREATE INDEX IF NOT EXISTS analytics_flow_rollups_expiry_idx ON analytics_flow_rollups(cohort_date, flow_id)`
+];
+var ANALYTICS_FLOW_BOOTSTRAP_STATEMENTS = statements.map(
+  (statement) => statement.replaceAll(" IF NOT EXISTS", "")
+);
+var migration = {
+  id: "202610030001_add_public_analytics_flows",
+  description: "Add customer project flow definitions, bounded continuity and aggregate reports.",
+  statements
+};
+var ANALYTICS_FLOW_SCHEMA_MIGRATIONS = [defineStorageSchemaMigration(migration)];
+
+// ../../packages/storage/src/browser-recovery-schema.ts
+var statements2 = [
   `ALTER TABLE alert_deliveries ADD COLUMN IF NOT EXISTS coalescing_key text`,
   `CREATE INDEX IF NOT EXISTS alert_deliveries_coalescing_idx ON alert_deliveries (alert_id, coalescing_key, created_at) WHERE coalescing_key IS NOT NULL`,
   `CREATE TABLE IF NOT EXISTS browser_recovery_events (
@@ -100756,10 +100885,10 @@ var BROWSER_RECOVERY_MIGRATIONS = [
   defineStorageSchemaMigration({
     id: "202609220001_add_browser_recovery_context",
     description: "Index browser recovery context and separate burst suppression from alert cooldown identity",
-    statements
+    statements: statements2
   })
 ];
-var BROWSER_RECOVERY_BOOTSTRAP_STATEMENTS = statements.filter((statement) => !statement.startsWith("ALTER TABLE")).map((statement) => statement.replaceAll(" IF NOT EXISTS", ""));
+var BROWSER_RECOVERY_BOOTSTRAP_STATEMENTS = statements2.filter((statement) => !statement.startsWith("ALTER TABLE")).map((statement) => statement.replaceAll(" IF NOT EXISTS", ""));
 
 // ../../packages/storage/src/availability-check-bootstrap-statements.ts
 var AVAILABILITY_CHECK_BOOTSTRAP_STATEMENTS = [
@@ -102734,7 +102863,8 @@ var STORAGE_BOOTSTRAP_STATEMENTS2 = [
   ...OPENAI_OAUTH_BOOTSTRAP_STATEMENTS,
   ...AVAILABILITY_CHECK_BOOTSTRAP_STATEMENTS,
   ...ANALYTICS_BOOTSTRAP_STATEMENTS,
-  ...WORKER_JOB_BOOTSTRAP_STATEMENTS
+  ...WORKER_JOB_BOOTSTRAP_STATEMENTS,
+  ...ANALYTICS_FLOW_BOOTSTRAP_STATEMENTS
 ];
 
 // ../../packages/storage/src/migrations.ts
@@ -104948,7 +105078,8 @@ var STORAGE_SCHEMA_MIGRATIONS2 = [
   ...AVAILABILITY_CHECK_STORAGE_SCHEMA_MIGRATIONS,
   ...ANALYTICS_STORAGE_SCHEMA_MIGRATIONS,
   ...OPENAI_OAUTH_STORAGE_SCHEMA_MIGRATIONS,
-  ...WORKER_JOB_SCHEMA_MIGRATIONS
+  ...WORKER_JOB_SCHEMA_MIGRATIONS,
+  ...ANALYTICS_FLOW_SCHEMA_MIGRATIONS
 ].sort((left, right) => left.id.localeCompare(right.id));
 
 // src/local-retrieval-store.ts
@@ -115211,6 +115342,10 @@ var CLI_USAGE_LINES = [
   "  debugbundle analytics saved-funnels create --project <id> --key <key> --name <name> --steps-json <json> [--auth-file <path>] [--json]",
   "  debugbundle analytics saved-funnels update <key> --project <id> [--name <name>] [--steps-json <json>] [--auth-file <path>] [--json]",
   "  debugbundle analytics saved-funnels archive <key> --project <id> [--auth-file <path>] [--json]",
+  "  debugbundle analytics flows list --project <id> [--auth-file <path>] [--json]",
+  "  debugbundle analytics flows save --project <id> --definition-json <json> [--auth-file <path>] [--json]",
+  "  debugbundle analytics flows report --project <id> --key <key> [--window <7d|30d|90d>] [--auth-file <path>] [--json]",
+  "  debugbundle analytics flows archive --project <id> --key <key> [--auth-file <path>] [--json]",
   "  debugbundle analytics summary --project <id> [--from <ISO8601>] [--to <ISO8601>] [--last <duration>] [--granularity <hour|day>] [--service <name>] [--environment <name>] [--limit <n>] [--auth-file <path>] [--json]",
   "  debugbundle analytics routes --project <id> [--from <ISO8601>] [--to <ISO8601>] [--last <duration>] [--granularity <hour|day>] [--service <name>] [--environment <name>] [--limit <n>] [--auth-file <path>] [--json]",
   "  debugbundle analytics journeys --project <id> [--from <ISO8601>] [--to <ISO8601>] [--last <duration>] [--granularity <hour|day>] [--service <name>] [--environment <name>] [--limit <n>] [--auth-file <path>] [--json]",
@@ -117261,6 +117396,103 @@ async function getAnalyticsJourneySampleWithAuthCommand(input3, dependencies) {
   });
 }
 
+// src/analytics-flow-commands.ts
+var AnalyticsFlowApiError = class extends Error {
+  constructor(status, message3) {
+    super(message3);
+    this.status = status;
+  }
+};
+function createAnalyticsFlowApi(http) {
+  const path = (input3) => `/v1/projects/${encodeURIComponent(input3.projectId)}/analytics/flows`;
+  async function request(input3, schema) {
+    const response = await http.request(input3);
+    if (response.status !== 200) {
+      const error2 = external_exports.object({ error: external_exports.string() }).safeParse(response.body);
+      throw new AnalyticsFlowApiError(
+        response.status,
+        error2.success ? error2.data.error : "Flow request failed."
+      );
+    }
+    const parsed = schema.safeParse(response.body);
+    if (!parsed.success) throw new AnalyticsFlowApiError(500, "Invalid flow response.");
+    return parsed.data;
+  }
+  return {
+    list: (input3) => request(
+      { method: "GET", path: path(input3), bearerToken: input3.bearerToken },
+      AnalyticsFlowsResponseSchema
+    ),
+    save: (input3) => {
+      const definition = AnalyticsFlowDefinitionInputSchema.parse(input3.definition);
+      return request(
+        {
+          method: "PUT",
+          path: `${path(input3)}/${definition.flow_key}`,
+          bearerToken: input3.bearerToken,
+          body: definition
+        },
+        AnalyticsFlowResponseSchema
+      );
+    },
+    archive: (input3) => request(
+      {
+        method: "DELETE",
+        path: `${path(input3)}/${encodeURIComponent(AnalyticsFlowKeySchema.parse(input3.flowKey))}`,
+        bearerToken: input3.bearerToken
+      },
+      external_exports.object({ archived: external_exports.literal(true) })
+    ),
+    report: (input3) => request(
+      {
+        method: "GET",
+        path: `${path(input3)}/${encodeURIComponent(input3.flowKey)}/report?window=${input3.window ?? "30d"}`,
+        bearerToken: input3.bearerToken
+      },
+      AnalyticsFlowReportSchema
+    )
+  };
+}
+async function analyticsFlowWithAuthCommand(input3, dependencies) {
+  return runAuthenticatedCliCommand(input3, {
+    dependencies,
+    async createApi(authInput, deps) {
+      const authState = await (deps?.readAuthState ?? readCliAuthState)(authInput);
+      return {
+        authState,
+        api: createAnalyticsFlowApi(
+          (deps?.createHttpClient ?? createCliHttpClient)({ baseUrl: authState.base_url })
+        )
+      };
+    },
+    async runCommand(auth, api) {
+      try {
+        const scope = { projectId: input3.projectId, bearerToken: auth.bearer_token };
+        let result;
+        if (input3.action === "list") result = await api.list(scope);
+        else if (input3.action === "save")
+          result = await api.save({
+            ...scope,
+            definition: AnalyticsFlowDefinitionInputSchema.parse(input3.definition)
+          });
+        else {
+          const item = { ...scope, flowKey: AnalyticsFlowKeySchema.parse(input3.flowKey) };
+          result = input3.action === "archive" ? await api.archive(item) : await api.report({
+            ...item,
+            ...input3.window === void 0 ? {} : { window: input3.window }
+          });
+        }
+        return { exitCode: 0, output: JSON.stringify(result, null, input3.json ? void 0 : 2) };
+      } catch (error2) {
+        return {
+          exitCode: error2 instanceof AnalyticsFlowApiError ? error2.status === 401 ? 2 : error2.status === 404 ? 3 : [400, 403, 409].includes(error2.status) ? 4 : 1 : 1,
+          output: error2 instanceof Error ? error2.message : "Flow request failed."
+        };
+      }
+    }
+  });
+}
+
 // src/management-analytics-command-handlers.ts
 function readFloatOption(parsedArgv, optionName) {
   const rawValue = readStringOption(parsedArgv, optionName);
@@ -117467,6 +117699,42 @@ function buildAnalyticsSettingsUpdate(parsedArgv) {
 }
 async function handleAnalyticsCommand(parsedArgv, dependencies) {
   const resource = requirePositional(parsedArgv, 1, "analytics resource");
+  if (resource === "flows") {
+    const action2 = requirePositional(parsedArgv, 2, "flows action");
+    if (!["list", "save", "archive", "report"].includes(action2))
+      throw new CliInputError("Unknown analytics flows command.");
+    expectNoUnknownOptions(parsedArgv, [
+      "project",
+      "project-id",
+      "key",
+      "definition-json",
+      "window",
+      "auth-file",
+      "json"
+    ]);
+    ensureNoExtraPositionals(parsedArgv, 3);
+    const projectId = readProjectOption(parsedArgv);
+    if (!projectId) throw new CliInputError("Missing required option --project.");
+    const flowKey = readStringOption(parsedArgv, "key");
+    if ((action2 === "report" || action2 === "archive") && !flowKey)
+      throw new CliInputError("Missing required option --key.");
+    const window2 = readStringOption(parsedArgv, "window");
+    if (window2 !== void 0 && window2 !== "7d" && window2 !== "30d" && window2 !== "90d")
+      throw new CliInputError("Invalid value for --window.");
+    const definition = action2 === "save" ? AnalyticsFlowDefinitionInputSchema.safeParse(
+      readJsonOption(parsedArgv, "definition-json")
+    ) : void 0;
+    if (definition && !definition.success) throw new CliInputError("Invalid flow definition.");
+    return await (dependencies.analyticsFlowCommand ?? analyticsFlowWithAuthCommand)(
+      appendCommonAuthOptions(parsedArgv, {
+        action: action2,
+        projectId,
+        ...flowKey === void 0 ? {} : { flowKey },
+        ...window2 === void 0 ? {} : { window: window2 },
+        ...definition?.success ? { definition: definition.data } : {}
+      })
+    );
+  }
   if (resource === "summary" || resource === "routes" || resource === "journeys" || resource === "devices" || resource === "referrers" || resource === "actions" || resource === "funnels") {
     expectNoUnknownOptions(parsedArgv, [
       "project",
@@ -124072,7 +124340,7 @@ async function handleCaptureRuleCommand2(parsedArgv, dependencies) {
 // package.json
 var package_default = {
   name: "@debugbundle/cli",
-  version: "1.12.0",
+  version: "1.13.0",
   private: false,
   description: "Command-line interface for DebugBundle",
   license: "Apache-2.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@debugbundle/cli",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "private": false,
   "description": "Command-line interface for DebugBundle",
   "license": "Apache-2.0",