@owlmetry/cli 0.1.10 → 0.1.12

package/dist/index.cjs

@@ -6899,7 +6899,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(", "))}`);
   }
@@ -7198,7 +7198,7 @@ var switchCommand = new Command("switch").description("Switch active team profil
 });
 
 // src/index.ts
-var program2 = new Command().name("owlmetry").version("0.1.10").description("OwlMetry CLI \u2014 query metrics and manage your apps from the terminal").addOption(
+var program2 = new Command().name("owlmetry").version("0.1.12").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.10
+version: 0.1.12
 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:
@@ -116,6 +125,14 @@ OwlMetry organises resources in a `Team → Project → Apps` hierarchy:
 
 Projects group apps cross-platform: an iOS app and its backend API can share the same project, enabling unified funnel and metric analysis across both.
 
+## Discovering IDs
+
+Always use CLI commands to get IDs — never read `~/.owlmetry/config.json` directly.
+
+- **Team ID**: `owlmetry whoami --format json` → `.teams[].id`
+- **Project ID**: `owlmetry projects --format json` → `[].id`
+- **App ID**: `owlmetry apps list --format json` → `[].id` (also returns `client_key`)
+
 ## Command Quick Reference
 
 Copy-paste ready. All commands support `--format json` for machine-readable output. Global flags: `--endpoint <url>`, `--api-key <key>`, `--team <name-or-id>`.
@@ -219,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.
@@ -241,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
 
@@ -258,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
 

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

@@ -1,6 +1,6 @@
 ---
 name: owlmetry-node
-version: 0.1.10
+version: 0.1.12
 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.10
+version: 0.1.12
 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.10",
+  "version": "0.1.12",
   "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",