@solvapay/next 1.0.0-preview.9 → 1.0.1-preview.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SolvaPay Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -12,54 +12,232 @@ npm install @solvapay/next @solvapay/server next
 
 ## Usage
 
-### Check Subscription
+All helpers return either a success result or a `NextResponse` error, making them easy to use in Next.js API routes.
 
-The `checkSubscription` helper provides a simple way to check user subscription status in Next.js API routes with built-in request deduplication:
+### Check Purchase
+
+Check user purchase status with built-in request deduplication and caching:
 
 ```typescript
-import { NextRequest, NextResponse } from 'next/server';
-import { checkSubscription } from '@solvapay/next';
+import { NextRequest, NextResponse } from 'next/server'
+import { checkPurchase } from '@solvapay/next'
 
 export async function GET(request: NextRequest) {
-  const result = await checkSubscription(request);
-  
+  const result = await checkPurchase(request)
+
   // If result is a NextResponse, it's an error response - return it
   if (result instanceof NextResponse) {
-    return result;
+    return result
   }
-  
-  // Otherwise, return the subscription data
-  return NextResponse.json(result);
+
+  // Otherwise, return the purchase data
+  return NextResponse.json(result)
 }
 ```
 
-### Features
+**Features:**
 
 - **Automatic Deduplication**: Prevents duplicate API calls by deduplicating concurrent requests
 - **Caching**: Caches results for 2 seconds to prevent duplicate sequential requests
 - **Automatic Cleanup**: Expired cache entries are automatically cleaned up
 - **Memory Safe**: Maximum cache size limits prevent memory issues
 
+### Sync Customer
+
+Sync customer with SolvaPay backend (ensures customer exists and returns customer reference):
+
+```typescript
+import { NextRequest, NextResponse } from 'next/server'
+import { syncCustomer } from '@solvapay/next'
+
+export async function POST(request: NextRequest) {
+  const result = await syncCustomer(request)
+
+  if (result instanceof NextResponse) {
+    return result
+  }
+
+  return NextResponse.json({ customerRef: result })
+}
+```
+
+### Create Payment Intent
+
+Create a Stripe payment intent for checkout:
+
+```typescript
+import { NextRequest, NextResponse } from 'next/server'
+import { createPaymentIntent } from '@solvapay/next'
+
+export async function POST(request: NextRequest) {
+  const { planRef, productRef } = await request.json()
+
+  if (!planRef || !productRef) {
+    return NextResponse.json({ error: 'Missing required parameters' }, { status: 400 })
+  }
+
+  const result = await createPaymentIntent(request, { planRef, productRef })
+  return result instanceof NextResponse ? result : NextResponse.json(result)
+}
+```
+
+### Process Payment
+
+Process payment after Stripe confirmation:
+
+```typescript
+import { NextRequest, NextResponse } from 'next/server'
+import { processPayment } from '@solvapay/next'
+
+export async function POST(request: NextRequest) {
+  const { paymentIntentId, productRef, planRef } = await request.json()
+
+  if (!paymentIntentId || !productRef) {
+    return NextResponse.json({ error: 'Missing required parameters' }, { status: 400 })
+  }
+
+  const result = await processPayment(request, { paymentIntentId, productRef, planRef })
+  return result instanceof NextResponse ? result : NextResponse.json(result)
+}
+```
+
+### List Plans
+
+List available plans (public route, no authentication required):
+
+```typescript
+import { NextRequest, NextResponse } from 'next/server'
+import { listPlans } from '@solvapay/next'
+
+export async function GET(request: NextRequest) {
+  const result = await listPlans(request)
+  return result instanceof NextResponse ? result : NextResponse.json(result)
+}
+```
+
+### Cancel Renewal
+
+Cancel renewal of a user's purchase:
+
+```typescript
+import { NextRequest, NextResponse } from 'next/server'
+import { cancelRenewal } from '@solvapay/next'
+
+export async function POST(request: NextRequest) {
+  const { purchaseRef, reason } = await request.json()
+
+  if (!purchaseRef) {
+    return NextResponse.json({ error: 'Missing purchaseRef' }, { status: 400 })
+  }
+
+  const result = await cancelRenewal(request, { purchaseRef, reason })
+  return result instanceof NextResponse ? result : NextResponse.json(result)
+}
+```
+
+### Create Checkout Session
+
+Create a hosted checkout session:
+
+```typescript
+import { NextRequest, NextResponse } from 'next/server'
+import { createCheckoutSession } from '@solvapay/next'
+
+export async function POST(request: NextRequest) {
+  const { productRef, planRef } = await request.json()
+
+  if (!productRef) {
+    return NextResponse.json({ error: 'Missing productRef' }, { status: 400 })
+  }
+
+  const result = await createCheckoutSession(request, { productRef, planRef })
+  return result instanceof NextResponse ? result : NextResponse.json(result)
+}
+```
+
+### Create Customer Session
+
+Create a customer portal session:
+
+```typescript
+import { NextRequest, NextResponse } from 'next/server'
+import { createCustomerSession } from '@solvapay/next'
+
+export async function POST(request: NextRequest) {
+  const result = await createCustomerSession(request)
+  return result instanceof NextResponse ? result : NextResponse.json(result)
+}
+```
+
+### Get Authenticated User
+
+Get authenticated user information (userId, email, name):
+
+```typescript
+import { NextRequest, NextResponse } from 'next/server'
+import { getAuthenticatedUser } from '@solvapay/next'
+
+export async function GET(request: NextRequest) {
+  const result = await getAuthenticatedUser(request, {
+    includeEmail: true,
+    includeName: true,
+  })
+
+  if (result instanceof NextResponse) {
+    return result
+  }
+
+  return NextResponse.json(result)
+}
+```
+
 ### Cache Management
 
 ```typescript
-import { 
-  clearSubscriptionCache, 
-  clearAllSubscriptionCache,
-  getSubscriptionCacheStats 
-} from '@solvapay/next';
+import {
+  clearPurchaseCache,
+  clearAllPurchaseCache,
+  getPurchaseCacheStats,
+} from '@solvapay/next'
 
 // Clear cache for a specific user
-clearSubscriptionCache(userId);
+clearPurchaseCache(userId)
 
 // Clear all cache entries
-clearAllSubscriptionCache();
+clearAllPurchaseCache()
 
 // Get cache statistics
-const stats = getSubscriptionCacheStats();
-console.log(`In-flight: ${stats.inFlight}, Cached: ${stats.cached}`);
+const stats = getPurchaseCacheStats()
+console.log(`In-flight: ${stats.inFlight}, Cached: ${stats.cached}`)
 ```
 
+## Helper Functions Reference
+
+All helper functions follow the same pattern:
+
+- Take a `Request` or `NextRequest` as the first parameter
+- Return either the success result or a `NextResponse` error
+- Automatically extract user information from request headers (set by middleware)
+- Support optional configuration options
+
+**Available Helpers:**
+
+- `checkPurchase(request, options?)` - Check purchase with caching
+- `syncCustomer(request, options?)` - Sync customer with backend
+- `createPaymentIntent(request, body, options?)` - Create payment intent
+- `processPayment(request, body, options?)` - Process payment
+- `listPlans(request)` - List available plans (public)
+- `cancelRenewal(request, body, options?)` - Cancel renewal
+- `createCheckoutSession(request, body, options?)` - Create hosted checkout
+- `createCustomerSession(request, options?)` - Create customer portal
+- `getAuthenticatedUser(request, options?)` - Get user info
+
+**Common Options:**
+
+- `solvaPay?: SolvaPay` - Custom SolvaPay instance
+- `includeEmail?: boolean` - Include user email (default: true)
+- `includeName?: boolean` - Include user name (default: true)
+
 ## Requirements
 
 - Next.js >= 13.0.0
@@ -69,3 +247,76 @@ console.log(`In-flight: ${stats.inFlight}, Cached: ${stats.cached}`);
 
 This package is separate from `@solvapay/server` to keep the server package framework-agnostic. Users who use Express, Fastify, or other frameworks don't need Next.js as a dependency.
 
+## Middleware Setup
+
+These helpers expect the user ID to be set in the `x-user-id` header by your Next.js middleware/proxy.
+
+### Quick Setup with Supabase
+
+The easiest way is to use `createSupabaseAuthMiddleware`:
+
+**For Next.js 15:**
+
+```typescript
+// middleware.ts (at project root)
+import { createSupabaseAuthMiddleware } from '@solvapay/next'
+
+export const middleware = createSupabaseAuthMiddleware({
+  publicRoutes: ['/api/list-plans'],
+})
+
+export const config = {
+  matcher: ['/api/:path*'],
+}
+```
+
+**For Next.js 16 with `src/` folder:**
+
+```typescript
+// src/proxy.ts (in src/ folder, not project root)
+import { createSupabaseAuthMiddleware } from '@solvapay/next'
+
+// Use 'proxy' export for Next.js 16 (no deprecation warning)
+export const proxy = createSupabaseAuthMiddleware({
+  publicRoutes: ['/api/list-plans'],
+})
+
+export const config = {
+  matcher: ['/api/:path*'],
+}
+```
+
+**File Location Notes:**
+
+- **Next.js 15**: Place `middleware.ts` at project root
+- **Next.js 16 without `src/` folder**: Place `middleware.ts` or `proxy.ts` at project root
+- **Next.js 16 with `src/` folder**: Place `src/proxy.ts` or `src/middleware.ts` (in `src/` folder, not root)
+
+> **Note:** Next.js 16 renamed "middleware" to "proxy". You can use either export name, but `proxy` is recommended to avoid deprecation warnings.
+
+### Custom Middleware
+
+Alternatively, you can create your own middleware:
+
+```typescript
+// middleware.ts (or src/proxy.ts for Next.js 16)
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+
+export async function middleware(request: NextRequest) {
+  // Extract user ID from your auth system
+  const userId = await getUserIdFromAuth(request)
+
+  // Clone request and add user ID header
+  const requestHeaders = new Headers(request.headers)
+  requestHeaders.set('x-user-id', userId)
+
+  return NextResponse.next({
+    request: {
+      headers: requestHeaders,
+    },
+  })
+}
+```
+
+You can also use the `requireUserId` utility from `@solvapay/auth` in your middleware.