@solvapay/server 1.0.0-preview.1 → 1.0.0-preview.11

package/README.md

@@ -93,6 +93,36 @@ const result = await protectedHandler({
 });
 ```
 
+### Authentication Integration
+
+You can integrate authentication adapters from `@solvapay/auth` with the `getCustomerRef` option:
+
+```ts
+import { createSolvaPay } from '@solvapay/server';
+import { SupabaseAuthAdapter } from '@solvapay/auth/supabase';
+
+const auth = new SupabaseAuthAdapter({
+  jwtSecret: process.env.SUPABASE_JWT_SECRET!
+});
+
+const solvaPay = createSolvaPay({ apiKey: process.env.SOLVAPAY_SECRET_KEY! });
+
+// Use with Next.js adapter
+export const POST = solvaPay.payable({ agent: 'my-api' }).next(
+  async (args) => {
+    return { result: 'success' };
+  },
+  {
+    getCustomerRef: async (req) => {
+      const userId = await auth.getUserIdFromRequest(req);
+      return userId ?? 'anonymous';
+    }
+  }
+);
+```
+
+This automatically extracts the user ID from authentication tokens and uses it as the customer reference for paywall checks.
+
 ### When to Use Each Adapter
 
 Choose the adapter based on your context:
@@ -160,11 +190,7 @@ type Plan = components['schemas']['Plan'];
 
 ## Testing
 
-> **📖 For detailed integration test setup**, see:
-> - [`packages/test-utils/INTEGRATION_TESTING.md`](../test-utils/INTEGRATION_TESTING.md) - Complete setup guide
-> - [`SDK_INTEGRATION_TESTS_IMPLEMENTATION.md`](../../SDK_INTEGRATION_TESTS_IMPLEMENTATION.md) - Implementation details
-
-This package includes comprehensive tests for SDK functionality.
+This package includes comprehensive tests for SDK functionality, including unit tests and integration tests with real backend.
 
 ### Running Tests
 
@@ -198,7 +224,7 @@ Unit tests (`__tests__/paywall.test.ts`) use a mock API client and test:
 
 ### Integration Tests
 
-Integration tests (`__tests__/paywall.integration.with-fetched-defaults.test.ts`) connect to a real SolvaPay backend and test:
+Integration tests (`__tests__/backend.integration.test.ts`) connect to a real SolvaPay backend and test:
 - SDK API methods with real responses
 - Actual limit enforcement
 - Real usage tracking
@@ -213,17 +239,106 @@ Set environment variables before running tests:
 # Option 1: Export in your shell (persists in session)
 export USE_REAL_BACKEND=true
 export SOLVAPAY_SECRET_KEY=your_secret_key_here
-export SOLVAPAY_API_BASE_URL=https://api-dev.solvapay.com  # optional
+export SOLVAPAY_API_BASE_URL=http://localhost:3001  # optional, defaults to dev API
 pnpm test:integration
 
 # Option 2: Inline with command (single use)
 USE_REAL_BACKEND=true SOLVAPAY_SECRET_KEY=your_key pnpm test:integration
 ```
 
-**Note:** This follows the industry standard used by major SDKs (Stripe, AWS, Twilio). No `.env` file is required.
-
 **Note:** Integration tests are automatically skipped if `USE_REAL_BACKEND` or `SOLVAPAY_SECRET_KEY` are not set. This allows CI/CD to run unit tests without backend credentials.
 
+### Payment Integration Tests (Stripe)
+
+Payment tests (`__tests__/payment-stripe.integration.test.ts`) verify the complete payment flow with Stripe:
+- Creating payment intents
+- Confirming payments with test cards
+- Webhook processing (optional)
+- Credit management and usage tracking
+
+**Required Setup:**
+
+```bash
+export USE_REAL_BACKEND=true
+export SOLVAPAY_SECRET_KEY=your_secret_key_here
+export STRIPE_TEST_SECRET_KEY=sk_test_your_stripe_key
+export SOLVAPAY_API_BASE_URL=http://localhost:3001
+```
+
+**Optional - Webhook Tests:**
+
+The E2E webhook test is skipped by default because it requires Stripe webhooks to be forwarded to your local backend. To enable webhook testing:
+
+1. **Install Stripe CLI:**
+   ```bash
+   # macOS
+   brew install stripe/stripe-cli/stripe
+   
+   # Linux / Windows - see https://stripe.com/docs/stripe-cli
+   ```
+
+2. **Login to Stripe:**
+   ```bash
+   stripe login
+   ```
+
+3. **Forward webhooks to your local backend:**
+   ```bash
+   # Terminal 1: Start your backend
+   cd path/to/solvapay-backend
+   pnpm dev
+   
+   # Terminal 2: Forward Stripe webhooks
+   stripe listen --forward-to localhost:3001/webhooks/stripe
+   ```
+
+4. **Run payment tests with webhook testing enabled:**
+   ```bash
+   ENABLE_WEBHOOK_TESTS=true pnpm test:integration:payment
+   ```
+
+The Stripe CLI will forward webhook events from Stripe to your local backend, allowing the E2E test to verify the complete payment flow including webhook processing.
+
+### Debugging and Logging
+
+The SDK and tests provide environment variable controls for logging:
+
+**SDK Debug Logging**
+
+Enable detailed logging for SDK operations (API calls, responses, errors):
+
+```bash
+# Enable SDK debug logging
+export SOLVAPAY_DEBUG=true
+
+# Run tests or your application
+pnpm test:integration
+```
+
+**Test Verbose Logging**
+
+Enable verbose logging for integration test progress and debug information:
+
+```bash
+# Enable verbose test logging (test setup, progress, debug info)
+export VERBOSE_TEST_LOGS=true
+
+# Run integration tests
+pnpm test:integration
+```
+
+**Combined Usage:**
+
+```bash
+# Enable all logging for maximum debugging
+SOLVAPAY_DEBUG=true VERBOSE_TEST_LOGS=true pnpm test:integration
+
+# Quiet mode (default) - minimal output
+pnpm test:integration
+```
+
+By default, both are **disabled** to keep test output clean and readable. Enable them when troubleshooting test failures or debugging SDK behavior.
+
 ### CI/CD
 
 ```yaml