+Made with ❤️ by the TMDB Addon community +
diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..8324cad --- /dev/null +++ b/docs/api.md @@ -0,0 +1,179 @@ +# API Documentation + +This document describes the API endpoints available in the TMDB Addon. + +## Base URL + +All URLs referenced in the documentation have the following base: +``` +http://your_domain:1337 +``` + +## Authentication + +Most endpoints don't require authentication. However, some features might require API keys to be set in the environment variables. + +## Endpoints + +### Manifest +```http +GET /manifest.json +``` + +Returns the Stremio addon manifest with addon details and available resources. + +#### Response +```json +{ + "id": "tmdb-addon", + "version": "1.0.0", + "name": "TMDB Addon", + "description": "TMDB Addon for Stremio", + "resources": ["catalog", "meta", "stream"], + "types": ["movie", "series"], + "catalogs": [...] +} +``` + +### Catalog +```http +GET /catalog/:type/:id/:extra?.json +``` + +Returns a catalog of items based on type and ID. + +#### Parameters +- `type`: Type of content (`movie` or `series`) +- `id`: Catalog ID +- `extra`: Additional parameters (optional) + +#### Response +```json +{ + "metas": [ + { + "id": "tmdb:106646", + "type": "movie", + "name": "Movie Title", + "poster": "https://image.url/poster.jpg", + "background": "https://image.url/background.jpg" + } + ] +} +``` + +### Meta +```http +GET /meta/:type/:id.json +``` + +Returns metadata for a specific item. + +#### Parameters +- `type`: Type of content (`movie` or `series`) +- `id`: TMDB ID or IMDb ID + +#### Response +```json +{ + "meta": { + "id": "tmdb:106646", + "type": "movie", + "name": "Movie Title", + "poster": "https://image.url/poster.jpg", + "background": "https://image.url/background.jpg", + "description": "Movie description", + "runtime": "120", + "year": 2023, + "director": ["Director Name"], + "cast": ["Actor 1", "Actor 2"] + } +} +``` + +### Configuration +```http +GET /configure +``` + +Returns the configuration page for the addon. + +## Error Responses + +The API uses standard HTTP response codes: + +- `200`: Success +- `400`: Bad Request +- `404`: Not Found +- `500`: Internal Server Error + +Error response format: +```json +{ + "error": "Error message", + "code": "ERROR_CODE" +} +``` + +## Rate Limiting + +The API implements rate limiting to prevent abuse: + +- 100 requests per minute per IP +- 1000 requests per hour per IP + +Rate limit headers: +``` +X-RateLimit-Limit: 100 +X-RateLimit-Remaining: 99 +X-RateLimit-Reset: 1613937600 +``` + +## Caching + +The API implements caching for better performance: + +- Manifest: 24 hours +- Catalog: 1 hour +- Meta: 24 hours + +Cache headers: +``` +Cache-Control: public, max-age=3600 +ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4" +``` + +## Examples + +### Fetching Popular Movies +```http +GET /catalog/movie/tmdb.top/skip=0&limit=100.json +``` + +### Getting Movie Details +```http +GET /meta/movie/tmdb:106646.json +``` + +### Configuring the Addon +```http +GET /configure +``` + +## Development + +For development and testing, you can use the following tools: + +1. **Postman Collection**: + Download our Postman collection for easy API testing. + +2. **Development Environment**: + ```bash + npm run dev:server + ``` + +## Additional Resources + +- [Stremio Addon SDK Documentation](https://github.com/Stremio/stremio-addon-sdk) +- [TMDB API Documentation](https://developers.themoviedb.org/3) +- [Fanart.tv API Documentation](https://fanarttv.docs.apiary.io/) \ No newline at end of file diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..8a11b8c --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,132 @@ +# Contributing Guide + +Thank you for your interest in contributing to the TMDB Addon! This document provides guidelines and instructions for contributing to the project. + +## Code of Conduct + +By participating in this project, you agree to abide by our Code of Conduct. Please read it before contributing. + +## How Can I Contribute? + +### Reporting Bugs + +1. Check if the bug has already been reported in the Issues section +2. If not, create a new issue using the bug report template +3. Include: + - Clear title and description + - Steps to reproduce + - Expected behavior + - Actual behavior + - Screenshots if applicable + - Your environment details + +### Suggesting Enhancements + +1. Check if the enhancement has been suggested in the Issues section +2. If not, create a new issue using the feature request template +3. Include: + - Clear title and description + - Use case + - Proposed solution + - Alternative solutions considered + +### Pull Requests + +1. Fork the repository +2. Create a new branch: + ```bash + git checkout -b feature/your-feature + ``` +3. Make your changes +4. Run tests and linting: + ```bash + npm test + npm run lint + ``` +5. Commit your changes: + ```bash + git commit -m "feat: add some feature" + ``` + We use [Conventional Commits](https://www.conventionalcommits.org/) specification. + +6. Push to your fork: + ```bash + git push origin feature/your-feature + ``` +7. Open a Pull Request + +## Commit Message Guidelines + +We follow the Conventional Commits specification: + +- `feat:` - A new feature +- `fix:` - A bug fix +- `docs:` - Documentation changes +- `style:` - Code style changes (formatting, etc) +- `refactor:` - Code changes that neither fix bugs nor add features +- `perf:` - Performance improvements +- `test:` - Adding or modifying tests +- `chore:` - Changes to build process or auxiliary tools + +Example: +``` +feat: add support for custom catalogs + +- Add catalog interface +- Implement catalog registration +- Add documentation +``` + +## Development Process + +1. **Pick an Issue**: + - Look for issues labeled `good first issue` or `help wanted` + - Comment on the issue to let others know you're working on it + +2. **Development**: + - Follow the [Development Guide](development.md) + - Keep changes focused and atomic + - Add tests for new features + +3. **Code Review**: + - All submissions require review + - Be open to feedback and suggestions + - Respond to comments promptly + +## Style Guide + +- Follow the existing code style +- Use TypeScript for type safety +- Write meaningful comments +- Keep functions small and focused +- Use descriptive variable names + +## Testing + +- Write tests for new features +- Ensure all tests pass before submitting +- Include both unit and integration tests +- Test edge cases + +## Documentation + +- Update documentation for new features +- Include JSDoc comments for functions +- Update README if necessary +- Add examples when helpful + +## Need Help? + +- Check the [Development Guide](development.md) +- Look through closed issues for similar problems +- Ask questions in the discussions section +- Join our community chat + +## Recognition + +Contributors will be recognized in: +- The project's README +- Release notes +- Our contributors page + +Thank you for contributing to TMDB Addon! \ No newline at end of file diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..d454702 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,154 @@ +# Development Guide + +This guide will help you set up your development environment and understand the project structure. + +## Prerequisites + +- Node.js 20.x or higher +- npm 9.x or higher +- Git +- MongoDB (local or Atlas) +- Basic knowledge of TypeScript and React + +## Project Structure + +``` +tmdb-addon/ +├── addon/ # Backend server code +├── configure/ # Frontend configuration UI +├── docs/ # Documentation +├── node_modules/ # Dependencies +└── package.json # Project configuration +``` + +## Setting Up Development Environment + +1. Clone the repository: +```bash +git clone https://github.com/mrcanelas/tmdb-addon.git +cd tmdb-addon +``` + +2. Install dependencies: +```bash +npm install +``` + +3. Set up environment variables: +```bash +cp .env.example .env +``` + +Edit `.env` with your development credentials: +```env +MONGODB_URI=your_mongodb_uri +FANART_API=your_fanart_key +TMDB_API=your_tmdb_key +HOST_NAME=http://localhost:1337 +PORT=1337 +``` + +4. Start development server: +```bash +# Terminal 1 - Backend +npm run dev:server + +# Terminal 2 - Frontend +npm run dev +``` + +## Development Workflow + +1. **Create a new branch**: +```bash +git checkout -b feature/your-feature-name +``` + +2. **Make your changes**: +- Backend changes go in the `addon/` directory +- Frontend changes go in the `configure/` directory + +3. **Testing**: +```bash +# Run tests +npm test + +# Run linter +npm run lint +``` + +4. **Building**: +```bash +npm run build +``` + +## Code Style + +We use ESLint and Prettier for code formatting. Configuration can be found in: +- `.eslintrc.js` +- `.prettierrc` + +## Hot Reload + +- Backend uses `nodemon` for automatic reloading +- Frontend uses Vite's hot module replacement + +## Debugging + +### Backend Debugging + +1. Using VS Code: +```json +{ + "version": "0.2.0", + "configurations": [ + { + "type": "node", + "request": "launch", + "name": "Debug Server", + "program": "${workspaceFolder}/addon/server.js", + "outFiles": ["${workspaceFolder}/dist/**/*.js"] + } + ] +} +``` + +2. Using Chrome DevTools: +```bash +node --inspect addon/server.js +``` + +### Frontend Debugging + +1. Use React Developer Tools browser extension +2. Vite's development server includes source maps + +## Common Development Tasks + +### Adding New UI Components + +1. Create component in `configure/components/` +2. Add styles using Tailwind CSS +3. Import and use in relevant pages + +## Best Practices + +1. **Code Organization**: + - Keep components small and focused + - Use TypeScript interfaces for type safety + - Follow the Single Responsibility Principle + +2. **Performance**: + - Implement caching where appropriate + - Use pagination for large datasets + - Optimize API calls + +3. **Security**: + - Validate all user inputs + - Use environment variables for secrets + - Implement rate limiting + +4. **Testing**: + - Write unit tests for critical functions + - Test edge cases + - Use meaningful test descriptions \ No newline at end of file diff --git a/docs/self-hosting.md b/docs/self-hosting.md new file mode 100644 index 0000000..224c03b --- /dev/null +++ b/docs/self-hosting.md @@ -0,0 +1,144 @@ +# Self-Hosting Guide + +This guide provides instructions for self-hosting the TMDB Addon for Stremio. + +## Table of Contents +- [Self-Hosting Guide](#self-hosting-guide) + - [Table of Contents](#table-of-contents) + - [Docker Installation (Recommended)](#docker-installation-recommended) + - [Using Docker Compose](#using-docker-compose) + - [Manual Installation](#manual-installation) + - [Environment Variables](#environment-variables) + - [Getting API Keys](#getting-api-keys) + - [TMDB API](#tmdb-api) + - [Fanart.tv API](#fanarttv-api) + - [MongoDB](#mongodb) + - [Verifying Installation](#verifying-installation) + - [Troubleshooting](#troubleshooting) + - [Common Issues](#common-issues) + +## Docker Installation (Recommended) + +The easiest way to run this addon is using Docker. The image is available on Docker Hub. + +```bash +docker run -d \ + --name tmdb-addon \ + -p 1337:1337 \ + -e MONGODB_URI=your_mongodb_uri \ + -e FANART_API=your_fanart_key \ + -e TMDB_API=your_tmdb_key \ + -e HOST_NAME=http://your_domain:1337 \ + mrcanelas/tmdb-addon:latest +``` + +### Using Docker Compose + +Create a `docker-compose.yml` file: + +```yaml +version: '3' +services: + tmdb-addon: + image: mrcanelas/tmdb-addon:latest + container_name: tmdb-addon + ports: + - "1337:1337" + environment: + - MONGODB_URI=your_mongodb_uri + - FANART_API=your_fanart_key + - TMDB_API=your_tmdb_key + - HOST_NAME=http://your_domain:1337 + restart: unless-stopped +``` + +Then run: +```bash +docker-compose up -d +``` + +## Manual Installation + +1. Clone the repository: +```bash +git clone https://github.com/mrcanelas/tmdb-addon.git +cd tmdb-addon +``` + +2. Install dependencies: +```bash +npm install +``` + +3. Configure environment variables: + - Copy `.env.example` to `.env` + - Fill in the required variables in the `.env` file + +4. Build the project: +```bash +npm run build +``` + +5. Start the server: +```bash +node addon/server.js +``` + +## Environment Variables + +| Variable | Description | Required | +|----------|-------------|----------| +| `MONGODB_URI` | MongoDB connection URI | Yes | +| `FANART_API` | Fanart.tv API key | Yes | +| `TMDB_API` | TMDB API key | Yes | +| `HOST_NAME` | Public URL of your addon (e.g., http://your_domain:1337) | Yes | +| `PORT` | Server port (default: 1337) | No | + +## Getting API Keys + +### TMDB API +1. Visit [TMDB Developer](https://www.themoviedb.org/settings/api) +2. Create an account if you don't have one +3. Request an API key +4. Use the API Read Access Token (v4 auth) + +### Fanart.tv API +1. Visit [Fanart.tv API](https://fanart.tv/get-an-api-key/) +2. Register for an account +3. Request a personal API key + +### MongoDB +1. Create an account on [MongoDB Atlas](https://www.mongodb.com/cloud/atlas) +2. Set up a free cluster +3. Get your connection string +4. Replace `