@luciq/react-native 19.4.0 → 19.6.0

package/.claude/commands/create-rca.md

@@ -0,0 +1,286 @@
+---
+description: Generate a Root Cause Analysis (RCA) document from PR and Jira ticket information
+---
+
+You are tasked with creating a comprehensive Root Cause Analysis (RCA) document. Follow these steps:
+
+## Parameters
+
+- `prUrls` (optional): One or more GitHub PR URLs related to the incident/fix, comma-separated
+  - Single PR: `prUrls=https://github.com/luciqai/luciq-reactnative-sdk/pull/45`
+  - Multiple PRs: `prUrls=https://github.com/luciqai/luciq-reactnative-sdk/pull/45,https://github.com/Instabug/ios/pull/6534`
+
+- `taskUrl` (required): The Jira task/incident URL
+  - Example: `taskUrl=https://instabug.atlassian.net/browse/MOB-21429`
+
+## 0. Prerequisites Check
+
+**IMPORTANT**: This command requires GitHub CLI (`gh`) and Jira CLI (`jira`). Check if they are installed:
+
+```bash
+gh --version 2>/dev/null || echo "GH_CLI_NOT_INSTALLED"
+jira version 2>/dev/null || echo "JIRA_CLI_NOT_INSTALLED"
+```
+
+### GitHub CLI Setup
+
+If GitHub CLI is not installed:
+
+```
+GitHub CLI Required
+========================
+1. Install: brew install gh
+2. Authenticate: gh auth login
+For more info: https://cli.github.com/
+```
+
+### Jira CLI Setup
+
+If Jira CLI is not installed:
+
+```
+Jira CLI Required
+========================
+1. Install: brew install ankitpokhrel/jira-cli/jira-cli
+2. Initialize: jira init
+3. Server URL: https://instabug.atlassian.net
+4. Auth type: API Token
+5. Generate token: https://id.atlassian.com/manage-profile/security/api-tokens
+For more info: https://github.com/ankitpokhrel/jira-cli
+```
+
+**Only proceed if both CLIs are installed and authenticated.**
+
+## 1. Gather PR Information (if prUrls provided)
+
+### Step 1.1: Parse PR URLs
+
+Split `prUrls` by comma. For each PR URL, extract owner, repo, and PR number.
+
+### Step 1.2: Fetch Details for Each PR
+
+```bash
+gh pr view <pr_number> --repo <owner>/<repo> --json number,title,body,author,createdAt,mergedAt,state,commits,changedFiles,additions,deletions
+```
+
+### Step 1.3: Analyze Changes for Each PR
+
+```bash
+gh pr diff <pr_number> --repo <owner>/<repo> --name-only
+```
+
+### Step 1.4: Document All PRs
+
+For each PR, document:
+
+- PR number and title
+- Files changed
+- Nature of the fix/change
+- Author and reviewers
+- Merge date
+
+Consolidate to identify common files, fix sequence, and overall scope.
+
+## 2. Gather Jira Information
+
+### Step 2.1: Extract Task ID
+
+From `taskUrl`, extract the task ID (e.g., `MOB-21429` from the URL).
+
+### Step 2.2: Fetch Jira Ticket Details
+
+```bash
+jira issue view <TASK_ID> --plain
+```
+
+Extract: summary, description, status, priority, reporter, assignee, created date, labels, components, comments.
+
+### Step 2.3: Fetch Related Issues
+
+```bash
+jira issue view <TASK_ID> --comments
+```
+
+Document key events and timeline from comments.
+
+## 3. Generate RCA Document
+
+### Step 3.1: Ask Clarifying Questions
+
+```
+To complete the RCA, please provide the following details:
+
+1. **Root Cause**: What was the actual technical root cause?
+2. **Data Loss**: Was there any data loss? If yes, what data?
+3. **Security Impact**: Was there any security breach or exposure?
+4. **Affected Products**: Which SDK products were affected? (APM, Crash Reporting, Bug Reporting, Session Replay, Surveys, Replies, Feature Requests, Network Logger)
+5. **Customer Impact**: How many customers were affected? What was the user experience impact?
+6. **Actions Taken**: What immediate actions were taken to resolve the issue?
+7. **Engaged People**: Who was involved in investigating and fixing the issue?
+8. **Future Improvements**: What preventive measures will be implemented?
+```
+
+### Step 3.2: Generate RCA from Template
+
+```markdown
+# Root Cause Analysis (RCA)
+
+**RCA Link**: [JIRA_TASK_ID](JIRA_TASK_URL)
+**Date**: [Current Date]
+**Author**: [User Name or Team]
+**Related PRs**:
+
+- [PR_TITLE_1](PR_URL_1)
+- [PR_TITLE_2](PR_URL_2)
+
+---
+
+## What Happened
+
+[Clear description of the incident: what, when, how discovered, initial symptoms]
+
+---
+
+## Why This Happened
+
+[Root cause in technical terms: what failed, why safeguards missed it, contributing factors, specific code/commits]
+
+---
+
+## Features Affected
+
+[List SDK features/modules impacted with brief description of impact]
+
+---
+
+## Was There Any Data Loss
+
+- [ ] Yes
+- [ ] No
+
+[If yes: what data, volume/timeframe, recoverability, recovery steps]
+
+---
+
+## Impact on Customers
+
+[Number affected, severity, UX degradation, escalations, duration]
+
+---
+
+## Security Breach
+
+- [ ] Yes
+- [ ] No
+
+[If yes: nature, data exposed, securing steps, disclosure requirements]
+
+---
+
+## Affected Products
+
+- [ ] APM (App Performance Monitoring)
+- [ ] Bug Reporting
+- [ ] Crash Reporting
+- [ ] Session Replay
+- [ ] Surveys
+- [ ] Replies
+- [ ] Feature Requests
+- [ ] Core SDK
+- [ ] Network Logger
+- [ ] Navigation/Screen Tracking
+- [ ] CLI (Source Map Upload)
+- [ ] Expo Plugin
+- [ ] Other: [Specify]
+
+---
+
+## Actions Taken
+
+| Timestamp | Action         | Owner    |
+| --------- | -------------- | -------- |
+| [Time 1]  | [Action taken] | [Person] |
+| [Time 2]  | [Action taken] | [Person] |
+
+---
+
+## Engaged People
+
+| Name     | Role   | Contribution    |
+| -------- | ------ | --------------- |
+| [Name 1] | [Role] | [What they did] |
+
+---
+
+## Future Improvements
+
+| Improvement     | Priority          | Owner   | Target Date | JIRA Ticket |
+| --------------- | ----------------- | ------- | ----------- | ----------- |
+| [Improvement 1] | [High/Medium/Low] | [Owner] | [Date]      | [MOB-XXXXX] |
+
+### Preventive Categories:
+
+- [ ] Code Review Process Enhancement
+- [ ] Testing Coverage Improvement
+- [ ] Monitoring/Alerting Enhancement
+- [ ] Documentation Update
+- [ ] Process Change
+- [ ] Tooling Improvement
+
+---
+
+## Lessons Learned
+
+1. [Lesson 1]
+2. [Lesson 2]
+3. [Lesson 3]
+
+---
+
+## Appendix
+
+### Timeline
+
+[Detailed timeline]
+
+### Technical Details
+
+[Stack traces, logs, etc.]
+
+### References
+
+- JIRA: [JIRA_URL]
+- PRs: [PR links with descriptions]
+- Related Documentation: [Links]
+```
+
+### Step 3.3: Present RCA to User
+
+Present the generated RCA and ask for corrections, additions, or updates.
+
+## 4. Output Options
+
+Ask the user:
+
+```
+How would you like to save this RCA?
+1. Display in terminal (copy manually)
+2. Save to a file (specify path)
+3. Both
+```
+
+Default save location:
+
+```bash
+cat > ./RCA-<TASK_ID>-$(date +%Y%m%d).md << 'EOF'
+<RCA_CONTENT>
+EOF
+```
+
+## Examples
+
+```
+/create-rca taskUrl=https://instabug.atlassian.net/browse/MOB-21429
+/create-rca taskUrl=https://instabug.atlassian.net/browse/MOB-21429 prUrls=https://github.com/luciqai/luciq-reactnative-sdk/pull/45
+/create-rca taskUrl=https://instabug.atlassian.net/browse/MOB-21429 prUrls=https://github.com/luciqai/luciq-reactnative-sdk/pull/45,https://github.com/Instabug/ios/pull/6534
+```

package/.claude/commands/debug-sdk.md

@@ -0,0 +1,66 @@
+---
+description: Troubleshoot common Luciq React Native SDK issues
+---
+
+# Debug SDK
+
+Troubleshoot common issues with the Luciq React Native SDK.
+
+## Common Issues
+
+### SDK Not Initializing
+
+1. Verify `Luciq.init()` is called before any other SDK method
+2. Check the app token is correct
+3. Check platform-specific setup (iOS Info.plist, Android manifest)
+4. Enable verbose logging to see initialization output
+
+### Crashes Not Captured
+
+1. Verify `CrashReporting` is enabled
+2. Check that the global error handler is properly set up
+3. Ensure both JS and native crash handlers are registered
+4. Check if the crash is on the native side vs JS side
+
+### Network Requests Not Logged
+
+1. Check network interception mode (JavaScript vs Native)
+2. For JS mode: verify XhrNetworkInterceptor is wrapping fetch/XMLHttpRequest
+3. Check that network logging is enabled in SDK settings
+4. Verify request filtering regex isn't excluding the requests
+
+### Screen Tracking Not Working
+
+1. Verify navigation integration is set up correctly
+2. Check which navigation library is being used (React Navigation v4/v6, react-native-navigation v7)
+3. Verify `reportScreenChange` is being called
+4. Check route names match expected patterns
+
+### Build Failures After SDK Update
+
+1. For iOS: `cd ios && pod install`
+2. For Android: Clean build `cd android && ./gradlew clean`
+3. Clear Metro cache: `npx react-native start --reset-cache`
+4. Clear node_modules: `rm -rf node_modules && yarn install`
+
+### Source Map Upload Issues
+
+1. Check `ios/sourcemaps.sh` has execute permissions
+2. Verify `android/sourcemaps.gradle` is properly included
+3. Run CLI manually: `npx luciq upload-sourcemaps`
+
+## Diagnostic Commands
+
+```bash
+# Check TypeScript compilation
+yarn build:lib
+
+# Run tests to verify SDK integrity
+yarn test
+
+# Check for lint issues
+yarn lint
+
+# Check formatting
+yarn format
+```

package/.claude/commands/describe-pr.md

@@ -0,0 +1,40 @@
+---
+description: Generate comprehensive PR descriptions following the repository template
+---
+
+# Generate PR Description
+
+Generate a PR description using the repository's `.github/pull_request_template.md`.
+
+## Steps
+
+1. **Read the PR template:**
+   - Read `.github/pull_request_template.md`
+   - If not found, inform the user and wait for instructions
+
+2. **Identify the PR:**
+   - Check if the current branch has an associated PR: `gh pr view --json url,number,title,state 2>/dev/null`
+   - If no PR exists, create one with `gh pr create --fill`
+
+3. **Gather PR information:**
+   - Get the full diff: `gh pr diff {number}`
+   - Get commit history: `gh pr view {number} --json commits`
+   - Get base branch: `gh pr view {number} --json baseRefName`
+   - Get metadata: `gh pr view {number} --json url,title,number,state`
+
+4. **Analyze changes thoroughly:**
+   - Read the entire diff
+   - Read referenced files not shown in the diff for context
+   - Identify user-facing vs internal changes
+   - Look for breaking changes
+
+5. **Generate the description:**
+   - Fill each template section based on analysis
+   - Be specific about problems solved and changes made
+   - Check appropriate type-of-change boxes
+   - Address all checklist items
+
+6. **Update the PR:**
+   - Show the user the generated description
+   - Update the PR: `gh pr edit {number} --body "<description>"`
+   - Confirm the update was successful

package/.claude/commands/new-api.md

@@ -0,0 +1,60 @@
+---
+description: Add a new public API method to an existing SDK feature
+---
+
+# New API Method
+
+Add a new public API method to an existing feature module.
+
+## Parameters
+
+- `module` (required): Target module (e.g., `BugReporting`, `APM`, `CrashReporting`, `Luciq`)
+- `method` (required): Method name and signature description
+
+## Steps
+
+### 1. Define Native Interface
+
+Add the method to the native interface in `src/native/Native<Module>.ts`:
+
+- Define parameter types and return type
+- Follow existing method patterns in the same file
+
+### 2. Add Module Method
+
+Add the method to the module in `src/modules/<Module>.ts`:
+
+- Export function calling through to the native module
+- Match the style of existing methods in the same module
+
+### 3. Create Models (if needed)
+
+Add any new models to `src/models/` or enums to `src/utils/Enums.ts`
+
+### 4. Update Exports (if needed)
+
+If new models were added, export them in `src/index.ts`
+
+### 5. Write Tests
+
+Add tests to `test/modules/<Module>.spec.ts`:
+
+- Test the method calls through to the native module correctly
+- Test parameter passing
+- Test error handling
+- Update mock in `test/mocks/` if new native methods were added
+
+### 6. Verify
+
+```bash
+yarn build:lib
+yarn test
+yarn lint
+```
+
+## Best Practices
+
+- Parameter naming should be consistent with existing SDK conventions
+- Include `@deprecated` JSDoc tag if replacing an existing method
+- Null/undefined parameters should have sensible defaults on the native side
+- Callbacks should follow existing callback patterns (NativeEventEmitter)

package/.claude/commands/new-feature.md

@@ -0,0 +1,75 @@
+---
+description: Scaffold a new SDK feature module following established patterns
+---
+
+# New Feature Module
+
+Scaffold a new feature module in the Luciq React Native SDK following established patterns.
+
+## Parameters
+
+- `name` (required): Feature name (e.g., `Surveys`, `FeatureRequests`)
+
+## Steps
+
+### 1. Plan the Module
+
+- Determine the public API surface
+- Identify required native module methods
+- List models needed
+
+### 2. Create Native Interface
+
+Create `src/native/Native<FeatureName>.ts`:
+
+- Define the typed interface for the native module
+- Follow existing patterns from other native interface files (e.g., `NativeAPM.ts`, `NativeBugReporting.ts`)
+
+### 3. Create Module
+
+Create `src/modules/<FeatureName>.ts`:
+
+- Export functions that call through to the native module
+- Follow the pattern of existing modules (e.g., `BugReporting`, `APM`)
+- Add proper error handling
+- Use `NativeEventEmitter` for native-to-JS callbacks if needed
+
+### 4. Create Models
+
+Create any needed models in `src/models/`:
+
+- Follow existing model patterns
+- Include proper TypeScript types and enums in `src/utils/Enums.ts`
+
+### 5. Export Public API
+
+Update `src/index.ts`:
+
+- Export the new module namespace
+- Export any new models and types
+
+### 6. Write Tests
+
+Create `test/modules/<FeatureName>.spec.ts`:
+
+- Add native module mock in `test/mocks/`
+- Register mock in `test/setup.ts`
+- Test each public method
+- Test error handling paths
+
+### 7. Build and Test
+
+```bash
+yarn build:lib
+yarn test
+yarn lint
+```
+
+## Checklist
+
+- [ ] Native interface defined in `src/native/`
+- [ ] Module created with exported functions
+- [ ] Models and enums created if needed
+- [ ] Public exports updated in `src/index.ts`
+- [ ] Tests written and passing
+- [ ] Lint passes

package/.claude/commands/pr-review.md

@@ -0,0 +1,85 @@
+---
+description: Comprehensive PR code review with parallel analysis agents
+---
+
+# PR Code Review
+
+Perform a thorough code review of the current branch's changes.
+
+## Steps
+
+### 1. Gather Changes
+
+```bash
+# Get the base branch
+git log --oneline -1 origin/master
+
+# Get all changed files
+git diff origin/master...HEAD --name-only
+
+# Get the full diff
+git diff origin/master...HEAD
+
+# Get commit history
+git log origin/master...HEAD --oneline
+```
+
+### 2. Context Gathering
+
+For each changed file, read surrounding context:
+
+- Other methods in the same module
+- Related test files
+- Native bridge interfaces if native module code changed
+- Public exports if API surface changed
+
+### 3. Review Categories
+
+Analyze changes across these dimensions in parallel:
+
+**a. Logical Errors**
+
+- Off-by-one errors, null handling, missing edge cases
+- Incorrect native module data mapping
+- Missing await on Promises
+
+**b. TypeScript/React Native Standards**
+
+- TypeScript strict mode compliance
+- Proper use of `import type` for type-only imports
+- Correct use of NativeModules and NativeEventEmitter
+- Proper async/await patterns
+
+**c. Native Bridge Safety**
+
+- NativeModule interfaces are consistent with native implementations
+- Error handling around native calls
+- Data serialization correctness between JS and native
+
+**d. Test Coverage**
+
+- New code has tests
+- Tests cover error paths
+- Mocks are properly set up in `test/mocks/`
+
+**e. Performance**
+
+- No blocking operations on JS thread
+- No unnecessary event listener subscriptions
+- Efficient data structures
+
+**f. SDK Best Practices**
+
+- No host app crashes
+- Backward compatible
+- Follows existing module patterns
+
+### 4. Report
+
+For each issue found:
+
+- **File:line** - exact location
+- **Severity** - critical / warning / suggestion
+- **Issue** - what's wrong
+- **Before/After** - code showing the fix
+- **Explanation** - why it matters

package/.claude/commands/research-codebase.md

@@ -0,0 +1,41 @@
+---
+description: Research and document how specific parts of the codebase work
+---
+
+# Research Codebase
+
+Research a specific topic in the Luciq React Native SDK codebase and document findings.
+
+## Parameters
+
+- `topic` (required): What to research (e.g., "how network interception works", "crash reporting flow")
+
+## Steps
+
+1. **Decompose the question** into searchable sub-topics
+
+2. **Search the codebase** using multiple strategies:
+   - Grep for relevant class names, method names, and keywords
+   - Glob for relevant file patterns
+   - Read key files to understand implementation
+
+3. **Trace the flow** from public API to native bridge:
+   - Start from the public module in `src/modules/`
+   - Follow through to native interface in `src/native/`
+   - Check any utilities involved from `src/utils/`
+   - Note the iOS (`ios/`) and Android (`android/`) native implementations
+
+4. **Document findings** with:
+   - Overview of the feature/system
+   - Entry points (file:line references)
+   - Core implementation details
+   - Data flow (JS -> NativeModules -> Native)
+   - Key patterns used
+   - Test coverage locations
+
+## Rules
+
+- Document and explain the codebase as it exists - no improvements or suggestions
+- All file paths must be relative to the repo root
+- Include file:line references for key code locations
+- Focus on accuracy over completeness