|
| 1 | +# meetup_bot Project Reference |
| 2 | + |
| 3 | +## General Instructions |
| 4 | + |
| 5 | +- Minimize inline comments |
| 6 | +- Retain tabs, spaces, and encoding |
| 7 | +- Fix linting errors before saving files. |
| 8 | + - Respect `.markdownlint.jsonc` rules for all markdown files |
| 9 | +- If under 50 lines of code (LOC), print the full function or class |
| 10 | +- If the token limit is close or it's over 50 LOC, print the line numbers and avoid comments altogether |
| 11 | +- Explain as much as possible in the chat unless asked to annotate (i.e., docstrings, newline comments, etc.) |
| 12 | + |
| 13 | +## Build, Lint, and Test Commands |
| 14 | + |
| 15 | +- Full test suite: `uv run pytest` or `task test` |
| 16 | +- Single test: `uv run pytest tests/test_filename.py::test_function_name` |
| 17 | +- Linting: `uv run ruff check --fix --respect-gitignore` or `task lint` |
| 18 | +- Formatting: `uv run ruff format --respect-gitignore` or `task format` |
| 19 | +- Check dependencies: `uv run deptry .` or `task deptry` |
| 20 | +- Pre-commit hooks: `pre-commit run --all-files` or `task pre-commit` |
| 21 | + |
| 22 | +## Code Style Guidelines |
| 23 | + |
| 24 | +- **Formatting**: 4 spaces, 130-char line limit, LF line endings |
| 25 | +- **Imports**: Ordered by type, combined imports when possible |
| 26 | +- **Naming**: snake_case functions/vars, PascalCase classes, UPPERCASE constants |
| 27 | +- **Type Hints**: Use Optional for nullable params, pipe syntax for Union |
| 28 | +- **Error Handling**: Specific exception types, descriptive error messages |
| 29 | +- **File Structure**: Core logic in app/core/, utilities in app/utils/ |
| 30 | +- **Docstrings**: Use double quotes for docstrings |
| 31 | +- **Tests**: Files in tests/, follow test_* naming convention |
| 32 | + |
| 33 | +## GraphQL API Troubleshooting |
| 34 | + |
| 35 | +When debugging GraphQL API issues (particularly for Meetup API): |
| 36 | + |
| 37 | +### 1. Direct GraphQL Testing |
| 38 | +- Test queries directly against the GraphQL endpoint using curl before debugging application code |
| 39 | +- Example: `curl -X POST "https://api.meetup.com/gql-ext" -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d '{"query": "query { self { id name } }"}'` |
| 40 | +- Start with simple queries (like `self { id name }`) then gradually add complexity |
| 41 | + |
| 42 | +### 2. API Migration Validation |
| 43 | +- Check API documentation for migration guides when encountering field errors |
| 44 | +- Common Meetup API changes: |
| 45 | + - `count` → `totalCount` |
| 46 | + - `upcomingEvents` → `memberEvents(first: N)` for self queries |
| 47 | + - `upcomingEvents` → `events(first: N)` for group queries |
| 48 | + - Syntax changes: `field(input: {first: N})` → `field(first: N)` |
| 49 | + |
| 50 | +### 3. Response Structure Analysis |
| 51 | +- Add temporary debug logging to inspect actual GraphQL responses |
| 52 | +- Check for `errors` array in GraphQL responses, not just HTTP status codes |
| 53 | +- Verify field existence with introspection or simple field queries |
| 54 | +- Example debug pattern: |
| 55 | + ```python |
| 56 | + response_data = r.json() |
| 57 | + if 'errors' in response_data: |
| 58 | + print('GraphQL Errors:', json.dumps(response_data['errors'], indent=2)) |
| 59 | + ``` |
| 60 | + |
| 61 | +### 4. Field Validation Process |
| 62 | +- Use GraphQL validation errors to identify undefined fields |
| 63 | +- Test field names individually: `{ self { fieldName } }` |
| 64 | +- Check if field requires parameters (e.g., `memberEvents` requires `first`) |
| 65 | +- Validate nested field access patterns |
| 66 | + |
| 67 | +### 5. Token and Authentication Debugging |
| 68 | +- Verify token generation is working: `uv run python -c "from app.sign_jwt import main; print(main())"` |
| 69 | +- Test tokens directly against GraphQL endpoint outside of application |
| 70 | +- Check token expiration and refresh token logic |
0 commit comments