{"id":25869472,"url":"https://github.com/javier1292/subscriptions-manager","last_synced_at":"2025-10-18T10:40:55.611Z","repository":{"id":279454727,"uuid":"938383594","full_name":"javier1292/subscriptions-manager","owner":"javier1292","description":"Automated subscription lifecycle management system leveraging AWS serverless infrastructure. Processes real-time webhook events from Lemon Squeezy and executes scheduled expiration checks.  ","archived":false,"fork":false,"pushed_at":"2025-02-25T16:24:39.000Z","size":21,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-04T20:24:23.084Z","etag":null,"topics":["amazon-iam","aws","aws-cloudformation","aws-cloudwatch","aws-dynamodb","aws-eventbridge","aws-lambda","serverless-framework"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/javier1292.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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}},"created_at":"2025-02-24T21:43:29.000Z","updated_at":"2025-02-27T21:05:23.000Z","dependencies_parsed_at":"2025-02-25T17:34:02.510Z","dependency_job_id":"2fb76f59-3d65-4ce9-aaf0-565fb8c801b5","html_url":"https://github.com/javier1292/subscriptions-manager","commit_stats":null,"previous_names":["javier1292/subscriptions-manager"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/javier1292%2Fsubscriptions-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/javier1292%2Fsubscriptions-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/javier1292%2Fsubscriptions-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/javier1292%2Fsubscriptions-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/javier1292","download_url":"https://codeload.github.com/javier1292/subscriptions-manager/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/javier1292%2Fsubscriptions-manager/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259103302,"owners_count":22805664,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["amazon-iam","aws","aws-cloudformation","aws-cloudwatch","aws-dynamodb","aws-eventbridge","aws-lambda","serverless-framework"],"created_at":"2025-03-02T05:17:32.720Z","updated_at":"2025-10-18T10:40:55.529Z","avatar_url":"https://github.com/javier1292.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Subscription Management System\n\n[![Serverless](https://img.shields.io/badge/Serverless-Framework-%23FD5750?style=flat-square)](https://www.serverless.com/)\n[![AWS](https://img.shields.io/badge/AWS-%23FF9900?style=flat-square\u0026logo=amazon-aws)](https://aws.amazon.com/)\n\nServerless solution for comprehensive subscription management with capabilities to:\n\n- Register events via webhook\n- Automate renewal notifications\n- Securely store data in DynamoDB\n- Send bulk emails with SES\n\n## Table of Contents\n\n1. [System Architecture](#system-architecture)\n2. [Technical Requirements](#technical-requirements)\n3. [Initial Setup](#initial-setup)\n4. [AWS Deployment](#aws-deployment)\n5. [API Endpoints](#api-endpoints)\n6. [Data Structure](#data-structure)\n7. [Workflows](#workflows)\n8. [Error Handling](#error-handling)\n9. [Security](#security)\n10. [Monitoring](#monitoring)\n11. [Contribution](#contribution)\n12. [License](#license)\n\n## System Architecture\n\n```mermaid\nflowchart TD\n    subgraph \".\"\n        D[(🗄️ DynamoDB\\nSubscriptions)]\n    end\n    subgraph \"API Gateway Flow\"\n        A[🍋 Lemon Squeezy\\nWebhook] --\u003e|POST /subscriptions| B[🌐 API Gateway]\n        B --\u003e|Invokes| C[λ Lambda\\nhandlerSubscription]\n        C --\u003e|PutItem| D\n    end\n\n    subgraph \"Scheduled Flow\"\n        E[⏰ EventBridge\\nCron: 0 10 * * *] --\u003e|Triggers| F[λ Lambda\\ncheckExpirations]\n        F --\u003e|Query| D\n        F --\u003e|Send Notification| G[✉️ SES/SMS]\n        end\n\n\n    style A fill:#FFD700,color:black\nstyle B fill:#9C27B0,color:white\nstyle C fill:#00BFFF,color:white\nstyle D fill:#FFA500,color:white\nstyle E fill:#9C27B0,color:white\nstyle F fill:#00BFFF,color:white\nstyle G fill:#34A853,color:white\n```\n\n## Technical Requirements\n\nAWS Account with permissions for:\n\n- Lambda\n- DynamoDB\n- SES\n- IAM\n- CloudFormation\n\nNode.js 18.x+\nServerless Framework 3.x+\nVerified SES Email for sending\n\n## Initial Setup\n\nClone repository\n\nInstall dependencies:\n\n```bash\nnpm install\n```\n\nConfigure variables in `serverless.yml`:\n\n```yaml\ncustom:\n  deploymentBucket: your-bucket-name\n  sesEmail: notifications@yourdomain.com\n  dynamoTable: Subscriptions\n```\n\n## AWS Deployment\n\nConfigure AWS credentials:\n\n```bash\naws configure\n```\n\nDeploy full stack:\n\n```bash\nserverless deploy --stage prod --region us-east-2\n```\n\nVerify created resources:\n\n```bash\nserverless info --stage prod --region us-east-2\n```\n\n## API Endpoints\n\n### Register Subscription Event\n\n**POST** `https://api.yourdomain.com/prod/subscriptions`\n\nExample Body:\n\n```json\n{\n  \"data\": {\n    \"id\": \"sub_ABC123\",\n    \"attributes\": {\n      \"user_email\": \"client@example.com\",\n      \"status\": \"active\",\n      \"variant_name\": \"premium\",\n      \"created_at\": \"2024-01-01T00:00:00Z\",\n      \"renews_at\": \"2024-12-31T00:00:00Z\"\n    }\n  }\n}\n```\n\nSuccess Response:\n\n```json\n{\n  \"operation\": \"updated\",\n  \"metadata\": {\n    \"subscriptionId\": \"sub_ABC123\",\n    \"status\": \"active\",\n    \"nextBillingDate\": \"2024-12-31T00:00:00Z\"\n  }\n}\n```\n\n## Data Structure\n\n### DynamoDB Table: Subscriptions\n\n| Attribute      | Type    | Description                      |\n| -------------- | ------- | -------------------------------- |\n| userId (PK)    | String  | User email address               |\n| subscriptionId | String  | Unique subscription ID           |\n| status         | String  | Current status (active/inactive) |\n| plan           | String  | Subscription plan name           |\n| startDate      | String  | Start date (ISO 8601)            |\n| endDate        | String  | Expiration date (ISO 8601)       |\n| cancelled      | Boolean | Cancellation status              |\n\nSecondary Indexes:\n\n- `status-endDate-index` (GSI)\n  - Partition Key: `status`\n  - Sort Key: `endDate`\n\n## Workflows\n\n### Notification Process\n\n- Daily execution at 10:00 UTC via EventBridge\n- DynamoDB query using GSI:\n  - \"active\" subscriptions\n  - `endDate \u003c= (Current Date + 3 days)`\n- Batch email sending via SES\n- CloudWatch metrics logging\n\nEmail Template:\n\n```html\n\u003cdiv style=\"font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto;\"\u003e\n  \u003ch2 style=\"color: #2c3e50;\"\u003eSubscription Renewal\u003c/h2\u003e\n  \u003cp\u003eDear user,\u003c/p\u003e\n  \u003cp\u003e\n    Your subscription \u003cstrong\u003e(${plan})\u003c/strong\u003e will expire on\n    \u003cstrong\u003e${endDate}\u003c/strong\u003e.\n  \u003c/p\u003e\n  \u003ca\n    href=\"https://yourdomain.com/renew/${subscriptionId}\"\n    style=\"background: #3498db; color: white; padding: 10px 20px; text-decoration: none; border-radius: 5px;\"\n  \u003e\n    Renew Now\n  \u003c/a\u003e\n  \u003cp style=\"margin-top: 20px; color: #7f8c8d;\"\u003e\n    Questions? Contact our support team.\n  \u003c/p\u003e\n\u003c/div\u003e\n```\n\n## Error Handling\n\n### HTTP Status Codes\n\n| Code | Scenario                | Recommended Action     |\n| ---- | ----------------------- | ---------------------- |\n| 400  | Missing required fields | Verify webhook payload |\n| 500  | Internal server error   | Check CloudWatch logs  |\n| 200  | No update needed        | No action required     |\n\n### Error Logging\n\nDetailed logs are stored in CloudWatch under:\n\n- `/aws/lambda/subscription-manager-prod-handlerSubscription`\n- `/aws/lambda/subscription-manager-prod-checkExpirations`\n\n## Security\n\n### IAM Permissions Model\n\n| Service    | Permissions             | Scope                    |\n| ---------- | ----------------------- | ------------------------ |\n| DynamoDB   | UpdateItem, Query       | Subscriptions table      |\n| SES        | SendEmail, SendRawEmail | From verified email      |\n| CloudWatch | PutMetricData           | Namespace: Subscriptions |\n\n### Best Practices\n\n- SES domain validation\n- AES-256 encryption in DynamoDB\n- Lambda timeout set to 15 seconds\n- Lambda versioning enabled\n\n## Monitoring\n\n### Key Metrics\n\n| Service  | Metric                    | Alert Threshold |\n| -------- | ------------------------- | --------------- |\n| Lambda   | Invocations               | \u003e 1000/min      |\n|          | Error Rate                | \u003e 5%            |\n| DynamoDB | ConsumedReadCapacityUnits | \u003e 80% capacity  |\n| SES      | Bounce Rate               | \u003e 1%            |\n\n### Example Dashboard\n\nCloudWatch Dashboard: `Subscription-System-Monitor`\n\n- Widget 1: Lambda Invocations (Last 24h)\n- Widget 2: DynamoDB Read Capacity\n- Widget 3: SES Delivery Metrics\n- Widget 4: Error Rates by Function\n\n## Contribution\n\n1. Fork the repository\n2. Create feature branch:\n\n   ```bash\n   git checkout -b feature/new-functionality\n   ```\n\n3. Commit changes:\n\n   ```bash\n   git commit -m \"feat: add new functionality\"\n   ```\n\n4. Push branch:\n\n   ```bash\n   git push origin feature/new-functionality\n   ```\n\n5. Open Pull Request\n\n## License\n\nDistributed under MIT License. See `LICENSE` for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjavier1292%2Fsubscriptions-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjavier1292%2Fsubscriptions-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjavier1292%2Fsubscriptions-manager/lists"}