{"_id":"@brijmcq/openclaw-billing-hook","_rev":"2-f6aff91ef0f5763b3ab91bc308553b2c","name":"@brijmcq/openclaw-billing-hook","dist-tags":{"latest":"0.0.2"},"versions":{"1.0.1":{"name":"@brijmcq/openclaw-billing-hook","version":"1.0.1","keywords":["openclaw","hook","billing","openrouter","quota"],"author":{"name":"brijmcq"},"license":"MIT","_id":"@brijmcq/openclaw-billing-hook@1.0.1","maintainers":[{"name":"brijmcq","email":"brijumaquio@gmail.com"}],"dist":{"shasum":"1fb266951152421ddeee0afeef3d30b36ff5508c","tarball":"https://registry.npmjs.org/@brijmcq/openclaw-billing-hook/-/openclaw-billing-hook-1.0.1.tgz","fileCount":5,"integrity":"sha512-0tnMahDDDuZbI1A/HWd5xkDAX7S8FVFc6hkdPCUJ4YmjPsdjne4VuBrJy8Ejpu2BROuc4S3UDUFmCM/TtuLp0Q==","signatures":[{"sig":"MEUCIHX0x0BXA5ZKIupSr2yxFYW4xfU1y9wNVjOqOubauosVAiEA43GO6+YLHZaX8OQjc1qZ2yApm42m+iY63hPGCAVnZ6s=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":9360},"main":"handler.js","type":"module","types":"./handler.d.ts","scripts":{"dev":"tsc --watch","build":"tsc"},"_npmUser":{"name":"brijmcq","email":"brijumaquio@gmail.com"},"openclaw":{"hooks":["./"]},"_npmVersion":"11.6.0","description":"Hook to intercept OpenRouter quota errors and show subscription message","directories":{},"_nodeVersion":"24.9.0","_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.9.3","@types/node":"^20.19.35"},"_npmOperationalInternal":{"tmp":"tmp/openclaw-billing-hook_1.0.1_1772720373625_0.449677357868824","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@brijmcq/openclaw-billing-hook","version":"0.0.2","description":"Hook to intercept OpenRouter quota errors and show subscription message","type":"module","openclaw":{"hooks":["./hooks/billing-quota-interceptor"]},"scripts":{"build":"cd hooks/billing-quota-interceptor && tsc --skipLibCheck"},"keywords":["openclaw","hook","billing","openrouter","quota"],"author":{"name":"brijmcq"},"license":"MIT","devDependencies":{"@types/node":"^20.11.0","typescript":"^5.3.0"},"_id":"@brijmcq/openclaw-billing-hook@0.0.2","_nodeVersion":"24.9.0","_npmVersion":"11.6.0","dist":{"integrity":"sha512-v0RlfawKvMkpi1ujJDEWYo8ZdW7QlvaRaEdBUzEs1us+V8gg0BbimJmrEnt1oTmiGI5CN0lj4aXIQQMgDornvw==","shasum":"ed5be0954453fcc4851deb1ae65472609bad6669","tarball":"https://registry.npmjs.org/@brijmcq/openclaw-billing-hook/-/openclaw-billing-hook-0.0.2.tgz","fileCount":7,"unpackedSize":18741,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAfhBMrlqGcMY7Gixro85RFtFg+dmFsLEp4zfIkZRVx0AiAR2OPrs1qSYmy8filwIvGPWToHxe0m7AbSBxATZXkQDg=="}]},"_npmUser":{"name":"brijmcq","email":"brijumaquio@gmail.com"},"directories":{},"maintainers":[{"name":"brijmcq","email":"brijumaquio@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/openclaw-billing-hook_0.0.2_1772720725571_0.49970233770946226"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-05T14:19:33.511Z","modified":"2026-03-05T14:25:25.800Z","1.0.1":"2026-03-05T14:19:33.761Z","0.0.2":"2026-03-05T14:25:25.706Z"},"author":{"name":"brijmcq"},"license":"MIT","keywords":["openclaw","hook","billing","openrouter","quota"],"description":"Hook to intercept OpenRouter quota errors and show subscription message","maintainers":[{"name":"brijmcq","email":"brijumaquio@gmail.com"}],"readme":"# OpenClaw Billing Hook\n\nA simple hook that intercepts OpenRouter quota errors and shows a friendly subscription message.\n\n## Installation\n\n### Via OpenClaw CLI (Recommended)\n\n```bash\nopenclaw hooks install @brijmcq/openclaw-billing-hook\nopenclaw hooks enable billing-quota-interceptor\n```\n\n### Via NPM\n\n```bash\nnpm install -g @brijmcq/openclaw-billing-hook\n```\n\nThen enable in your `openclaw.json`:\n\n```json\n{\n  \"hooks\": {\n    \"internal\": {\n      \"enabled\": true,\n      \"entries\": {\n        \"billing-quota-interceptor\": {\n          \"enabled\": true\n        }\n      }\n    }\n  }\n}\n```\n\n## What It Does\n\nWhen you hit your OpenRouter quota limit, instead of seeing:\n\n```\nError: 429 Too Many Requests - Rate limit exceeded\n```\n\nYou'll see:\n\n```\n⚠️ Monthly Credit Limit Reached\n\nYou've used your monthly OpenRouter allowance.\n\nSubscribe for $99/month: https://billing.example.com/subscribe\n\nOr wait for your next billing cycle to reset.\n```\n\n## How It Works\n\nThe hook listens to the `message_sending` event and checks outbound messages for quota error indicators. When detected, it replaces the error message with a friendly subscription prompt.\n\n## Configuration\n\n### Option 1: Dynamic API (Recommended)\n\nThe hook can fetch subscription links from your API endpoint. Configure via environment variable or OpenClaw config:\n\n**Via Environment Variable:**\n```bash\nexport BILLING_API_URL=https://api.yourdomain.com/billing/subscription-link\nopenclaw gateway --port 18789\n```\n\n**Via OpenClaw Config:**\n```json\n{\n  \"hooks\": {\n    \"internal\": {\n      \"enabled\": true,\n      \"entries\": {\n        \"billing-quota-interceptor\": {\n          \"enabled\": true,\n          \"env\": {\n            \"BILLING_API_URL\": \"https://api.yourdomain.com/billing/subscription-link\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n### API Contract\n\nYour API endpoint should accept:\n\n**Request:**\n```json\nPOST /billing/subscription-link\nContent-Type: application/json\n\n{\n  \"customer_id\": \"user@example.com\",\n  \"channel\": \"telegram\",\n  \"event_type\": \"quota_exceeded\",\n  \"timestamp\": \"2026-03-05T10:30:00Z\"\n}\n```\n\n**Response:**\n```json\n{\n  \"subscription_url\": \"https://billing.yourdomain.com/subscribe?customer=xyz\"\n}\n```\n\nThe hook will use this URL in the subscription message. You can return customer-specific URLs with tracking parameters.\n\n### Option 2: Static URL (Fallback)\n\nIf `BILLING_API_URL` is not set or API call fails, uses: `https://billing.example.com/subscribe`\n\nTo customize the fallback, edit `handler.ts` and change `FALLBACK_SUBSCRIPTION_URL`.\n\n## Restart Gateway\n\nAfter installing/enabling, restart your gateway:\n\n```bash\nopenclaw gateway --stop\nopenclaw gateway --port 18789\n```\n\n## Verify Installation\n\n```bash\n# List hooks\nopenclaw hooks list\n\n# Should show: 💳 billing-quota-interceptor ✓\n\n# Check logs\nopenclaw logs | grep billing\n```\n\n## Troubleshooting\n\n### Hook Not Listed\n\n```bash\nopenclaw hooks list\n```\n\nIf not shown, verify installation:\n- Check `~/.openclaw/hooks/` directory\n- Verify HOOK.md exists\n- Try `openclaw hooks install` again\n\n### Hook Not Intercepting\n\nCheck logs for the hook execution:\n\n```bash\nopenclaw logs | grep \"billing-hook\"\n```\n\nVerify the hook is enabled:\n\n```bash\nopenclaw hooks check\n```\n\n## Development\n\n### Build\n\n```bash\nnpm install\nnpm run build\n```\n\n### Test Locally\n\n```bash\n# Copy to OpenClaw hooks directory\ncp -r . ~/.openclaw/hooks/billing-quota-interceptor/\n\n# Enable\nopenclaw hooks enable billing-quota-interceptor\n\n# Restart gateway\nopenclaw gateway --stop\nopenclaw gateway --port 18789\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}