@solvapay/next 1.0.8-preview.9 → 1.0.8

package/dist/index.d.cts

@@ -1,6 +1,5 @@
 import { NextResponse } from 'next/server';
-import * as _solvapay_server from '@solvapay/server';
-import { AuthenticatedUser, SolvaPay, CustomerBalanceResult, ActivatePlanResult, listPlansCore, getMerchantCore, getProductCore } from '@solvapay/server';
+import { AuthenticatedUser, SolvaPay } from '@solvapay/server';
 export { AuthMiddlewareOptions, SupabaseAuthMiddlewareOptions, createAuthMiddleware, createSupabaseAuthMiddleware } from './middleware.cjs';
 import '@solvapay/auth';
 
@@ -189,11 +188,24 @@ declare function getAuthenticatedUser(request: globalThis.Request, options?: {
  */
 
 /**
- * Sync customer - Next.js wrapper
+ * Get the authenticated customer's SolvaPay reference.
  *
- * @param request - Next.js request object
- * @param options - Configuration options
- * @returns Customer reference or NextResponse error
+ * Unlike the other route-wrapper helpers, this one returns the raw customer
+ * reference string on success so callers can use it to build their own
+ * response body. Errors are still returned as a `NextResponse`.
+ *
+ * @example
+ * ```ts
+ * // app/api/sync-customer/route.ts
+ * import { NextResponse } from 'next/server'
+ * import { syncCustomer } from '@solvapay/next/helpers'
+ *
+ * export async function POST(request: Request) {
+ *   const result = await syncCustomer(request)
+ *   if (result instanceof NextResponse) return result
+ *   return NextResponse.json({ customerRef: result })
+ * }
+ * ```
  */
 declare function syncCustomer(request: globalThis.Request, options?: {
     solvaPay?: SolvaPay;
@@ -201,16 +213,37 @@ declare function syncCustomer(request: globalThis.Request, options?: {
     includeName?: boolean;
 }): Promise<string | NextResponse>;
 /**
- * Get customer credits - Next.js wrapper
+ * Next.js route wrapper for GET /api/customer-balance.
  *
- * @param request - Next.js request object
- * @param options - Configuration options
- * @returns Customer credits result or NextResponse error
+ * @example
+ * ```ts
+ * // app/api/customer-balance/route.ts
+ * import { getCustomerBalance } from '@solvapay/next/helpers'
+ * export const GET = (request: Request) => getCustomerBalance(request)
+ * ```
  */
 declare function getCustomerBalance(request: globalThis.Request, options?: {
     solvaPay?: SolvaPay;
-}): Promise<CustomerBalanceResult | NextResponse>;
+}): Promise<NextResponse>;
 
+/**
+ * Next.js Payment Helpers
+ */
+
+/**
+ * Next.js route wrapper for POST /api/create-payment-intent.
+ *
+ * @example
+ * ```ts
+ * // app/api/create-payment-intent/route.ts
+ * import { createPaymentIntent } from '@solvapay/next/helpers'
+ *
+ * export async function POST(request: Request) {
+ *   const { planRef, productRef } = await request.json()
+ *   return createPaymentIntent(request, { planRef, productRef })
+ * }
+ * ```
+ */
 declare function createPaymentIntent(request: globalThis.Request, body: {
     planRef: string;
     productRef: string;
@@ -218,13 +251,21 @@ declare function createPaymentIntent(request: globalThis.Request, body: {
     solvaPay?: SolvaPay;
     includeEmail?: boolean;
     includeName?: boolean;
-}): Promise<{
-    processorPaymentId: string;
-    clientSecret: string;
-    publishableKey: string;
-    accountId?: string;
-    customerRef: string;
-} | NextResponse>;
+}): Promise<NextResponse>;
+/**
+ * Next.js route wrapper for POST /api/create-topup-payment-intent.
+ *
+ * @example
+ * ```ts
+ * // app/api/create-topup-payment-intent/route.ts
+ * import { createTopupPaymentIntent } from '@solvapay/next/helpers'
+ *
+ * export async function POST(request: Request) {
+ *   const { amount, currency, description } = await request.json()
+ *   return createTopupPaymentIntent(request, { amount, currency, description })
+ * }
+ * ```
+ */
 declare function createTopupPaymentIntent(request: globalThis.Request, body: {
     amount: number;
     currency: string;
@@ -233,25 +274,46 @@ declare function createTopupPaymentIntent(request: globalThis.Request, body: {
     solvaPay?: SolvaPay;
     includeEmail?: boolean;
     includeName?: boolean;
-}): Promise<{
-    processorPaymentId: string;
-    clientSecret: string;
-    publishableKey: string;
-    accountId?: string;
-    customerRef: string;
-} | NextResponse>;
+}): Promise<NextResponse>;
+/**
+ * Next.js route wrapper for POST /api/process-payment.
+ *
+ * @example
+ * ```ts
+ * // app/api/process-payment/route.ts
+ * import { processPaymentIntent } from '@solvapay/next/helpers'
+ *
+ * export async function POST(request: Request) {
+ *   const { paymentIntentId, productRef, planRef } = await request.json()
+ *   return processPaymentIntent(request, { paymentIntentId, productRef, planRef })
+ * }
+ * ```
+ */
 declare function processPaymentIntent(request: globalThis.Request, body: {
     paymentIntentId: string;
     productRef: string;
     planRef?: string;
 }, options?: {
     solvaPay?: SolvaPay;
-}): Promise<_solvapay_server.ProcessPaymentResult | NextResponse>;
+}): Promise<NextResponse>;
 
 /**
  * Next.js Checkout Helpers
  */
-
+/**
+ * Next.js route wrapper for POST /api/create-checkout-session.
+ *
+ * @example
+ * ```ts
+ * // app/api/create-checkout-session/route.ts
+ * import { createCheckoutSession } from '@solvapay/next/helpers'
+ *
+ * export async function POST(request: Request) {
+ *   const { productRef, planRef } = await request.json()
+ *   return createCheckoutSession(request, { productRef, planRef })
+ * }
+ * ```
+ */
 declare function createCheckoutSession(request: globalThis.Request, body: {
     productRef: string;
     planRef?: string;
@@ -261,19 +323,40 @@ declare function createCheckoutSession(request: globalThis.Request, body: {
     includeEmail?: boolean;
     includeName?: boolean;
     returnUrl?: string;
-}): Promise<{
-    sessionId: string;
-    checkoutUrl: string;
-} | NextResponse>;
+}): Promise<NextResponse>;
+/**
+ * Next.js route wrapper for POST /api/create-customer-session.
+ *
+ * @example
+ * ```ts
+ * // app/api/create-customer-session/route.ts
+ * import { createCustomerSession } from '@solvapay/next/helpers'
+ * export const POST = (request: Request) => createCustomerSession(request)
+ * ```
+ */
 declare function createCustomerSession(request: globalThis.Request, options?: {
     solvaPay?: SolvaPay;
     includeEmail?: boolean;
     includeName?: boolean;
-}): Promise<{
-    sessionId: string;
-    customerUrl: string;
-} | NextResponse>;
+}): Promise<NextResponse>;
 
+/**
+ * Next.js route wrapper for POST /api/activate-plan.
+ *
+ * Clears the purchase cache for the authenticated user on success so the
+ * next `checkPurchase` sees the new plan immediately.
+ *
+ * @example
+ * ```ts
+ * // app/api/activate-plan/route.ts
+ * import { activatePlan } from '@solvapay/next/helpers'
+ *
+ * export async function POST(request: Request) {
+ *   const { productRef, planRef } = await request.json()
+ *   return activatePlan(request, { productRef, planRef })
+ * }
+ * ```
+ */
 declare function activatePlan(request: globalThis.Request, body: {
     productRef: string;
     planRef: string;
@@ -281,54 +364,83 @@ declare function activatePlan(request: globalThis.Request, body: {
     solvaPay?: SolvaPay;
     includeEmail?: boolean;
     includeName?: boolean;
-}): Promise<ActivatePlanResult | NextResponse>;
+}): Promise<NextResponse>;
+
+/**
+ * Next.js route wrapper around `getPaymentMethodCore`.
+ *
+ * @example
+ * ```ts
+ * // app/api/payment-method/route.ts
+ * import { getPaymentMethod } from '@solvapay/next/helpers'
+ * export const GET = (request: Request) => getPaymentMethod(request)
+ * ```
+ */
+declare function getPaymentMethod(request: globalThis.Request, options?: {
+    solvaPay?: SolvaPay;
+    includeEmail?: boolean;
+    includeName?: boolean;
+}): Promise<NextResponse>;
 
 /**
  * Next.js Purchase Cancellation & Reactivation Helpers
  */
 /**
- * Cancel purchase - Next.js wrapper
+ * Next.js route wrapper for POST /api/cancel-renewal.
  *
- * @param request - Next.js request object
- * @param body - Cancellation parameters
- * @param options - Configuration options
- * @returns Cancelled purchase response or NextResponse error
+ * @example
+ * ```ts
+ * // app/api/cancel-renewal/route.ts
+ * import { cancelRenewal } from '@solvapay/next/helpers'
+ *
+ * export async function POST(request: Request) {
+ *   const { purchaseRef, reason } = await request.json()
+ *   return cancelRenewal(request, { purchaseRef, reason })
+ * }
+ * ```
  */
 declare function cancelRenewal(request: globalThis.Request, body: {
     purchaseRef: string;
     reason?: string;
 }, options?: {
     solvaPay?: SolvaPay;
-}): Promise<Record<string, unknown> | NextResponse>;
+}): Promise<NextResponse>;
 /**
- * Reactivate purchase - Next.js wrapper
+ * Next.js route wrapper for POST /api/reactivate-renewal.
  *
  * Undoes a pending cancellation, restoring auto-renewal.
  *
- * @param request - Next.js request object
- * @param body - Reactivation parameters
- * @param options - Configuration options
- * @returns Reactivated purchase response or NextResponse error
+ * @example
+ * ```ts
+ * // app/api/reactivate-renewal/route.ts
+ * import { reactivateRenewal } from '@solvapay/next/helpers'
+ *
+ * export async function POST(request: Request) {
+ *   const { purchaseRef } = await request.json()
+ *   return reactivateRenewal(request, { purchaseRef })
+ * }
+ * ```
  */
 declare function reactivateRenewal(request: globalThis.Request, body: {
     purchaseRef: string;
 }, options?: {
     solvaPay?: SolvaPay;
-}): Promise<Record<string, unknown> | NextResponse>;
+}): Promise<NextResponse>;
 
-type ListPlansSuccess = Exclude<Awaited<ReturnType<typeof listPlansCore>>, {
-    error: string;
-}>;
 /**
- * Next.js Plans Helper
+ * Next.js route wrapper for GET /api/list-plans?productRef=...
+ *
+ * @example
+ * ```ts
+ * // app/api/list-plans/route.ts
+ * import { listPlans } from '@solvapay/next/helpers'
+ * export const GET = (request: Request) => listPlans(request)
+ * ```
  */
 declare function listPlans(request: globalThis.Request, options?: {
     solvaPay?: SolvaPay;
-}): Promise<ListPlansSuccess | NextResponse>;
+}): Promise<NextResponse>;
 
-type GetMerchantSuccess = Exclude<Awaited<ReturnType<typeof getMerchantCore>>, {
-    error: string;
-}>;
 /**
  * Next.js route wrapper for GET /api/merchant.
  *
@@ -341,11 +453,8 @@ type GetMerchantSuccess = Exclude<Awaited<ReturnType<typeof getMerchantCore>>, {
  */
 declare function getMerchant(request: globalThis.Request, options?: {
     solvaPay?: SolvaPay;
-}): Promise<GetMerchantSuccess | NextResponse>;
+}): Promise<NextResponse>;
 
-type GetProductSuccess = Exclude<Awaited<ReturnType<typeof getProductCore>>, {
-    error: string;
-}>;
 /**
  * Next.js route wrapper for GET /api/get-product?productRef=...
  *
@@ -358,8 +467,22 @@ type GetProductSuccess = Exclude<Awaited<ReturnType<typeof getProductCore>>, {
  */
 declare function getProduct(request: globalThis.Request, options?: {
     solvaPay?: SolvaPay;
-}): Promise<GetProductSuccess | NextResponse>;
+}): Promise<NextResponse>;
 
+/**
+ * Next.js route wrapper for POST /api/track-usage.
+ *
+ * @example
+ * ```ts
+ * // app/api/track-usage/route.ts
+ * import { trackUsage } from '@solvapay/next/helpers'
+ *
+ * export async function POST(request: Request) {
+ *   const body = await request.json()
+ *   return trackUsage(request, body)
+ * }
+ * ```
+ */
 declare function trackUsage(request: globalThis.Request, body: {
     actionType?: 'transaction' | 'api_call' | 'hour' | 'email' | 'storage' | 'custom';
     units?: number;
@@ -418,7 +541,14 @@ interface CheckPurchaseOptions {
  *
  * Delegates to `checkPurchaseCore` from `@solvapay/server` for the actual logic,
  * wrapping with Next.js-specific deduplication and response formatting.
+ *
+ * @example
+ * ```ts
+ * // app/api/check-purchase/route.ts
+ * import { checkPurchase } from '@solvapay/next'
+ * export const GET = (request: Request) => checkPurchase(request)
+ * ```
  */
-declare function checkPurchase(request: Request, options?: CheckPurchaseOptions): Promise<PurchaseCheckResult | NextResponse>;
+declare function checkPurchase(request: Request, options?: CheckPurchaseOptions): Promise<NextResponse>;
 
-export { type CheckPurchaseOptions, type PurchaseCheckResult, type RequestDeduplicationOptions, activatePlan, cancelRenewal, checkPurchase, clearAllPurchaseCache, clearPurchaseCache, createCheckoutSession, createCustomerSession, createPaymentIntent, createTopupPaymentIntent, getAuthenticatedUser, getCustomerBalance, getMerchant, getProduct, getPurchaseCacheStats, listPlans, processPaymentIntent, reactivateRenewal, syncCustomer, trackUsage };
+export { type CheckPurchaseOptions, type PurchaseCheckResult, type RequestDeduplicationOptions, activatePlan, cancelRenewal, checkPurchase, clearAllPurchaseCache, clearPurchaseCache, createCheckoutSession, createCustomerSession, createPaymentIntent, createTopupPaymentIntent, getAuthenticatedUser, getCustomerBalance, getMerchant, getPaymentMethod, getProduct, getPurchaseCacheStats, listPlans, processPaymentIntent, reactivateRenewal, syncCustomer, trackUsage };