@misterhomer1992/payment-manager 1.0.0

package/tasks/prd.json

@@ -0,0 +1,336 @@
+{
+  "name": "Payment Manager Library",
+  "branchName": "feature/payment-manager-library",
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "Project Scaffolding",
+      "description": "As a developer setting up the library, I want a properly configured TypeScript npm package, so that the library can be built, tested, and published.",
+      "acceptanceCriteria": [
+        "package.json with name payment-manager, proper main/types fields pointing to dist/",
+        "tsconfig.json targeting ES2020, module NodeNext, outDir dist/, strict mode enabled",
+        "firebase-admin listed as peerDependencies only (>=12.0.0)",
+        "@misterhomer1992/wayforpay-api as regular dependency (^3.0.1)",
+        "Dev dependencies: typescript, jest, ts-jest, @types/jest",
+        "jest.config.ts configured for ts-jest",
+        "npm scripts: build, test, prepublishOnly (runs build)",
+        ".gitignore excludes node_modules/, dist/"
+      ],
+      "priority": 1,
+      "passes": true,
+      "dependsOn": [],
+      "labels": [
+        "scaffolding",
+        "setup"
+      ],
+      "completionNotes": "Completed by agent"
+    },
+    {
+      "id": "US-002",
+      "title": "Type Definitions",
+      "description": "As a developer consuming the library, I want complete TypeScript type definitions for all entities and API surfaces, so that I get full type safety and autocompletion.",
+      "acceptanceCriteria": [
+        "src/types/plan.ts — SubscriptionPlanEntity type",
+        "src/types/subscription.ts — SubscriptionEntity type with pendingPlanId? and pendingPlanChangeDate? fields",
+        "src/types/payment.ts — PaymentEntity type with paymentLink? and paymentLinkCreatedAt? fields",
+        "src/types/tokenPack.ts — TokenPackEntity and UserTokenBalance types",
+        "src/types/webhook.ts — WebhookResponse, DeactivationResult, ServiceUrlRequestParams types",
+        "src/types/orderReference.ts — OrderReferenceParams and ParsedOrderReference types",
+        "src/types/index.ts — re-exports all types",
+        "src/types/errors.ts — PaymentManagerError base class plus PlanNotFoundError, PlanInactiveError, SubscriptionAlreadyActiveError, SubscriptionNotFoundError, TokenPackNotFoundError, TokenPackInactiveError, InvalidWebhookSecretError, PaymentProviderError, InvalidOrderReferenceError"
+      ],
+      "priority": 1,
+      "passes": true,
+      "dependsOn": [
+        "US-001"
+      ],
+      "labels": [
+        "types",
+        "typescript"
+      ],
+      "completionNotes": "Completed by agent"
+    },
+    {
+      "id": "US-003",
+      "title": "Config & Initialization",
+      "description": "As a developer consuming the library, I want to initialize the library with a config object and receive a typed PaymentManager interface, so that I can use all library functions with my own Firestore instance and Wayforpay credentials.",
+      "acceptanceCriteria": [
+        "src/config.ts — module-level config singleton with setConfig() and getConfig() functions",
+        "PaymentManagerConfig type includes firestore, wayforpay credentials, platform, optional webhookSecret, optional logger",
+        "src/index.ts — init(config) function that stores config and returns PaymentManager object",
+        "PaymentManager interface exposes plans, subscriptions, tokenPacks, userTokens, webhooks namespaces",
+        "All public types re-exported from src/index.ts"
+      ],
+      "priority": 1,
+      "passes": true,
+      "dependsOn": [
+        "US-001",
+        "US-002"
+      ],
+      "labels": [
+        "config",
+        "initialization"
+      ],
+      "completionNotes": "Completed by agent"
+    },
+    {
+      "id": "US-004",
+      "title": "Utility Functions",
+      "description": "As a developer working on the library internals, I want reliable utility functions for order references, proration, grace periods, and webhook responses, so that core business logic is correct and testable in isolation.",
+      "acceptanceCriteria": [
+        "src/utils/orderReference.ts — buildOrderReference(params) constructs order reference strings for subscriptions and token packs",
+        "src/utils/orderReference.ts — parseOrderReference(ref) extracts version, platform, userId, type, planId/tknId, date; strips _WFPREG-* suffix; throws InvalidOrderReferenceError on malformed input",
+        "src/utils/proration.ts — implements upgrade proration formula: calculates remainingRatio, remainingValue, newDailyRate, daysOnNewPlan, newExpiresAt",
+        "src/utils/proration.ts — cycleDays helper: daily=1, monthly=30, yearly=365",
+        "src/utils/gracePeriod.ts — getGracePeriod(regularMode): daily→6 hours, monthly→1 day, yearly→1 day",
+        "src/utils/gracePeriod.ts — getExpirationWithGrace(expiresAt, regularMode) adds grace period to expiration",
+        "src/utils/webhookResponse.ts — buildWebhookResponse returns { orderReference, status, time, signature } with HMAC-MD5 signature"
+      ],
+      "priority": 1,
+      "passes": true,
+      "dependsOn": [
+        "US-002"
+      ],
+      "labels": [
+        "utilities",
+        "business-logic"
+      ],
+      "completionNotes": "Completed by agent"
+    },
+    {
+      "id": "US-005",
+      "title": "Firestore Collection Modules",
+      "description": "As a developer working on the library internals, I want clean Firestore CRUD abstractions for each entity collection, so that services can read/write data without duplicating Firestore logic.",
+      "acceptanceCriteria": [
+        "src/collections/plans.ts — getById, getAll, create, update, upsert for subscriptionPlans collection",
+        "src/collections/subscriptions.ts — getActiveByUserId, getByUserId, create, update, getAllActiveAndCancelled for subscriptions collection",
+        "src/collections/payments.ts — create, update, findPendingByUserAndPlan, findPendingByUserAndTokenPack, findByOrderReference for payments collection",
+        "src/collections/tokenPacks.ts — getById, getAll, create, update, remove for tokenPacks collection",
+        "src/collections/userTokenBalances.ts — getByUserId (returns zero-balance default if not found), addTokens (atomic increment via FieldValue.increment), update for userTokenBalances collection"
+      ],
+      "priority": 2,
+      "passes": true,
+      "dependsOn": [
+        "US-002",
+        "US-003"
+      ],
+      "labels": [
+        "firestore",
+        "data-access"
+      ],
+      "completionNotes": "Completed by agent"
+    },
+    {
+      "id": "US-006",
+      "title": "Plan Service",
+      "description": "As a library consumer, I want to manage subscription plans (CRUD + seeding), so that I can define and configure what plans are available to users.",
+      "acceptanceCriteria": [
+        "seedDefaultPlans() writes 4 default plans (basic-daily, basic-monthly, pro-daily, pro-monthly) to Firestore via upsert",
+        "create(plan) creates a new plan with createdAt/updatedAt timestamps",
+        "getById(planId) returns plan or null",
+        "getAll() returns all plans",
+        "update(planId, data) updates plan fields with updatedAt timestamp",
+        "deactivate(planId) sets isActive: false",
+        "Default plans defined in src/constants/defaultPlans.ts",
+        "Logs via optional logger: plan created, plan updated, default plans seeded"
+      ],
+      "priority": 2,
+      "passes": true,
+      "dependsOn": [
+        "US-004",
+        "US-005"
+      ],
+      "labels": [
+        "service",
+        "plans"
+      ],
+      "completionNotes": "Completed by agent"
+    },
+    {
+      "id": "US-007",
+      "title": "Payment Service",
+      "description": "As a library consumer, I want payment records created and payment URLs cached, so that duplicate Wayforpay API calls are avoided within a 5-minute window.",
+      "acceptanceCriteria": [
+        "createSubscriptionPayment(userId, planId, currency, productName) — checks for cached pending payment within 5min, builds order reference, creates PaymentEntity, calls generateRegularPurchase, stores paymentLink + paymentLinkCreatedAt, returns { paymentUrl }",
+        "createTokenPackPayment(userId, packId, currency, productName, price) — same caching logic, builds token pack order reference, calls generatePurchase (one-time), returns { paymentUrl }",
+        "updatePaymentStatus(orderReference, status) updates payment by order reference",
+        "Logs via optional logger: payment created, cached URL returned"
+      ],
+      "priority": 2,
+      "passes": true,
+      "dependsOn": [
+        "US-004",
+        "US-005"
+      ],
+      "labels": [
+        "service",
+        "payments",
+        "wayforpay"
+      ],
+      "completionNotes": "Completed by agent"
+    },
+    {
+      "id": "US-008",
+      "title": "Subscription Service",
+      "description": "As a library consumer, I want to manage the full subscription lifecycle, so that users can subscribe, upgrade, downgrade, and cancel.",
+      "acceptanceCriteria": [
+        "create(params) — cancels existing active subscription if present, validates plan exists and isActive, delegates to payment service for URL, returns { paymentUrl }",
+        "expire(userId) — sets subscription status to 'expired'",
+        "deactivate(userId) — calls cancelRegularPurchase on Wayforpay, sets status to 'cancelled'",
+        "changePlan(userId, newPlanId) — upgrade: calculates prorated newExpiresAt, updates planId and expiresAt immediately, calls editRegularPurchase",
+        "changePlan(userId, newPlanId) — downgrade: sets pendingPlanId and pendingPlanChangeDate, calls editRegularPurchase, does NOT change planId immediately",
+        "changePlan(userId, newPlanId) — same price: throws error",
+        "getActiveByUserId(userId) returns active subscription or null",
+        "Logs via optional logger: subscription created, upgraded, downgraded, expired, cancelled"
+      ],
+      "priority": 2,
+      "passes": true,
+      "dependsOn": [
+        "US-004",
+        "US-005",
+        "US-006",
+        "US-007"
+      ],
+      "labels": [
+        "service",
+        "subscriptions"
+      ],
+      "completionNotes": "Completed by agent"
+    },
+    {
+      "id": "US-009",
+      "title": "Token Pack Service",
+      "description": "As a library consumer, I want to manage token packs and allow users to buy extra tokens, so that users can purchase additional credits beyond their subscription limits.",
+      "acceptanceCriteria": [
+        "create(pack) creates new token pack with auto-generated ID",
+        "remove(packId) deletes token pack",
+        "activate(packId) sets isActive: true",
+        "deactivate(packId) sets isActive: false",
+        "getAll() returns all token packs",
+        "buyExtraTokens(params) validates pack exists and isActive, delegates to payment service for one-time payment URL, returns { paymentUrl }",
+        "getBalance(userId) returns UserTokenBalance (zero-balance default if no record)",
+        "Logs via optional logger: token pack created, purchase initiated"
+      ],
+      "priority": 2,
+      "passes": true,
+      "dependsOn": [
+        "US-005",
+        "US-007"
+      ],
+      "labels": [
+        "service",
+        "tokens"
+      ],
+      "completionNotes": "Completed by agent"
+    },
+    {
+      "id": "US-010",
+      "title": "Payment Check Webhook Handler",
+      "description": "As a library consumer, I want to process Wayforpay PAYMENT_CHECK webhooks, so that subscriptions are activated/renewed and token purchases are fulfilled when payments succeed.",
+      "acceptanceCriteria": [
+        "handlePaymentCheck(reqBody, headers) validates webhook secret from x-secret-key header (config webhookSecret first, falls back to env var NOTIFY_TELEGRAM_USER_SECRET)",
+        "Parses request body: JSON.parse(Object.keys(reqBody)[0])",
+        "Only reason codes 1100 and 4100 are successful; otherwise returns reject response",
+        "Subscription payment (type=sub): creates new SubscriptionEntity on first payment, extends expiresAt on recurrent payment, applies pending downgrade when pendingPlanChangeDate <= now",
+        "Token pack payment (type=tkn): looks up TokenPackEntity, atomically increments UserTokenBalance.balance and totalPurchased",
+        "Updates PaymentEntity status to 'approved' for successful payments",
+        "Always returns signed WebhookResponse: { orderReference, status, time, signature } with HMAC-MD5",
+        "Logs via optional logger: webhook received, payment processed, subscription created/renewed, tokens added"
+      ],
+      "priority": 3,
+      "passes": true,
+      "dependsOn": [
+        "US-004",
+        "US-005",
+        "US-008",
+        "US-009"
+      ],
+      "labels": [
+        "webhook",
+        "payments"
+      ],
+      "completionNotes": "Completed by agent"
+    },
+    {
+      "id": "US-011",
+      "title": "Subscription Deactivation Check Handler",
+      "description": "As a library consumer, I want a cron-compatible handler that expires overdue subscriptions, so that subscriptions don't remain active after their grace period ends.",
+      "acceptanceCriteria": [
+        "handleSubscriptionDeactivationCheck(headers) validates webhook secret (same as US-010)",
+        "Queries all subscriptions where status IN ['active', 'cancelled']",
+        "For each subscription: fetches plan, computes expirationWithGrace, expires subscription if now > expirationWithGrace",
+        "Checks pending downgrades: if pendingPlanChangeDate <= now, applies downgrade",
+        "Returns DeactivationResult: { expired: string[], downgraded: string[] } (arrays of user IDs)",
+        "Logs via optional logger: subscriptions expired, downgrades applied"
+      ],
+      "priority": 3,
+      "passes": true,
+      "dependsOn": [
+        "US-004",
+        "US-005"
+      ],
+      "labels": [
+        "webhook",
+        "cron",
+        "expiration"
+      ],
+      "completionNotes": "Completed by agent"
+    },
+    {
+      "id": "US-012",
+      "title": "Wire Public API in index.ts",
+      "description": "As a library consumer, I want a single entry point that exposes the complete PaymentManager interface, so that I can import and use all functionality from one place.",
+      "acceptanceCriteria": [
+        "init(config) returns PaymentManager with namespaces: plans, subscriptions, tokenPacks, userTokens, webhooks",
+        "All public types exported from package root",
+        "Error classes exported from package root",
+        "Calling any method before init() throws a clear error"
+      ],
+      "priority": 3,
+      "passes": true,
+      "dependsOn": [
+        "US-006",
+        "US-007",
+        "US-008",
+        "US-009",
+        "US-010",
+        "US-011"
+      ],
+      "labels": [
+        "api",
+        "entry-point"
+      ],
+      "completionNotes": "Completed by agent"
+    },
+    {
+      "id": "US-013",
+      "title": "Unit Tests",
+      "description": "As a developer maintaining the library, I want comprehensive unit tests for core logic, so that business logic is verified and regressions are caught.",
+      "acceptanceCriteria": [
+        "orderReference.test.ts — builds correct sub/token order references, parses correctly, strips _WFPREG-* suffix, throws on malformed input",
+        "proration.test.ts — correct prorated expiration mid-cycle, edge cases for first/last day, works with daily/monthly/yearly modes",
+        "gracePeriod.test.ts — returns 6h for daily, 1d for monthly, 1d for yearly, getExpirationWithGrace adds correct duration",
+        "webhookResponse.test.ts — correct response structure, valid HMAC-MD5 signature",
+        "paymentCheckHandler.test.ts — rejects invalid secret, rejects bad reason codes, creates new subscription, renews existing, applies pending downgrade, adds tokens, returns signed response",
+        "deactivationCheckHandler.test.ts — rejects invalid secret, expires subs past grace, keeps subs within grace, applies pending downgrades",
+        "All tests pass with npm test",
+        "Zero type errors with npx tsc --noEmit"
+      ],
+      "priority": 3,
+      "passes": true,
+      "dependsOn": [
+        "US-004",
+        "US-010",
+        "US-011"
+      ],
+      "labels": [
+        "testing",
+        "unit-tests"
+      ],
+      "completionNotes": "Completed by agent"
+    }
+  ],
+  "metadata": {
+    "updatedAt": "2026-02-06T14:29:35.896Z"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist/",
+    "declaration": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}