@luciq/react-native 19.4.0 → 19.6.0

package/.claude/agents/codebase-analyzer.md

@@ -0,0 +1,33 @@
+---
+description: Analyze HOW code works in the Luciq React Native SDK - trace flows, understand patterns
+---
+
+# Codebase Analyzer
+
+You are a specialist agent for understanding HOW code works. You read code, trace data flow, and document implementation details.
+
+## Tools
+
+Use: Grep, Glob, Read
+
+## Strategy
+
+1. Start from the entry point (public API method)
+2. Follow the call chain: Module export -> NativeModule call -> Native bridge
+3. Note key logic, branching, error handling
+4. Document the data flow
+
+## Output Format
+
+- **Overview**: What this code does in 1-2 sentences
+- **Entry Points**: file:line references to public API
+- **Core Implementation**: key logic with file:line references
+- **Data Flow**: JS -> NativeModules -> Native (iOS/Android) path
+- **Key Patterns**: design patterns used
+- **Error Handling**: how errors propagate
+
+## Rules
+
+- Document and explain only - no suggestions, critiques, or improvements
+- All file paths relative to repo root
+- Include file:line references for key locations

package/.claude/agents/codebase-locator.md

@@ -0,0 +1,42 @@
+---
+description: Find WHERE code lives in the Luciq React Native SDK
+---
+
+# Codebase Locator
+
+You are a specialist agent for finding WHERE code lives. You locate files, classes, and functions without reading their contents.
+
+## Tools
+
+Use only: Grep, Glob
+
+## Strategy
+
+1. Start with broad searches across the repo
+2. Narrow by directory:
+   - Implementation files (`src/modules/`, `src/utils/`)
+   - Public API exports (`src/index.ts`)
+   - Native bridge interfaces (`src/native/`)
+   - Models and types (`src/models/`)
+   - Test files (`test/`)
+   - CLI code (`cli/`)
+   - Expo plugin (`plugin/`)
+   - iOS native code (`ios/`)
+   - Android native code (`android/`)
+   - Example apps (`examples/`)
+
+## Output Format
+
+Categorize findings:
+
+- **Implementation**: source files with the core logic
+- **API Surface**: public exports and native bridge interfaces
+- **Native**: iOS (Objective-C/Swift) and Android (Java/Kotlin) code
+- **Tests**: test files covering the code
+- **Config**: package.json, tsconfig, jest.config, etc.
+
+## Rules
+
+- Do NOT read file contents - just report locations
+- Do NOT suggest improvements or critique code
+- Report file paths relative to repo root

package/.claude/agents/codebase-pattern-finder.md

@@ -0,0 +1,40 @@
+---
+description: Find existing code patterns and examples in the Luciq React Native SDK
+---
+
+# Codebase Pattern Finder
+
+You are a specialist agent for finding existing code patterns and examples. You identify how things are done in this codebase so new code can follow the same patterns.
+
+## Tools
+
+Use: Grep, Glob, Read
+
+## Pattern Types
+
+- **Module pattern**: How feature modules are structured (exported namespace, NativeModule calls)
+- **Native bridge pattern**: How NativeModules and NativeEventEmitter are used
+- **Test pattern**: How tests are structured (Jest mocks, setup, assertions)
+- **Model pattern**: How TypeScript data models and enums are defined
+- **Utility pattern**: How utilities like XhrNetworkInterceptor, CustomSpansManager work
+
+## Strategy
+
+1. Identify the pattern type being searched for
+2. Find 2-3 concrete examples in the codebase
+3. Read and extract the relevant code sections
+4. Note key aspects (naming, structure, conventions)
+
+## Output Format
+
+For each pattern found:
+
+- **File**: relative path and line range
+- **Code**: the relevant excerpt
+- **Key Aspects**: what makes this pattern work
+
+## Rules
+
+- Do NOT evaluate or recommend patterns - just document what exists
+- Show concrete code examples, not abstractions
+- Include file:line references

package/.claude/commands/apply-pr-reviews.md

@@ -0,0 +1,253 @@
+---
+description: Fetch unresolved PR review comments for the current branch and apply them one by one
+---
+
+You are tasked with applying PR review comments systematically. Follow these steps:
+
+## 0. Prerequisites Check
+
+**IMPORTANT**: This command requires GitHub CLI (`gh`). Check if it's installed and authenticated:
+
+```bash
+gh --version 2>/dev/null || echo "GH_CLI_NOT_INSTALLED"
+```
+
+If GitHub CLI is not installed or the command fails, **STOP HERE** and provide these setup instructions to the user:
+
+```
+GitHub CLI Required
+========================
+
+This command requires GitHub CLI to fetch PR review comments.
+
+Setup Instructions:
+
+1. Install GitHub CLI:
+   brew install gh
+
+2. Authenticate with GitHub:
+   gh auth login
+
+3. Follow the prompts to complete authentication
+
+4. Run the command again: /apply-pr-reviews
+
+For more info: https://cli.github.com/
+```
+
+If `gh` is installed, verify authentication:
+
+```bash
+gh auth status
+```
+
+If not authenticated, provide the authentication instructions above.
+
+**Only proceed to step 1 if GitHub CLI is properly installed and authenticated.**
+
+## 1. Get Current Branch and PR Information
+
+First, determine the current git branch:
+
+```bash
+git branch --show-current
+```
+
+Then fetch the PR associated with this branch using GitHub CLI:
+
+```bash
+gh pr list --head <branch-name> --json number,title,url,state --limit 1
+```
+
+## 2. Fetch Unresolved PR Review Comments
+
+Use GitHub CLI to fetch inline review comments (file-specific comments):
+
+```bash
+gh api repos/{owner}/{repo}/pulls/{pr_number}/comments --jq '.[] | select(.in_reply_to_id == null) | {id: .id, path: .path, line: .line, body: .body, user: .user.login, created_at: .created_at}'
+```
+
+This fetches:
+
+- Comment ID (for marking as resolved)
+- File path (where the comment is located)
+- Line number (specific line in the file)
+- Comment body (the reviewer's feedback)
+- Author (who left the comment)
+- Timestamp (when it was created)
+
+**Note**: We filter for `in_reply_to_id == null` to get only top-level comments, not replies.
+
+## 3. Iterate Through Comments
+
+For each unresolved comment, perform the following workflow:
+
+### Step 3.1: Display Comment Context
+
+Show the reviewer's comment clearly:
+
+- **File**: `path/to/file.ts`
+- **Line**: 42
+- **Reviewer**: @username
+- **Comment**: "This function should handle the error case"
+- **Code Context**: Show 5 lines before and after the commented line
+
+### Step 3.2: Analyze Comment Validity
+
+Evaluate if the comment should be applied:
+
+- **Is it actionable?** (vs just a question or discussion)
+- **Is it still relevant?** (code might have changed)
+- **Is it technically sound?** (does it follow project standards)
+- **Priority level**: Critical, Important, Nice-to-have
+- **Check for similar issues**: Search the entire file for other occurrences of the same pattern/issue
+
+### Step 3.2.1: Check for Similar Issues in File
+
+**IMPORTANT**: Before applying any fix, search the entire file for similar occurrences of the same issue:
+
+1. **Pattern matching**: If the comment is about a specific pattern, search the entire file for all instances
+2. **Consistency check**: Look for similar code structures that might need the same fix
+3. **Cross-module check**: Check if similar code exists in other modules under `src/modules/`
+4. **Report findings**: If multiple occurrences are found, ask the user if they want to fix all instances or just the commented line
+
+### Step 3.3: Present Analysis
+
+Display your analysis:
+
+```
+VALID - This comment is actionable and relevant
+  Priority: Important
+  Reason: Missing error handling is a bug risk
+  Suggested fix: Add try-catch with proper error handling
+```
+
+or
+
+```
+SKIP - Not applicable
+  Reason: Code was refactored in commit abc123 and already handles this case
+```
+
+### Step 3.4: Apply Valid Comments
+
+If the comment is valid and should be applied:
+
+1. Read the file at the specified path
+2. **Check for similar issues** (Step 3.2.1) - Search for other occurrences of the same pattern
+3. If multiple occurrences found, ask user for preference:
+
+   ```
+   Found 3 additional occurrences of the same issue in this file:
+   - Line 15: missing await
+   - Line 42: missing await
+   - Line 67: missing await
+
+   How would you like to proceed?
+   [a] Apply fix to ALL occurrences (recommended for consistency)
+   [o] Apply fix to ONLY the commented line
+   [s] Show me all occurrences first, then decide
+   [c] Cancel this fix
+   ```
+
+4. Locate the exact code section(s)
+5. Implement the requested change(s)
+6. Ensure the fix follows project coding standards
+7. Show the diff of changes made
+
+### Step 3.5: Confirm with User
+
+After analyzing each comment, ask:
+
+```
+Should I apply this fix?
+[y] Yes, apply it
+[n] No, skip this comment
+[m] Mark as resolved without changes (not applicable)
+[a] Auto-apply all remaining valid comments
+[q] Quit
+```
+
+### Step 3.6: Reply to Comment
+
+After the user decides to apply/skip, ask if they want to reply to the comment:
+
+```
+Do you want to reply to this comment?
+[y] Yes, use the auto-generated reply
+[c] Yes, but I'll provide a custom reply
+[n] No, don't reply
+```
+
+**Auto-generated replies based on action:**
+
+- If applied: "Applied (changes not yet committed)"
+- If skipped: "Skipped: [reason]"
+- If marked as not applicable: "Not applicable: [reason]"
+
+**IMPORTANT**: Do NOT include commit hashes in auto-generated replies because the changes haven't been committed yet.
+
+### Step 3.7: Post Reply to GitHub
+
+Once user confirms the reply, post it as a **threaded reply** under the original comment.
+
+Use GitHub's dedicated replies endpoint, which only needs the original comment ID and the reply body (path/line/side/commit_id are inferred from the parent comment and will cause a 422 if included):
+
+```bash
+gh api --method POST \
+  repos/{owner}/{repo}/pulls/{pr_number}/comments/<comment_id>/replies \
+  -f body='<reply message>'
+```
+
+## 4. Summary Report
+
+After processing all comments, provide:
+
+```
+PR Review Comments - Summary
+============================
+Total comments: 15
+Applied: 8
+Skipped: 5
+Already resolved: 2
+
+Changes made in:
+  - src/modules/APM.ts (3 changes)
+  - src/utils/XhrNetworkInterceptor.ts (2 changes)
+  - test/modules/APM.spec.ts (3 changes)
+
+Next steps:
+  - Run tests: yarn test
+  - Run lint: yarn lint
+  - Review changes: git diff
+  - Commit changes: git add . && git commit -m "fix: apply PR review feedback"
+```
+
+## 5. Error Handling
+
+If any step fails:
+
+- **GitHub CLI not found**: Stop immediately and show setup instructions
+- **Not authenticated**: Stop and show `gh auth login` instructions
+- **PR not found**: Verify branch name and check if PR exists
+- **API errors**: Show clear error message with API response
+- **File not found**: Skip that comment and mark it as outdated
+- **Line number mismatch**: Show context and ask user to verify
+- Continue with remaining comments after non-fatal errors
+- Report all errors in the summary
+
+## Optional Arguments
+
+User can provide in `$ARGUMENTS`:
+
+- PR number (e.g., `123`) - Process specific PR instead of auto-detecting from branch
+- `--auto` - Auto-apply all valid comments without confirmation
+- `--dry-run` - Show what would be done without making changes
+- `--priority=critical` - Only apply critical priority comments
+
+Examples:
+
+- `/apply-pr-reviews` - Auto-detect PR from current branch
+- `/apply-pr-reviews 123` - Process PR #123
+- `/apply-pr-reviews --auto` - Auto-apply all valid comments
+- `/apply-pr-reviews --dry-run` - Preview changes only

package/.claude/commands/create-jira-workitem.md

@@ -0,0 +1,27 @@
+---
+description: Create a Jira work item using Atlassian CLI
+---
+
+Create a Jira work item using Atlassian CLI.
+
+Example:
+
+```
+acli jira workitem create \
+    --summary "Task Title" \
+    --description "Task description in Atlassian Document Format" \
+    --project "MOB" \
+    --type "Task" \
+    --assignee @me \
+    --label "React-Native"
+```
+
+Follow the following rules unless specified otherwise:
+
+- Prefix task summary with `[React Native]`
+- Make the description concise
+- Use MOB (Mobile) project
+- Default to assign-self (@me)
+- Create a Task if suitable
+
+Use `acli jira workitem create -h` for command usage when you need to.

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

@@ -0,0 +1,138 @@
+---
+description: Create a PR with commit suggestion, template filling, and GitHub CLI
+---
+
+# Create Pull Request
+
+Automates the complete PR workflow: suggest commit, fill PR template, create draft PR.
+
+## Parameters
+
+- `baseBranch` (optional): Target branch. Defaults to `master`.
+- `taskUrl` (required): Jira task URL (e.g., `https://instabug.atlassian.net/browse/MOB-20541`).
+
+## Step 0: Prerequisites Check
+
+```bash
+gh --version 2>/dev/null || echo "GH_CLI_NOT_INSTALLED"
+```
+
+If GitHub CLI is not installed, **STOP** and show:
+
+```
+GitHub CLI Required
+========================
+1. Install: brew install gh
+2. Authenticate: gh auth login
+3. Re-run: /create-pr
+```
+
+If installed, verify authentication:
+
+```bash
+gh auth status
+```
+
+**Only proceed if `gh` is installed and authenticated.**
+
+---
+
+## Step 1: Suggest Commit Message
+
+Analyze staged/unstaged changes and suggest a commit message:
+
+```
+<type>(<scope>): <subject>
+
+<body>
+```
+
+Types: `feat`, `fix`, `refactor`, `perf`, `test`, `docs`, `chore`
+
+Scope should reference the affected area (e.g., `apm`, `bug-reporting`, `network-logger`, `session-replay`, `cli`).
+
+Example:
+
+```
+feat(apm): add custom span duration tracking
+
+- Implement CustomSpansManager for measuring span durations
+- Add method to APM module for starting/ending spans
+- Include unit tests for edge cases
+```
+
+**Present the suggested commit message and wait for user approval.**
+
+Once approved, stage and commit. Never use `git add -A` / `git add .` since they can pull in `.env`, credentials, or other stray files.
+
+```bash
+# Show the working tree so the user can confirm what gets staged
+git status
+
+# Stage only the intended files explicitly (expand as needed)
+git add <path1> <path2> ...
+
+# Verify the staged diff before committing
+git diff --cached
+
+git commit -m "<approved-message>"
+```
+
+**Do not proceed until the user approves the staged file list and the commit succeeds.**
+
+---
+
+## Step 2: Generate PR Description
+
+Read the PR template:
+
+```bash
+cat .github/pull_request_template.md
+```
+
+Fill the template based on the actual changes:
+
+1. **Description of the change** - Summarize what changed and why
+2. **Type of change** - Check the appropriate box based on the changes:
+   - Bug fix, New feature, or Breaking change
+3. **Related issues** - Use the `taskUrl` parameter to link the Jira ticket
+4. **Checklists** - Fill based on analysis of the changes
+
+**Present the filled template to the user and ask for modifications.**
+
+---
+
+## Step 3: Create Pull Request
+
+Extract the task ID from `taskUrl` (the part after `/browse/`).
+
+Generate PR title in format: `<type>: [TASK-ID] brief description`
+
+Types: `feat`, `fix`, `refactor`, `perf`, `test`, `docs`, `chore`
+
+Examples:
+
+- `feat: [MOB-20541] add network request duration tracking to APM`
+- `fix: [MOB-18732] fix crash when initializing SDK on iOS 14`
+- `chore: [MOB-19000] update CI Node version to 20.11.1`
+
+**Present the title to the user for approval.**
+
+Once approved:
+
+```bash
+# Push the branch
+git push -u origin HEAD
+
+# Save PR description to a unique temp file (avoids collisions with concurrent runs)
+PR_BODY_FILE="$(mktemp -t pr-description.XXXXXX)"
+trap 'rm -f "$PR_BODY_FILE"' EXIT
+cat > "$PR_BODY_FILE" << 'EOF'
+<filled PR template from Step 2>
+EOF
+
+# Create draft PR
+gh pr create --base {baseBranch} --title "<approved-title>" --body-file "$PR_BODY_FILE" --draft --assignee @me
+```
+
+Display the PR URL when done.

package/.claude/commands/create-public-release-notes.md

@@ -0,0 +1,145 @@
+---
+description: Transform internal release notes into public-facing release notes for React Native SDK consumers
+---
+
+# Create Public Release Notes
+
+Transform internal release notes into public-facing release notes suitable for React Native SDK consumers.
+
+## Parameters
+
+- `releaseNotesUrl` (required): The URL containing the internal release notes
+  - Example: `releaseNotesUrl=https://your-wiki.com/RN+19.3.0+Internal+Release+Notes`
+  - The version number will be automatically extracted from the URL
+
+## Step 1: Extract Version and Request Content
+
+Extract the version number from the `releaseNotesUrl` parameter.
+
+Prompt the user:
+
+```
+I'll help you transform the internal release notes from:
+{releaseNotesUrl}
+
+Since this page may require authentication, please follow these steps:
+
+1. Open the URL in your browser: {releaseNotesUrl}
+2. Copy ALL the release notes content from the page
+3. Paste the content below
+
+I'll transform it into professional, public-facing release notes for React Native SDK v{version}.
+
+Please paste the content now:
+```
+
+Wait for the user to provide the internal notes content.
+
+## Step 2: Analyze and Categorize
+
+Review the internal notes and for each item:
+
+1. Identify the type (Feature, Improvement, Bug Fix, Other)
+2. Determine if public-facing (remove internal-only items)
+3. Extract the core user-facing change
+4. Remove all internal jargon and references
+
+## Step 3: Transform Content
+
+### Tone and Style
+
+- Professional, concise, and clear - write for SDK consumers
+- Use team perspective: "We've added...", "Fixed an issue where...", "Improved..."
+
+### Remove
+
+- Ticket IDs (MOB-XXXX)
+- Developer names
+- Internal tools references
+- Debug logs mentions
+- CI/CD references
+- QA process details
+- Feature flags
+
+### Keep
+
+- New features
+- Improvements
+- Public bug fixes
+- SDK API changes
+- Performance enhancements
+- Compatibility updates
+
+### Generalize
+
+- "Fixed internal NativeModule marshaling" -> "Improved platform communication reliability"
+- "Updated XhrNetworkInterceptor implementation" -> "Enhanced network request tracking accuracy"
+
+### React Native-Specific Considerations
+
+- Note platform-specific fixes (iOS/Android) when relevant
+- Highlight TypeScript API changes clearly
+- Mention React Navigation or Expo compatibility changes
+- Note any changes to the CLI tool or source map upload process
+
+## Step 4: Generate Output
+
+Format as a flat list with category prefixes:
+
+```markdown
+### React Native SDK v{version} Release Notes
+
+- **New Feature:** Added support for custom performance span tracking.
+- **New Feature:** Introduced native network interception mode.
+- **Improvement:** Enhanced session replay performance on Android.
+- **Improvement:** Reduced SDK initialization time.
+- **Bug Fix:** Fixed an issue where crash reports were not sent when app was backgrounded.
+- **Bug Fix:** Fixed a crash on iOS when navigating rapidly between screens.
+- **Other:** Deprecated `oldMethod()` in favor of `newMethod()`.
+```
+
+### Breaking Changes
+
+If breaking changes exist, list them first with warning prefix:
+
+```markdown
+- **Breaking:** Minimum React Native version increased to 0.70.0.
+- **Breaking:** `init()` now requires `invocationEvents` parameter.
+```
+
+## Step 5: Present and Refine
+
+Show the generated notes and ask:
+
+1. Adjust any wording?
+2. Add or remove any items?
+3. Save to a file?
+
+## Step 6: Save Output (Optional)
+
+If requested:
+
+```bash
+cat > rn-sdk-v{version}-release-notes.md << 'EOF'
+<content>
+
+---
+*Generated from: {releaseNotesUrl}*
+*Version: {version}*
+*Generated on: {current_date}*
+EOF
+```
+
+## Quality Checklist
+
+- [ ] No internal ticket IDs
+- [ ] No developer names
+- [ ] No internal tool mentions
+- [ ] No technical jargon SDK users wouldn't understand
+- [ ] All items are user-facing
+- [ ] Language is professional and clear
+- [ ] Each bullet is concise (1-2 lines max)
+- [ ] Version number is correct
+- [ ] Items are properly prefixed with categories
+- [ ] Empty categories are omitted
+- [ ] Platform-specific fixes mention the platform