@owlmetry/cli 0.1.3 → 0.1.6

package/dist/index.cjs

@@ -7183,7 +7183,7 @@ var switchCommand = new Command("switch").description("Switch active team profil
 });
 
 // src/index.ts
-var program2 = new Command().name("owlmetry").version("0.1.3").description("OwlMetry CLI \u2014 query metrics and manage your apps from the terminal").addOption(
+var program2 = new Command().name("owlmetry").version("0.1.6").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.3
+version: 0.1.6
 description: >-
   Install the OwlMetry CLI, sign up, and manage projects, apps, metrics,
   funnels, and events. Use when adding OwlMetry to a project, querying

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

@@ -1,6 +1,6 @@
 ---
 name: owlmetry-node
-version: 0.1.3
+version: 0.1.6
 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
@@ -37,6 +37,8 @@ Zero runtime dependencies. Node.js 20+. ESM only.
 
 ## Configure
 
+Place `Owl.configure()` in the **main entry point** of your service — the root `index.ts`, `server.ts`, or `app.ts` file where your server starts. It must run once at process startup, before any other `Owl` calls. Do **not** put it in a helper/utility file — it should be alongside your other top-level initialization (e.g., `express()`, `Fastify()`, Firebase `setGlobalOptions`).
+
 ```typescript
 import { Owl } from '@owlmetry/node';
 
@@ -57,6 +59,16 @@ Owl.configure({
 - Generates a fresh `sessionId` (UUID) on each `configure()` call
 - Registers a `beforeExit` handler to auto-flush on graceful shutdown
 
+**Serverless (Firebase Cloud Functions, AWS Lambda, Vercel):** After adding `Owl.configure()`, also wrap your exported handler functions with `Owl.wrapHandler()` to guarantee events are flushed before the runtime freezes. This is essential boilerplate for serverless — without it, buffered events are lost:
+
+```typescript
+// Before:
+export const myFunction = onCall(async (request) => { ... });
+
+// After:
+export const myFunction = onCall(Owl.wrapHandler(async (request) => { ... }));
+```
+
 ## Next Steps — Codebase Instrumentation
 
 Once `Owl.configure()` is in place and the project builds successfully, **you MUST stop here and ask the user** which area they'd like to instrument first — even if the user's original prompt asked you to "instrument the app." Do not proceed with any code changes until the user chooses. Present these three options:

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

@@ -1,6 +1,6 @@
 ---
 name: owlmetry-swift
-version: 0.1.3
+version: 0.1.6
 description: >-
   Integrate the OwlMetry Swift SDK into an iOS or macOS app for analytics,
   event tracking, metrics, funnels, and A/B experiments. Use when
@@ -68,7 +68,7 @@ Once the user confirms the package is added, retry the build to verify, then pro
 
 ## Configure
 
-Configuration must happen once, before any other `Owl` calls — typically in your `@main` App init or AppDelegate `didFinishLaunching`. Each `configure()` call generates a fresh `session_id` (UUID) that groups all subsequent events together. This means each app launch gets its own session, making it easy to see everything a user did in a single sitting.
+Configuration must happen once, as early as possible — in the `@main` App `init()` or AppDelegate `didFinishLaunching`. **Do not defer it** to a later point (e.g., after async setup or user consent). The SDK measures app launch time (`_launch_ms`) from process start to the `configure()` call, so placing it early gives an accurate cold-start metric. It also ensures no events are dropped before configuration. Each `configure()` call generates a fresh `session_id` (UUID) that groups all subsequent events together.
 
 ```swift
 import OwlMetry
@@ -94,19 +94,93 @@ struct MyApp: App {
 - `apiKey: String` — client key, must start with `owl_client_` (required)
 - `flushOnBackground: Bool` — auto-flush when app backgrounds (default: `true`)
 - `compressionEnabled: Bool` — gzip request bodies (default: `true`)
+- `networkTrackingEnabled: Bool` — auto-track URLSession HTTP requests (default: `true`)
 
 Auto-detects: bundle ID, debug mode (`#if DEBUG`). Auto-generates: session ID (fresh each launch).
 
+## User Identity (set up during initial configuration)
+
+After adding `Owl.configure()`, find where the app handles authentication and add `Owl.setUser()` / `Owl.clearUser()`. This is part of the basic setup — do it now, before moving on to instrumentation.
+
+Look for the auth state change handler (e.g., Firebase Auth listener, login/logout methods) and add:
+
+```swift
+// After successful login — claims all previous anonymous events for this user
+Owl.setUser(userId)
+
+// On logout — reverts to anonymous tracking
+Owl.clearUser()
+```
+
+**Where to find it:** Search for login/logout methods, auth state listeners, or session management code. Look for patterns like setting a user ID on other services (crash reporting, analytics), storing auth tokens, or clearing user state. Place `Owl.setUser()` right after the user ID becomes available. Place `Owl.clearUser()` in the sign-out/logout handler.
+
+The SDK automatically flushes buffered events before claiming identity, so anonymous events from before login are retroactively linked to the user.
+
 ## Next Steps — Codebase Instrumentation
 
-Once `Owl.configure()` is in place and the project builds successfully, **you MUST stop here and ask the user** which area they'd like to instrument first — even if the user's original prompt asked you to "instrument the app." Do not proceed with any code changes until the user chooses. Present these three options:
+Once `Owl.configure()` is in place and the project builds successfully, **you MUST stop here and ask the user** which area they'd like to instrument first — even if the user's original prompt asked you to "instrument the app." Do not proceed with any code changes until the user chooses. Present these options:
 
-1. **Event & error logging** — Audit the codebase for user actions, screen views, error handling, and key flows. Add `Owl.info()`, `Owl.warn()`, `Owl.error()` calls at meaningful points. This is SDK-only — no CLI setup required beyond what's already done.
-2. **Structured metrics** — Identify operations worth measuring (network requests, data loading, image processing, etc.). Add `Owl.startOperation()` / `Owl.recordMetric()` to track durations and success rates. **Requires CLI first:** each metric slug must be defined on the server via `owlmetry metrics create` (use the `/owlmetry-cli` skill) before the SDK can emit events for it.
-3. **Funnel tracking** — Identify user journeys (onboarding, checkout, key conversions). Add `Owl.track()` calls at each step to measure drop-off. **Requires CLI first:** the funnel definition (with steps and event filters) must be created via `owlmetry funnels create` (use the `/owlmetry-cli` skill) before tracking makes sense.
+1. **Screen tracking** — Add `.owlScreen("ScreenName")` to every distinct screen in the app. This is the quickest win — automatic screen view and time-on-screen tracking with a single modifier per screen. No CLI setup needed.
+2. **Event & error logging** — Audit the codebase for user actions, error handling, and key flows. Add `Owl.info()`, `Owl.warn()`, `Owl.error()` calls at meaningful points. This is SDK-only — no CLI setup required beyond what's already done.
+3. **Structured metrics** — Identify operations worth measuring (data loading, image processing, etc.). Add `Owl.startOperation()` / `Owl.recordMetric()` to track durations and success rates. **Requires CLI first:** each metric slug must be defined on the server via `owlmetry metrics create` (use the `/owlmetry-cli` skill) before the SDK can emit events for it.
+4. **Funnel tracking** — Identify user journeys (onboarding, checkout, key conversions). Add `Owl.track()` calls at each step to measure drop-off. **Requires CLI first:** the funnel definition (with steps and event filters) must be created via `owlmetry funnels create` (use the `/owlmetry-cli` skill) before tracking makes sense.
 
 After the user chooses, do a thorough audit of the entire codebase to find all relevant locations, then present a summary of proposed changes before making any edits.
 
+## Screen Tracking (`.owlScreen()`)
+
+The SDK provides a SwiftUI view modifier that automatically tracks screen appearances and time-on-screen with zero manual event calls.
+
+```swift
+struct HomeView: View {
+    var body: some View {
+        VStack { ... }
+            .owlScreen("Home")
+    }
+}
+
+struct SettingsView: View {
+    var body: some View {
+        Form { ... }
+            .owlScreen("Settings")
+    }
+}
+```
+
+**What it does automatically:**
+- On appear: emits `sdk:screen_appeared` (info level) with `screenName` set — included in production data
+- On disappear: emits `sdk:screen_disappeared` (debug level) with `screenName` set and `_duration_ms` attribute — only visible in dev data mode
+
+**Where to place it:** Attach `.owlScreen("ScreenName")` to the outermost view of each screen — typically on the `NavigationStack`, `Form`, `ScrollView`, or root `VStack`. Use it on every distinct screen in the app. Choose names that are short, readable, and consistent (e.g., `"Home"`, `"Settings"`, `"Profile"`, `"Checkout"`).
+
+**Prefer `.owlScreen()` over manual `Owl.info()` for screen views** — it handles both appear and disappear with duration tracking. Use manual `Owl.info()` with `screenName:` only for events within a screen (button taps, state changes), not for screen appearances themselves.
+
+## Network Request Tracking
+
+The SDK automatically tracks all URLSession HTTP requests made via completion handler APIs. This is **enabled by default** — no code needed beyond `Owl.configure()`. To disable:
+
+```swift
+try Owl.configure(
+    endpoint: "https://ingest.owlmetry.com",
+    apiKey: "owl_client_...",
+    networkTrackingEnabled: false
+)
+```
+
+**What it captures automatically:**
+- `_http_method` — GET, POST, etc.
+- `_http_url` — sanitized URL (scheme + host + path only, query params stripped for privacy)
+- `_http_status` — response status code
+- `_http_duration_ms` — request duration in milliseconds
+- `_http_response_size` — response body size in bytes
+- `_http_error` — error description (failures only)
+
+**Log levels:** `.info` for 2xx/3xx responses, `.warn` for 4xx/5xx, `.error` for network failures (no response).
+
+**Safety:** The SDK's own requests to the OwlMetry ingest endpoint are automatically filtered out. Query parameters are stripped from URLs to prevent accidental logging of tokens or user IDs.
+
+**Coverage:** Tracks requests made with `URLSession.dataTask(with:completionHandler:)` (both URL and URLRequest overloads). Delegate-based and async/await requests are not tracked in this version.
+
 ## Log Events
 
 Events are the core unit of data in OwlMetry. Use the four log levels to capture different kinds of information:
@@ -251,8 +325,8 @@ Owl.clearExperiments()
 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`)
-- Key screen views (`info` with `screenName` in `onAppear`)
 - Authentication events (login, logout, signup)
 - Errors and failures (`error` in `catch` blocks, error handlers)
 - Core business actions (purchase, share, create, delete)
@@ -266,7 +340,7 @@ When instrumenting a new app, follow this priority:
 - A/B experiments when testing alternative UI or flows
 
 **Where to place calls:**
-- Screen views: `.onAppear` modifiers in SwiftUI, `viewDidAppear` in UIKit
+- Screen views: `.owlScreen("Name")` on the outermost view of each screen (SwiftUI), `viewDidAppear` in UIKit
 - User actions: button action handlers, gesture callbacks
 - Errors: `catch` blocks, `Result.failure` handlers
 - Metrics: wrap the async operation between `startOperation()` and `complete()`/`fail()`
@@ -296,3 +370,10 @@ Every event automatically includes:
 - `_connection` — network type (wifi, cellular, ethernet, offline) via `NWPathMonitor`
 - `experiments` — current A/B experiment assignments
 - `environment` — specific runtime (ios, ipados, macos)
+
+**Auto-emitted lifecycle events** (no manual calls needed):
+- `sdk:session_started` — on `configure()`, includes `_launch_ms` (time from process start to configure)
+- `sdk:app_foregrounded` — when app enters foreground
+- `sdk:app_backgrounded` — when app enters background
+- `sdk:screen_appeared` (info) / `sdk:screen_disappeared` (debug) — when using `.owlScreen()` modifier (disappear includes `_duration_ms`)
+- `sdk:network_request` (info/warn/error) — URLSession HTTP requests with method, URL, status, duration (enabled by default, disable with `networkTrackingEnabled: false`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmetry/cli",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "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",