Repository navigation
Expand file tree
/
Copy path.cursorrules
More file actions
135 lines (108 loc) · 6.39 KB
/
Copy path.cursorrules
File metadata and controls
135 lines (108 loc) · 6.39 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
# Stremio Streaming Catalogs Addon - Development Rules
## Project Overview
This is a Stremio addon that provides streaming catalogs from 20+ streaming services (Netflix, Disney+, HBO Max, etc.). It consists of a Node.js/Express backend and a Vue.js frontend.
## Architecture
- **Backend**: Express.js server serving Stremio addon API endpoints
- **Frontend**: Vue.js 3 + Vite + Tailwind CSS web interface
- **Ports**: Backend runs on 7700, Frontend dev server on 5173
- **Build**: Frontend builds to `vue/dist/` which backend serves statically
## Key Files
- `index.js` - Main Express server with addon endpoints
- `addon.js` - Core addon logic for fetching streaming catalogs
- `vue/src/App.vue` - Main Vue component with streaming service selection
- `vue/dist/` - Built frontend (generated, not committed to git)
## Environment Variables
- Backend: Optional `.env` in root (MIXPANEL_KEY, PORT, REFRESH_INTERVAL, NODE_ENV)
- Frontend: `vue/.env` (production) and `vue/.env.development` (dev) - both included in repo
- Critical: `VITE_APP_URL` in frontend .env files must point to backend URL
## Development Workflow
1. Backend: `npm run dev` (nodemon auto-reload)
2. Frontend: `cd vue && npm run dev` (Vite hot reload)
3. Build: `cd vue && npm run build` (creates dist for backend to serve)
## Common Issues & Solutions
- **Server crashes on startup**: Usually due to external API rate limits or network issues in `loadNewCatalog()`
- **Frontend not loading**: Check `VITE_APP_URL` in .env files points to correct backend URL
- **Build issues**: Ensure `vue/dist/` exists (run `npm run build` in vue directory)
- **Rate limiting (429 errors)**: May occur during development when making many API calls
## API Endpoints
- `/manifest.json` - Stremio addon manifest
- `/:configuration/manifest.json` - Dynamic manifest based on user selection
- `/catalog/:type/:id.json` - Streaming catalog data
- All other routes serve the Vue frontend
## External Dependencies
- Fetches catalogs from various streaming service APIs
- Uses Mixpanel for analytics (optional)
- Requires internet connection for catalog loading
## Git Considerations
- `vue/dist/` is in .gitignore (build artifacts)
- `.env` files are committed (pre-configured for dev/prod)
- `node_modules/` excluded from both root and vue directories
## Performance Notes
- Catalogs refresh every 6 hours by default (configurable via REFRESH_INTERVAL)
- Server caches responses with appropriate headers
- Frontend uses Vite for fast development builds
## Deployment
- Backend serves built frontend from `vue/dist/`
- Production: Set NODE_ENV=production, build frontend, start backend
- Environment files already configured for both dev and production
## Adding New Streaming Providers
### **CRITICAL: Always Use GraphQL API - Never Guess Provider Codes!**
**IMPORTANT**: Never guess provider codes like 'vki' for Viki. Always use the GraphQL API to find the actual `shortName` from the `clearName`. The provider code is the `shortName` field, not something you can guess.
**Reference**: See `docs/justwatch.graphql` for the complete GraphQL schema (reverse engineered, so examples may be incomplete).
**Step 1: Research Provider**
```bash
# Find provider code using clearName (this is the actual provider code!)
curl -s "https://apis.justwatch.com/graphql" -H "Content-Type: application/json" \
-d '{"operationName":"Packages","variables":{"platform":"WEB","country":"US"},"query":"query Packages { packages(platform: WEB, country: US) { shortName clearName } }"}' | jq '.data.packages[] | select(.clearName | contains("ProviderName"))'
# Find provider icon URL
curl -s "https://apis.justwatch.com/graphql" -H "Content-Type: application/json" \
-d '{"operationName":"GetPackages","variables":{"country":"US","platform":"WEB"},"query":"query GetPackages($country: Country!, $platform: Platform!) { packages(country: $country, platform: $platform) { id icon } }"}' | jq '.data.packages[] | select(.icon | contains("providername")) | .icon'
```
**Step 2: Test Content Availability**
```bash
# Check if provider has content
curl -s "https://apis.justwatch.com/graphql" -H "Content-Type: application/json" \
-d '{"operationName":"GetPopularTitles","variables":{"popularTitlesSortBy":"TRENDING","first":1,"platform":"WEB","popularTitlesFilter":{"objectTypes":["MOVIE"],"packages":["PROVIDER_CODE"]},"language":"en","country":"US"},"query":"query GetPopularTitles($country: Country!, $popularTitlesFilter: TitleFilter, $popularAfterCursor: String, $popularTitlesSortBy: PopularTitlesSorting! = POPULAR, $first: Int!, $language: Language!, $offset: Int = 0, $sortRandomSeed: Int! = 0, $profile: PosterProfile, $backdropProfile: BackdropProfile, $format: ImageFormat) { popularTitles(country: $country, filter: $popularTitlesFilter, offset: $offset, after: $popularAfterCursor, sortBy: $popularTitlesSortBy, first: $first, sortRandomSeed: $sortRandomSeed) { totalCount } }"}' | grep -o '"totalCount":[0-9]*'
```
### **Integration Steps (In Order)**
**1. Backend (index.js)**
```javascript
// Add to movies/series objects
'mbi': [],
// Add catalog loading
movies.mbi = await addon.getMetas('MOVIE', ['mbi'], 'US');
series.mbi = await addon.getMetas('SHOW', ['mbi'], 'US');
// Add manifest entry
if (selectedProviders.includes('mbi')) {
catalogs.push({ id: 'mbi', type: 'movie', name: 'Mubi' });
catalogs.push({ id: 'mbi', type: 'series', name: 'Mubi' });
}
```
**2. Download Icon**
```bash
curl -s "https://images.justwatch.com/icon/ICON_ID/s100/providername.webp" -o vue/public/providername.webp
```
**3. Frontend (App.vue)**
```html
<!-- Add icon to template -->
<Popper v-show="showProvider('mbi')" hover content="Mubi">
<img src="/mubi.webp" @click="toggle('mbi')" class="rounded-xl"
:class="!isActive('mbi') ? 'inactive' : ''" role="button" />
</Popper>
```
```javascript
// Add to regions object
'United States': ['nfx', 'mbi', ...],
'Any': ['nfx', 'mbi', ...],
```
**4. Test Integration**
```bash
curl -s "http://localhost:7700/catalog/movie/mbi.json" | jq '.metas | length'
curl -s "http://localhost:7700/catalog/series/mbi.json" | jq '.metas | length'
```
### **Common Provider Codes**
- nfx: Netflix, nfk: Netflix Kids, dnp: Disney+, amp: Prime, atp: Apple TV+
- hbm: HBO Max, pmp: Paramount+, pcp: Peacock, hlu: Hulu, cru: Crunchyroll
- cts: Curiosity Stream, mgl: MagellanTV, jhs: JioHotstar, zee: Zee5
- hay: Hayu, nlz: NLZIET, sst: SkyShowtime, cpd: Canal+, dpe: Discovery+
- stz: Starz, mbi: Mubi, vik: Viki, sgo: Sky Go, sonyliv: Sony Liv