@solvapay/next 1.0.0-preview.19 → 1.0.0-preview.21

package/README.md

@@ -14,23 +14,23 @@ npm install @solvapay/next @solvapay/server next
 
 All helpers return either a success result or a `NextResponse` error, making them easy to use in Next.js API routes.
 
-### Check Subscription
+### Check Purchase
 
-Check user subscription status with built-in request deduplication and caching:
+Check user purchase status with built-in request deduplication and caching:
 
 ```typescript
 import { NextRequest, NextResponse } from 'next/server'
-import { checkSubscription } from '@solvapay/next'
+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
   }
 
-  // Otherwise, return the subscription data
+  // Otherwise, return the purchase data
   return NextResponse.json(result)
 }
 ```
@@ -70,13 +70,13 @@ import { NextRequest, NextResponse } from 'next/server'
 import { createPaymentIntent } from '@solvapay/next'
 
 export async function POST(request: NextRequest) {
-  const { planRef, agentRef } = await request.json()
+  const { planRef, productRef } = await request.json()
 
-  if (!planRef || !agentRef) {
+  if (!planRef || !productRef) {
     return NextResponse.json({ error: 'Missing required parameters' }, { status: 400 })
   }
 
-  const result = await createPaymentIntent(request, { planRef, agentRef })
+  const result = await createPaymentIntent(request, { planRef, productRef })
   return result instanceof NextResponse ? result : NextResponse.json(result)
 }
 ```
@@ -90,13 +90,13 @@ import { NextRequest, NextResponse } from 'next/server'
 import { processPayment } from '@solvapay/next'
 
 export async function POST(request: NextRequest) {
-  const { paymentIntentId, agentRef, planRef } = await request.json()
+  const { paymentIntentId, productRef, planRef } = await request.json()
 
-  if (!paymentIntentId || !agentRef) {
+  if (!paymentIntentId || !productRef) {
     return NextResponse.json({ error: 'Missing required parameters' }, { status: 400 })
   }
 
-  const result = await processPayment(request, { paymentIntentId, agentRef, planRef })
+  const result = await processPayment(request, { paymentIntentId, productRef, planRef })
   return result instanceof NextResponse ? result : NextResponse.json(result)
 }
 ```
@@ -115,22 +115,22 @@ export async function GET(request: NextRequest) {
 }
 ```
 
-### Cancel Subscription
+### Cancel Renewal
 
-Cancel a user's subscription:
+Cancel renewal of a user's purchase:
 
 ```typescript
 import { NextRequest, NextResponse } from 'next/server'
-import { cancelSubscription } from '@solvapay/next'
+import { cancelRenewal } from '@solvapay/next'
 
 export async function POST(request: NextRequest) {
-  const { subscriptionRef, reason } = await request.json()
+  const { purchaseRef, reason } = await request.json()
 
-  if (!subscriptionRef) {
-    return NextResponse.json({ error: 'Missing subscriptionRef' }, { status: 400 })
+  if (!purchaseRef) {
+    return NextResponse.json({ error: 'Missing purchaseRef' }, { status: 400 })
   }
 
-  const result = await cancelSubscription(request, { subscriptionRef, reason })
+  const result = await cancelRenewal(request, { purchaseRef, reason })
   return result instanceof NextResponse ? result : NextResponse.json(result)
 }
 ```
@@ -144,13 +144,13 @@ import { NextRequest, NextResponse } from 'next/server'
 import { createCheckoutSession } from '@solvapay/next'
 
 export async function POST(request: NextRequest) {
-  const { agentRef, planRef } = await request.json()
+  const { productRef, planRef } = await request.json()
 
-  if (!agentRef) {
-    return NextResponse.json({ error: 'Missing agentRef' }, { status: 400 })
+  if (!productRef) {
+    return NextResponse.json({ error: 'Missing productRef' }, { status: 400 })
   }
 
-  const result = await createCheckoutSession(request, { agentRef, planRef })
+  const result = await createCheckoutSession(request, { productRef, planRef })
   return result instanceof NextResponse ? result : NextResponse.json(result)
 }
 ```
@@ -195,19 +195,19 @@ export async function GET(request: NextRequest) {
 
 ```typescript
 import {
-  clearSubscriptionCache,
-  clearAllSubscriptionCache,
-  getSubscriptionCacheStats,
+  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()
+const stats = getPurchaseCacheStats()
 console.log(`In-flight: ${stats.inFlight}, Cached: ${stats.cached}`)
 ```
 
@@ -222,12 +222,12 @@ All helper functions follow the same pattern:
 
 **Available Helpers:**
 
-- `checkSubscription(request, options?)` - Check subscription with caching
+- `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)
-- `cancelSubscription(request, body, options?)` - Cancel subscription
+- `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

package/dist/index.cjs

@@ -30,19 +30,19 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  cancelSubscription: () => cancelSubscription,
-  checkSubscription: () => checkSubscription,
-  clearAllSubscriptionCache: () => clearAllSubscriptionCache,
-  clearSubscriptionCache: () => clearSubscriptionCache,
+  cancelRenewal: () => cancelRenewal,
+  checkPurchase: () => checkPurchase,
+  clearAllPurchaseCache: () => clearAllPurchaseCache,
+  clearPurchaseCache: () => clearPurchaseCache,
   createAuthMiddleware: () => createAuthMiddleware,
   createCheckoutSession: () => createCheckoutSession,
   createCustomerSession: () => createCustomerSession,
   createPaymentIntent: () => createPaymentIntent,
   createSupabaseAuthMiddleware: () => createSupabaseAuthMiddleware,
   getAuthenticatedUser: () => getAuthenticatedUser,
-  getSubscriptionCacheStats: () => getSubscriptionCacheStats,
+  getPurchaseCacheStats: () => getPurchaseCacheStats,
   listPlans: () => listPlans,
-  processPayment: () => processPayment,
+  processPaymentIntent: () => processPaymentIntent,
   syncCustomer: () => syncCustomer
 });
 module.exports = __toCommonJS(index_exports);
@@ -152,10 +152,10 @@ function createRequestDeduplicator(options = {}) {
     getStats
   };
 }
-var sharedSubscriptionDeduplicator = null;
+var sharedPurchaseDeduplicator = null;
 function getSharedDeduplicator(options) {
-  if (!sharedSubscriptionDeduplicator) {
-    sharedSubscriptionDeduplicator = createRequestDeduplicator({
+  if (!sharedPurchaseDeduplicator) {
+    sharedPurchaseDeduplicator = createRequestDeduplicator({
       cacheTTL: 2e3,
       // Cache results for 2 seconds
       maxCacheSize: 1e3,
@@ -165,17 +165,17 @@ function getSharedDeduplicator(options) {
       ...options
     });
   }
-  return sharedSubscriptionDeduplicator;
+  return sharedPurchaseDeduplicator;
 }
-function clearSubscriptionCache(userId) {
+function clearPurchaseCache(userId) {
   const deduplicator = getSharedDeduplicator();
   deduplicator.clearCache(userId);
 }
-function clearAllSubscriptionCache() {
+function clearAllPurchaseCache() {
   const deduplicator = getSharedDeduplicator();
   deduplicator.clearAllCache();
 }
-function getSubscriptionCacheStats() {
+function getPurchaseCacheStats() {
   const deduplicator = getSharedDeduplicator();
   return deduplicator.getStats();
 }
@@ -223,14 +223,14 @@ async function createPaymentIntent(request, body, options = {}) {
   try {
     const userResult = await (0, import_server7.getAuthenticatedUserCore)(request);
     if (!(0, import_server6.isErrorResult)(userResult)) {
-      clearSubscriptionCache(userResult.userId);
+      clearPurchaseCache(userResult.userId);
     }
   } catch {
   }
   return result;
 }
-async function processPayment(request, body, options = {}) {
-  const result = await (0, import_server6.processPaymentCore)(request, body, options);
+async function processPaymentIntent(request, body, options = {}) {
+  const result = await (0, import_server6.processPaymentIntentCore)(request, body, options);
   if ((0, import_server6.isErrorResult)(result)) {
     return import_server5.NextResponse.json(
       { error: result.error, details: result.details },
@@ -240,7 +240,7 @@ async function processPayment(request, body, options = {}) {
   try {
     const userResult = await (0, import_server7.getAuthenticatedUserCore)(request);
     if (!(0, import_server6.isErrorResult)(userResult)) {
-      clearSubscriptionCache(userResult.userId);
+      clearPurchaseCache(userResult.userId);
     }
   } catch {
   }
@@ -271,12 +271,12 @@ async function createCustomerSession(request, options = {}) {
   return result;
 }
 
-// src/helpers/subscription.ts
+// src/helpers/renewal.ts
 var import_server10 = require("next/server");
 var import_server11 = require("@solvapay/server");
 var import_server12 = require("@solvapay/server");
-async function cancelSubscription(request, body, options = {}) {
-  const result = await (0, import_server11.cancelSubscriptionCore)(request, body, options);
+async function cancelRenewal(request, body, options = {}) {
+  const result = await (0, import_server11.cancelPurchaseCore)(request, body, options);
   if ((0, import_server11.isErrorResult)(result)) {
     return import_server10.NextResponse.json(
       { error: result.error, details: result.details },
@@ -286,7 +286,7 @@ async function cancelSubscription(request, body, options = {}) {
   try {
     const userResult = await (0, import_server12.getAuthenticatedUserCore)(request);
     if (!(0, import_server11.isErrorResult)(userResult)) {
-      clearSubscriptionCache(userResult.userId);
+      clearPurchaseCache(userResult.userId);
     }
   } catch {
   }
@@ -378,7 +378,7 @@ function createSupabaseAuthMiddleware(options = {}) {
 }
 
 // src/index.ts
-async function checkSubscription(request, options = {}) {
+async function checkPurchase(request, options = {}) {
   try {
     const { requireUserId, getUserEmailFromRequest, getUserNameFromRequest } = await import("@solvapay/auth");
     const userIdOrError = requireUserId(request);
@@ -397,14 +397,14 @@ async function checkSubscription(request, options = {}) {
         const customer = await solvaPay.getCustomer({ customerRef: cachedCustomerRef });
         if (customer && customer.customerRef) {
           if (customer.externalRef && customer.externalRef === userId) {
-            const filteredSubscriptions = (customer.subscriptions || []).filter(
-              (sub) => sub.status === "active"
+            const filteredPurchases = (customer.purchases || []).filter(
+              (p) => p.status === "active"
             );
             return {
               customerRef: customer.customerRef,
               email: customer.email,
               name: customer.name,
-              subscriptions: filteredSubscriptions
+              purchases: filteredPurchases
             };
           }
         }
@@ -419,51 +419,51 @@ async function checkSubscription(request, options = {}) {
           name: name || void 0
         });
         const customer = await solvaPay.getCustomer({ customerRef: ensuredCustomerRef });
-        const filteredSubscriptions = (customer.subscriptions || []).filter(
-          (sub) => sub.status === "active"
+        const filteredPurchases = (customer.purchases || []).filter(
+          (p) => p.status === "active"
         );
         const result = {
           customerRef: customer.customerRef || userId,
           email: customer.email,
           name: customer.name,
-          subscriptions: filteredSubscriptions
+          purchases: filteredPurchases
         };
         return result;
       } catch (error) {
-        console.error("[checkSubscription] Error fetching customer:", error);
+        console.error("[checkPurchase] Error fetching customer:", error);
         return {
           customerRef: userId,
-          subscriptions: []
+          purchases: []
         };
       }
     });
     return response;
   } catch (error) {
-    console.error("Check subscription failed:", error);
+    console.error("Check purchase failed:", error);
     if (error instanceof import_core.SolvaPayError) {
       return import_server16.NextResponse.json({ error: error.message }, { status: 500 });
     }
     const errorMessage = error instanceof Error ? error.message : "Unknown error";
     return import_server16.NextResponse.json(
-      { error: "Failed to check subscription", details: errorMessage },
+      { error: "Failed to check purchase", details: errorMessage },
       { status: 500 }
     );
   }
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  cancelSubscription,
-  checkSubscription,
-  clearAllSubscriptionCache,
-  clearSubscriptionCache,
+  cancelRenewal,
+  checkPurchase,
+  clearAllPurchaseCache,
+  clearPurchaseCache,
   createAuthMiddleware,
   createCheckoutSession,
   createCustomerSession,
   createPaymentIntent,
   createSupabaseAuthMiddleware,
   getAuthenticatedUser,
-  getSubscriptionCacheStats,
+  getPurchaseCacheStats,
   listPlans,
-  processPayment,
+  processPaymentIntent,
   syncCustomer
 });

package/dist/index.d.cts

@@ -4,9 +4,9 @@ import { AuthenticatedUser, SolvaPay } from '@solvapay/server';
 import { AuthAdapter } from '@solvapay/auth';
 
 /**
- * Subscription Cache Utilities
+ * Purchase Cache Utilities
  *
- * Cache management functions for subscription data.
+ * Cache management functions for purchase data.
  * Separated from index.ts to avoid circular dependencies.
  */
 /**
@@ -30,46 +30,58 @@ interface RequestDeduplicationOptions {
     cacheErrors?: boolean;
 }
 /**
- * Subscription check result
+ * Purchase check result
  */
-interface SubscriptionCheckResult {
+interface PurchaseCheckResult {
     customerRef: string;
     email?: string;
     name?: string;
-    subscriptions: Array<{
+    purchases: Array<{
         reference: string;
-        planName?: string;
-        agentName?: string;
+        productName?: string;
+        productReference?: string;
         status?: string;
         startDate?: string;
+        planSnapshot?: {
+            meterId?: string;
+            limit?: number;
+            freeUnits?: number;
+        };
+        usage?: {
+            used?: number;
+            overageUnits?: number;
+            overageCost?: number;
+            periodStart?: string;
+            periodEnd?: string;
+        };
         [key: string]: unknown;
     }>;
 }
 /**
- * Clear subscription cache for a specific user.
+ * Clear purchase cache for a specific user.
  *
- * Useful when you know subscription status has changed (e.g., after a successful
- * checkout, subscription update, or cancellation). This forces the next
- * `checkSubscription()` call to fetch fresh data from the backend.
+ * Useful when you know purchase status has changed (e.g., after a successful
+ * checkout, purchase update, or cancellation). This forces the next
+ * `checkPurchase()` call to fetch fresh data from the backend.
  *
  * @param userId - User ID to clear cache for
  *
  * @example
  * ```typescript
- * import { clearSubscriptionCache } from '@solvapay/next';
+ * import { clearPurchaseCache } from '@solvapay/next';
  *
  * // After successful payment
  * await processPayment(request, body);
- * clearSubscriptionCache(userId); // Force refresh on next check
+ * clearPurchaseCache(userId); // Force refresh on next check
  * ```
  *
- * @see {@link checkSubscription} for subscription checking
- * @see {@link clearAllSubscriptionCache} to clear all cache entries
+ * @see {@link checkPurchase} for purchase checking
+ * @see {@link clearAllPurchaseCache} to clear all cache entries
  * @since 1.0.0
  */
-declare function clearSubscriptionCache(userId: string): void;
+declare function clearPurchaseCache(userId: string): void;
 /**
- * Clear all subscription cache entries.
+ * Clear all purchase cache entries.
  *
  * Useful for testing, debugging, or when you need to force fresh lookups
  * for all users. This clears both the in-flight request cache and the
@@ -77,23 +89,23 @@ declare function clearSubscriptionCache(userId: string): void;
  *
  * @example
  * ```typescript
- * import { clearAllSubscriptionCache } from '@solvapay/next';
+ * import { clearAllPurchaseCache } from '@solvapay/next';
  *
  * // In a test setup
  * beforeEach(() => {
- *   clearAllSubscriptionCache();
+ *   clearAllPurchaseCache();
  * });
  * ```
  *
- * @see {@link clearSubscriptionCache} to clear cache for a specific user
- * @see {@link getSubscriptionCacheStats} for cache monitoring
+ * @see {@link clearPurchaseCache} to clear cache for a specific user
+ * @see {@link getPurchaseCacheStats} for cache monitoring
  * @since 1.0.0
  */
-declare function clearAllSubscriptionCache(): void;
+declare function clearAllPurchaseCache(): void;
 /**
- * Get subscription cache statistics for monitoring and debugging.
+ * Get purchase cache statistics for monitoring and debugging.
  *
- * Returns the current state of the subscription cache, including:
+ * Returns the current state of the purchase cache, including:
  * - Number of in-flight requests (being deduplicated)
  * - Number of cached results
  *
@@ -103,11 +115,11 @@ declare function clearAllSubscriptionCache(): void;
  *
  * @example
  * ```typescript
- * import { getSubscriptionCacheStats } from '@solvapay/next';
+ * import { getPurchaseCacheStats } from '@solvapay/next';
  *
  * // In a monitoring endpoint
  * export async function GET() {
- *   const stats = getSubscriptionCacheStats();
+ *   const stats = getPurchaseCacheStats();
  *   return Response.json({
  *     cache: {
  *       inFlight: stats.inFlight,
@@ -117,10 +129,10 @@ declare function clearAllSubscriptionCache(): void;
  * }
  * ```
  *
- * @see {@link checkSubscription} for subscription checking
+ * @see {@link checkPurchase} for purchase checking
  * @since 1.0.0
  */
-declare function getSubscriptionCacheStats(): {
+declare function getPurchaseCacheStats(): {
     inFlight: number;
     cached: number;
 };
@@ -188,17 +200,9 @@ declare function syncCustomer(request: globalThis.Request, options?: {
     includeName?: boolean;
 }): Promise<string | NextResponse>;
 
-/**
- * Create payment intent - Next.js wrapper
- *
- * @param request - Next.js request object
- * @param body - Payment intent parameters
- * @param options - Configuration options
- * @returns Payment intent response or NextResponse error
- */
 declare function createPaymentIntent(request: globalThis.Request, body: {
     planRef: string;
-    agentRef: string;
+    productRef: string;
 }, options?: {
     solvaPay?: SolvaPay;
     includeEmail?: boolean;
@@ -210,17 +214,9 @@ declare function createPaymentIntent(request: globalThis.Request, body: {
     accountId?: string;
     customerRef: string;
 } | NextResponse>;
-/**
- * Process payment - Next.js wrapper
- *
- * @param request - Next.js request object
- * @param body - Payment processing parameters
- * @param options - Configuration options
- * @returns Process payment result or NextResponse error
- */
-declare function processPayment(request: globalThis.Request, body: {
+declare function processPaymentIntent(request: globalThis.Request, body: {
     paymentIntentId: string;
-    agentRef: string;
+    productRef: string;
     planRef?: string;
 }, options?: {
     solvaPay?: SolvaPay;
@@ -228,20 +224,10 @@ declare function processPayment(request: globalThis.Request, body: {
 
 /**
  * Next.js Checkout Helpers
- *
- * Next.js-specific wrappers for checkout helpers.
  */
 
-/**
- * Create checkout session - Next.js wrapper
- *
- * @param request - Next.js request object
- * @param body - Checkout session parameters
- * @param options - Configuration options
- * @returns Checkout session response or NextResponse error
- */
 declare function createCheckoutSession(request: globalThis.Request, body: {
-    agentRef: string;
+    productRef: string;
     planRef?: string;
     returnUrl?: string;
 }, options?: {
@@ -253,13 +239,6 @@ declare function createCheckoutSession(request: globalThis.Request, body: {
     sessionId: string;
     checkoutUrl: string;
 } | NextResponse>;
-/**
- * Create customer session - Next.js wrapper
- *
- * @param request - Next.js request object
- * @param options - Configuration options
- * @returns Customer session response or NextResponse error
- */
 declare function createCustomerSession(request: globalThis.Request, options?: {
     solvaPay?: SolvaPay;
     includeEmail?: boolean;
@@ -270,20 +249,18 @@ declare function createCustomerSession(request: globalThis.Request, options?: {
 } | NextResponse>;
 
 /**
- * Next.js Subscription Helpers
- *
- * Next.js-specific wrappers for subscription helpers.
+ * Next.js Purchase Cancellation Helpers
  */
 /**
- * Cancel subscription - Next.js wrapper
+ * Cancel purchase - Next.js wrapper
  *
  * @param request - Next.js request object
  * @param body - Cancellation parameters
  * @param options - Configuration options
- * @returns Cancelled subscription response or NextResponse error
+ * @returns Cancelled purchase response or NextResponse error
  */
-declare function cancelSubscription(request: globalThis.Request, body: {
-    subscriptionRef: string;
+declare function cancelRenewal(request: globalThis.Request, body: {
+    purchaseRef: string;
     reason?: string;
 }, options?: {
     solvaPay?: SolvaPay;
@@ -291,19 +268,10 @@ declare function cancelSubscription(request: globalThis.Request, body: {
 
 /**
  * Next.js Plans Helper
- *
- * Next.js-specific wrapper for plans helper.
- * This is a public route - no authentication required.
- */
-/**
- * List plans - Next.js wrapper
- *
- * @param request - Next.js request object
- * @returns Plans response or NextResponse error
  */
 declare function listPlans(request: globalThis.Request): Promise<{
     plans: Array<Record<string, unknown>>;
-    agentRef: string;
+    productRef: string;
 } | NextResponse>;
 
 /**
@@ -489,9 +457,9 @@ declare function createSupabaseAuthMiddleware(options?: SupabaseAuthMiddlewareOp
  */
 
 /**
- * Options for checking subscriptions
+ * Options for checking purchases
  */
-interface CheckSubscriptionOptions {
+interface CheckPurchaseOptions {
     /**
      * Request deduplication options
      *
@@ -518,9 +486,9 @@ interface CheckSubscriptionOptions {
     includeName?: boolean;
 }
 /**
- * Check user subscription status with automatic deduplication and caching.
+ * Check user purchase status with automatic deduplication and caching.
  *
- * This Next.js helper function provides optimized subscription checking with:
+ * This Next.js helper function provides optimized purchase checking with:
  * - Automatic request deduplication (concurrent requests share the same promise)
  * - Short-term caching (2 seconds) to prevent duplicate sequential requests
  * - Fast path optimization using cached customer references from client
@@ -531,7 +499,7 @@ interface CheckSubscriptionOptions {
  * 2. Gets user email and name from Supabase JWT token (if available)
  * 3. Validates cached customer reference (if provided via header)
  * 4. Ensures customer exists in SolvaPay backend
- * 5. Returns customer subscription information
+ * 5. Returns customer purchase information
  *
  * @param request - Next.js request object (NextRequest extends Request)
  * @param options - Configuration options
@@ -539,15 +507,15 @@ interface CheckSubscriptionOptions {
  * @param options.solvaPay - Optional SolvaPay instance (creates new one if not provided)
  * @param options.includeEmail - Whether to include email in response (default: true)
  * @param options.includeName - Whether to include name in response (default: true)
- * @returns Subscription check result with customer data and subscriptions, or NextResponse error
+ * @returns Purchase check result with customer data and purchases, or NextResponse error
  *
  * @example
  * ```typescript
  * import { NextRequest, NextResponse } from 'next/server';
- * import { checkSubscription } from '@solvapay/next';
+ * import { checkPurchase } from '@solvapay/next';
  *
  * export async function GET(request: NextRequest) {
- *   const result = await checkSubscription(request);
+ *   const result = await checkPurchase(request);
  *
  *   if (result instanceof NextResponse) {
  *     return result; // Error response
@@ -557,10 +525,10 @@ interface CheckSubscriptionOptions {
  * }
  * ```
  *
- * @see {@link clearSubscriptionCache} for cache management
- * @see {@link getSubscriptionCacheStats} for cache monitoring
+ * @see {@link clearPurchaseCache} for cache management
+ * @see {@link getPurchaseCacheStats} for cache monitoring
  * @since 1.0.0
  */
-declare function checkSubscription(request: Request, options?: CheckSubscriptionOptions): Promise<SubscriptionCheckResult | NextResponse>;
+declare function checkPurchase(request: Request, options?: CheckPurchaseOptions): Promise<PurchaseCheckResult | NextResponse>;
 
-export { type AuthMiddlewareOptions, type CheckSubscriptionOptions, type RequestDeduplicationOptions, type SubscriptionCheckResult, type SupabaseAuthMiddlewareOptions, cancelSubscription, checkSubscription, clearAllSubscriptionCache, clearSubscriptionCache, createAuthMiddleware, createCheckoutSession, createCustomerSession, createPaymentIntent, createSupabaseAuthMiddleware, getAuthenticatedUser, getSubscriptionCacheStats, listPlans, processPayment, syncCustomer };
+export { type AuthMiddlewareOptions, type CheckPurchaseOptions, type PurchaseCheckResult, type RequestDeduplicationOptions, type SupabaseAuthMiddlewareOptions, cancelRenewal, checkPurchase, clearAllPurchaseCache, clearPurchaseCache, createAuthMiddleware, createCheckoutSession, createCustomerSession, createPaymentIntent, createSupabaseAuthMiddleware, getAuthenticatedUser, getPurchaseCacheStats, listPlans, processPaymentIntent, syncCustomer };

package/dist/index.d.ts

@@ -4,9 +4,9 @@ import { AuthenticatedUser, SolvaPay } from '@solvapay/server';
 import { AuthAdapter } from '@solvapay/auth';
 
 /**
- * Subscription Cache Utilities
+ * Purchase Cache Utilities
  *
- * Cache management functions for subscription data.
+ * Cache management functions for purchase data.
  * Separated from index.ts to avoid circular dependencies.
  */
 /**
@@ -30,46 +30,58 @@ interface RequestDeduplicationOptions {
     cacheErrors?: boolean;
 }
 /**
- * Subscription check result
+ * Purchase check result
  */
-interface SubscriptionCheckResult {
+interface PurchaseCheckResult {
     customerRef: string;
     email?: string;
     name?: string;
-    subscriptions: Array<{
+    purchases: Array<{
         reference: string;
-        planName?: string;
-        agentName?: string;
+        productName?: string;
+        productReference?: string;
         status?: string;
         startDate?: string;
+        planSnapshot?: {
+            meterId?: string;
+            limit?: number;
+            freeUnits?: number;
+        };
+        usage?: {
+            used?: number;
+            overageUnits?: number;
+            overageCost?: number;
+            periodStart?: string;
+            periodEnd?: string;
+        };
         [key: string]: unknown;
     }>;
 }
 /**
- * Clear subscription cache for a specific user.
+ * Clear purchase cache for a specific user.
  *
- * Useful when you know subscription status has changed (e.g., after a successful
- * checkout, subscription update, or cancellation). This forces the next
- * `checkSubscription()` call to fetch fresh data from the backend.
+ * Useful when you know purchase status has changed (e.g., after a successful
+ * checkout, purchase update, or cancellation). This forces the next
+ * `checkPurchase()` call to fetch fresh data from the backend.
  *
  * @param userId - User ID to clear cache for
  *
  * @example
  * ```typescript
- * import { clearSubscriptionCache } from '@solvapay/next';
+ * import { clearPurchaseCache } from '@solvapay/next';
  *
  * // After successful payment
  * await processPayment(request, body);
- * clearSubscriptionCache(userId); // Force refresh on next check
+ * clearPurchaseCache(userId); // Force refresh on next check
  * ```
  *
- * @see {@link checkSubscription} for subscription checking
- * @see {@link clearAllSubscriptionCache} to clear all cache entries
+ * @see {@link checkPurchase} for purchase checking
+ * @see {@link clearAllPurchaseCache} to clear all cache entries
  * @since 1.0.0
  */
-declare function clearSubscriptionCache(userId: string): void;
+declare function clearPurchaseCache(userId: string): void;
 /**
- * Clear all subscription cache entries.
+ * Clear all purchase cache entries.
  *
  * Useful for testing, debugging, or when you need to force fresh lookups
  * for all users. This clears both the in-flight request cache and the
@@ -77,23 +89,23 @@ declare function clearSubscriptionCache(userId: string): void;
  *
  * @example
  * ```typescript
- * import { clearAllSubscriptionCache } from '@solvapay/next';
+ * import { clearAllPurchaseCache } from '@solvapay/next';
  *
  * // In a test setup
  * beforeEach(() => {
- *   clearAllSubscriptionCache();
+ *   clearAllPurchaseCache();
  * });
  * ```
  *
- * @see {@link clearSubscriptionCache} to clear cache for a specific user
- * @see {@link getSubscriptionCacheStats} for cache monitoring
+ * @see {@link clearPurchaseCache} to clear cache for a specific user
+ * @see {@link getPurchaseCacheStats} for cache monitoring
  * @since 1.0.0
  */
-declare function clearAllSubscriptionCache(): void;
+declare function clearAllPurchaseCache(): void;
 /**
- * Get subscription cache statistics for monitoring and debugging.
+ * Get purchase cache statistics for monitoring and debugging.
  *
- * Returns the current state of the subscription cache, including:
+ * Returns the current state of the purchase cache, including:
  * - Number of in-flight requests (being deduplicated)
  * - Number of cached results
  *
@@ -103,11 +115,11 @@ declare function clearAllSubscriptionCache(): void;
  *
  * @example
  * ```typescript
- * import { getSubscriptionCacheStats } from '@solvapay/next';
+ * import { getPurchaseCacheStats } from '@solvapay/next';
  *
  * // In a monitoring endpoint
  * export async function GET() {
- *   const stats = getSubscriptionCacheStats();
+ *   const stats = getPurchaseCacheStats();
  *   return Response.json({
  *     cache: {
  *       inFlight: stats.inFlight,
@@ -117,10 +129,10 @@ declare function clearAllSubscriptionCache(): void;
  * }
  * ```
  *
- * @see {@link checkSubscription} for subscription checking
+ * @see {@link checkPurchase} for purchase checking
  * @since 1.0.0
  */
-declare function getSubscriptionCacheStats(): {
+declare function getPurchaseCacheStats(): {
     inFlight: number;
     cached: number;
 };
@@ -188,17 +200,9 @@ declare function syncCustomer(request: globalThis.Request, options?: {
     includeName?: boolean;
 }): Promise<string | NextResponse>;
 
-/**
- * Create payment intent - Next.js wrapper
- *
- * @param request - Next.js request object
- * @param body - Payment intent parameters
- * @param options - Configuration options
- * @returns Payment intent response or NextResponse error
- */
 declare function createPaymentIntent(request: globalThis.Request, body: {
     planRef: string;
-    agentRef: string;
+    productRef: string;
 }, options?: {
     solvaPay?: SolvaPay;
     includeEmail?: boolean;
@@ -210,17 +214,9 @@ declare function createPaymentIntent(request: globalThis.Request, body: {
     accountId?: string;
     customerRef: string;
 } | NextResponse>;
-/**
- * Process payment - Next.js wrapper
- *
- * @param request - Next.js request object
- * @param body - Payment processing parameters
- * @param options - Configuration options
- * @returns Process payment result or NextResponse error
- */
-declare function processPayment(request: globalThis.Request, body: {
+declare function processPaymentIntent(request: globalThis.Request, body: {
     paymentIntentId: string;
-    agentRef: string;
+    productRef: string;
     planRef?: string;
 }, options?: {
     solvaPay?: SolvaPay;
@@ -228,20 +224,10 @@ declare function processPayment(request: globalThis.Request, body: {
 
 /**
  * Next.js Checkout Helpers
- *
- * Next.js-specific wrappers for checkout helpers.
  */
 
-/**
- * Create checkout session - Next.js wrapper
- *
- * @param request - Next.js request object
- * @param body - Checkout session parameters
- * @param options - Configuration options
- * @returns Checkout session response or NextResponse error
- */
 declare function createCheckoutSession(request: globalThis.Request, body: {
-    agentRef: string;
+    productRef: string;
     planRef?: string;
     returnUrl?: string;
 }, options?: {
@@ -253,13 +239,6 @@ declare function createCheckoutSession(request: globalThis.Request, body: {
     sessionId: string;
     checkoutUrl: string;
 } | NextResponse>;
-/**
- * Create customer session - Next.js wrapper
- *
- * @param request - Next.js request object
- * @param options - Configuration options
- * @returns Customer session response or NextResponse error
- */
 declare function createCustomerSession(request: globalThis.Request, options?: {
     solvaPay?: SolvaPay;
     includeEmail?: boolean;
@@ -270,20 +249,18 @@ declare function createCustomerSession(request: globalThis.Request, options?: {
 } | NextResponse>;
 
 /**
- * Next.js Subscription Helpers
- *
- * Next.js-specific wrappers for subscription helpers.
+ * Next.js Purchase Cancellation Helpers
  */
 /**
- * Cancel subscription - Next.js wrapper
+ * Cancel purchase - Next.js wrapper
  *
  * @param request - Next.js request object
  * @param body - Cancellation parameters
  * @param options - Configuration options
- * @returns Cancelled subscription response or NextResponse error
+ * @returns Cancelled purchase response or NextResponse error
  */
-declare function cancelSubscription(request: globalThis.Request, body: {
-    subscriptionRef: string;
+declare function cancelRenewal(request: globalThis.Request, body: {
+    purchaseRef: string;
     reason?: string;
 }, options?: {
     solvaPay?: SolvaPay;
@@ -291,19 +268,10 @@ declare function cancelSubscription(request: globalThis.Request, body: {
 
 /**
  * Next.js Plans Helper
- *
- * Next.js-specific wrapper for plans helper.
- * This is a public route - no authentication required.
- */
-/**
- * List plans - Next.js wrapper
- *
- * @param request - Next.js request object
- * @returns Plans response or NextResponse error
  */
 declare function listPlans(request: globalThis.Request): Promise<{
     plans: Array<Record<string, unknown>>;
-    agentRef: string;
+    productRef: string;
 } | NextResponse>;
 
 /**
@@ -489,9 +457,9 @@ declare function createSupabaseAuthMiddleware(options?: SupabaseAuthMiddlewareOp
  */
 
 /**
- * Options for checking subscriptions
+ * Options for checking purchases
  */
-interface CheckSubscriptionOptions {
+interface CheckPurchaseOptions {
     /**
      * Request deduplication options
      *
@@ -518,9 +486,9 @@ interface CheckSubscriptionOptions {
     includeName?: boolean;
 }
 /**
- * Check user subscription status with automatic deduplication and caching.
+ * Check user purchase status with automatic deduplication and caching.
  *
- * This Next.js helper function provides optimized subscription checking with:
+ * This Next.js helper function provides optimized purchase checking with:
  * - Automatic request deduplication (concurrent requests share the same promise)
  * - Short-term caching (2 seconds) to prevent duplicate sequential requests
  * - Fast path optimization using cached customer references from client
@@ -531,7 +499,7 @@ interface CheckSubscriptionOptions {
  * 2. Gets user email and name from Supabase JWT token (if available)
  * 3. Validates cached customer reference (if provided via header)
  * 4. Ensures customer exists in SolvaPay backend
- * 5. Returns customer subscription information
+ * 5. Returns customer purchase information
  *
  * @param request - Next.js request object (NextRequest extends Request)
  * @param options - Configuration options
@@ -539,15 +507,15 @@ interface CheckSubscriptionOptions {
  * @param options.solvaPay - Optional SolvaPay instance (creates new one if not provided)
  * @param options.includeEmail - Whether to include email in response (default: true)
  * @param options.includeName - Whether to include name in response (default: true)
- * @returns Subscription check result with customer data and subscriptions, or NextResponse error
+ * @returns Purchase check result with customer data and purchases, or NextResponse error
  *
  * @example
  * ```typescript
  * import { NextRequest, NextResponse } from 'next/server';
- * import { checkSubscription } from '@solvapay/next';
+ * import { checkPurchase } from '@solvapay/next';
  *
  * export async function GET(request: NextRequest) {
- *   const result = await checkSubscription(request);
+ *   const result = await checkPurchase(request);
  *
  *   if (result instanceof NextResponse) {
  *     return result; // Error response
@@ -557,10 +525,10 @@ interface CheckSubscriptionOptions {
  * }
  * ```
  *
- * @see {@link clearSubscriptionCache} for cache management
- * @see {@link getSubscriptionCacheStats} for cache monitoring
+ * @see {@link clearPurchaseCache} for cache management
+ * @see {@link getPurchaseCacheStats} for cache monitoring
  * @since 1.0.0
  */
-declare function checkSubscription(request: Request, options?: CheckSubscriptionOptions): Promise<SubscriptionCheckResult | NextResponse>;
+declare function checkPurchase(request: Request, options?: CheckPurchaseOptions): Promise<PurchaseCheckResult | NextResponse>;
 
-export { type AuthMiddlewareOptions, type CheckSubscriptionOptions, type RequestDeduplicationOptions, type SubscriptionCheckResult, type SupabaseAuthMiddlewareOptions, cancelSubscription, checkSubscription, clearAllSubscriptionCache, clearSubscriptionCache, createAuthMiddleware, createCheckoutSession, createCustomerSession, createPaymentIntent, createSupabaseAuthMiddleware, getAuthenticatedUser, getSubscriptionCacheStats, listPlans, processPayment, syncCustomer };
+export { type AuthMiddlewareOptions, type CheckPurchaseOptions, type PurchaseCheckResult, type RequestDeduplicationOptions, type SupabaseAuthMiddlewareOptions, cancelRenewal, checkPurchase, clearAllPurchaseCache, clearPurchaseCache, createAuthMiddleware, createCheckoutSession, createCustomerSession, createPaymentIntent, createSupabaseAuthMiddleware, getAuthenticatedUser, getPurchaseCacheStats, listPlans, processPaymentIntent, syncCustomer };

package/dist/index.js

@@ -105,10 +105,10 @@ function createRequestDeduplicator(options = {}) {
     getStats
   };
 }
-var sharedSubscriptionDeduplicator = null;
+var sharedPurchaseDeduplicator = null;
 function getSharedDeduplicator(options) {
-  if (!sharedSubscriptionDeduplicator) {
-    sharedSubscriptionDeduplicator = createRequestDeduplicator({
+  if (!sharedPurchaseDeduplicator) {
+    sharedPurchaseDeduplicator = createRequestDeduplicator({
       cacheTTL: 2e3,
       // Cache results for 2 seconds
       maxCacheSize: 1e3,
@@ -118,17 +118,17 @@ function getSharedDeduplicator(options) {
       ...options
     });
   }
-  return sharedSubscriptionDeduplicator;
+  return sharedPurchaseDeduplicator;
 }
-function clearSubscriptionCache(userId) {
+function clearPurchaseCache(userId) {
   const deduplicator = getSharedDeduplicator();
   deduplicator.clearCache(userId);
 }
-function clearAllSubscriptionCache() {
+function clearAllPurchaseCache() {
   const deduplicator = getSharedDeduplicator();
   deduplicator.clearAllCache();
 }
-function getSubscriptionCacheStats() {
+function getPurchaseCacheStats() {
   const deduplicator = getSharedDeduplicator();
   return deduplicator.getStats();
 }
@@ -168,7 +168,7 @@ async function syncCustomer(request, options = {}) {
 import { NextResponse as NextResponse3 } from "next/server";
 import {
   createPaymentIntentCore,
-  processPaymentCore,
+  processPaymentIntentCore,
   isErrorResult as isErrorResult3
 } from "@solvapay/server";
 import { getAuthenticatedUserCore as getAuthenticatedUserCore2 } from "@solvapay/server";
@@ -183,14 +183,14 @@ async function createPaymentIntent(request, body, options = {}) {
   try {
     const userResult = await getAuthenticatedUserCore2(request);
     if (!isErrorResult3(userResult)) {
-      clearSubscriptionCache(userResult.userId);
+      clearPurchaseCache(userResult.userId);
     }
   } catch {
   }
   return result;
 }
-async function processPayment(request, body, options = {}) {
-  const result = await processPaymentCore(request, body, options);
+async function processPaymentIntent(request, body, options = {}) {
+  const result = await processPaymentIntentCore(request, body, options);
   if (isErrorResult3(result)) {
     return NextResponse3.json(
       { error: result.error, details: result.details },
@@ -200,7 +200,7 @@ async function processPayment(request, body, options = {}) {
   try {
     const userResult = await getAuthenticatedUserCore2(request);
     if (!isErrorResult3(userResult)) {
-      clearSubscriptionCache(userResult.userId);
+      clearPurchaseCache(userResult.userId);
     }
   } catch {
   }
@@ -235,12 +235,12 @@ async function createCustomerSession(request, options = {}) {
   return result;
 }
 
-// src/helpers/subscription.ts
+// src/helpers/renewal.ts
 import { NextResponse as NextResponse5 } from "next/server";
-import { cancelSubscriptionCore, isErrorResult as isErrorResult5 } from "@solvapay/server";
+import { cancelPurchaseCore, isErrorResult as isErrorResult5 } from "@solvapay/server";
 import { getAuthenticatedUserCore as getAuthenticatedUserCore3 } from "@solvapay/server";
-async function cancelSubscription(request, body, options = {}) {
-  const result = await cancelSubscriptionCore(request, body, options);
+async function cancelRenewal(request, body, options = {}) {
+  const result = await cancelPurchaseCore(request, body, options);
   if (isErrorResult5(result)) {
     return NextResponse5.json(
       { error: result.error, details: result.details },
@@ -250,7 +250,7 @@ async function cancelSubscription(request, body, options = {}) {
   try {
     const userResult = await getAuthenticatedUserCore3(request);
     if (!isErrorResult5(userResult)) {
-      clearSubscriptionCache(userResult.userId);
+      clearPurchaseCache(userResult.userId);
     }
   } catch {
   }
@@ -342,7 +342,7 @@ function createSupabaseAuthMiddleware(options = {}) {
 }
 
 // src/index.ts
-async function checkSubscription(request, options = {}) {
+async function checkPurchase(request, options = {}) {
   try {
     const { requireUserId, getUserEmailFromRequest, getUserNameFromRequest } = await import("@solvapay/auth");
     const userIdOrError = requireUserId(request);
@@ -361,14 +361,14 @@ async function checkSubscription(request, options = {}) {
         const customer = await solvaPay.getCustomer({ customerRef: cachedCustomerRef });
         if (customer && customer.customerRef) {
           if (customer.externalRef && customer.externalRef === userId) {
-            const filteredSubscriptions = (customer.subscriptions || []).filter(
-              (sub) => sub.status === "active"
+            const filteredPurchases = (customer.purchases || []).filter(
+              (p) => p.status === "active"
             );
             return {
               customerRef: customer.customerRef,
               email: customer.email,
               name: customer.name,
-              subscriptions: filteredSubscriptions
+              purchases: filteredPurchases
             };
           }
         }
@@ -383,50 +383,50 @@ async function checkSubscription(request, options = {}) {
           name: name || void 0
         });
         const customer = await solvaPay.getCustomer({ customerRef: ensuredCustomerRef });
-        const filteredSubscriptions = (customer.subscriptions || []).filter(
-          (sub) => sub.status === "active"
+        const filteredPurchases = (customer.purchases || []).filter(
+          (p) => p.status === "active"
         );
         const result = {
           customerRef: customer.customerRef || userId,
           email: customer.email,
           name: customer.name,
-          subscriptions: filteredSubscriptions
+          purchases: filteredPurchases
         };
         return result;
       } catch (error) {
-        console.error("[checkSubscription] Error fetching customer:", error);
+        console.error("[checkPurchase] Error fetching customer:", error);
         return {
           customerRef: userId,
-          subscriptions: []
+          purchases: []
         };
       }
     });
     return response;
   } catch (error) {
-    console.error("Check subscription failed:", error);
+    console.error("Check purchase failed:", error);
     if (error instanceof SolvaPayError) {
       return NextResponse8.json({ error: error.message }, { status: 500 });
     }
     const errorMessage = error instanceof Error ? error.message : "Unknown error";
     return NextResponse8.json(
-      { error: "Failed to check subscription", details: errorMessage },
+      { error: "Failed to check purchase", details: errorMessage },
       { status: 500 }
     );
   }
 }
 export {
-  cancelSubscription,
-  checkSubscription,
-  clearAllSubscriptionCache,
-  clearSubscriptionCache,
+  cancelRenewal,
+  checkPurchase,
+  clearAllPurchaseCache,
+  clearPurchaseCache,
   createAuthMiddleware,
   createCheckoutSession,
   createCustomerSession,
   createPaymentIntent,
   createSupabaseAuthMiddleware,
   getAuthenticatedUser,
-  getSubscriptionCacheStats,
+  getPurchaseCacheStats,
   listPlans,
-  processPayment,
+  processPaymentIntent,
   syncCustomer
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solvapay/next",
-  "version": "1.0.0-preview.19",
+  "version": "1.0.0-preview.21",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -29,9 +29,9 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@solvapay/auth": "1.0.0-preview.19",
-    "@solvapay/core": "1.0.0-preview.19",
-    "@solvapay/server": "1.0.0-preview.19"
+    "@solvapay/auth": "1.0.0-preview.21",
+    "@solvapay/server": "1.0.0-preview.21",
+    "@solvapay/core": "1.0.0-preview.21"
   },
   "peerDependencies": {
     "next": ">=13.0.0"