@solvapay/server 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

@@ -5,6 +5,7 @@ Universal server SDK for Node.js and edge runtimes. Includes API client, paywall
 **Works in**: Node.js, Vercel Edge Functions, Cloudflare Workers, Deno, Supabase Edge Functions, and more.
 
 ## Install
+
 ```bash
 pnpm add @solvapay/server
 ```
@@ -16,39 +17,39 @@ pnpm add @solvapay/server
 The same imports work in **Node.js and edge runtimes**. The correct implementation is automatically selected:
 
 ```ts
-import { createSolvaPayClient, verifyWebhook } from '@solvapay/server';
+import { createSolvaPayClient, verifyWebhook } from '@solvapay/server'
 
 // Works in Node.js, Edge Functions, Cloudflare Workers, Deno, etc.
-const apiClient = createSolvaPayClient({ 
-  apiKey: process.env.SOLVAPAY_SECRET_KEY! 
-});
+const apiClient = createSolvaPayClient({
+  apiKey: process.env.SOLVAPAY_SECRET_KEY!,
+})
 
 // Auto-selects Node crypto or Web Crypto based on runtime
-const event = await verifyWebhook({ 
-  body, 
-  signature, 
-  secret: process.env.SOLVAPAY_WEBHOOK_SECRET! 
-});
+const event = await verifyWebhook({
+  body,
+  signature,
+  secret: process.env.SOLVAPAY_WEBHOOK_SECRET!,
+})
 ```
 
 **Edge Runtime Examples:**
 
 ```ts
 // Supabase Edge Function
-import { serve } from 'https://deno.land/std@0.168.0/http/server.ts';
-import { createSolvaPayClient, verifyWebhook } from 'https://esm.sh/@solvapay/server@latest';
+import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
+import { createSolvaPayClient, verifyWebhook } from 'https://esm.sh/@solvapay/server@latest'
 
 const solvapay = createSolvaPayClient({
   apiKey: Deno.env.get('SOLVAPAY_SECRET_KEY')!,
-});
+})
 
 // Vercel Edge Function
-import { createSolvaPayClient } from '@solvapay/server';
+import { createSolvaPayClient } from '@solvapay/server'
 
-export const runtime = 'edge';
+export const runtime = 'edge'
 const solvapay = createSolvaPayClient({
   apiKey: process.env.SOLVAPAY_SECRET_KEY!,
-});
+})
 ```
 
 ### Paywall Protection
@@ -59,12 +60,12 @@ Use the unified payable API to protect your endpoints and functions with usage l
 import { createSolvaPay } from '@solvapay/server';
 
 // Create SolvaPay instance with your API key
-const solvaPay = createSolvaPay({ 
-  apiKey: process.env.SOLVAPAY_SECRET_KEY! 
+const solvaPay = createSolvaPay({
+  apiKey: process.env.SOLVAPAY_SECRET_KEY!
 });
 
-// Create a payable with your agent configuration
-const payable = solvaPay.payable({ agent: 'my-agent' });
+// Create a payable with your product configuration
+const payable = solvaPay.payable({ product: 'my-product' });
 
 // Use the appropriate adapter for your context:
 
@@ -88,8 +89,8 @@ const protectedHandler = await payable.function(async (args) => {
   return { result: 'success' };
 });
 
-const result = await protectedHandler({ 
-  auth: { customer_ref: 'customer_123' } 
+const result = await protectedHandler({
+  auth: { customer_ref: 'customer_123' }
 });
 ```
 
@@ -98,30 +99,62 @@ const result = await protectedHandler({
 You can integrate authentication adapters from `@solvapay/auth` 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)
+      if (!userId) {
+        throw new Error('Unauthorized')
+      }
+      return userId
+    },
+  },
+)
 ```
 
 This automatically extracts the user ID from authentication tokens and uses it as the customer reference for paywall checks.
+Fail closed on missing/invalid auth. Do not fall back to shared identities like `anonymous`.
+
+For MCP bearer-token flows, the SDK also exports helper utilities:
+
+```ts
+import {
+  getCustomerRefFromBearerAuthHeader,
+  McpBearerAuthError,
+} from '@solvapay/server'
+
+const handler = solvaPay.payable({ product: 'my-api' }).mcp(
+  async args => ({ ok: true }),
+  {
+    getCustomerRef: args => {
+      try {
+        return getCustomerRefFromBearerAuthHeader(args._authHeader as string | undefined)
+      } catch (error) {
+        if (error instanceof McpBearerAuthError) {
+          throw new Error('Unauthorized')
+        }
+        throw error
+      }
+    },
+  },
+)
+```
+
+`payable({ getCustomerRef })` is now supported as a default extractor across adapters. Adapter-level
+`getCustomerRef` still takes precedence when both are provided.
 
 ### When to Use Each Adapter
 
@@ -175,18 +208,20 @@ This will fetch the OpenAPI spec from `http://localhost:3001/v1/openapi.json` an
 ### Using Generated Types
 
 ```typescript
-import type { paths, components } from './types/generated';
+import type { paths, components } from './types/generated'
 
 // Use path operation types
-type CheckLimitsRequest = paths['/v1/sdk/limits']['post']['requestBody']['content']['application/json'];
-type CheckLimitsResponse = paths['/v1/sdk/limits']['post']['responses']['200']['content']['application/json'];
+type CheckLimitsRequest =
+  paths['/v1/sdk/limits']['post']['requestBody']['content']['application/json']
+type CheckLimitsResponse =
+  paths['/v1/sdk/limits']['post']['responses']['200']['content']['application/json']
 
 // Use component schemas
-type Agent = components['schemas']['Agent'];
-type Plan = components['schemas']['Plan'];
+type Agent = components['schemas']['Agent']
+type Plan = components['schemas']['Plan']
 ```
 
-**Note:** The generated types complement the existing hand-written types in `src/types.ts`. Run `pnpm generate:types` whenever the backend API changes to keep types in sync.
+**Note:** The generated types complement the existing hand-written types in `src/types/client.ts`. Run `pnpm generate:types` whenever the backend API changes to keep types in sync.
 
 ## Testing
 
@@ -213,18 +248,20 @@ pnpm test:watch
 
 ### Unit Tests
 
-Unit tests (`__tests__/paywall.test.ts`) use a mock API client and test:
+Unit tests (`__tests__/paywall.unit.test.ts`, `__tests__/mcp-auth.unit.test.ts`) use a mock API client and test:
+
 - Paywall protection logic
 - Handler creation (HTTP, Next.js, MCP)
 - Error handling
 - Authentication flows
-- Agent resolution
+- Product resolution
 
 **No backend required** - runs fast and deterministically.
 
 ### Integration Tests
 
 Integration tests (`__tests__/backend.integration.test.ts`) connect to a real SolvaPay backend and test:
+
 - SDK API methods with real responses
 - Actual limit enforcement
 - Real usage tracking
@@ -251,6 +288,7 @@ USE_REAL_BACKEND=true SOLVAPAY_SECRET_KEY=your_key pnpm test:integration
 ### Payment Integration Tests (Stripe)
 
 Payment tests (`__tests__/payment-stripe.integration.test.ts`) verify the complete payment flow with Stripe:
+
 - Creating payment intents
 - Confirming payments with test cards
 - Webhook processing (optional)
@@ -270,24 +308,27 @@ export SOLVAPAY_API_BASE_URL=http://localhost:3001
 The E2E webhook test is skipped by default because it requires Stripe webhooks to be forwarded to your local backend. To enable webhook testing:
 
 1. **Install Stripe CLI:**
+
    ```bash
    # macOS
    brew install stripe/stripe-cli/stripe
-   
+
    # Linux / Windows - see https://stripe.com/docs/stripe-cli
    ```
 
 2. **Login to Stripe:**
+
    ```bash
    stripe login
    ```
 
 3. **Forward webhooks to your local backend:**
+
    ```bash
    # Terminal 1: Start your backend
    cd path/to/solvapay-backend
    pnpm dev
-   
+
    # Terminal 2: Forward Stripe webhooks
    stripe listen --forward-to localhost:3001/webhooks/stripe
    ```
@@ -354,4 +395,4 @@ By default, both are **disabled** to keep test output clean and readable. Enable
   run: pnpm test:integration
 ```
 
-More: docs/architecture.md
+More: [docs/guides/architecture.md](../../docs/guides/architecture.md)

package/dist/chunk-MLKGABMK.js

@@ -0,0 +1,9 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+export {
+  __export
+};