@solvapay/auth 1.0.0-preview.9 → 1.0.1-preview.2

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

@@ -21,25 +21,27 @@ pnpm add jose
 Extract user ID from Supabase JWT tokens:
 
 ```ts
-import { SupabaseAuthAdapter } from '@solvapay/auth/supabase';
+import { SupabaseAuthAdapter } from '@solvapay/auth/supabase'
 
 const auth = new SupabaseAuthAdapter({
-  jwtSecret: process.env.SUPABASE_JWT_SECRET!
-});
+  jwtSecret: process.env.SUPABASE_JWT_SECRET!,
+})
 
 // In your API route
 export async function POST(request: Request) {
-  const userId = await auth.getUserIdFromRequest(request);
-  
+  const userId = await auth.getUserIdFromRequest(request)
+
   if (!userId) {
-    return new Response('Unauthorized', { status: 401 });
+    return new Response('Unauthorized', { status: 401 })
   }
-  
-  // Use userId as customerRef for SolvaPay
-  const solvaPay = createSolvaPay({ apiKey: process.env.SOLVAPAY_SECRET_KEY! });
-  const customer = await solvaPay.getCustomer({ customerRef: userId });
-  
-  return Response.json({ userId, customer });
+
+  // Use userId as cache key and externalRef
+  // The ensureCustomer method returns the SolvaPay backend customer reference
+  const solvaPay = createSolvaPay({ apiKey: process.env.SOLVAPAY_SECRET_KEY! })
+  const ensuredCustomerRef = await solvaPay.ensureCustomer(userId, userId)
+  const customer = await solvaPay.getCustomer({ customerRef: ensuredCustomerRef })
+
+  return Response.json({ userId, customer })
 }
 ```
 
@@ -48,14 +50,14 @@ export async function POST(request: Request) {
 For testing and examples:
 
 ```ts
-import { MockAuthAdapter } from '@solvapay/auth/mock';
+import { MockAuthAdapter } from '@solvapay/auth/mock'
 
-const auth = new MockAuthAdapter();
+const auth = new MockAuthAdapter()
 
 // Set header: x-mock-user-id: user_123
 // Or set env: MOCK_USER_ID=user_123
 
-const userId = await auth.getUserIdFromRequest(request);
+const userId = await auth.getUserIdFromRequest(request)
 ```
 
 ### Integration with SolvaPay Server SDK
@@ -63,27 +65,102 @@ const userId = await auth.getUserIdFromRequest(request);
 Use auth adapters with the `getCustomerRef` option:
 
 ```ts
-import { createSolvaPay } from '@solvapay/server';
-import { SupabaseAuthAdapter } from '@solvapay/auth/supabase';
+import { createSolvaPay } from '@solvapay/server'
+import { SupabaseAuthAdapter } from '@solvapay/auth/supabase'
 
 const auth = new SupabaseAuthAdapter({
-  jwtSecret: process.env.SUPABASE_JWT_SECRET!
-});
+  jwtSecret: process.env.SUPABASE_JWT_SECRET!,
+})
 
-const solvaPay = createSolvaPay({ apiKey: process.env.SOLVAPAY_SECRET_KEY! });
+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' };
+export const POST = solvaPay.payable({ product: 'my-api' }).next(
+  async args => {
+    return { result: 'success' }
   },
   {
-    getCustomerRef: async (req) => {
-      const userId = await auth.getUserIdFromRequest(req);
-      return userId ?? 'anonymous';
-    }
+    getCustomerRef: async req => {
+      const userId = await auth.getUserIdFromRequest(req)
+      return userId ?? 'anonymous'
+    },
+  },
+)
+```
+
+## Next.js Route Utilities
+
+The package also provides helper functions for extracting user information in Next.js API routes:
+
+### getUserIdFromRequest
+
+Extract user ID from request headers (commonly set by middleware):
+
+```ts
+import { getUserIdFromRequest } from '@solvapay/auth'
+
+export async function GET(request: Request) {
+  const userId = getUserIdFromRequest(request)
+
+  if (!userId) {
+    return new Response('Unauthorized', { status: 401 })
   }
-);
+
+  // Use userId...
+}
+```
+
+### requireUserId
+
+Require user ID or return error response:
+
+```ts
+import { requireUserId } from '@solvapay/auth'
+
+export async function GET(request: Request) {
+  const userIdOrError = requireUserId(request)
+
+  if (userIdOrError instanceof Response) {
+    return userIdOrError // Returns 401 error
+  }
+
+  // userIdOrError is now a string
+  const userId = userIdOrError
+}
+```
+
+### getUserEmailFromRequest
+
+Extract email from Supabase JWT token in Authorization header:
+
+```ts
+import { getUserEmailFromRequest } from '@solvapay/auth'
+
+export async function GET(request: Request) {
+  const email = await getUserEmailFromRequest(request)
+  // Returns email string or null
+}
+```
+
+### getUserNameFromRequest
+
+Extract name from Supabase JWT token in Authorization header:
+
+```ts
+import { getUserNameFromRequest } from '@solvapay/auth'
+
+export async function GET(request: Request) {
+  const name = await getUserNameFromRequest(request)
+  // Returns name string or null
+}
+```
+
+**Note:** `getUserEmailFromRequest` and `getUserNameFromRequest` require the `SUPABASE_JWT_SECRET` environment variable to be set, or you can pass it as an option:
+
+```ts
+const email = await getUserEmailFromRequest(request, {
+  jwtSecret: process.env.SUPABASE_JWT_SECRET!,
+})
 ```
 
 ## API Reference
@@ -92,7 +169,7 @@ export const POST = solvaPay.payable({ agent: 'my-api' }).next(
 
 ```ts
 interface AuthAdapter {
-  getUserIdFromRequest(req: Request | RequestLike): Promise<string | null>;
+  getUserIdFromRequest(req: Request | RequestLike): Promise<string | null>
 }
 ```
 
@@ -100,12 +177,13 @@ interface AuthAdapter {
 
 ```ts
 class SupabaseAuthAdapter implements AuthAdapter {
-  constructor(config: { jwtSecret: string });
-  getUserIdFromRequest(req: Request | RequestLike): Promise<string | null>;
+  constructor(config: { jwtSecret: string })
+  getUserIdFromRequest(req: Request | RequestLike): Promise<string | null>
 }
 ```
 
 **Configuration:**
+
 - `jwtSecret`: Supabase JWT secret from dashboard (Settings → API → JWT Secret)
 
 **Returns:** User ID from `sub` claim or `null` if missing/invalid
@@ -114,11 +192,12 @@ class SupabaseAuthAdapter implements AuthAdapter {
 
 ```ts
 class MockAuthAdapter implements AuthAdapter {
-  getUserIdFromRequest(req: Request | RequestLike): Promise<string | null>;
+  getUserIdFromRequest(req: Request | RequestLike): Promise<string | null>
 }
 ```
 
 **Behavior:**
+
 1. Checks `x-mock-user-id` header
 2. Falls back to `MOCK_USER_ID` environment variable
 3. Returns `null` if neither is found
@@ -130,5 +209,42 @@ class MockAuthAdapter implements AuthAdapter {
 
 ## Edge Runtime Support
 
-Both adapters work in Edge runtimes (Vercel Edge Functions, Cloudflare Workers, etc.). SupabaseAuthAdapter uses dynamic imports for `jose` to ensure Edge compatibility.
+Both adapters and Next.js utilities work in Edge runtimes (Vercel Edge Functions, Cloudflare Workers, etc.). SupabaseAuthAdapter and JWT utilities use dynamic imports for `jose` to ensure Edge compatibility.
+
+## Next.js Integration
+
+These utilities work seamlessly with Next.js authentication middleware.
+In Next.js 16, this middleware lives in `proxy.ts` and typically sets the
+`x-user-id` header after authentication:
+
+```ts
+// proxy.ts
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+
+export async function proxy(request: NextRequest) {
+  // Extract user ID from your auth system (Supabase, Auth0, etc.)
+  const userId = await getUserIdFromAuth(request)
+
+  // Clone the request and add user ID header
+  const requestHeaders = new Headers(request.headers)
+  requestHeaders.set('x-user-id', userId)
+
+  return NextResponse.next({
+    request: {
+      headers: requestHeaders,
+    },
+  })
+}
+```
+
+Then in your API routes, use the utilities:
 
+```ts
+import { requireUserId } from '@solvapay/auth'
+
+export async function GET(request: Request) {
+  const userId = requireUserId(request)
+  // userId is guaranteed to exist or an error response is returned
+}
+```

package/dist/adapter-Lx7F0MH7.d.cts

@@ -0,0 +1,64 @@
+/**
+ * Auth Adapter Interface
+ *
+ * Defines the contract for authentication adapters that extract user IDs from requests.
+ * Implementations should never throw - return null if authentication fails or is missing.
+ */
+/**
+ * Request-like object that has headers
+ */
+interface RequestLike {
+    headers: Headers | {
+        get(name: string): string | null;
+    };
+}
+/**
+ * Authentication adapter interface for extracting user IDs from requests.
+ *
+ * This interface defines the contract for authentication adapters that can
+ * extract user IDs from various authentication systems (Supabase, custom JWT,
+ * session-based auth, etc.). Adapters should never throw - return null if
+ * authentication fails or is missing.
+ *
+ * @example
+ * ```typescript
+ * import type { AuthAdapter } from '@solvapay/auth';
+ *
+ * // Custom adapter implementation
+ * const myAdapter: AuthAdapter = {
+ *   async getUserIdFromRequest(req) {
+ *     // Extract user ID from request (JWT, session, etc.)
+ *     const token = req.headers.get('authorization')?.replace('Bearer ', '');
+ *     if (!token) return null;
+ *
+ *     // Validate and extract user ID
+ *     const payload = await verifyToken(token);
+ *     return payload.userId || null;
+ *   }
+ * };
+ * ```
+ *
+ * @see SupabaseAuthAdapter (from `@solvapay/auth/supabase`) for Supabase implementation
+ * @see {@link MockAuthAdapter} for testing implementation
+ * @since 1.0.0
+ */
+interface AuthAdapter {
+    /**
+     * Extract the authenticated user ID from a request.
+     *
+     * This method should:
+     * - Never throw exceptions (return null on failure)
+     * - Handle missing/invalid authentication gracefully
+     * - Work with both Request objects and objects with headers
+     *
+     * @param req - Request object or object with headers
+     * @returns The user ID string if authenticated, null otherwise
+     *
+     * @remarks
+     * This method should never throw. If authentication fails or is missing,
+     * return null and let the caller decide how to handle unauthenticated requests.
+     */
+    getUserIdFromRequest(req: Request | RequestLike): Promise<string | null>;
+}
+
+export type { AuthAdapter as A, RequestLike as R };

package/dist/adapter-Lx7F0MH7.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Auth Adapter Interface
+ *
+ * Defines the contract for authentication adapters that extract user IDs from requests.
+ * Implementations should never throw - return null if authentication fails or is missing.
+ */
+/**
+ * Request-like object that has headers
+ */
+interface RequestLike {
+    headers: Headers | {
+        get(name: string): string | null;
+    };
+}
+/**
+ * Authentication adapter interface for extracting user IDs from requests.
+ *
+ * This interface defines the contract for authentication adapters that can
+ * extract user IDs from various authentication systems (Supabase, custom JWT,
+ * session-based auth, etc.). Adapters should never throw - return null if
+ * authentication fails or is missing.
+ *
+ * @example
+ * ```typescript
+ * import type { AuthAdapter } from '@solvapay/auth';
+ *
+ * // Custom adapter implementation
+ * const myAdapter: AuthAdapter = {
+ *   async getUserIdFromRequest(req) {
+ *     // Extract user ID from request (JWT, session, etc.)
+ *     const token = req.headers.get('authorization')?.replace('Bearer ', '');
+ *     if (!token) return null;
+ *
+ *     // Validate and extract user ID
+ *     const payload = await verifyToken(token);
+ *     return payload.userId || null;
+ *   }
+ * };
+ * ```
+ *
+ * @see SupabaseAuthAdapter (from `@solvapay/auth/supabase`) for Supabase implementation
+ * @see {@link MockAuthAdapter} for testing implementation
+ * @since 1.0.0
+ */
+interface AuthAdapter {
+    /**
+     * Extract the authenticated user ID from a request.
+     *
+     * This method should:
+     * - Never throw exceptions (return null on failure)
+     * - Handle missing/invalid authentication gracefully
+     * - Work with both Request objects and objects with headers
+     *
+     * @param req - Request object or object with headers
+     * @returns The user ID string if authenticated, null otherwise
+     *
+     * @remarks
+     * This method should never throw. If authentication fails or is missing,
+     * return null and let the caller decide how to handle unauthenticated requests.
+     */
+    getUserIdFromRequest(req: Request | RequestLike): Promise<string | null>;
+}
+
+export type { AuthAdapter as A, RequestLike as R };

package/dist/{chunk-B4VVTQWS.js → chunk-IOLE5BMD.js}

@@ -46,7 +46,8 @@ async function getUserNameFromRequest(request, options) {
     const { payload } = await jwtVerify(token, secret, {
       algorithms: ["HS256"]
     });
-    const name = payload.user_metadata?.name || payload.name || null;
+    const payloadWithMetadata = payload;
+    const name = payloadWithMetadata.user_metadata?.full_name || payloadWithMetadata.user_metadata?.name || payloadWithMetadata.name || null;
     return name ? String(name) : null;
   } catch {
     return null;
@@ -58,13 +59,10 @@ function requireUserId(request, options) {
   const errorDetails = options?.errorDetails || "User ID not found. Ensure middleware is configured.";
   const userId = request.headers.get(headerName);
   if (!userId) {
-    return new Response(
-      JSON.stringify({ error: errorMessage, details: errorDetails }),
-      {
-        status: 401,
-        headers: { "Content-Type": "application/json" }
-      }
-    );
+    return new Response(JSON.stringify({ error: errorMessage, details: errorDetails }), {
+      status: 401,
+      headers: { "Content-Type": "application/json" }
+    });
   }
   return userId;
 }

package/dist/index.cjs

@@ -31,6 +31,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   MockAuthAdapter: () => MockAuthAdapter,
+  SolvapayAuthAdapter: () => SolvapayAuthAdapter,
+  SolvapayOAuthClient: () => SolvapayOAuthClient,
   getUserEmailFromRequest: () => getUserEmailFromRequest,
   getUserIdFromRequest: () => getUserIdFromRequest,
   getUserNameFromRequest: () => getUserNameFromRequest,
@@ -53,6 +55,125 @@ var MockAuthAdapter = class {
   }
 };
 
+// src/solvapay.ts
+var SolvapayAuthAdapter = class {
+  apiBaseUrl;
+  constructor(config) {
+    this.apiBaseUrl = config.apiBaseUrl.replace(/\/$/, "");
+  }
+  async getUserIdFromRequest(req) {
+    try {
+      const headers = "headers" in req ? req.headers : req;
+      const authHeader = headers.get("authorization");
+      if (!authHeader || !authHeader.startsWith("Bearer ")) {
+        return null;
+      }
+      const token = authHeader.slice(7);
+      if (!token) {
+        return null;
+      }
+      const response = await fetch(`${this.apiBaseUrl}/v1/customer/auth/userinfo`, {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json"
+        }
+      });
+      if (!response.ok) {
+        return null;
+      }
+      const userInfo = await response.json();
+      return userInfo.sub || userInfo.id || userInfo.customerRef || null;
+    } catch {
+      return null;
+    }
+  }
+};
+var SolvapayOAuthClient = class {
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * Get the URL to redirect the user to for login
+   */
+  getAuthorizationUrl(options = {}) {
+    const params = new URLSearchParams({
+      response_type: "code",
+      client_id: this.config.clientId,
+      redirect_uri: this.config.redirectUri
+    });
+    if (options.state) params.append("state", options.state);
+    if (options.scope) params.append("scope", options.scope);
+    return `${this.config.authUrl}?${params.toString()}`;
+  }
+  /**
+   * Exchange an authorization code for an access token
+   */
+  async exchangeCodeForToken(code) {
+    const body = new URLSearchParams({
+      grant_type: "authorization_code",
+      code,
+      client_id: this.config.clientId,
+      redirect_uri: this.config.redirectUri
+    });
+    if (this.config.clientSecret) {
+      body.append("client_secret", this.config.clientSecret);
+    }
+    const response = await fetch(this.config.tokenUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json"
+      },
+      body: body.toString()
+    });
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`Failed to exchange code: ${response.status} ${text}`);
+    }
+    return response.json();
+  }
+  /**
+   * Revoke a token (Sign Out)
+   */
+  async revokeToken(token) {
+    const revokeUrl = this.config.tokenUrl.replace("/token", "/revoke");
+    const body = new URLSearchParams({
+      token,
+      client_id: this.config.clientId
+    });
+    if (this.config.clientSecret) {
+      body.append("client_secret", this.config.clientSecret);
+    }
+    await fetch(revokeUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded"
+      },
+      body: body.toString()
+    });
+  }
+  /**
+   * Get user info using access token
+   */
+  async getUserInfo(accessToken, userInfoUrl) {
+    if (!userInfoUrl) {
+      throw new Error("userInfoUrl is required");
+    }
+    const response = await fetch(userInfoUrl, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        Accept: "application/json"
+      }
+    });
+    if (!response.ok) {
+      throw new Error(`Failed to fetch user info: ${response.status}`);
+    }
+    return response.json();
+  }
+};
+
 // src/next-utils.ts
 function getUserIdFromRequest(request, options) {
   const headerName = options?.headerName || "x-user-id";
@@ -101,7 +222,8 @@ async function getUserNameFromRequest(request, options) {
     const { payload } = await jwtVerify(token, secret, {
       algorithms: ["HS256"]
     });
-    const name = payload.user_metadata?.name || payload.name || null;
+    const payloadWithMetadata = payload;
+    const name = payloadWithMetadata.user_metadata?.full_name || payloadWithMetadata.user_metadata?.name || payloadWithMetadata.name || null;
     return name ? String(name) : null;
   } catch {
     return null;
@@ -113,19 +235,18 @@ function requireUserId(request, options) {
   const errorDetails = options?.errorDetails || "User ID not found. Ensure middleware is configured.";
   const userId = request.headers.get(headerName);
   if (!userId) {
-    return new Response(
-      JSON.stringify({ error: errorMessage, details: errorDetails }),
-      {
-        status: 401,
-        headers: { "Content-Type": "application/json" }
-      }
-    );
+    return new Response(JSON.stringify({ error: errorMessage, details: errorDetails }), {
+      status: 401,
+      headers: { "Content-Type": "application/json" }
+    });
   }
   return userId;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   MockAuthAdapter,
+  SolvapayAuthAdapter,
+  SolvapayOAuthClient,
   getUserEmailFromRequest,
   getUserIdFromRequest,
   getUserNameFromRequest,

package/dist/index.d.cts

@@ -1,3 +1,70 @@
-export { A as AuthAdapter, R as RequestLike } from './adapter-4HTpALyc.cjs';
+import { A as AuthAdapter, R as RequestLike } from './adapter-Lx7F0MH7.cjs';
 export { MockAuthAdapter, MockAuthAdapter as MockAuthAdapterType } from './mock.cjs';
 export { getUserEmailFromRequest, getUserIdFromRequest, getUserNameFromRequest, requireUserId } from './next-utils.cjs';
+
+/**
+ * SolvaPay Auth Adapter
+ *
+ * Validates SolvaPay OAuth tokens by calling the userinfo endpoint.
+ * Suitable for validating opaque tokens issued by SolvaPay's hosted OAuth service.
+ */
+
+interface SolvapayAuthAdapterConfig {
+    /**
+     * SolvaPay API Base URL (e.g. https://api.solvapay.com)
+     */
+    apiBaseUrl: string;
+}
+/**
+ * SolvaPay authentication adapter
+ *
+ * Validates tokens by calling the SolvaPay userinfo endpoint.
+ * This is required for opaque tokens which cannot be verified offline.
+ */
+declare class SolvapayAuthAdapter implements AuthAdapter {
+    private apiBaseUrl;
+    constructor(config: SolvapayAuthAdapterConfig);
+    getUserIdFromRequest(req: Request | RequestLike): Promise<string | null>;
+}
+/**
+ * SolvaPay OAuth Client Helpers
+ */
+interface SolvapayOAuthConfig {
+    clientId: string;
+    clientSecret?: string;
+    authUrl: string;
+    tokenUrl: string;
+    redirectUri: string;
+}
+interface TokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    refresh_token?: string;
+    scope?: string;
+}
+declare class SolvapayOAuthClient {
+    private config;
+    constructor(config: SolvapayOAuthConfig);
+    /**
+     * Get the URL to redirect the user to for login
+     */
+    getAuthorizationUrl(options?: {
+        state?: string;
+        scope?: string;
+    }): string;
+    /**
+     * Exchange an authorization code for an access token
+     */
+    exchangeCodeForToken(code: string): Promise<TokenResponse>;
+    /**
+     * Revoke a token (Sign Out)
+     */
+    revokeToken(token: string): Promise<void>;
+    /**
+     * Get user info using access token
+     */
+    getUserInfo(accessToken: string, userInfoUrl?: string): Promise<Record<string, unknown>>;
+}
+
+export { AuthAdapter, RequestLike, SolvapayAuthAdapter, type SolvapayAuthAdapterConfig, SolvapayOAuthClient, type SolvapayOAuthConfig, type TokenResponse };