evaldoc 1.0.0

package/docs/payments.md

@@ -0,0 +1,159 @@
+You are a senior full-stack engineer. Implement Stripe payments for EvalDoc (a healthcare AI link platform) using Node.js + Firebase (Firestore + Auth) + Stripe.
+
+Goal:
+- Doctors set their own subscription prices (daily/weekly/monthly).
+- Patients must pay before accessing the doctor’s AI session.
+- Platform (EvalDoc) takes 25% of the doctor’s fee.
+- Doctor receives 75% via Stripe Connect Express payouts.
+- Access is controlled strictly by Stripe webhook events (not by client redirects).
+
+Tech stack:
+- Backend: Node.js (Express) deployed on Firebase Cloud Functions (or Cloud Run if you prefer).
+- DB: Firestore.
+- Auth: Firebase Auth.
+- Payments: Stripe Checkout + Stripe Connect (Express).
+- Use Stripe test mode for development, environment variables for keys.
+
+Deliverables:
+1) A working backend with endpoints to:
+   A. Onboard a doctor to Stripe Connect Express.
+   B. Create/update doctor-specific Products + Prices (daily/weekly/monthly).
+   C. Create a patient Stripe Customer if needed.
+   D. Create a Stripe Checkout Session (subscription) for a patient buying a doctor plan, charging on behalf of the doctor with a 25% application fee.
+   E. Webhook endpoint to process Stripe events and update Firestore access.
+2) Firestore data model for doctors, patients, prices, subscriptions, and access.
+3) Minimal client-side flow description (no full UI needed, just required calls and checks).
+
+IMPORTANT BUSINESS LOGIC:
+- A patient can only access a doctor AI session if Firestore shows access.status == "ACTIVE" for that doctor + patient, based on Stripe webhooks.
+- A doctor must complete Stripe onboarding (charges_enabled / payouts_enabled) before patients can purchase.
+- Platform fee: 25% of the subscription amount.
+- Use destination charges / connected account routing so money flows to doctor and platform gets its fee.
+
+========================
+FIRESTORE MODEL
+========================
+Create collections:
+
+doctors/{doctorId}
+  - displayName
+  - stripeAccountId (string)
+  - stripeOnboardingStatus: "NOT_STARTED" | "PENDING" | "COMPLETE"
+  - chargesEnabled (bool)
+  - payoutsEnabled (bool)
+  - stripeProductId (string)
+  - stripePriceIds: { day?: string, week?: string, month?: string }
+  - currency (e.g., "usd")
+  - createdAt, updatedAt
+
+patients/{patientId}
+  - stripeCustomerId (string)
+  - createdAt, updatedAt
+
+subscriptions/{subId}
+  - doctorId
+  - patientId
+  - stripeSubscriptionId
+  - stripeCustomerId
+  - stripePriceId
+  - status (active, past_due, canceled, unpaid, etc.)
+  - currentPeriodEnd (timestamp)
+  - createdAt, updatedAt
+
+access/{doctorId_patientId}
+  - doctorId
+  - patientId
+  - status: "ACTIVE" | "INACTIVE"
+  - stripeSubscriptionId
+  - currentPeriodEnd (timestamp)
+  - updatedAt
+
+========================
+ENDPOINTS TO IMPLEMENT
+========================
+
+1) POST /stripe/doctor/create-connect-account
+Auth: doctor must be logged in (Firebase Auth).
+- Create Stripe Connect Express account for the doctor if not exists.
+- Save stripeAccountId to doctors/{doctorId}.
+- Return accountId.
+
+2) POST /stripe/doctor/create-account-link
+Auth: doctor logged in.
+- Create an Account Link (Stripe-hosted onboarding) using doctor.stripeAccountId
+- Requires refresh_url + return_url from env
+- Return the url for the doctor to complete onboarding.
+
+3) POST /stripe/doctor/set-pricing
+Auth: doctor logged in.
+Input: currency, amounts for intervals (day/week/month), enabledIntervals list.
+- Validate min amounts, currency format, etc.
+- Ensure doctor has stripeAccountId and (optionally) charges_enabled/payouts_enabled or allow pricing setup before completion.
+- Create a Stripe Product for the doctor if not exists (name: "EvalDoc AI Access - Dr. {displayName}")
+- For each enabled interval, create (or replace) Stripe Price objects:
+  - recurring.interval = "day" | "week" | "month"
+  - unit_amount in cents
+- Save stripeProductId and stripePriceIds.* in Firestore.
+
+4) POST /stripe/patient/create-checkout-session
+Auth: patient logged in.
+Input: doctorId, interval ("day"/"week"/"month")
+- Load doctor document; require:
+  - stripeAccountId exists
+  - chargesEnabled == true (or at least doctor onboarding complete)
+  - selected priceId exists
+- Ensure patient has stripeCustomerId (create stripe customer if missing).
+- Create a Stripe Checkout Session in mode="subscription", line_items=[{price: doctorPriceId, quantity:1}], customer=patientCustomerId.
+- IMPORTANT: route funds to doctor + take 25% platform fee.
+  - Use Stripe Connect approach for subscriptions:
+    - Use application_fee_percent = 25 (or application_fee_amount if you compute fixed cents)
+    - Ensure the payment is made for the connected account (destination / transfer settings).
+  - If there are multiple Stripe ways, choose the correct one for subscriptions with Connect and document it in comments.
+- Provide success_url and cancel_url including session_id.
+- Return checkout session url.
+
+5) POST /stripe/webhook
+No auth; verify Stripe signature using STRIPE_WEBHOOK_SECRET.
+- Handle these events at minimum:
+  - checkout.session.completed
+  - customer.subscription.created
+  - customer.subscription.updated
+  - customer.subscription.deleted
+  - invoice.payment_succeeded
+  - invoice.payment_failed
+- For each relevant event, resolve doctorId + patientId:
+  - Store doctorId and patientId as metadata when creating the Checkout Session (recommended).
+- Update Firestore:
+  - subscriptions/{subId} upsert by stripeSubscriptionId
+  - access/{doctorId_patientId} set ACTIVE if subscription is active and paid; set INACTIVE on canceled/unpaid/past_due/payment_failed depending on policy.
+- Save currentPeriodEnd from Stripe subscription.
+
+========================
+ACCESS POLICY
+========================
+- ACTIVE only when subscription.status == "active" and latest invoice is paid (or invoice.payment_succeeded).
+- INACTIVE on:
+  - invoice.payment_failed (immediately) OR after a grace period (choose and implement one; default immediate for now).
+  - subscription canceled/deleted.
+
+========================
+SECURITY REQUIREMENTS
+========================
+- All doctor endpoints require Firebase Auth and ensure role=doctor (use a custom claim or doctors collection check).
+- Patient endpoint requires Firebase Auth and ensure role=patient.
+- Prevent patients from purchasing if doctor onboarding incomplete.
+- Never trust client to mark access active; only webhooks do that.
+- Add idempotency in webhook handling (avoid duplicate writes; use stripe event id as processed marker, or upsert by subscription id).
+
+========================
+OUTPUT FORMAT
+========================
+- Provide:
+  1) Folder/file structure.
+  2) Environment variables list.
+  3) Implementation code (backend) with clear comments.
+  4) Example Firestore documents.
+  5) Example requests/responses.
+  6) A short “How to test in Stripe test mode” checklist.
+
+Proceed now. Make reasonable assumptions. If multiple Stripe Connect approaches exist for subscriptions, pick one that works and explain why in code comments.

package/eslint.config.js

@@ -0,0 +1,76 @@
+'use strict';
+
+// ESLint 9 flat config for a Node.js CommonJS (Express) project.
+//
+// Node + Jest globals are declared inline so this config has no external
+// dependencies at parse time (works even before `npm install`). If you prefer,
+// you can replace the inline maps below with the `globals` package:
+//   const globals = require('globals');
+//   ...globals.node, ...globals.jest
+
+const nodeGlobals = {
+  process: 'readonly',
+  __dirname: 'readonly',
+  __filename: 'readonly',
+  module: 'writable',
+  require: 'readonly',
+  exports: 'writable',
+  console: 'readonly',
+  Buffer: 'readonly',
+  global: 'readonly',
+  globalThis: 'readonly',
+  setTimeout: 'readonly',
+  clearTimeout: 'readonly',
+  setInterval: 'readonly',
+  clearInterval: 'readonly',
+  setImmediate: 'readonly',
+  clearImmediate: 'readonly',
+  queueMicrotask: 'readonly',
+  URL: 'readonly',
+  URLSearchParams: 'readonly',
+  TextEncoder: 'readonly',
+  TextDecoder: 'readonly',
+  AbortController: 'readonly',
+  fetch: 'readonly',
+  structuredClone: 'readonly'
+};
+
+const jestGlobals = {
+  describe: 'readonly',
+  it: 'readonly',
+  test: 'readonly',
+  expect: 'readonly',
+  beforeAll: 'readonly',
+  afterAll: 'readonly',
+  beforeEach: 'readonly',
+  afterEach: 'readonly',
+  jest: 'readonly',
+  xdescribe: 'readonly',
+  xit: 'readonly',
+  xtest: 'readonly',
+  fdescribe: 'readonly',
+  fit: 'readonly'
+};
+
+module.exports = [
+  {
+    ignores: ['node_modules/**', 'coverage/**', 'public/vendor/**', 'functions/node_modules/**']
+  },
+  {
+    files: ['**/*.js'],
+    languageOptions: {
+      ecmaVersion: 2022,
+      sourceType: 'commonjs',
+      globals: {
+        ...nodeGlobals,
+        ...jestGlobals
+      }
+    },
+    rules: {
+      'no-unused-vars': 'warn',
+      'no-undef': 'error',
+      eqeqeq: 'warn',
+      'no-console': 'off'
+    }
+  }
+];

package/firebase.json

@@ -0,0 +1,27 @@
+{
+  "hosting": {
+    "public": "public",
+    "ignore": [
+      "firebase.json",
+      "**/.*",
+      "**/node_modules/**"
+    ],
+    "rewrites": [
+      {
+        "source": "/app/**",
+        "destination": "/app/index.html"
+      },
+      {
+        "source": "**",
+        "destination": "/index.html"
+      }
+    ]
+  },
+  "firestore": {
+    "rules": "firestore.rules",
+    "indexes": "firestore.indexes.json"
+  },
+  "storage": {
+    "rules": "storage.rules"
+  }
+}

package/firestore.indexes.json

@@ -0,0 +1,88 @@
+{
+  "indexes": [
+    {
+      "collectionGroup": "conversations",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "providerId", "order": "ASCENDING" },
+        { "fieldPath": "sessionId", "order": "ASCENDING" },
+        { "fieldPath": "createdAt", "order": "DESCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "conversations",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "providerId", "order": "ASCENDING" },
+        { "fieldPath": "updatedAt", "order": "DESCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "threads",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "doctorId", "order": "ASCENDING" },
+        { "fieldPath": "lastMessageAt", "order": "DESCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "threads",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "doctorId", "order": "ASCENDING" },
+        { "fieldPath": "status", "order": "ASCENDING" },
+        { "fieldPath": "lastMessageAt", "order": "DESCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "threads",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "doctorId", "order": "ASCENDING" },
+        { "fieldPath": "triageCategory", "order": "ASCENDING" },
+        { "fieldPath": "lastMessageAt", "order": "DESCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "threads",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "patientId", "order": "ASCENDING" },
+        { "fieldPath": "lastMessageAt", "order": "DESCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "notifications",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "doctorId", "order": "ASCENDING" },
+        { "fieldPath": "createdAt", "order": "DESCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "notifications",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "doctorId", "order": "ASCENDING" },
+        { "fieldPath": "read", "order": "ASCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "doctorExamples",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "topic", "order": "ASCENDING" },
+        { "fieldPath": "createdAt", "order": "DESCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "waitlist",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "email", "order": "ASCENDING" },
+        { "fieldPath": "approved", "order": "ASCENDING" }
+      ]
+    }
+  ],
+  "fieldOverrides": []
+}

package/firestore.rules

@@ -0,0 +1,125 @@
+rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+    function isSignedIn() {
+      return request.auth != null;
+    }
+
+    function isOwner(ownerUid) {
+      return isSignedIn() && request.auth.uid == ownerUid;
+    }
+
+    // Provider documents
+    match /providers/{providerId} {
+      // Public: Anyone can read published providers
+      allow read: if resource.data.status == "published";
+
+      // Providers can only be created via backend API (Admin SDK)
+      allow create: if false;
+
+      // Providers can update their own profile
+      allow update: if isOwner(resource.data.ownerUid);
+
+      // Only backend can delete
+      allow delete: if false;
+
+      // Analytics subcollection
+      match /analyticsDaily/{dayId} {
+        allow read: if isOwner(providerId);
+        allow write: if false;
+      }
+
+      // Doctor examples subcollection
+      match /doctorExamples/{exampleId} {
+        allow read: if isSignedIn() && request.auth.uid == get(/databases/$(database)/documents/providers/$(providerId)).data.ownerUid;
+        allow write: if false;
+      }
+    }
+
+    // Handle lookup
+    match /handles/{handle} {
+      allow read: if true;
+      allow write: if false;
+    }
+
+    // Conversations (legacy)
+    match /conversations/{conversationId} {
+      allow read, write: if false;
+
+      match /messages/{messageId} {
+        allow read, write: if false;
+      }
+    }
+
+    // Safety events
+    match /safetyEvents/{eventId} {
+      allow read, write: if false;
+    }
+
+    // Audit log — backend-only, no client access
+    match /auditLog/{logId} {
+      allow read, write: if false;
+    }
+
+    // Platform configuration
+    match /platformConfig/{docId} {
+      allow read: if true;
+      allow write: if false;
+    }
+
+    // Payment access records: patients can read their own access status
+    match /access/{accessId} {
+      allow read: if isSignedIn() && resource.data.patientId == request.auth.uid;
+      allow write: if false;
+    }
+
+    // Subscriptions: patients can read their own
+    match /subscriptions/{subscriptionId} {
+      allow read: if isSignedIn() && resource.data.patientId == request.auth.uid;
+      allow write: if false;
+    }
+
+    // Transactions: patients can read their own
+    match /transactions/{transactionId} {
+      allow read: if isSignedIn() && resource.data.patientId == request.auth.uid;
+      allow write: if false;
+    }
+
+    // Patients collection
+    match /patients/{patientId} {
+      allow read, update: if isSignedIn() && request.auth.uid == patientId;
+      allow create, delete: if false;
+    }
+
+    // Notifications: doctors read their own
+    match /notifications/{notificationId} {
+      allow read: if isSignedIn() && resource.data.doctorId == request.auth.uid;
+      allow write: if false;
+    }
+
+    // Threads
+    match /threads/{threadId} {
+      allow read: if isSignedIn() && resource.data.patientId == request.auth.uid;
+      allow read: if isSignedIn() && request.auth.token.doctorId == resource.data.doctorId;
+      allow write: if false;
+
+      match /messages/{messageId} {
+        allow read: if isSignedIn() && (
+          get(/databases/$(database)/documents/threads/$(threadId)).data.patientId == request.auth.uid ||
+          request.auth.token.doctorId == get(/databases/$(database)/documents/threads/$(threadId)).data.doctorId
+        );
+        allow write: if false;
+      }
+    }
+
+    // Waitlist — all access via server-side Admin SDK only
+    match /waitlist/{docId} {
+      allow read, write: if false;
+    }
+
+    // Deny all other documents by default
+    match /{document=**} {
+      allow read, write: if false;
+    }
+  }
+}