release - v0.3.0 (#12)

* chore: reorganizing docs (#1)

* Feature - Core Hooks + Tests (#2)

* feat: creation of core hooks + update docs

* feat: tests added

* chore: increasing percentage of test coverage

* docs: update changelog with testing and hooks implementation

* Feature - Setup CI/CD (#3)

* feat: creating develop and main flows

* feat: adding documentation of CICD and project structure

* Feature - Live Location Updates (#6)

* feat: adding new native logic and react hooks for live location updates

* fix(tests): small fix on lint of setup-minimal.ts

* chore(docs): updating docs + increasing project version

* chore: updating README.md

* feat: adding tests to useLocationUpdates hook

* Fix - Fix Live update locations (#7)

* fix: fixing tracking of locations, adding interval to get information

* chore: just adjusting css of example App

* chore(docs): updating docs

* chore - Incrementing Workflows (#8)

* chore(workflows): updating workflows to allows coverage and badges

* chore(docs): updating docs

* chore(docs): updating docs (#9)

* chore - update workflows (#10)

* chore(workflows): updating workflows to allows coverage and badges

* chore(docs): updating docs

* chore(workflow): updating workflow adding test info

* chore - sponsor documentation (#11)

* chore(docs): updating docs

* chore(docs): updating docs

Author: gabriel-sisjr

.github/workflows/ci.yml

@@ -46,6 +46,14 @@ jobs:
       - name: Run unit tests
         run: yarn test --maxWorkers=2 --coverage
 
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          file: ./coverage/lcov.info
+          flags: unittests
+          fail_ci_if_error: false
+
   build-library:
     runs-on: ubuntu-latest
 

.github/workflows/prerelease.yml

@@ -16,6 +16,8 @@ jobs:
     permissions:
       contents: write
       id-token: write
+      issues: write
+      pull-requests: write
 
     steps:
       - name: Checkout
@@ -57,7 +59,48 @@ jobs:
         run: yarn prepare
 
       - name: Run tests
-        run: yarn test --maxWorkers=2
+        run: yarn test --coverage --maxWorkers=2
+
+      - name: Upload coverage artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-prerelease
+          path: |
+            coverage/**
+          if-no-files-found: warn
+
+      - name: Upload coverage reports to Codecov
+        if: always()
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          file: ./coverage/lcov.info
+          flags: prerelease
+          fail_ci_if_error: false
+
+      - name: Publish coverage summary
+        if: always()
+        run: |
+          if [ -f coverage/coverage-summary.json ]; then
+            echo "### Test Coverage" >> $GITHUB_STEP_SUMMARY
+            node -e '
+              const fs = require("fs");
+              const s = JSON.parse(fs.readFileSync("coverage/coverage-summary.json", "utf8"));
+              const t = s.total;
+              const row = (k,v)=>`| ${k} | ${v.pct}% | ${v.covered}/${v.total} |`;
+              console.log("| Metric | % | Covered/Total |\n|---|---:|---:|\n" +
+                [
+                  row("Statements", t.statements),
+                  row("Branches", t.branches),
+                  row("Functions", t.functions),
+                  row("Lines", t.lines)
+                ].join("\n")
+              );
+            ' >> $GITHUB_STEP_SUMMARY
+          else
+            echo "No coverage summary found." >> $GITHUB_STEP_SUMMARY
+          fi
 
       - name: Publish to NPM (beta tag)
         run: |

.github/workflows/publish.yml

@@ -16,6 +16,8 @@ jobs:
     permissions:
       contents: write
       id-token: write
+      issues: write
+      pull-requests: write
 
     steps:
       - name: Checkout
@@ -61,7 +63,48 @@ jobs:
 
       - name: Run tests
         if: steps.version-check.outputs.version_changed == 'true'
-        run: yarn test --maxWorkers=2
+        run: yarn test --coverage --maxWorkers=2
+
+      - name: Upload coverage artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-release
+          path: |
+            coverage/**
+          if-no-files-found: warn
+
+      - name: Upload coverage reports to Codecov
+        if: always()
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          file: ./coverage/lcov.info
+          flags: release
+          fail_ci_if_error: false
+
+      - name: Publish coverage summary
+        if: always()
+        run: |
+          if [ -f coverage/coverage-summary.json ]; then
+            echo "### Test Coverage" >> $GITHUB_STEP_SUMMARY
+            node -e '
+              const fs = require("fs");
+              const s = JSON.parse(fs.readFileSync("coverage/coverage-summary.json", "utf8"));
+              const t = s.total;
+              const row = (k,v)=>`| ${k} | ${v.pct}% | ${v.covered}/${v.total} |`;
+              console.log("| Metric | % | Covered/Total |\n|---|---:|---:|\n" +
+                [
+                  row("Statements", t.statements),
+                  row("Branches", t.branches),
+                  row("Functions", t.functions),
+                  row("Lines", t.lines)
+                ].join("\n")
+              );
+            ' >> $GITHUB_STEP_SUMMARY
+          else
+            echo "No coverage summary found." >> $GITHUB_STEP_SUMMARY
+          fi
 
       - name: Publish to NPM
         if: steps.version-check.outputs.version_changed == 'true'
@@ -123,3 +166,43 @@ jobs:
               prerelease: false
             });
 
+      - name: Comment on related PRs
+        if: steps.version-check.outputs.version_changed == 'true'
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const version = require('./package.json').version;
+            // Find PRs that were just merged into main
+            const { data: prs } = await github.rest.pulls.list({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: 'closed',
+              base: 'main',
+              sort: 'updated',
+              direction: 'desc',
+              per_page: 5
+            });
+
+            const recentlyMergedPRs = prs.filter(pr => {
+              const mergedAt = new Date(pr.merged_at);
+              const fiveMinutesAgo = new Date(Date.now() - 5 * 60 * 1000);
+              return pr.merged_at && mergedAt > fiveMinutesAgo;
+            });
+
+            for (const pr of recentlyMergedPRs) {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: pr.number,
+                body: `🎉 A release has been published: **v${version}**\n\n` +
+                      `Install with:\n` +
+                      "```bash\n" +
+                      `npm install @gabriel-sisjr/react-native-background-location@${version}\n` +
+                      `# or\n` +
+                      `yarn add @gabriel-sisjr/react-native-background-location@${version}\n` +
+                      "```\n\n" +
+                      `This version includes your changes and is available for installation!`
+              });
+            }
+

CHANGELOG.md

@@ -142,13 +142,126 @@ Starting with 0.2.0, the project follows a two-branch strategy:
 - **`main`**: Production-ready releases (stable versions)
 - **`develop`**: Latest development code (beta releases available via `npm install @gabriel-sisjr/react-native-background-location@beta`)
 
+## [0.3.0] - 2025-01-26
+
+### Added
+
+- 🎯 **Real-time Location Updates**: New `useLocationUpdates` hook for automatic location watching
+  - Real-time event-driven location updates via native events
+  - Automatic subscription to `onLocationUpdate` events from Android background service
+  - Access to last location received in real-time
+  - Optional filtering by specific tripId
+  - Callback support for each new location
+  - Automatic loading of existing locations on mount
+  - Complete TypeScript support with full type definitions
+  - Automatic cleanup of event listeners on unmount
+  - Graceful handling when native module unavailable
+
+- 📡 **Android Event System**: Native event emission infrastructure
+  - LocationService emits `onLocationUpdate` events via DeviceEventManagerModule
+  - Events sent whenever new GPS location is collected
+  - Non-blocking async event emission
+  - Context-aware event system with React Native bridge
+
+- 📚 **Enhanced Documentation**:
+  - Complete real-time updates guide in `docs/getting-started/REAL_TIME_UPDATES.md`
+  - Usage examples demonstrating manual vs automatic modes
+  - Best practices for combining hooks
+  - FAQ section with common questions
+  - Updated example app with toggle for manual/automatic modes
+
+- 🎨 **Improved Example App**:
+  - Added toggle switch to demonstrate manual vs automatic update modes
+  - Real-time visualization of last location
+  - Visual indicators for active mode
+  - Conditional UI elements based on update mode
+
+### API Additions
+
+**New Hook**: `useLocationUpdates`
+```typescript
+const {
+  locations,        // Real-time array of all locations
+  lastLocation,     // Most recent location received
+  isTracking,       // Tracking status
+  tripId,          // Current trip ID
+  isLoading,       // Loading state
+  error,           // Error state
+  clearError       // Clear error function
+} = useLocationUpdates({
+  tripId?: string,                    // Filter by tripId
+  onLocationUpdate?: (location) => void,  // Callback per location
+  autoLoad?: boolean                  // Load existing locations
+});
+```
+
+### Changed
+
+- 📦 **Version Bump**: Updated to 0.3.0 following semantic versioning (minor release for new features)
+- 🔄 **Event System**: Android LocationService now emits native events for real-time updates
+- 📱 **Module Integration**: BackgroundLocationModule now provides ReactContext to LocationService
+
+### Technical Details
+
+**File Changes:**
+- `android/src/main/java/com/backgroundlocation/LocationService.kt`: Added event emission
+- `android/src/main/java/com/backgroundlocation/BackgroundLocationModule.kt`: Added context setup
+- `src/hooks/useLocationUpdates.ts`: New hook for real-time updates
+- `src/types.ts`: Added `LocationUpdateEvent`, `UseLocationUpdatesOptions`, `UseLocationUpdatesResult`
+- `src/hooks/index.ts`: Exported new hook and types
+- `src/index.tsx`: Exported new hook and types
+- `example/src/App.tsx`: Enhanced with toggle demonstration
+
+**Architecture:**
+- Event-driven updates (no polling required)
+- Non-blocking event emission
+- Automatic subscription/unsubscription
+- Memory efficient with minimal overhead
+- Compatible with existing imperative API
+
+### Migration Guide
+
+If upgrading from 0.2.0:
+
+**No Breaking Changes** - All existing APIs remain fully supported.
+
+**New Feature - Real-time Updates:**
+
+```typescript
+// Option 1: Manual refresh (existing)
+import { useBackgroundLocation } from '@gabriel-sisjr/react-native-background-location';
+const { locations, refreshLocations } = useBackgroundLocation();
+// ... call refreshLocations() periodically
+
+// Option 2: Automatic updates (NEW)
+import { useLocationUpdates } from '@gabriel-sisjr/react-native-background-location';
+const { locations } = useLocationUpdates();
+// ... locations update automatically in real-time
+
+// Option 3: Combine both (recommended)
+const control = useBackgroundLocation(); // For start/stop
+const updates = useLocationUpdates(); // For real-time data
+```
+
+### Requirements
+
+- React Native 0.70 or higher
+- Android API 21+ (Android 5.0 Lollipop)
+- Google Play Services Location 21.3.0
+
+### Known Limitations
+
+- iOS event emitters not yet implemented (iOS support planned)
+- Events only processed when app is in foreground
+- Real-time updates currently Android-only
+
 ## [Unreleased]
 
 ### Planned
 
 - iOS implementation with Swift
+- iOS event emitter support
 - Customizable location update intervals
-- Event emitters for real-time updates
 - Geofencing support
 - Distance filtering
 - SQLite storage option for large datasets