luciq-cli 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b148325e3ea055acf54acad389f7d5617534b687bf06125fb2b5fd565150d23
-  data.tar.gz: 6faf85d4ff073213742b72294db3e95a0e22e802e559d3cfdd0e8957822e1849
+  metadata.gz: 6882405a8d129fe6337191a3fafcf09ce88290166b640acb36c016af9c4bdd35
+  data.tar.gz: 866a5f76f6d8d1b922b24c73dc33687c9a9cd7dc8a139722d449c129b8e474a5
 SHA512:
-  metadata.gz: 924ab969fefff13e013d4412414626b530dbcd81e46683dc471d70357e190122eec1eb730dfd6b12636dbd49573c1498d7b8ce5593e920bac9082635e945f9f8
-  data.tar.gz: 8ef521174571a0db1a2eefc181b39c291ace667f3dd21251a15cf193bb35aed06d4b310b93f28bcd1cdfced0a09407a157b0f9a46456722214ae21221eb4df34
+  metadata.gz: 2c48c7bbb0a56349d8bd41e9ad78a7b4c459a50e0befa5dd1b69a2eb98beca174c3fb1cfdbfba1d2815b55ab9b8eb96b75738f5b49abf4c9ee45d19b9bc208e9
+  data.tar.gz: 5eb8bc3833309adfb682cfcf3c13b2c4690803a4086df71f8fa8b6d23be99b865bdcbbb144d390d65b0b4f46b6e6377da79e894dfb168daac14bdd795729f561

data/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-07-05
+
+### Added
+
+- `luciq crashes` - Query crashes: `list`, `show`, `patterns`, `diagnostics`, `hangs`, `occurrence-tokens`, `occurrence`
+- `luciq bugs` - Query and update bugs: `list`, `show`, `update` (status, priority, tags, duplicate marking)
+- `luciq apm` - Query APM data: `groups`, `group`, `occurrence`, and funnels (`funnel-events`, `funnel-create`, `funnel-update`, `funnel-delete`)
+- `luciq reviews list` - Query app reviews
+- `luciq surveys` - Query surveys: `list`, `show`
+- `luciq apps list` - List accessible applications
+- `luciq insights` - Show aggregated app-health insights
+- `luciq issues list` - List issues across sources ranked by impact
+- `luciq opportunities` - Query opportunities: `list`, `show`
+- `luciq alerts` - Manage alert rules: `list`, `show`, `init`, `create`, `update`, `delete`
+- `luciq incidents` - Manage triggered alerts: `list`, `show`, `resolve`, `reopen`
+- Typed filter flags with a raw `--filters` JSON escape hatch on query commands
+
 ## [0.1.0] - 2025-12-16
 
 ### Added

data/README.md

@@ -1,6 +1,8 @@
 # Luciq CLI
 
-Command-line interface for uploading symbol files to Luciq.
+Command-line interface for Luciq: upload symbol files and query or manage your
+app data — crashes, bugs, APM, reviews, surveys, issues, opportunities, alerts,
+and more.
 
 ## Installation
 
@@ -46,10 +48,10 @@ luciq login --auth-token YOUR_CLI_TOKEN
 
 ### 2. Upload Symbol Files
 
-Upload Android mapping files (`.zip` containing a single mapping text file):
+Upload Android mapping files (`mapping.txt`):
 
 ```bash
-luciq upload android-mapping mapping.zip \
+luciq upload android-mapping mapping.txt \
   --app-token YOUR_APP_TOKEN \
   --version-name 1.0.0 \
   --version-code 1
@@ -69,8 +71,214 @@ luciq upload android-mapping mapping.zip \
 | `luciq logout` | Remove saved authentication |
 | `luciq whoami` | Show current authenticated user |
 | `luciq info` | Show CLI configuration |
-| `luciq upload android-mapping FILE` | Upload Android mapping file |
 | `luciq version` | Show CLI version |
+| `luciq upload` | Upload symbol files (see below) |
+| `luciq crashes` | Query crashes, hangs, and occurrences |
+| `luciq bugs` | Query and update bugs |
+| `luciq apm` | Query APM metrics and manage funnels |
+| `luciq reviews` | Query app store reviews |
+| `luciq surveys` | Query surveys and their responses |
+| `luciq apps` | List accessible applications |
+| `luciq issues` | List issues across sources, ranked by impact |
+| `luciq opportunities` | Query product opportunities |
+| `luciq alerts` | Manage alert rules |
+| `luciq incidents` | Manage triggered alerts |
+| `luciq insights` | Show aggregated app-health insights |
+
+See [Query & management commands](#query--management-commands) for the full option
+set of the data commands.
+
+### Upload commands
+
+Run `luciq upload help SUBCOMMAND` for the full options of any command.
+
+**iOS**
+
+| Command | File | Description |
+|---------|------|-------------|
+| `luciq upload ios-dsym FILE` | `.zip` | iOS dSYM symbols |
+
+**Android**
+
+| Command | File | Description |
+|---------|------|-------------|
+| `luciq upload android-mapping FILE` | `mapping.txt` | Proguard/R8 mapping file |
+| `luciq upload android-ndk FILE` | `.zip` | NDK `.so` shared object files (`--arch`) |
+
+**React Native**
+
+| Command | File | Description |
+|---------|------|-------------|
+| `luciq upload react-native-ios-dsym FILE` | `.zip` | iOS native dSYM symbols |
+| `luciq upload react-native-ios-sourcemap FILE` | `.json`/`.txt` | iOS JavaScript source map |
+| `luciq upload react-native-android-mapping FILE` | `mapping.txt` | Android native Proguard/R8 mapping |
+| `luciq upload react-native-android-sourcemap FILE` | `.json`/`.txt` | Android JavaScript source map |
+| `luciq upload react-native-ndk FILE` | `.zip` | NDK `.so` shared object files (`--arch`) |
+
+**Flutter**
+
+| Command | File | Description |
+|---------|------|-------------|
+| `luciq upload flutter-ios-dsym FILE` | `.zip` | iOS native dSYM symbols |
+| `luciq upload flutter-ios-sourcemap FILE` | `.zip` | iOS Dart symbol files |
+| `luciq upload flutter-android-mapping FILE` | `mapping.txt` | Android native Proguard/R8 mapping |
+| `luciq upload flutter-android-sourcemap FILE` | `.zip` | Android Dart symbol files |
+| `luciq upload flutter-ndk FILE` | `.zip` | NDK `.so` shared object files (`--arch`) |
+
+Common options: `--app-token` is required for every command. dSYM commands
+(`*-ios-dsym`) need only `--app-token`. Mapping, source-map, and Flutter Dart-symbol
+commands also require `--version-name` / `--version-code` (React Native source-map
+commands additionally accept `--codepush`). NDK commands require `--version-name` and
+`--arch` (`armeabi-v7a`, `arm64-v8a`, `x86`, `x86_64`) — not `--version-code`.
+
+## Query & management commands
+
+Beyond uploading symbols, the CLI queries and manages your Luciq data. Every
+response is printed as pretty-printed JSON, so it pipes cleanly into tools like
+`jq`.
+
+### Shared options
+
+Most data commands target one application in one environment and share a common
+set of options:
+
+| Option | Description |
+|--------|-------------|
+| `--slug` | Application slug (required) |
+| `--mode` | Environment: `production`, `beta`, `staging`, `alpha`, `qa`, `development` (required) |
+| `--offset`, `--limit` | Pagination |
+| `--sort-by`, `--direction` | Sort field and direction (`asc`/`desc`) — some commands use `--sort-direction` instead |
+| `--filters` | Raw filter JSON object, merged with the typed filter flags (typed flags win on key conflicts) |
+
+Common filters have dedicated typed flags (`--status`, `--platform`,
+`--app-version`, …). Anything a tool supports but that has no flag can be passed
+through `--filters`, e.g. `--filters '{"devices":["iPhone15,2"],"os_versions":["17.4"]}'`.
+Run `luciq <group> help <subcommand>` for the full option list and the filter
+keys each command accepts.
+
+### Crashes
+
+`luciq crashes SUBCOMMAND`
+
+| Subcommand | Description |
+|------------|-------------|
+| `list` | List crashes. Flags: `--status` (open/closed/in_progress), `--platform` (IOS/ANDROID/DART/JAVASCRIPT), `--type` (CRASH/ANR/OOM/NON_FATAL), `--app-version` |
+| `show --number N` | Details for one crash |
+| `patterns --number N` | Grouped patterns. Flags: `--pattern-key`, `--sort-by`, `--direction` |
+| `diagnostics --number N` | Diagnostics for one crash |
+| `hangs` | List app hangs (same filters as `list`) |
+| `occurrence-tokens --number N` | Occurrence cursor tokens. Flags: `--current-token`, `--direction` (first/last) |
+| `occurrence --number N --ulid U` | Details for a single occurrence |
+
+```bash
+luciq crashes list --slug my-app --mode production --status open --limit 20
+luciq crashes show --slug my-app --mode production --number 42
+```
+
+### Bugs
+
+`luciq bugs SUBCOMMAND`
+
+| Subcommand | Description |
+|------------|-------------|
+| `list` | List bugs. Flags: `--status` (new/closed/in_progress), `--priority` (na/trivial/minor/major/blocker), `--app-version` |
+| `show --number N` | Details for one bug |
+| `update --number N` | Update a bug. Flags: `--status`, `--priority`, `--tags`, `--clear-tags`, `--duplicate-of`, `--action` |
+
+```bash
+luciq bugs update --slug my-app --mode production --number 7 --status closed --priority major
+luciq bugs update --slug my-app --mode production --number 7 --duplicate-of 3
+```
+
+Provide at least one change. Duplicate marking (`--duplicate-of` / `--action`)
+can't be combined with `--status`/`--priority`; use `--clear-tags` to remove all
+tags.
+
+### APM
+
+`luciq apm SUBCOMMAND`
+
+| Subcommand | Description |
+|------------|-------------|
+| `groups --metric M` | Rank groups worst-first. `--metric`: network, launch, flows, screen_loading, frame_drop, funnels. `--sort` is a JSON object `{"by":…,"direction":…}` |
+| `group --metric M` | Panels for one group; identify with `--group-uuid` or `--group-url`. `--views` is a JSON array (default `["summary"]`); `--method` applies to network |
+| `occurrence --metric M --selector S` | Inspect occurrences (`--selector`: worst/by_token/list). Flags: `--token`, `--current-token`, `--direction`, `--limit` |
+| `funnel-events` | List events pickable for funnels. Flags: `--event-type`, `--q`, `--limit` |
+| `funnel-create --name N --events JSON` | Create a funnel from 2–20 steps |
+| `funnel-update --ulid U` | Update a funnel (`--name`, `--events`) |
+| `funnel-delete --ulid U` | Delete a funnel |
+
+```bash
+luciq apm groups --slug my-app --mode production --metric network \
+  --sort '{"by":"p95","direction":"desc"}'
+```
+
+### Reviews
+
+`luciq reviews list` — Flags: `--rating` (1–5), `--country`, `--os` (ios/android),
+`--sort-by date`, `--sort-direction`.
+
+### Surveys
+
+`luciq surveys SUBCOMMAND`
+
+| Subcommand | Description |
+|------------|-------------|
+| `list` | List surveys. Flags: `--type` (0=custom 1=nps 2=app_store), `--status` (0=draft 1=published 2=paused) |
+| `show --id N` | A survey's questions and response statistics. `--page` paginates responses |
+
+### Apps
+
+`luciq apps list` — List the applications you can access (no `--slug`/`--mode`).
+Optional `--platform` (ios/android/react_native/flutter).
+
+### Insights
+
+`luciq insights --slug my-app --mode production` — Aggregated app-health insights.
+Narrow with `--filters` (`date_ms`, `app_version`).
+
+### Issues
+
+`luciq issues list` — Issues across crashes, APM, AI, and bugs, ranked by Apdex
+impact. Flags: `--limit`, `--sort-by` (apdex_impact/occurrences_counter),
+`--sort-direction`, `--top-issues` (curated shortlist), `--pagination`
+(per-source cursor tokens JSON).
+
+### Opportunities
+
+`luciq opportunities SUBCOMMAND`
+
+| Subcommand | Description |
+|------------|-------------|
+| `list` | List opportunities. Flags: `--status`, `--priority` (1–4/unset), `--team-id` |
+| `show --id N` | Details for one opportunity |
+
+### Alerts
+
+`luciq alerts SUBCOMMAND` — Manage alert rules.
+
+| Subcommand | Description |
+|------------|-------------|
+| `list` | List rules (`--sort-by`, `--sort-direction`) |
+| `show --ulid U` | Show one rule |
+| `init` | Show the menu (types, triggers, conditions, actions) for building a rule |
+| `create --payload JSON` | Create a rule |
+| `update --ulid U --payload JSON` | Update a rule |
+| `delete --ulid U` | Delete a rule |
+
+Run `luciq alerts init` first to discover the valid rule building blocks, then
+pass the rule body as `--payload`.
+
+### Incidents
+
+`luciq incidents SUBCOMMAND` — Manage triggered alerts.
+
+| Subcommand | Description |
+|------------|-------------|
+| `list` | List incidents. Flags: `--sort-by`, `--sort-direction`, `--status`, `--type` |
+| `show --ulid U` | Show one incident |
+| `resolve --ulid U` | Resolve an incident |
+| `reopen --ulid U` | Reopen an incident |
 
 ## Configuration
 

data/lib/luciq/api/client.rb

@@ -9,6 +9,11 @@ require 'luciq/config'
 module Luciq
   module API
     class Client
+      SYMBOLS_FILES_PATH = '/api/sdk/v3/symbols_files'
+      SO_FILES_PATH = '/api/web/public/so_files'
+      FLUTTER_IOS_SYMBOLS_PATH = '/api/web/public/flutter-symbol-files/ios'
+      FLUTTER_ANDROID_SYMBOLS_PATH = '/api/web/public/flutter-symbol-files/android'
+
       def initialize
         @token = Config.load_token
         @base_url = Config.load_base_url
@@ -21,24 +26,166 @@ module Luciq
         execute(uri, request)
       end
 
+      # Invokes a query tool by name with a hash of arguments (slug, mode,
+      # filters, pagination, ...) sent as a JSON body.
+      def invoke_tool(tool_name, arguments = {})
+        uri = build_uri("/api/cli/tools/#{tool_name}")
+        request = Net::HTTP::Post.new(uri)
+        request['Content-Type'] = 'application/json'
+        request.body = arguments.to_json
+        apply_headers(request)
+        execute(uri, request)
+      end
+
+      def upload_ios_dsym(file_path:, app_token:)
+        upload_dsym(file_path: file_path, app_token: app_token)
+      end
+
       def upload_android_mapping(file_path:, app_token:, version_code:, version_name:)
-        uri = build_uri('/api/web/public/mappings')
+        upload_mapping(
+          file_path: file_path, app_token: app_token,
+          version_code: version_code, version_name: version_name
+        )
+      end
 
+      def upload_android_ndk(file_path:, app_token:, app_version:, arch:)
+        upload_so_file(file_path: file_path, app_token: app_token, app_version: app_version, arch: arch)
+      end
+
+      def upload_react_native_ios_dsym(file_path:, app_token:)
+        upload_dsym(file_path: file_path, app_token: app_token)
+      end
+
+      def upload_react_native_ios_sourcemap(file_path:, app_token:, app_version:)
+        upload_react_native_sourcemap(
+          file_path: file_path, app_token: app_token, os: 'ios', app_version: app_version
+        )
+      end
+
+      def upload_react_native_android_mapping(file_path:, app_token:, version_code:, version_name:)
+        upload_mapping(
+          file_path: file_path, app_token: app_token,
+          version_code: version_code, version_name: version_name
+        )
+      end
+
+      def upload_react_native_android_sourcemap(file_path:, app_token:, app_version:)
+        upload_react_native_sourcemap(
+          file_path: file_path, app_token: app_token, os: 'android', app_version: app_version
+        )
+      end
+
+      def upload_react_native_ndk(file_path:, app_token:, app_version:, arch:)
+        upload_so_file(file_path: file_path, app_token: app_token, app_version: app_version, arch: arch)
+      end
+
+      def upload_flutter_ios_dsym(file_path:, app_token:)
+        upload_dsym(file_path: file_path, app_token: app_token)
+      end
+
+      def upload_flutter_ios_sourcemap(file_path:, app_token:, version_name:, version_code:)
+        upload_flutter_symbols(
+          FLUTTER_IOS_SYMBOLS_PATH,
+          file_path: file_path, app_token: app_token,
+          version_name: version_name, version_code: version_code
+        )
+      end
+
+      def upload_flutter_android_mapping(file_path:, app_token:, version_code:, version_name:)
+        upload_mapping(
+          file_path: file_path, app_token: app_token,
+          version_code: version_code, version_name: version_name
+        )
+      end
+
+      def upload_flutter_android_sourcemap(file_path:, app_token:, version_name:, version_code:)
+        upload_flutter_symbols(
+          FLUTTER_ANDROID_SYMBOLS_PATH,
+          file_path: file_path, app_token: app_token,
+          version_name: version_name, version_code: version_code
+        )
+      end
+
+      def upload_flutter_ndk(file_path:, app_token:, app_version:, arch:)
+        upload_so_file(file_path: file_path, app_token: app_token, app_version: app_version, arch: arch)
+      end
+
+      private
+
+      def upload_dsym(file_path:, app_token:)
+        uri = build_uri(SYMBOLS_FILES_PATH)
         File.open(file_path, 'rb') do |file|
           params = {
-            'mapping_file' => UploadIO.new(file, 'application/octet-stream', File.basename(file_path)),
+            'symbols_file' => UploadIO.new(file, 'application/octet-stream', File.basename(file_path)),
             'application_token' => app_token,
-            'app_version_code' => version_code,
-            'app_version_name' => version_name
+            'os' => 'ios'
           }
+          post_multipart(uri, params)
+        end
+      end
 
-          request = Net::HTTP::Post::Multipart.new(uri.path, params)
-          apply_headers(request)
-          execute(uri, request)
+      def upload_mapping(file_path:, app_token:, version_code:, version_name:)
+        uri = build_uri(SYMBOLS_FILES_PATH)
+        File.open(file_path, 'rb') do |file|
+          params = {
+            'symbols_file' => UploadIO.new(file, 'application/octet-stream', File.basename(file_path)),
+            'application_token' => app_token,
+            'os' => 'android',
+            'app_version' => { code: version_code, name: version_name }.to_json
+          }
+          post_multipart(uri, params)
         end
       end
 
-      private
+      def upload_react_native_sourcemap(file_path:, app_token:, os:, app_version:)
+        uri = build_uri(SYMBOLS_FILES_PATH)
+        File.open(file_path, 'rb') do |file|
+          params = {
+            'symbols_file' => UploadIO.new(file, source_map_content_type(file_path), File.basename(file_path)),
+            'application_token' => app_token,
+            'platform' => 'react_native',
+            'os' => os,
+            'app_version' => app_version.to_json
+          }
+          post_multipart(uri, params)
+        end
+      end
+
+      def upload_so_file(file_path:, app_token:, app_version:, arch:)
+        uri = build_uri(SO_FILES_PATH)
+        File.open(file_path, 'rb') do |file|
+          params = {
+            'so_file' => UploadIO.new(file, 'application/octet-stream', File.basename(file_path)),
+            'application_token' => app_token,
+            'app_version' => app_version,
+            'arch' => arch
+          }
+          post_multipart(uri, params)
+        end
+      end
+
+      def upload_flutter_symbols(path, file_path:, app_token:, version_name:, version_code:)
+        uri = build_uri(path)
+        File.open(file_path, 'rb') do |file|
+          params = {
+            'file' => UploadIO.new(file, 'application/octet-stream', File.basename(file_path)),
+            'application_token' => app_token,
+            'app_version_name' => version_name,
+            'app_version_code' => version_code
+          }
+          post_multipart(uri, params)
+        end
+      end
+
+      def post_multipart(uri, params)
+        request = Net::HTTP::Post::Multipart.new(uri.path, params)
+        apply_headers(request)
+        execute(uri, request)
+      end
+
+      def source_map_content_type(file_path)
+        file_path.downcase.end_with?('.json') ? 'application/json' : 'text/plain'
+      end
 
       def build_uri(path)
         URI("#{@base_url}#{path}")
@@ -56,9 +203,11 @@ module Luciq
         http.read_timeout = 300
 
         response = http.request(request)
-        return JSON.parse(response.body) if response.is_a?(Net::HTTPSuccess)
+        raise "Request failed (#{response.code}): #{response.body}" unless response.is_a?(Net::HTTPSuccess)
 
-        raise "Request failed (#{response.code}): #{response.body}"
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        response.body
       end
     end
   end

data/lib/luciq/cli.rb

@@ -3,25 +3,10 @@
 require 'thor'
 require 'luciq/version'
 require 'luciq/commands/auth'
-require 'luciq/commands/upload'
+require 'luciq/upload_cli'
+require 'luciq/query_cli'
 
 module Luciq
-  class UploadCLI < Thor
-    desc 'android-mapping FILE', 'Upload Android mapping file'
-    long_desc <<~DESC
-      Upload Android mapping files to Luciq for crash symbolication.
-      File format: .zip containing a single text file
-      Example:
-        luciq upload android-mapping mapping.zip --app-token APP_TOKEN --version-name 1.0.0 --version-code 1
-    DESC
-    option :app_token, type: :string, required: true, desc: 'Your Luciq application token'
-    option :version_name, type: :string, required: true, desc: 'App version name (e.g., 1.0.0)'
-    option :version_code, type: :string, required: true, desc: 'App version code (e.g., 1)'
-    def android_mapping(file)
-      Commands::Upload.new(options).android_mapping(file)
-    end
-  end
-
   class CLI < Thor
     def self.exit_on_failure?
       true
@@ -56,6 +41,50 @@ module Luciq
     desc 'upload SUBCOMMAND', 'Upload symbol files to Luciq'
     subcommand 'upload', UploadCLI
 
+    desc 'crashes SUBCOMMAND', 'Query crashes (list, show, patterns, diagnostics, hangs, occurrence-tokens, occurrence)'
+    subcommand 'crashes', CrashesCLI
+
+    desc 'bugs SUBCOMMAND', 'Query bugs (list, show, update)'
+    subcommand 'bugs', BugsCLI
+
+    desc 'apm SUBCOMMAND', 'Query APM data (groups, group, occurrence, funnels)'
+    subcommand 'apm', ApmCLI
+
+    desc 'reviews SUBCOMMAND', 'Query app reviews (list)'
+    subcommand 'reviews', ReviewsCLI
+
+    desc 'surveys SUBCOMMAND', 'Query surveys (list, show)'
+    subcommand 'surveys', SurveysCLI
+
+    desc 'apps SUBCOMMAND', 'List accessible applications'
+    subcommand 'apps', AppsCLI
+
+    desc 'issues SUBCOMMAND', 'Query issues ranked by impact (list)'
+    subcommand 'issues', IssuesCLI
+
+    desc 'opportunities SUBCOMMAND', 'Query opportunities (list, show)'
+    subcommand 'opportunities', OpportunitiesCLI
+
+    desc 'alerts SUBCOMMAND', 'Manage alert rules (list, show, init, create, update, delete)'
+    subcommand 'alerts', AlertsCLI
+
+    desc 'incidents SUBCOMMAND', 'Manage triggered alerts (list, show, resolve, reopen)'
+    subcommand 'incidents', IncidentsCLI
+
+    desc 'insights', 'Show aggregated app-health insights for an application'
+    long_desc(<<~DESC, wrap: false)
+      Show aggregated app-health insights for an application.
+
+      Filters via --filters:
+        date_ms      {"gte": <ms>, "lte": <ms>}
+        app_version  ["1.2.3", ...]
+    DESC
+    QueryOptions.app(self)
+    QueryOptions.raw_filters(self)
+    def insights
+      Commands::Query.new(options).insights
+    end
+
     desc 'version', 'Show CLI version'
     def version
       puts "luciq-cli #{Luciq::VERSION}"