{"id":35163928,"url":"https://github.com/ducks/discourse-yaks","last_synced_at":"2026-05-22T07:34:52.127Z","repository":{"id":319534748,"uuid":"1072314019","full_name":"ducks/discourse-yaks","owner":"ducks","description":"Virtual currency system for Discourse - users earn and spend \"Yaks\" to unlock premium post features like colored highlights, pins, and boosts. Includes wallet management, configurable purchase packages, and transaction history. Payment integration ready (currently stubbed).","archived":false,"fork":false,"pushed_at":"2025-10-19T02:34:17.000Z","size":103,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-19T11:44:19.200Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ducks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-08T14:48:42.000Z","updated_at":"2025-10-19T02:34:21.000Z","dependencies_parsed_at":null,"dependency_job_id":"c48605d0-2cc1-4fca-b3d1-dd9c79a06c74","html_url":"https://github.com/ducks/discourse-yaks","commit_stats":null,"previous_names":["ducks/discourse-yaks"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ducks/discourse-yaks","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ducks%2Fdiscourse-yaks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ducks%2Fdiscourse-yaks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ducks%2Fdiscourse-yaks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ducks%2Fdiscourse-yaks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ducks","download_url":"https://codeload.github.com/ducks/discourse-yaks/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ducks%2Fdiscourse-yaks/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33333530,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-21T12:23:38.849Z","status":"online","status_checked_at":"2026-05-22T02:00:06.671Z","response_time":265,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-28T19:03:35.509Z","updated_at":"2026-05-22T07:34:52.121Z","avatar_url":"https://github.com/ducks.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Discourse Yaks - Virtual Currency System\n\nA virtual currency system for Discourse forums that allows users to earn and spend \"Yaks\" on premium features. The name is a playful pun on \"yakking\" (talking/chatting) and \"yak shaving\" (developer rabbit holes).\n\n## Features\n\n### Core Wallet System\n- **Balance Tracking**: Each user has a wallet with current balance and lifetime statistics\n- **Transaction History**: Complete audit trail of all Yak transactions\n- **Multiple Transaction Types**: Purchase, earn, spend, refund, and admin grants\n\n### Available Features\n\n**Currently Implemented:**\n1. **Post Highlighting** - Add a colored border and background to posts (gold, blue, red, green, purple)\n2. **Topic Pinning** - Pin topics to the top of their category for a limited time\n3. **Custom User Title** - Set a custom title displayed next to your username\n4. **Custom Avatar Flair** - Display custom flair badge next to your avatar\n5. **Topic Boost** - Pin topic globally with visual highlighting\n\n**All features support quantity purchases** - Buy multiple units to extend duration (e.g., 2x = double duration at 2x cost, up to 12x)\n\n**Planned Features:**\n6. **Post Pinning** - Pin posts to the top of topics\n7. **Post Boost** - Priority in feeds and search\n\n### Admin Tools\n- System-wide statistics dashboard\n- Grant Yaks to users\n- View transaction history with filtering\n- Create and manage custom features\n- Edit earning rules (amount, daily caps, trust level requirements)\n- Manage purchase packages\n- Full audit logging\n\n## Installation\n\n1. Add the plugin to your `app.yml`:\n\n```yaml\nhooks:\n  after_code:\n    - exec:\n        cd: $home/plugins\n        cmd:\n          - git clone https://github.com/discourse/discourse-yaks.git\n```\n\n2. Rebuild your container:\n\n```bash\n./launcher rebuild app\n```\n\n3. Enable the plugin in Admin → Settings → Plugins → `yaks_enabled`\n\n4. Default features will be seeded automatically when enabled\n\n## Configuration\n\n### Site Settings\n\n- **yaks_enabled** - Enable/disable the Yaks currency system\n- **yaks_dollar_to_yak_rate** - Exchange rate (default: 20 Yaks per $1)\n- **yaks_earning_enabled** - Allow users to earn Yaks through contributions\n- **yaks_min_likes_for_reward** - Minimum likes needed to earn Yaks (default: 5)\n- **yaks_max_reward_per_post** - Maximum Yaks per post (default: 50)\n- **yaks_show_balance_publicly** - Show balances on user profiles\n\n## Usage\n\n### For Users\n\n#### Viewing Balance\nUsers can view their Yak balance at `/yaks` which shows:\n- Current balance\n- Lifetime earned and spent\n- Transaction history\n- Available features to purchase\n\n#### Spending Yaks\n1. Navigate to a post or topic you want to enhance\n2. Click the \"Spend Yaks\" button (in post actions menu or topic footer)\n3. Select a feature and customize options (e.g., highlight color)\n4. Confirm the purchase\n5. The feature is applied immediately and your balance is updated\n\nNote: Topic pins appear at the top of their category, not the global Latest feed. Topic boosts pin globally across all categories.\n\n#### Earning Yaks\nUsers can earn Yaks automatically through:\n- Creating posts\n- Creating topics\n- Receiving likes on posts\n- Having solutions accepted (with Solved plugin)\n\nAll earning rules are configurable by admins:\n- Amount of Yaks awarded per action\n- Daily caps to prevent abuse\n- Minimum trust level requirements\n- Enable/disable specific rules\n\nUsers can also receive Yaks through:\n- Admin grants\n- Purchases (stubbed endpoint, awaiting Stripe integration)\n\n#### Purchasing Yaks\n- Visit `/yaks/purchase` to see available packages\n- Payment integration stubbed for now (awaiting Stripe)\n- Packages configurable via site settings\n\n### For Admins\n\n#### Granting Yaks\n```bash\nPOST /admin/yaks/give\n{\n  \"user_id\": 123,\n  \"amount\": 100,\n  \"reason\": \"Community contribution award\"\n}\n```\n\n#### Viewing Statistics\n- Navigate to Admin → Yaks\n- View system-wide stats and recent transactions\n- Filter transactions by user or type\n\n#### Creating Custom Features\n```bash\nPOST /admin/yaks/features\n{\n  \"feature_key\": \"custom_avatar_frame\",\n  \"feature_name\": \"Custom Avatar Frame\",\n  \"description\": \"Add a decorative frame to your avatar\",\n  \"cost\": 75,\n  \"category\": \"user\",\n  \"settings\": {\n    \"duration_days\": 30\n  }\n}\n```\n\n## API Endpoints\n\n### User Endpoints\n- `GET /yaks` - View wallet and available features\n- `POST /yaks/spend` - Purchase and apply a feature\n- `POST /yaks/purchase` - Buy Yaks (stubbed)\n\n### Admin Endpoints\n- `GET /admin/yaks` - System statistics\n- `POST /admin/yaks/give` - Grant Yaks to users\n- `GET /admin/yaks/transactions` - Transaction history\n- `POST /admin/yaks/features` - Create new feature\n- `PUT /admin/yaks/features/:id` - Update feature\n\n## Database Schema\n\n### Tables\n- `yak_wallets` - User wallet balances and lifetime stats\n- `yak_transactions` - Complete transaction history\n- `yak_features` - Available purchasable features\n- `yak_feature_uses` - Tracking of applied features\n\n### Custom Fields\n- `users.yak_balance` - Cached balance for quick lookups\n- `posts.yak_features` - JSON field storing active post features\n\n## Development\n\n### Running Tests\n\n```bash\n# Run all plugin tests\nLOAD_PLUGINS=1 bin/rspec plugins/discourse-yaks/spec\n\n# Run specific test file\nLOAD_PLUGINS=1 bin/rspec plugins/discourse-yaks/spec/models/yak_wallet_spec.rb\n```\n\n### Project Structure\n\n```\nplugins/discourse-yaks/\n├── plugin.rb                    # Main plugin definition\n├── config/\n│   ├── settings.yml             # Site settings\n│   └── locales/en.yml          # Translations\n├── db/migrate/\n│   └── 20250103000001_create_yak_system.rb\n├── app/\n│   ├── controllers/\n│   │   ├── yaks_controller.rb\n│   │   └── admin/yaks_controller.rb\n│   ├── models/\n│   │   ├── yak_wallet.rb\n│   │   ├── yak_transaction.rb\n│   │   ├── yak_feature.rb\n│   │   └── yak_feature_use.rb\n│   └── services/\n│       └── yak_feature_service.rb\n├── assets/\n│   ├── javascripts/discourse/   # Frontend components (complete)\n│   │   ├── components/\n│   │   ├── initializers/\n│   │   ├── routes/\n│   │   └── templates/\n│   └── stylesheets/yaks.scss\n├── spec/                        # Full test suite\n└── README.md\n```\n\n## Current Status\n\n### Implemented (Version 20251019)\n**Backend:**\n- Core wallet and transaction system\n- Database schema and migrations\n- All models with full test coverage\n- YakFeatureService with modular post/topic support\n- Controllers (user and admin endpoints)\n- Site settings configuration\n- Feature expiration system with background jobs\n- Earning system with configurable rules\n- Real-time balance updates via MessageBus\n- Quantity support for extended feature durations\n\n**Frontend:**\n- Balance display in user menu with reactive updates\n- Spend Yaks button in post actions menu and topic footer\n- Modular feature selection modal with quantity support\n- Full wallet page with stats and transaction history\n- Purchase flow with configurable packages\n- Post highlighting with 5 color options\n- Topic pinning and boosting UI\n- Custom title and flair modals with live preview\n- Shared YakFeatureQuantity helper class\n- Modern Discourse API patterns\n\n**Admin UI:**\n- System statistics dashboard\n- Manage purchase packages\n- Edit features\n- Edit earning rules\n- Transaction history with filters\n\n**Features Working End-to-End:**\n- Post highlighting with expiration\n- Topic pinning and boosting\n- Custom user titles and avatar flair\n- Earning Yaks through posts, topics, likes, solutions\n- Quantity purchases for extended durations\n\n### Next Steps\n1. **Implement Remaining Features**\n   - Post pinning logic and display\n   - Post boost logic and display\n\n2. **Authorization \u0026 Security**\n   - Guardian implementation\n   - Rate limiting on endpoints\n   - Security audit\n\n3. **Payment Integration**\n   - Replace stub with real Stripe integration\n   - Webhook handlers\n   - Refund processing\n\n4. **Testing**\n   - Controller request specs\n   - System specs for UI interactions\n   - JavaScript component tests\n\n## Security Considerations\n\n- All spending actions require authentication\n- Transaction atomicity ensures balance consistency\n- Rate limiting on spending (to be implemented)\n- Admin actions logged via StaffActionLogger\n- Input validation on all endpoints\n\n## Performance\n\n- Denormalized `users.yak_balance` for fast lookups\n- Indexed foreign keys on all relations\n- JSONB for flexible feature_data storage\n- Efficient scopes for common queries\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Write tests for new functionality\n4. Ensure all tests pass\n5. Submit a pull request\n\n## License\n\nGPL v2 (same as Discourse)\n\n## Support\n\n- Report issues on GitHub\n- Community discussion on Meta Discourse\n- Documentation at discourse.org\n\n---\n\n**Version**: 20251019\n**Status**: Alpha - Backend and frontend complete. Five features working end-to-end with expiration system. Earning system operational. Admin UI fully functional.\n**Discourse Version**: Tested with Discourse 3.4+\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fducks%2Fdiscourse-yaks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fducks%2Fdiscourse-yaks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fducks%2Fdiscourse-yaks/lists"}