@solvapay/server 1.0.0-preview.1

package/README.md

@@ -0,0 +1,242 @@
+# @solvapay/server
+
+Universal server SDK for Node.js and edge runtimes. Includes API client, paywall protection, and webhook verification.
+
+**Works in**: Node.js, Vercel Edge Functions, Cloudflare Workers, Deno, Supabase Edge Functions, and more.
+
+## Install
+```bash
+pnpm add @solvapay/server
+```
+
+## Usage
+
+### Basic Client
+
+The same imports work in **Node.js and edge runtimes**. The correct implementation is automatically selected:
+
+```ts
+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! 
+});
+
+// Auto-selects Node crypto or Web Crypto based on runtime
+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';
+
+const solvapay = createSolvaPayClient({
+  apiKey: Deno.env.get('SOLVAPAY_SECRET_KEY')!,
+});
+
+// Vercel Edge Function
+import { createSolvaPayClient } from '@solvapay/server';
+
+export const runtime = 'edge';
+const solvapay = createSolvaPayClient({
+  apiKey: process.env.SOLVAPAY_SECRET_KEY!,
+});
+```
+
+### Paywall Protection
+
+Use the unified payable API to protect your endpoints and functions with usage limits and metered billing:
+
+```ts
+import { createSolvaPay } from '@solvapay/server';
+
+// Create SolvaPay instance with your API key
+const solvaPay = createSolvaPay({ 
+  apiKey: process.env.SOLVAPAY_SECRET_KEY! 
+});
+
+// Create a payable with your agent configuration
+const payable = solvaPay.payable({ agent: 'my-agent' });
+
+// Use the appropriate adapter for your context:
+
+// For HTTP frameworks (Express, Fastify)
+app.post('/tasks', payable.http(async (args) => {
+  return { result: 'success' };
+}));
+
+// For Next.js App Router
+export const POST = payable.next(async (args) => {
+  return { result: 'success' };
+});
+
+// For MCP servers
+server.setRequestHandler(ListToolsRequestSchema, payable.mcp(async (args) => {
+  return { tools: [...] };
+}));
+
+// For direct function protection (testing, background jobs)
+const protectedHandler = await payable.function(async (args) => {
+  return { result: 'success' };
+});
+
+const result = await protectedHandler({ 
+  auth: { customer_ref: 'customer_123' } 
+});
+```
+
+### When to Use Each Adapter
+
+Choose the adapter based on your context:
+
+- **`payable.http()`** - Use with Express, Fastify, or other traditional HTTP frameworks
+  - Handles request/response objects automatically
+  - Extracts args from body, params, query
+  - Formats errors as HTTP responses
+
+- **`payable.next()`** - Use with Next.js App Router API routes
+  - Works with Web Request/Response APIs
+  - Handles route parameters and context
+  - Returns proper Response objects
+
+- **`payable.mcp()`** - Use with Model Context Protocol servers
+  - Wraps responses in MCP format
+  - Handles MCP-specific error reporting
+  - Provides structured content
+
+- **`payable.function()`** - Use for direct function protection
+  - No framework overhead
+  - Perfect for testing
+  - Use in background jobs, cron tasks, or non-HTTP contexts
+
+## API Client Methods
+
+The `createSolvaPayClient` returns an object implementing `SolvaPayClient`:
+
+- `checkLimits(params)` - Check if customer is within usage limits
+- `trackUsage(params)` - Track usage for metered billing
+- `createCustomer(params)` - Create a new customer
+- `getCustomer(params)` - Get customer details by reference
+
+## Type Generation
+
+This package supports automatic TypeScript type generation from the SolvaPay backend OpenAPI specification.
+
+### Generating Types
+
+To generate types from your locally running backend:
+
+```bash
+# Ensure your backend is running on http://localhost:3001
+# Then run:
+pnpm generate:types
+```
+
+This will fetch the OpenAPI spec from `http://localhost:3001/v1/openapi.json` and generate TypeScript types in `src/types/generated.ts`. Only `/v1/sdk/` routes are included in the generated types.
+
+### Using Generated Types
+
+```typescript
+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'];
+
+// Use component schemas
+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.
+
+## Testing
+
+> **📖 For detailed integration test setup**, see:
+> - [`packages/test-utils/INTEGRATION_TESTING.md`](../test-utils/INTEGRATION_TESTING.md) - Complete setup guide
+> - [`SDK_INTEGRATION_TESTS_IMPLEMENTATION.md`](../../SDK_INTEGRATION_TESTS_IMPLEMENTATION.md) - Implementation details
+
+This package includes comprehensive tests for SDK functionality.
+
+### Running Tests
+
+```bash
+# Run unit tests only (fast, uses mock backend)
+pnpm test
+
+# Run integration tests (requires real backend)
+pnpm test:integration
+
+# Run all tests
+pnpm test:all
+
+# Run all tests with real backend
+pnpm test:all:integration
+
+# Watch mode
+pnpm test:watch
+```
+
+### Unit Tests
+
+Unit tests (`__tests__/paywall.test.ts`) use a mock API client and test:
+- Paywall protection logic
+- Handler creation (HTTP, Next.js, MCP)
+- Error handling
+- Authentication flows
+- Agent resolution
+
+**No backend required** - runs fast and deterministically.
+
+### Integration Tests
+
+Integration tests (`__tests__/paywall.integration.with-fetched-defaults.test.ts`) connect to a real SolvaPay backend and test:
+- SDK API methods with real responses
+- Actual limit enforcement
+- Real usage tracking
+- Multi-framework handlers with backend
+- Error handling with real backend responses
+
+**Setup required:**
+
+Set environment variables before running tests:
+
+```bash
+# Option 1: Export in your shell (persists in session)
+export USE_REAL_BACKEND=true
+export SOLVAPAY_SECRET_KEY=your_secret_key_here
+export SOLVAPAY_API_BASE_URL=https://api-dev.solvapay.com  # optional
+pnpm test:integration
+
+# Option 2: Inline with command (single use)
+USE_REAL_BACKEND=true SOLVAPAY_SECRET_KEY=your_key pnpm test:integration
+```
+
+**Note:** This follows the industry standard used by major SDKs (Stripe, AWS, Twilio). No `.env` file is required.
+
+**Note:** Integration tests are automatically skipped if `USE_REAL_BACKEND` or `SOLVAPAY_SECRET_KEY` are not set. This allows CI/CD to run unit tests without backend credentials.
+
+### CI/CD
+
+```yaml
+# Always run unit tests
+- name: Run unit tests
+  run: pnpm test
+
+# Optionally run integration tests if secrets available
+- name: Run integration tests
+  if: ${{ secrets.SOLVAPAY_SECRET_KEY != '' }}
+  env:
+    SOLVAPAY_SECRET_KEY: ${{ secrets.SOLVAPAY_SECRET_KEY }}
+  run: pnpm test:integration
+```
+
+More: docs/architecture.md

package/dist/chunk-R5U7XKVJ.js

@@ -0,0 +1,16 @@
+var __defProp = Object.defineProperty;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+export {
+  __require,
+  __export
+};