@owlmetry/cli 0.1.6 → 0.1.7

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.6").description("OwlMetry CLI \u2014 query metrics and manage your apps from the terminal").addOption(
+var program2 = new Command().name("owlmetry").version("0.1.7").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,10 +1,12 @@
 ---
 name: owlmetry-cli
-version: 0.1.6
+version: 0.1.7
 description: >-
   Install the OwlMetry CLI, sign up, and manage projects, apps, metrics,
   funnels, and events. Use when adding OwlMetry to a project, querying
   analytics, or when another OwlMetry skill needs CLI setup as a prerequisite.
+  IMPORTANT: You MUST load this skill before running ANY `owlmetry` CLI
+  command. The CLI has non-obvious subcommand syntax and flags — do not guess.
 allowed-tools: Bash
 ---
 
@@ -14,11 +16,13 @@ OwlMetry is a self-hosted analytics platform for mobile and backend apps. It cap
 
 The **CLI** is the management and query tool — it does not ingest events. You use it to create projects and apps, define metrics and funnels, query event data, and view analytics. SDKs handle event ingestion using client keys (`owl_client_...`). The CLI uses agent keys (`owl_agent_...`) for reading data and managing resources.
 
+> **Do not guess CLI syntax.** The `owlmetry` command has specific subcommand patterns (e.g., `owlmetry apps` not `owlmetry apps list`, flags like `--format json` not `--message`). Always reference the command documentation in this skill file before running a command. If you haven't loaded this skill yet, load it first.
+
 ## Version Check
 
 Run these checks silently. Only inform the user if updates are available.
 
-1. **Skill version**: `curl -sf https://raw.githubusercontent.com/Jasonvdb/owlmetry/main/skills/owlmetry-cli/SKILL.md | head -5` — compare the `version:` field to `0.1.0`. If newer, ask the user if they want to update the local skill file.
+1. **Skill version**: `curl -sf https://raw.githubusercontent.com/Jasonvdb/owlmetry/main/skills/owlmetry-cli/SKILL.md | head -5` — compare the remote `version:` field to this file's `version:` frontmatter above. If the remote version is newer, ask the user if they want to update the local skill file.
 2. **CLI version** (if installed): compare `owlmetry --version` to `npm view @owlmetry/cli version 2>/dev/null`. If a newer version exists, offer `npm install -g @owlmetry/cli@latest`.
 
 If everything is current or the remote is unreachable, continue silently.

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

@@ -1,6 +1,6 @@
 ---
 name: owlmetry-node
-version: 0.1.6
+version: 0.1.7
 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
@@ -18,7 +18,7 @@ The SDK has zero runtime dependencies. All calls are non-blocking — events are
 
 Run these checks silently. Only inform the user if updates are available.
 
-1. **Skill version**: `curl -sf https://raw.githubusercontent.com/Jasonvdb/owlmetry/main/skills/owlmetry-node/SKILL.md | head -5` — compare the `version:` field to `0.1.0`. If newer, ask the user if they want to update.
+1. **Skill version**: `curl -sf https://raw.githubusercontent.com/Jasonvdb/owlmetry/main/skills/owlmetry-node/SKILL.md | head -5` — compare the remote `version:` field to this file's `version:` frontmatter above. If the remote version is newer, ask the user if they want to update.
 2. **SDK version**: `npm ls @owlmetry/node --json 2>/dev/null` for current version, `npm view @owlmetry/node version 2>/dev/null` for latest. If newer, offer `npm install @owlmetry/node@latest`.
 
 ## Prerequisite
@@ -27,6 +27,8 @@ You need an **ingest endpoint** and a **client key** (`owl_client_...`) for a ba
 
 If the user doesn't have these yet, follow the `/owlmetry-cli` skill first — it handles sign-up, project creation, and app creation. The ingest endpoint is saved to `~/.owlmetry/config.json` (`ingest_endpoint` field) and the client key is returned when creating an app.
 
+> **Any time you need to run an `owlmetry` CLI command** (querying events, creating metrics/funnels, listing apps, etc.), **load the `/owlmetry-cli` skill first**. Do not guess CLI syntax — it has non-obvious subcommand patterns and flags.
+
 ## Install
 
 ```bash
@@ -62,13 +64,24 @@ Owl.configure({
 **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) => { ... }));
+// AWS Lambda / generic serverless:
+export const handler = Owl.wrapHandler(async (event, context) => { ... });
+
+// Firebase Cloud Functions v2:
+// IMPORTANT: Explicitly type the request parameter — TypeScript cannot infer
+// the CallableRequest type through wrapHandler's generics.
+import { onCall, type CallableRequest } from 'firebase-functions/v2/https';
+
+export const myFunction = onCall(
+  Owl.wrapHandler(async (request: CallableRequest) => {
+    const { data, auth } = request;  // works — TypeScript knows the type
+    // ...
+  })
+);
 ```
 
+**TypeScript note:** `wrapHandler()` uses generic rest parameters (`<TArgs extends unknown[]>`), which means TypeScript sometimes infers handler parameters as `unknown` when the outer function (like Firebase's `onCall`) expects a specific callback type. If you see type errors like `Property 'data' does not exist on type 'unknown'`, explicitly annotate the handler's parameters (e.g., `request: CallableRequest`, `event: APIGatewayEvent`).
+
 ## 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:
@@ -97,16 +110,21 @@ Events are the core data unit. Use the four log levels to capture different kind
 
 - **`info`** — normal operations: server started, request handled, job completed, user action processed.
 - **`debug`** — verbose detail for development: cache lookups, query plans, config loading, intermediate state.
-- **`warn`** — recoverable problems: slow queries, rate limits approaching, fallback paths, deprecated API usage.
-- **`error`** — failures: database connection errors, external API failures, unhandled rejections, missing resources.
+- **`warn`** — something didn't go as expected but the process can continue: failed validation, precondition checks that fail, slow queries, rate limits approaching, fallback paths, deprecated API usage, missing optional config.
+- **`error`** — a caught exception or hard failure inside a `try`/`catch`: database connection errors, external API timeouts, unhandled rejections, file system errors. Reserve for actual thrown errors, not for anticipated validation outcomes.
 
 Choose **message strings** that are specific and searchable. Prefer `"Payment processing failed"` over `"error occurred"`. Use attributes for structured data you'll filter on later.
 
 ```typescript
 Owl.info('Server started', { port: 4000 });
 Owl.debug('Cache miss', { key: 'user:123' });
-Owl.warn('Slow query', { duration_ms: 2500, table: 'events' });
-Owl.error('Database connection failed', { host: 'db.example.com' });
+Owl.warn('Invalid request payload', { field: 'email', reason: 'missing' });
+
+try {
+  await db.connect();
+} catch (err) {
+  Owl.error('Database connection failed', { host: 'db.example.com', error: String(err) });
+}
 ```
 
 All methods: `Owl.info/debug/warn/error(message: string, attrs?: Record<string, unknown>)`.
@@ -118,7 +136,12 @@ Source module (file:line) is auto-captured from the call stack.
 Owl.info('Request handled', { method: 'POST', path: '/api/orders', status: 201 });
 Owl.info('Background job completed', { job: 'send-emails', processed: 150 });
 Owl.warn('Rate limit approaching', { current: 95, limit: 100, client_id: 'abc' });
-Owl.error('External API timeout', { service: 'stripe', endpoint: '/charges', timeout_ms: 10000 });
+
+try {
+  await stripe.charges.create(params);
+} catch (err) {
+  Owl.error('Stripe charge failed', { endpoint: '/charges', error: String(err) });
+}
 ```
 
 ## Per-Request User Scoping
@@ -339,7 +362,8 @@ When instrumenting a backend service, follow this priority:
 **Always instrument (events — no CLI setup needed):**
 - Server startup and shutdown (`info`)
 - Request handling: key route hits, responses sent (`info` with method/path/status)
-- Errors and failures: catch blocks, unhandled rejections, external API failures (`error`)
+- Caught exceptions: catch blocks, unhandled rejections, external API failures (`error`)
+- Validation failures and pre-checks: bad input, missing optional config, rate limits (`warn`)
 - Authentication events: login, logout, token refresh (`info`)
 - Core business actions: order placed, payment processed, email sent (`info`)
 - Background jobs: started, completed, failed (`info`/`error`)

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

@@ -1,6 +1,6 @@
 ---
 name: owlmetry-swift
-version: 0.1.6
+version: 0.1.7
 description: >-
   Integrate the OwlMetry Swift SDK into an iOS or macOS app for analytics,
   event tracking, metrics, funnels, and A/B experiments. Use when
@@ -18,7 +18,7 @@ The SDK is a static `Owl` enum with no external dependencies. All calls are non-
 
 Run these checks silently. Only inform the user if updates are available.
 
-1. **Skill version**: `curl -sf https://raw.githubusercontent.com/Jasonvdb/owlmetry/main/skills/owlmetry-swift/SKILL.md | head -5` — compare the `version:` field to `0.1.0`. If newer, ask the user if they want to update.
+1. **Skill version**: `curl -sf https://raw.githubusercontent.com/Jasonvdb/owlmetry/main/skills/owlmetry-swift/SKILL.md | head -5` — compare the remote `version:` field to this file's `version:` frontmatter above. If the remote version is newer, ask the user if they want to update.
 2. **SDK version**: Read `Package.resolved` for the current resolved revision, then compare against `curl -sf https://api.github.com/repos/Jasonvdb/owlmetry/releases/latest | jq -r .tag_name`. If newer, inform the user.
 
 ## Prerequisite
@@ -27,9 +27,16 @@ You need an **ingest endpoint** and a **client key** (`owl_client_...`) for an A
 
 If the user doesn't have these yet, follow the `/owlmetry-cli` skill first — it handles sign-up, project creation, and app creation. The ingest endpoint is saved to `~/.owlmetry/config.json` (`ingest_endpoint` field) and the client key is returned when creating an app.
 
+> **Any time you need to run an `owlmetry` CLI command** (querying events, creating metrics/funnels, listing apps, etc.), **load the `/owlmetry-cli` skill first**. Do not guess CLI syntax — it has non-obvious subcommand patterns and flags.
+
 ## Add Swift Package
 
-**Swift Package Manager (Package.swift):**
+**Minimum platforms:** iOS 16.0, macOS 13.0. Zero external dependencies.
+
+### Option A — Package.swift projects
+
+If the project has a `Package.swift`, add the dependency there:
+
 ```swift
 dependencies: [
     .package(url: "https://github.com/Jasonvdb/owlmetry.git", branch: "main")
@@ -42,29 +49,31 @@ Add to your target:
 ])
 ```
 
-**Xcode:** File > Add Package Dependencies > enter `https://github.com/Jasonvdb/owlmetry.git`, select branch `main`, add `OwlMetry` to your target.
+Then run `swift package resolve` to fetch the dependency.
 
-**Minimum platforms:** iOS 16.0, macOS 13.0. Zero external dependencies.
+### Option B — Xcode projects (.xcodeproj)
 
-## Verify Package Integration
+For `.xcodeproj`-based projects with no `Package.swift`, add the OwlMetry Swift package by editing `<Project>.xcodeproj/project.pbxproj` directly to add a remote Swift package reference for `https://github.com/Jasonvdb/owlmetry.git` (branch: `main`, product: `OwlMetry`). Do not ask the user to add it manually in Xcode.
 
-After adding the package, build the project to verify the dependency resolves and `import OwlMetry` compiles. Do not proceed with configuration until the build succeeds.
+### Option C — Ask the user (last resort)
 
-If the build fails with a "No such module 'OwlMetry'" error, ask the user to add the package manually in Xcode:
+If pbxproj editing fails or the project structure is too complex, ask the user to add the package in Xcode:
 
-1. Open the `.xcodeproj` or `.xcworkspace` in Xcode
-2. Select the project in the navigator (blue icon at the top)
-3. Select the app target under "Targets"
-4. Go to the "General" tab
-5. Scroll to "Frameworks, Libraries, and Embedded Content"
-6. Click the **+** button
-7. Click "Add Other…" > "Add Package Dependency…"
-8. Enter the URL: `https://github.com/Jasonvdb/owlmetry.git`
-9. Set "Dependency Rule" to **Branch** → `main`
-10. Click "Add Package"
-11. Select the **OwlMetry** library and click "Add Package"
+1. File > Add Package Dependencies
+2. Enter URL: `https://github.com/Jasonvdb/owlmetry.git`
+3. Set rule to **Branch** > `main`
+4. Add **OwlMetry** to the app target
+
+## Verify Package Integration
 
-Once the user confirms the package is added, retry the build to verify, then proceed with configuration.
+After adding the package, resolve dependencies and build:
+
+```bash
+xcodebuild -resolvePackageDependencies -project <path>.xcodeproj -quiet
+xcodebuild -project <path>.xcodeproj -scheme <SchemeName> -destination 'platform=iOS Simulator,name=iPhone 16' build -quiet
+```
+
+If the build succeeds, proceed with configuration. The "No such module 'OwlMetry'" warning in editors (SourceKit) is expected and resolves during a real `xcodebuild`.
 
 ## Configure
 
@@ -187,16 +196,26 @@ Events are the core unit of data in OwlMetry. Use the four log levels to capture
 
 - **`info`** — normal operations worth recording: screen views, user actions, feature usage, successful completions. This is your default level.
 - **`debug`** — verbose detail useful only during development: cache hits, state transitions, intermediate values. These are filtered out in production data mode.
-- **`warn`** — something unexpected that the app recovered from: slow responses, fallback paths taken, retries needed.
-- **`error`** — something failed: network errors, parse failures, missing data, caught exceptions.
+- **`warn`** — something didn't go as expected but the app can continue: failed validation, precondition checks that fail, slow responses, fallback paths taken, deprecated API usage, missing optional data.
+- **`error`** — a caught exception or hard failure inside a `do`/`catch` block: network errors, JSON decode failures, file I/O errors, keychain access failures. Reserve for actual thrown errors, not for anticipated validation outcomes.
 
 Choose **message strings** that are specific and searchable. Prefer `"Failed to load profile image"` over `"error"`. Use `screenName` to tie events to where they happened in the UI. Use `customAttributes` for structured data you'll want to filter or search on later.
 
 ```swift
+// In a screen context — pass screenName to tie the event to the screen
 Owl.info("User opened settings", screenName: "SettingsView")
 Owl.debug("Cache hit", screenName: "HomeView", customAttributes: ["key": "user_prefs"])
-Owl.warn("Slow network response", customAttributes: ["latency_ms": "1200"])
-Owl.error("Failed to load profile", screenName: "ProfileView")
+Owl.warn("Invalid email format", screenName: "SignUpView", customAttributes: ["input": email])
+
+do {
+    let profile = try await api.loadProfile(id: userId)
+} catch {
+    Owl.error("Failed to load profile", screenName: "ProfileView", customAttributes: ["error": "\(error)"])
+}
+
+// Outside a screen context — omit screenName entirely
+Owl.info("Background sync completed", customAttributes: ["items": "\(count)"])
+Owl.error("Keychain write failed", customAttributes: ["error": "\(error)"])
 ```
 
 All logging methods share the same signature:
@@ -204,6 +223,8 @@ All logging methods share the same signature:
 Owl.info(_ message: String, screenName: String? = nil, customAttributes: [String: String]? = nil)
 ```
 
+**`screenName` is optional.** Only pass it when the event originates from a specific screen in the UI (e.g., a button tap handler inside a view). **Do NOT pass `screenName`** when logging from utility functions, services, managers, network layers, background tasks, or anywhere that isn't directly tied to a visible screen. Passing a fabricated or guessed screen name is worse than omitting it — it pollutes screen-level analytics.
+
 Source file, function, and line are auto-captured.
 
 **Avoid logging PII** (emails, phone numbers, passwords) or high-frequency events (every frame, every scroll position). Focus on actions and outcomes.
@@ -328,7 +349,8 @@ When instrumenting a new app, follow this priority:
 - Screen views (`.owlScreen("ScreenName")` on every distinct screen)
 - App launch / cold start (`info` in `init()` or `didFinishLaunching`)
 - Authentication events (login, logout, signup)
-- Errors and failures (`error` in `catch` blocks, error handlers)
+- Caught exceptions (`error` in `catch` blocks, error handlers)
+- Validation failures and pre-checks (`warn` for bad input, missing optional data, fallback paths)
 - Core business actions (purchase, share, create, delete)
 
 **Instrument when relevant (metrics — requires CLI `owlmetry metrics create` first):**
@@ -341,8 +363,9 @@ When instrumenting a new app, follow this priority:
 
 **Where to place calls:**
 - 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
+- User actions: button action handlers, gesture callbacks — pass `screenName` since you know which screen the user is on
+- Errors: `catch` blocks, `Result.failure` handlers — pass `screenName` only if the error is caught inside a view; omit it if caught in a service, manager, or utility
+- Services, utilities, background tasks: log freely but **never pass `screenName`** — these are not screen-bound
 - Metrics: wrap the async operation between `startOperation()` and `complete()`/`fail()`
 
 **What NOT to instrument:**

package/package.json

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