expo-app-blocker 0.1.20 → 0.1.22

package/.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,33 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as contributors and maintainers pledge to make participation in this project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy toward other community members
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening a GitHub issue or contacting the maintainers directly. All complaints will be reviewed and investigated and will result in a response deemed necessary and appropriate.
+
+Maintainers who do not follow or enforce the Code of Conduct may be removed from the project team.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

package/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,93 @@
+name: Bug Report
+description: Something isn't working as expected
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Before filing a bug, please check [existing issues](https://github.com/eylonshm/expo-app-blocker/issues) and the [Platform Notes](https://github.com/eylonshm/expo-app-blocker#platform-notes) in the README.
+
+  - type: input
+    id: version
+    attributes:
+      label: expo-app-blocker version
+      placeholder: "e.g. 1.2.0"
+    validations:
+      required: true
+
+  - type: input
+    id: expo_version
+    attributes:
+      label: Expo SDK version
+      placeholder: "e.g. 52"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: platform
+    attributes:
+      label: Platform
+      options:
+        - iOS
+        - Android
+        - Both
+    validations:
+      required: true
+
+  - type: input
+    id: os_version
+    attributes:
+      label: OS version
+      placeholder: "e.g. iOS 17.4 / Android 14"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: device_type
+    attributes:
+      label: Device type
+      options:
+        - Physical device
+        - Simulator / Emulator
+    validations:
+      required: true
+
+  - type: input
+    id: device_model
+    attributes:
+      label: Device model
+      placeholder: "e.g. iPhone 15 Pro, Pixel 7"
+
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: A clear description of the bug. Include what you expected vs what actually happened.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Call `requestPermissions()`
+        2. Call `setBlockConfiguration(...)`
+        3. Open blocked app
+        4. ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant logs or errors
+      description: Paste Xcode console output (iOS) or `adb logcat` output (Android). Redact any personal data.
+      render: shell
+
+  - type: textarea
+    id: config
+    attributes:
+      label: Plugin config (app.json)
+      description: Paste the relevant `expo-app-blocker` plugin config from your `app.json`.
+      render: json

package/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question / Help
+    url: https://github.com/eylonshm/expo-app-blocker/discussions
+    about: Ask questions and get help from the community
+  - name: Apple Developer Portal Setup
+    url: https://github.com/eylonshm/expo-app-blocker/blob/master/docs/APPLE_DEVELOPER_SETUP.md
+    about: Step-by-step guide for iOS entitlement and App ID setup

package/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,42 @@
+name: Feature Request
+description: Suggest a new feature or API addition
+labels: ["enhancement"]
+body:
+  - type: dropdown
+    id: platform
+    attributes:
+      label: Platform
+      options:
+        - iOS
+        - Android
+        - Both
+        - Not platform-specific
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: Describe the use case or limitation you're running into.
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: What would you like to see added or changed? Include API shape if relevant.
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any workarounds you've tried, or other libraries that handle this differently.
+
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Willing to contribute?
+      options:
+        - label: I'd be willing to open a PR for this

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,24 @@
+## Summary
+
+<!-- What does this PR do? Why? -->
+
+## Changes
+
+<!-- List the key changes. Focus on the "what" and "why", not line-by-line. -->
+
+- 
+
+## Testing
+
+- [ ] Tested on **iOS** (physical device)
+- [ ] Tested on **Android** (device or emulator)
+- [ ] Ran `npx expo prebuild --clean` and verified native output
+
+<!-- Describe how you tested this. Include device/OS version if relevant. -->
+
+## Checklist
+
+- [ ] README updated (if public API, props, or config options changed)
+- [ ] Types and JSDoc updated (if new exports added)
+- [ ] No unrelated changes included
+- [ ] PR title is clear and descriptive

package/.github/SECURITY.md

@@ -0,0 +1,30 @@
+# Security Policy
+
+## Scope
+
+`expo-app-blocker` is a client-side Expo native module. It has no server components, no network requests, and no data collection. Security concerns are most likely to involve:
+
+- Unsafe handling of app tokens or opaque selection data
+- Bypassable blocking behavior (iOS shield dismissal, Android overlay escapes)
+- Improper use of entitlements or Android permissions
+- Dependency vulnerabilities
+
+## Reporting a Vulnerability
+
+**Please do not report security vulnerabilities via public GitHub issues.**
+
+Report vulnerabilities privately using [GitHub's private vulnerability reporting](https://github.com/eylonshm/expo-app-blocker/security/advisories/new).
+
+Include as much of the following as possible:
+
+- Description of the vulnerability and potential impact
+- Steps to reproduce or proof-of-concept
+- Affected versions
+- Platform (iOS / Android) and OS version
+- Suggested fix, if you have one
+
+You can expect an acknowledgement within 72 hours. We'll keep you updated as we investigate and patch.
+
+## Supported Versions
+
+Only the latest published version on npm receives security fixes. We recommend always staying up to date.

package/.github/dependabot.yml

@@ -0,0 +1,29 @@
+version: 2
+updates:
+  # npm dependencies
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    groups:
+      expo:
+        patterns:
+          - "expo*"
+          - "@expo/*"
+    ignore:
+      # Peer deps — version is dictated by the consuming app, not this package
+      - dependency-name: "expo"
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "react-native"
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "react"
+        update-types: ["version-update:semver-major"]
+
+  # GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"

package/.github/workflows/publish.yml

@@ -10,7 +10,7 @@ jobs:
     if: "!startsWith(github.event.head_commit.message, 'v')"
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - uses: actions/setup-node@v4
         with:

package/.github/workflows/stale.yml

@@ -0,0 +1,30 @@
+name: Close stale issues
+
+on:
+  schedule:
+    - cron: "0 8 * * 1" # every Monday at 08:00 UTC
+  workflow_dispatch:
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/stale@v9
+        with:
+          stale-issue-message: >
+            This issue has been inactive for 60 days. It will be closed in 7 days
+            unless there is further activity. If this is still relevant, please
+            leave a comment or a 👍 reaction.
+          close-issue-message: >
+            Closed due to inactivity. Feel free to reopen if this is still relevant.
+          stale-pr-message: >
+            This PR has been inactive for 30 days. It will be closed in 7 days
+            unless there is further activity.
+          close-pr-message: >
+            Closed due to inactivity. Feel free to reopen if you'd like to continue.
+          days-before-issue-stale: 60
+          days-before-issue-close: 7
+          days-before-pr-stale: 30
+          days-before-pr-close: 7
+          exempt-issue-labels: "pinned,security,in-progress"
+          exempt-pr-labels: "pinned,in-progress"

package/README.md

@@ -12,6 +12,9 @@ https://github.com/user-attachments/assets/37f34797-6b92-40d5-911a-90c40e9ffaaa
 
 > **iOS requires Apple Developer Portal setup before building.** See [Prerequisites](#prerequisites) for details.
 
+> [!IMPORTANT]
+> **Submit your Family Controls distribution approval request now.** App Store distribution requires Apple approval per bundle ID — it can take days to weeks and you can't ship without it. [Request here](https://developer.apple.com/contact/request/family-controls-distribution) (you'll need to submit once per bundle ID — 4 total). You can develop and test locally without waiting.
+
 <details>
 <summary><strong>Table of Contents</strong></summary>
 
@@ -167,7 +170,9 @@ npx expo run:android         # Android works on emulator
 
 3. Assign the App Group to all 4 App IDs
 
-4. Request **Family Controls** capability approval (works in dev builds without approval)
+4. Request **Family Controls** capability approval (required for App Store/TestFlight — works in local dev builds without it)
+   - Submit the form **once per bundle ID** (4 total): [developer.apple.com/contact/request/family-controls-distribution](https://developer.apple.com/contact/request/family-controls-distribution)
+   - Incomplete capability setup causes cryptic provisioning errors — make sure all 4 App IDs have Family Controls + App Groups enabled
 
 ### Android
 
@@ -564,6 +569,8 @@ const styles = StyleSheet.create({
 - **FamilyActivityPicker is required** - No API to enumerate installed apps on iOS
 - **Shield customization is limited** - Only icon, title, subtitle, button labels, and colors can be changed. No custom views, fonts, or animations
 - **Cannot open apps from shield** - Use notifications as a workaround to redirect users to your app
+- **Permission status may lag** - After a user grants or revokes Screen Time access outside your app, the status may not update until the app is restarted. Re-check on app foreground
+- **Picker may crash on large categories** - The native `FamilyActivityPicker` can crash when scrolling through very large app categories. Consider providing fallback UI (e.g. a retry button) if this affects your users
 
 ### Android Limitations
 

package/docs/APPLE_DEVELOPER_SETUP.md

@@ -9,6 +9,27 @@ This guide walks you through the one-time setup required in the Apple Developer
 
 ---
 
+## Step 0: Request Family Controls Approval (Do This First)
+
+> **Do this before anything else.** App Store and TestFlight distribution require explicit Apple approval for the Family Controls entitlement. Approval can take days to weeks — start the process immediately.
+
+Because `expo-app-blocker` creates 4 bundle identifiers (main app + 3 extensions), **you must submit the request form once for each bundle ID**:
+
+| Bundle ID | Submit for |
+|---|---|
+| `com.yourapp.id` | Main app |
+| `com.yourapp.id.DeviceActivityMonitor` | DeviceActivityMonitor extension |
+| `com.yourapp.id.ShieldAction` | ShieldAction extension |
+| `com.yourapp.id.ShieldConfiguration` | ShieldConfiguration extension |
+
+Submit each one at: https://developer.apple.com/contact/request/family-controls-distribution
+
+**You can continue with local development builds without waiting for approval.** Approval is only required to distribute via TestFlight or the App Store.
+
+> **Warning:** If you skip or partially complete the capability setup in Steps 2–6, you will run into cryptic provisioning errors during build. Make sure all 4 App IDs have both **Family Controls** and **App Groups** enabled before building.
+
+---
+
 ## Step 1: Create the App Group
 
 The App Group enables data sharing between your main app and the three iOS extensions.
@@ -129,16 +150,13 @@ When you're done, you should have:
 
 ## About Family Controls Approval
 
-- **Development builds** (run from Xcode): Family Controls works **without** formal Apple approval
-- **TestFlight**: May require approval depending on your account
-- **App Store**: Requires Family Controls capability approval from Apple
-
-To request approval:
-1. Go to https://developer.apple.com/contact/request/family-controls-distribution
-2. Fill out the form explaining your app's use case
-3. Wait for Apple's response (can take days to weeks)
+| Distribution method | Approval required? |
+|---|---|
+| Local dev build (Xcode / `expo run:ios`) | No |
+| TestFlight | Yes |
+| App Store | Yes |
 
-**You can develop and test locally without waiting for approval.**
+See [Step 0](#step-0-request-family-controls-approval-do-this-first) for submission instructions. You must submit once per bundle ID (4 total).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-app-blocker",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "Expo module for cross-platform app blocking. Android: UsageStatsManager + Overlay. iOS: Screen Time API (FamilyControls + ManagedSettings + DeviceActivity).",
   "main": "src/index.ts",
   "types": "src/index.ts",