@owlmetry/cli 0.1.11 → 0.1.13

package/dist/index.cjs

@@ -6359,6 +6359,9 @@ var METRIC_PHASES = ["start", "complete", "fail", "cancel", "record"];
 // ../../packages/shared/dist/audit.js
 init_cjs_shims();
 
+// ../../packages/shared/dist/time.js
+init_cjs_shims();
+
 // src/commands/apps.ts
 var appsCommand = new Command("apps").description("Manage apps");
 appsCommand.command("list").description("List apps").option("--project-id <id>", "Filter by project ID").action(async (opts, cmd) => {
@@ -6492,33 +6495,6 @@ function resolveJsonArray(inline, filePath, opts) {
   return parsed;
 }
 
-// src/utils/time.ts
-init_cjs_shims();
-var RELATIVE_PATTERN = /^(\d+)([smhdw])$/;
-var MULTIPLIERS = {
-  s: 1e3,
-  m: 6e4,
-  h: 36e5,
-  d: 864e5,
-  w: 6048e5
-};
-function parseTimeInput(input) {
-  const match = input.match(RELATIVE_PATTERN);
-  if (match) {
-    const amount = parseInt(match[1], 10);
-    const unit = match[2];
-    const ms = amount * MULTIPLIERS[unit];
-    return new Date(Date.now() - ms).toISOString();
-  }
-  const date = new Date(input);
-  if (isNaN(date.getTime())) {
-    throw new Error(
-      `Invalid time input: "${input}". Use relative (e.g. 1h, 30m, 7d) or ISO 8601 format.`
-    );
-  }
-  return date.toISOString();
-}
-
 // src/utils/pagination.ts
 init_cjs_shims();
 function paginationHint(result) {
@@ -6538,8 +6514,8 @@ var eventsCommand = new Command("events").description("Query events").option("--
   new Option("--data-mode <mode>", "Data mode: production, development, or all").choices(["production", "development", "all"]).default("production")
 ).action(async (opts, cmd) => {
   const { client, globals } = createClient(cmd);
-  const since = opts.since ? parseTimeInput(opts.since) : !opts.until ? parseTimeInput("24h") : void 0;
-  const until = opts.until ? parseTimeInput(opts.until) : void 0;
+  const since = opts.since ?? (!opts.until ? "24h" : void 0);
+  const until = opts.until;
   const result = await client.queryEvents({
     project_id: opts.projectId,
     app_id: opts.appId,
@@ -6797,8 +6773,8 @@ metricsCommand.command("events <slug>").description("Query raw metric events for
   new Option("--data-mode <mode>", "Data mode: production, development, or all").choices(["production", "development", "all"]).default("production")
 ).action(async (slug, opts, cmd) => {
   const { client, globals } = createClient(cmd);
-  const since = opts.since ? parseTimeInput(opts.since) : !opts.until ? parseTimeInput("24h") : void 0;
-  const until = opts.until ? parseTimeInput(opts.until) : void 0;
+  const since = opts.since ?? (!opts.until ? "24h" : void 0);
+  const until = opts.until;
   const result = await client.queryMetricEvents(slug, opts.projectId, {
     phase: opts.phase,
     tracking_id: opts.trackingId,
@@ -6840,7 +6816,7 @@ metricsCommand.command("create").description("Create a new metric definition").r
   });
   output(globals.format, metric, () => formatMetricDetail(metric));
 });
-metricsCommand.command("query <slug>").description("Query metric aggregation").requiredOption("--project-id <id>", "Project ID").option("--since <date>", "Start date (ISO)").option("--until <date>", "End date (ISO)").option("--app-id <id>", "Filter by app ID").option("--app-version <version>", "Filter by app version").option("--device-model <model>", "Filter by device model").option("--os-version <version>", "Filter by OS version").option("--user-id <id>", "Filter by user ID").option("--environment <env>", "Filter by environment (ios, ipados, macos, android, web, backend)").option("--group-by <field>", "Group by: app_id, app_version, device_model, os_version, environment, time:hour, time:day, time:week").addOption(
+metricsCommand.command("query <slug>").description("Query metric aggregation").requiredOption("--project-id <id>", "Project ID").option("--since <date>", "Start time (e.g. 1h, 30m, 7d, or ISO 8601)").option("--until <date>", "End time (e.g. 1h, 30m, 7d, or ISO 8601)").option("--app-id <id>", "Filter by app ID").option("--app-version <version>", "Filter by app version").option("--device-model <model>", "Filter by device model").option("--os-version <version>", "Filter by OS version").option("--user-id <id>", "Filter by user ID").option("--environment <env>", "Filter by environment (ios, ipados, macos, android, web, backend)").option("--group-by <field>", "Group by: app_id, app_version, device_model, os_version, environment, time:hour, time:day, time:week").addOption(
   new Option("--data-mode <mode>", "Data mode: production, development, or all").choices(["production", "development", "all"]).default("production")
 ).action(async (slug, opts, cmd) => {
   const { client, globals } = createClient(cmd);
@@ -6899,7 +6875,7 @@ ${funnel.description}`);
     const step = funnel.steps[i];
     const filter = step.event_filter;
     const filterParts = [];
-    if (filter.message) filterParts.push(`message=${filter.message}`);
+    if (filter.step_name) filterParts.push(`step=${filter.step_name}`);
     if (filter.screen_name) filterParts.push(`screen=${filter.screen_name}`);
     lines.push(`  ${i + 1}. ${step.name}  ${source_default.dim(filterParts.join(", "))}`);
   }
@@ -7010,7 +6986,7 @@ funnelsCommand.command("delete <slug>").description("Delete a funnel definition"
   await client.deleteFunnel(slug, opts.projectId);
   console.log(source_default.green(`Funnel "${slug}" deleted.`));
 });
-funnelsCommand.command("query <slug>").description("Query funnel analytics").requiredOption("--project-id <id>", "Project ID").option("--since <date>", "Start date (ISO)").option("--until <date>", "End date (ISO)").option("--open", "Make this an open funnel. In an open funnel, users don't have to complete a previous step in order to be included in a subsequent step.").option("--app-version <version>", "Filter by app version").option("--environment <env>", "Filter by environment (ios, ipados, macos, android, web, backend)").option("--experiment <name:variant>", "Filter by experiment (format: name:variant)").option("--group-by <field>", "Group by: environment, app_version, or experiment:<name>").addOption(
+funnelsCommand.command("query <slug>").description("Query funnel analytics").requiredOption("--project-id <id>", "Project ID").option("--since <date>", "Start time (e.g. 1h, 30m, 7d, or ISO 8601)").option("--until <date>", "End time (e.g. 1h, 30m, 7d, or ISO 8601)").option("--open", "Make this an open funnel. In an open funnel, users don't have to complete a previous step in order to be included in a subsequent step.").option("--app-version <version>", "Filter by app version").option("--environment <env>", "Filter by environment (ios, ipados, macos, android, web, backend)").option("--experiment <name:variant>", "Filter by experiment (format: name:variant)").option("--group-by <field>", "Group by: environment, app_version, or experiment:<name>").addOption(
   new Option("--data-mode <mode>", "Data mode: production, development, or all").choices(["production", "development", "all"]).default("production")
 ).action(async (slug, opts, cmd) => {
   const { client, globals } = createClient(cmd);
@@ -7036,15 +7012,13 @@ auditLogCommand.command("list").description("List audit log entries").requiredOp
   new Option("--limit <n>", "Max entries to return").argParser((v) => parsePositiveInt(v, "--limit"))
 ).option("--cursor <cursor>", "Pagination cursor").action(async (opts, cmd) => {
   const { client, globals } = createClient(cmd);
-  const since = opts.since ? parseTimeInput(opts.since) : void 0;
-  const until = opts.until ? parseTimeInput(opts.until) : void 0;
   const result = await client.queryAuditLogs(opts.teamId, {
     resource_type: opts.resourceType,
     resource_id: opts.resourceId,
     actor_id: opts.actorId,
     action: opts.action,
-    since,
-    until,
+    since: opts.since,
+    until: opts.until,
     cursor: opts.cursor,
     limit: opts.limit
   });
@@ -7198,7 +7172,7 @@ var switchCommand = new Command("switch").description("Switch active team profil
 });
 
 // src/index.ts
-var program2 = new Command().name("owlmetry").version("0.1.11").description("OwlMetry CLI \u2014 query metrics and manage your apps from the terminal").addOption(
+var program2 = new Command().name("owlmetry").version("0.1.13").description("OwlMetry CLI \u2014 query metrics and manage your apps from the terminal").addOption(
   new Option("--format <format>", "Output format").choices(["table", "json", "log"]).default("table")
 ).option("--endpoint <url>", "OwlMetry API server URL").option("--api-key <key>", "API key").option("--ingest-endpoint <url>", "OwlMetry ingest endpoint URL (for SDKs; defaults to API endpoint for self-hosted)").option("--team <name-or-id>", "Use a specific team profile for this command");
 program2.addCommand(authCommand);

package/dist/skills/owlmetry-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: owlmetry-cli
-version: 0.1.11
+version: 0.1.13
 description: >-
   Install the OwlMetry CLI, sign up, and manage projects, apps, metrics,
   funnels, and events. Use when adding OwlMetry to a project, querying
@@ -106,6 +106,15 @@ Use the `client_key` from Step 3 to configure the appropriate SDK:
 
 Pass the **ingest endpoint** and client key to the SDK's `configure()` call. Read `~/.owlmetry/config.json` for the `ingest_endpoint` value (set during auth). For the hosted platform it's `https://ingest.owlmetry.com`. For self-hosted it defaults to the API endpoint.
 
+### Step 5 — Add to project's CLAUDE.md
+
+Add this to the project's `CLAUDE.md` so future sessions know OwlMetry is integrated and load the right skills:
+
+```markdown
+### OwlMetry
+Load the `/owlmetry-cli` skill before running any `owlmetry` CLI commands or doing analytics work — it links to the appropriate SDK skill for your platform.
+```
+
 ## Resource Hierarchy
 
 OwlMetry organises resources in a `Team → Project → Apps` hierarchy:
@@ -155,7 +164,7 @@ owlmetry metrics create --project-id <id> --name <name> --slug <slug> [--lifecyc
 owlmetry metrics update <slug> --project-id <id> [--name <name>] [--status active|paused] --format json
 owlmetry metrics delete <slug> --project-id <id>
 owlmetry metrics events <slug> --project-id <id> [--phase <phase>] [--user-id <id>] [--since <time>] [--until <time>] --format json
-owlmetry metrics query <slug> --project-id <id> [--since <date>] [--until <date>] [--app-id <id>] [--user-id <id>] [--group-by <field>] --format json
+owlmetry metrics query <slug> --project-id <id> [--since <time>] [--until <time>] [--app-id <id>] [--user-id <id>] [--group-by <field>] --format json
 
 # Funnels
 owlmetry funnels list --project-id <id> --format json
@@ -163,7 +172,7 @@ owlmetry funnels view <slug> --project-id <id> --format json
 owlmetry funnels create --project-id <id> --name <name> --slug <slug> --steps-file <path> [--description <desc>] --format json
 owlmetry funnels update <slug> --project-id <id> --steps-file <path> --format json
 owlmetry funnels delete <slug> --project-id <id>
-owlmetry funnels query <slug> --project-id <id> [--since <date>] [--until <date>] [--open] [--group-by <field>] --format json
+owlmetry funnels query <slug> --project-id <id> [--since <time>] [--until <time>] [--open] [--group-by <field>] --format json
 
 # Events
 owlmetry events [--project-id <id>] [--app-id <id>] [--level <level>] [--user-id <id>] [--session-id <id>] [--since <time>] [--limit <n>] --format json
@@ -227,9 +236,9 @@ Slugs: lowercase letters, numbers, hyphens only (`/^[a-z0-9-]+$/`).
 
 ### Funnel Definitions
 
-Funnels measure how users progress through a multi-step flow and where they drop off. Each funnel has an ordered list of steps, and each step has an `event_filter` that matches incoming events (by `message` and/or `screen_name`).
+Funnels measure how users progress through a multi-step flow and where they drop off. Each funnel has an ordered list of steps, and each step has an `event_filter` that matches on `step_name` and/or `screen_name`.
 
-SDKs emit funnel events via `track("step-name")`, which generates events with message `"track:step-name"`. The `event_filter` in each step must match these messages exactly.
+Step definitions match directly on the step name passed to `track()` in the SDK — no prefix or transformation needed.
 
 Funnels support two analysis modes:
 - **Closed mode** (default): sequential — a user must complete steps in order (step 2 only counts if step 1 was completed first). Use for linear flows like onboarding or checkout.
@@ -249,8 +258,8 @@ owlmetry funnels delete <slug> --project-id <id>
 # 1. Write steps to a JSON file
 cat > /tmp/funnel-steps.json << 'EOF'
 [
-  {"name": "Step Name", "event_filter": {"message": "track:step-name"}},
-  {"name": "Next Step", "event_filter": {"message": "track:next-step"}}
+  {"name": "Step Name", "event_filter": {"step_name": "step-name"}},
+  {"name": "Next Step", "event_filter": {"step_name": "next-step"}}
 ]
 EOF
 
@@ -266,7 +275,7 @@ owlmetry funnels update <slug> --project-id <id> --steps-file /tmp/updated-steps
 
 Inline `--steps '<json>'` also works but is error-prone in shell environments due to JSON quoting. Prefer `--steps-file`.
 
-Steps JSON format: `[{"name":"Step Name","event_filter":{"message":"track:step-name"}}]`
+Steps JSON format: `[{"name":"Step Name","event_filter":{"step_name":"step-name"}}]`
 
 ## Querying
 
@@ -308,7 +317,7 @@ There are two ways to look at metric data:
 
 ```bash
 owlmetry metrics events <slug> --project-id <id> [--phase start|complete|fail|cancel|record] [--tracking-id <id>] [--user-id <id>] [--since <time>] [--until <time>] [--environment <env>] [--data-mode <mode>] --format json
-owlmetry metrics query <slug> --project-id <id> [--since <date>] [--until <date>] [--app-id <id>] [--app-version <v>] [--environment <env>] [--user-id <id>] [--group-by app_id|app_version|device_model|os_version|environment|time:hour|time:day|time:week] [--data-mode <mode>] --format json
+owlmetry metrics query <slug> --project-id <id> [--since <time>] [--until <time>] [--app-id <id>] [--app-version <v>] [--environment <env>] [--user-id <id>] [--group-by app_id|app_version|device_model|os_version|environment|time:hour|time:day|time:week] [--data-mode <mode>] --format json
 ```
 
 ### Funnel Analytics
@@ -316,7 +325,7 @@ owlmetry metrics query <slug> --project-id <id> [--since <date>] [--until <date>
 Funnel queries return conversion rates and drop-off between steps. The output shows how many users entered each step and what percentage continued to the next. Use `--group-by` to segment results and compare conversion across environments, app versions, or A/B experiment variants.
 
 ```bash
-owlmetry funnels query <slug> --project-id <id> [--since <date>] [--until <date>] [--open] [--app-version <v>] [--environment <env>] [--experiment <name:variant>] [--group-by environment|app_version|experiment:<name>] [--data-mode <mode>] --format json
+owlmetry funnels query <slug> --project-id <id> [--since <time>] [--until <time>] [--open] [--app-version <v>] [--environment <env>] [--experiment <name:variant>] [--group-by environment|app_version|experiment:<name>] [--data-mode <mode>] --format json
 ```
 
 `--open` = open funnel mode (steps evaluated independently, not sequentially).

package/dist/skills/owlmetry-node/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: owlmetry-node
-version: 0.1.11
+version: 0.1.13
 description: >-
   Integrate the OwlMetry Node.js SDK into a backend service for server-side
   analytics, event tracking, metrics, funnels, and A/B experiments. Use when
@@ -175,7 +175,7 @@ const owl = Owl.withUser(userId);
 owl.track('checkout-completed', { item_count: '3' });
 ```
 
-Each `track()` call emits an info-level event with message `"track:<stepName>"`. Define matching funnels via `/owlmetry-cli`.
+The step name you pass to `track()` must match the `step_name` in the funnel definition's `event_filter`. For example, if the step filter is `{"step_name": "signup-started"}`, then call `Owl.track('signup-started')`. Define matching funnels via `/owlmetry-cli`.
 
 **Note:** `track()` attributes must be `Record<string, string>` (string values only).
 

package/dist/skills/owlmetry-swift/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: owlmetry-swift
-version: 0.1.11
+version: 0.1.13
 description: >-
   Integrate the OwlMetry Swift SDK into an iOS or macOS app for analytics,
   event tracking, metrics, funnels, and A/B experiments. Use when
@@ -256,10 +256,17 @@ Owl.clearUser(newAnonymousId: true)
 Funnels measure how users progress through a multi-step flow (onboarding, checkout, activation) and where they drop off. The system has three parts:
 
 1. **Define** the funnel server-side (via CLI or API) with ordered steps and event filters.
-2. **Track** steps client-side with `Owl.track("step-name")` — each call emits an event with message `"track:step-name"`.
+2. **Track** steps client-side with `Owl.track("step-name")`.
 3. **Query** analytics to see conversion rates and drop-off between steps.
 
-Choose step names that match the `event_filter` in your funnel definition. For example, if the step filter is `{"message": "track:welcome-screen"}`, then call `Owl.track("welcome-screen")`.
+The step name you pass to `Owl.track()` must match the `step_name` in the funnel definition's `event_filter`. For example, if the step filter is `{"step_name": "welcome-screen"}`, then call `Owl.track("welcome-screen")`.
+
+**Funnel design rules:**
+- Each step must be a point that **every user in the funnel passes through** on the way to the goal. If a step is conditional (e.g., paywall only shown to free users), it breaks the chain — users who skip it show as 0% conversion from that point.
+- Keep funnels focused on **one flow**. Don't combine "import a model" + "explore features" into one funnel — those are separate journeys with separate goals.
+- **Optional interactions are not steps.** Toggling a setting, viewing info, or using a tool are engagement events (log with `Owl.info()`), not funnel progression. A funnel step should represent the user moving closer to the goal.
+- Split alternative paths into **separate funnels**. If users can take a screenshot OR record a video, create two funnels — don't put both paths in one.
+- Aim for **3-6 steps** per funnel. Too few = no drop-off insight. Too many = noise.
 
 Use `attributes` when you need to segment funnel analytics later (e.g., by signup method or referral source).
 
@@ -270,15 +277,15 @@ Owl.track("complete-profile")
 Owl.track("first-post")
 ```
 
-Each `track()` call emits an info-level event with message `"track:<stepName>"`. Define matching funnel definitions via `/owlmetry-cli`:
+Define matching funnel definitions via `/owlmetry-cli`:
 ```bash
 # Write steps to a JSON file (avoids shell quoting issues)
 cat > /tmp/funnel-steps.json << 'EOF'
 [
-  {"name": "Welcome", "event_filter": {"message": "track:welcome-screen"}},
-  {"name": "Account", "event_filter": {"message": "track:create-account"}},
-  {"name": "Profile", "event_filter": {"message": "track:complete-profile"}},
-  {"name": "First Post", "event_filter": {"message": "track:first-post"}}
+  {"name": "Welcome", "event_filter": {"step_name": "welcome-screen"}},
+  {"name": "Account", "event_filter": {"step_name": "create-account"}},
+  {"name": "Profile", "event_filter": {"step_name": "complete-profile"}},
+  {"name": "First Post", "event_filter": {"step_name": "first-post"}}
 ]
 EOF
 
@@ -388,13 +395,27 @@ Owl.clearExperiments()
 - All events automatically include an `experiments` field with current assignments.
 - Query funnel analytics segmented by variant via CLI: `owlmetry funnels query <slug> --project <id> --group-by experiment:checkout-redesign`
 
+## What the SDK Tracks Automatically
+
+Do not re-implement any of these — they are built into the SDK and emitted without any code:
+
+- **`sdk:configured`** — emitted on `Owl.configure()`
+- **`sdk:backgrounded`** / **`sdk:foregrounded`** — app state transitions
+- **`sdk:shutdown`** — on `Owl.shutdown()`
+- **`session_id`** — fresh UUID per `configure()` call, included on every event
+- **`_launch_time_ms`** — app launch time, included in the `session_started` event
+- **`_connection`** — network type (wifi, cellular, etc.), included on every event
+- **Device model, OS version, locale** — included on every event
+- **`is_dev`** — automatically `true` in DEBUG builds
+
+You do NOT need to manually track app launch, app foreground/background, session start, network type, or device info. These are already covered.
+
 ## Instrumentation Strategy
 
 When instrumenting a new app, follow this priority:
 
 **Always instrument (events — no CLI setup needed):**
 - Screen views (`.owlScreen("ScreenName")` on every distinct screen)
-- App launch / cold start (`info` in `init()` or `didFinishLaunching`)
 - Authentication events (login, logout, signup)
 - Caught exceptions (`error` in `catch` blocks, error handlers)
 - Validation failures and pre-checks (`warn` for bad input, missing optional data, fallback paths)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmetry/cli",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "OwlMetry CLI — manage projects, apps, metrics, funnels, and events from the terminal. Includes AI skill files for agent-assisted development.",
   "type": "module",
   "license": "MIT",