diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..60ec5ff --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,36 @@ +--- +name: Bug report +about: Report a reproducible issue +title: "[Bug]: " +labels: bug +assignees: '' +--- + +## Description + +Describe the problem clearly. + +## Reproduction Steps + +1. +2. +3. + +## Expected Behavior + +What did you expect to happen? + +## Actual Behavior + +What happened instead? + +## Environment + +- Platform: +- OS / Device: +- App version / commit: +- Node version: + +## Additional Context + +Logs, screenshots, or videos. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..91f7f0e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,23 @@ +--- +name: Feature request +about: Suggest an improvement +title: "[Feature]: " +labels: enhancement +assignees: '' +--- + +## Problem Statement + +What problem are you trying to solve? + +## Proposed Solution + +Describe the desired behavior and UX. + +## Alternatives Considered + +What alternatives did you evaluate? + +## Additional Context + +Any references, mockups, or constraints. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..872f2e2 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,29 @@ +## Summary + +- What changed? +- Why was this needed? + +## Verification + +- [ ] `npm ci` +- [ ] `npm run start` (or relevant platform run) +- [ ] Relevant manual verification completed + +Commands and outputs: + +```txt + +``` + +## Risk / Impact + +- Affected areas: +- Backward compatibility concerns: +- Rollback plan (if needed): + +## Checklist + +- [ ] Scope is focused and minimal +- [ ] Documentation updated (if behavior/setup changed) +- [ ] No secrets or credentials added +- [ ] Screenshots attached for UI changes (if applicable) diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..d8f34fe --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,22 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Added + +- Open-source baseline documentation: + - `README.md` expanded for setup, architecture, release, and security notes + - `LICENSE` (MIT) + - `CONTRIBUTING.md` + - `CODE_OF_CONDUCT.md` + - `SECURITY.md` + - `CHANGELOG.md` + +### Changed + +- Repository naming aligned to `sub2api-mobile` in public docs. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..02e7c74 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,109 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +- Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery, and sexual attention or + advances of any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email + address, without their explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for +moderation decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported via GitHub Issues or by contacting repository maintainers through +GitHub. + +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the +[Contributor Covenant](https://www.contributor-covenant.org), version 2.1, +available at +https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..de0185c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,64 @@ +# Contributing to sub2api-mobile + +Thanks for your interest in contributing. + +## Development Setup + +1. Fork and clone the repository. +2. Install dependencies: + + ```bash + npm ci + ``` + +3. Start the app: + + ```bash + npm run start + ``` + +4. For web + admin proxy testing (recommended for admin endpoints): + + ```bash + SUB2API_BASE_URL="https://your-upstream-host.example.com" \ + SUB2API_ADMIN_API_KEY="admin-xxxx" \ + ALLOW_ORIGIN="http://localhost:8081" \ + npm run dev:web-proxy + ``` + +## Branching and Commits + +- Create a feature branch from `main`. +- Keep commits focused and atomic. +- Prefer Conventional Commit prefixes when possible (`feat:`, `fix:`, `docs:`, `chore:`). + +## Pull Request Guidelines + +Before opening a PR: + +- Ensure the app builds and starts. +- Confirm no secrets are committed. +- Update documentation when behavior or setup changes. +- Keep screenshots up to date for visible UI changes. + +In your PR description, include: + +- What changed +- Why it changed +- Any risk/impact notes +- Verification evidence (commands + results) + +## Coding Guidelines + +- Follow existing project patterns and naming conventions. +- Keep changes minimal and avoid unrelated refactors. +- Prefer clear, maintainable code over clever shortcuts. + +## Reporting Issues + +- Use GitHub Issues with reproduction steps. +- Include platform details (`ios` / `android` / `web`) and environment info. + +## Community + +By participating, you agree to our [Code of Conduct](CODE_OF_CONDUCT.md). diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..f6677af --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 ckken + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 20be527..7f42b15 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,116 @@ -# x-sapi-mobile +# sub2api-mobile + +Mobile-first admin console for Sub2API operations, built with Expo + React Native + Expo Router. ## Mobile Preview ![Mobile Preview](docs/mobile.jpg) + +## Highlights + +- Cross-platform app (iOS / Android / Web) for operational and admin workflows. +- Server health and metrics monitoring views. +- User, API key, account, and group management pages. +- Built-in local admin proxy (`server/index.js`) for safer web-side admin integration. +- Multi-account admin server switching in settings. + +## Tech Stack + +- Expo SDK 54 +- React Native 0.81 +- React 19 +- Expo Router +- TanStack Query +- Valtio +- Express (local proxy) + +## Prerequisites + +- Node.js 20+ +- npm 10+ + +## Getting Started + +Install dependencies: + +```bash +npm ci +``` + +Run locally: + +```bash +npm run start +``` + +Common targets: + +```bash +npm run android +npm run ios +npm run web +``` + +## Local Admin Proxy (Web-Friendly) + +For web usage with admin APIs, start the local proxy with environment variables: + +```bash +SUB2API_BASE_URL="https://your-upstream-host.example.com" \ +SUB2API_ADMIN_API_KEY="admin-xxxx" \ +ALLOW_ORIGIN="http://localhost:8081" \ +npm run proxy +``` + +Then point the app `Base URL` to: + +```txt +http://localhost:8787 +``` + +See full details in [docs/LOCAL_PROXY_SETUP.md](docs/LOCAL_PROXY_SETUP.md). + +## Build & Release + +EAS scripts: + +```bash +npm run eas:build:development +npm run eas:build:preview +npm run eas:build:production +``` + +OTA update scripts: + +```bash +npm run eas:update:preview -- "your message" +npm run eas:update:production -- "your message" +``` + +Additional release notes: [docs/EXPO_RELEASE.md](docs/EXPO_RELEASE.md) + +## Project Structure + +```txt +app/ Expo Router routes/screens +src/components/ Reusable UI components +src/services/ Admin API request layer +src/store/ Global config/account state (Valtio) +src/lib/ Utilities, query client, fetch helpers +docs/ Operational and release documentation +server/ Local Express proxy for admin APIs +``` + +## Security Notes + +- Web builds are intentionally configured to avoid persistent storage of `adminApiKey`. +- Native platforms continue to use secure storage semantics. +- For responsible disclosure, see [SECURITY.md](SECURITY.md). + +## Contributing + +Please read [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). + +## License + +This project is licensed under the MIT License. See [LICENSE](LICENSE). diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..e08efcc --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,35 @@ +# Security Policy + +## Supported Versions + +This project is currently maintained on the `main` branch only. + +| Version | Supported | +| ------- | --------- | +| main | ✅ | + +## Reporting a Vulnerability + +If you discover a security issue, please report it privately first. + +Preferred channels: + +1. Open a private security advisory in GitHub (if enabled). +2. If private advisory is not available, open an issue with minimal details and + request a private follow-up from maintainers. + +Please include: + +- A clear description of the vulnerability +- Affected files/endpoints/flows +- Reproduction steps or proof of concept +- Potential impact +- Suggested remediation (if available) + +## Response Expectations + +- Initial triage target: within 3 business days +- Status update target: within 7 business days +- Fix timeline depends on severity and release constraints + +We will coordinate disclosure timing after remediation is available.