@solvapay/server 1.0.8-preview.8 → 1.0.8-preview.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (141) hide show
  1. package/dist/edge.d.ts +24 -1
  2. package/dist/edge.js +72 -0
  3. package/dist/index.cjs +12 -307
  4. package/dist/index.d.cts +3 -35
  5. package/dist/index.d.ts +3 -35
  6. package/dist/index.js +12 -303
  7. package/package.json +7 -7
  8. package/dist/chunk-R5U7XKVJ.js +0 -16
  9. package/dist/dist-EPVKJAIP.js +0 -94
  10. package/dist/dist-JBJ4HMP7.js +0 -94
  11. package/dist/esm-5GYCIXIY.js +0 -3475
  12. package/dist/esm-UW7WCMEK.js +0 -3475
  13. package/dist/src/adapters/base.d.ts +0 -57
  14. package/dist/src/adapters/base.d.ts.map +0 -1
  15. package/dist/src/adapters/base.js +0 -73
  16. package/dist/src/adapters/base.js.map +0 -1
  17. package/dist/src/adapters/http.d.ts +0 -25
  18. package/dist/src/adapters/http.d.ts.map +0 -1
  19. package/dist/src/adapters/http.js +0 -99
  20. package/dist/src/adapters/http.js.map +0 -1
  21. package/dist/src/adapters/index.d.ts +0 -11
  22. package/dist/src/adapters/index.d.ts.map +0 -1
  23. package/dist/src/adapters/index.js +0 -10
  24. package/dist/src/adapters/index.js.map +0 -1
  25. package/dist/src/adapters/mcp.d.ts +0 -24
  26. package/dist/src/adapters/mcp.d.ts.map +0 -1
  27. package/dist/src/adapters/mcp.js +0 -75
  28. package/dist/src/adapters/mcp.js.map +0 -1
  29. package/dist/src/adapters/next.d.ts +0 -24
  30. package/dist/src/adapters/next.d.ts.map +0 -1
  31. package/dist/src/adapters/next.js +0 -109
  32. package/dist/src/adapters/next.js.map +0 -1
  33. package/dist/src/client.d.ts +0 -58
  34. package/dist/src/client.d.ts.map +0 -1
  35. package/dist/src/client.js +0 -495
  36. package/dist/src/client.js.map +0 -1
  37. package/dist/src/edge.d.ts +0 -22
  38. package/dist/src/edge.d.ts.map +0 -1
  39. package/dist/src/edge.js +0 -91
  40. package/dist/src/edge.js.map +0 -1
  41. package/dist/src/factory.d.ts +0 -605
  42. package/dist/src/factory.d.ts.map +0 -1
  43. package/dist/src/factory.js +0 -215
  44. package/dist/src/factory.js.map +0 -1
  45. package/dist/src/helpers/auth.d.ts +0 -47
  46. package/dist/src/helpers/auth.d.ts.map +0 -1
  47. package/dist/src/helpers/auth.js +0 -73
  48. package/dist/src/helpers/auth.js.map +0 -1
  49. package/dist/src/helpers/checkout.d.ts +0 -45
  50. package/dist/src/helpers/checkout.d.ts.map +0 -1
  51. package/dist/src/helpers/checkout.js +0 -89
  52. package/dist/src/helpers/checkout.js.map +0 -1
  53. package/dist/src/helpers/customer.d.ts +0 -51
  54. package/dist/src/helpers/customer.d.ts.map +0 -1
  55. package/dist/src/helpers/customer.js +0 -77
  56. package/dist/src/helpers/customer.js.map +0 -1
  57. package/dist/src/helpers/error.d.ts +0 -15
  58. package/dist/src/helpers/error.d.ts.map +0 -1
  59. package/dist/src/helpers/error.js +0 -35
  60. package/dist/src/helpers/error.js.map +0 -1
  61. package/dist/src/helpers/index.d.ts +0 -17
  62. package/dist/src/helpers/index.d.ts.map +0 -1
  63. package/dist/src/helpers/index.js +0 -23
  64. package/dist/src/helpers/index.js.map +0 -1
  65. package/dist/src/helpers/payment.d.ts +0 -107
  66. package/dist/src/helpers/payment.d.ts.map +0 -1
  67. package/dist/src/helpers/payment.js +0 -150
  68. package/dist/src/helpers/payment.js.map +0 -1
  69. package/dist/src/helpers/plans.d.ts +0 -19
  70. package/dist/src/helpers/plans.d.ts.map +0 -1
  71. package/dist/src/helpers/plans.js +0 -53
  72. package/dist/src/helpers/plans.js.map +0 -1
  73. package/dist/src/helpers/renewal.d.ts +0 -23
  74. package/dist/src/helpers/renewal.d.ts.map +0 -1
  75. package/dist/src/helpers/renewal.js +0 -90
  76. package/dist/src/helpers/renewal.js.map +0 -1
  77. package/dist/src/helpers/subscription.d.ts +0 -23
  78. package/dist/src/helpers/subscription.d.ts.map +0 -1
  79. package/dist/src/helpers/subscription.js +0 -101
  80. package/dist/src/helpers/subscription.js.map +0 -1
  81. package/dist/src/helpers/types.d.ts +0 -22
  82. package/dist/src/helpers/types.d.ts.map +0 -1
  83. package/dist/src/helpers/types.js +0 -7
  84. package/dist/src/helpers/types.js.map +0 -1
  85. package/dist/src/index.d.ts +0 -73
  86. package/dist/src/index.d.ts.map +0 -1
  87. package/dist/src/index.js +0 -106
  88. package/dist/src/index.js.map +0 -1
  89. package/dist/src/mcp/auth-bridge.d.ts +0 -9
  90. package/dist/src/mcp/auth-bridge.d.ts.map +0 -1
  91. package/dist/src/mcp/auth-bridge.js +0 -46
  92. package/dist/src/mcp/auth-bridge.js.map +0 -1
  93. package/dist/src/mcp/oauth-bridge.d.ts +0 -48
  94. package/dist/src/mcp/oauth-bridge.d.ts.map +0 -1
  95. package/dist/src/mcp/oauth-bridge.js +0 -110
  96. package/dist/src/mcp/oauth-bridge.js.map +0 -1
  97. package/dist/src/mcp-auth.d.ts +0 -17
  98. package/dist/src/mcp-auth.d.ts.map +0 -1
  99. package/dist/src/mcp-auth.js +0 -57
  100. package/dist/src/mcp-auth.js.map +0 -1
  101. package/dist/src/paywall.d.ts +0 -119
  102. package/dist/src/paywall.d.ts.map +0 -1
  103. package/dist/src/paywall.js +0 -700
  104. package/dist/src/paywall.js.map +0 -1
  105. package/dist/src/register-virtual-tools-mcp.d.ts +0 -23
  106. package/dist/src/register-virtual-tools-mcp.d.ts.map +0 -1
  107. package/dist/src/register-virtual-tools-mcp.js +0 -86
  108. package/dist/src/register-virtual-tools-mcp.js.map +0 -1
  109. package/dist/src/types/client.d.ts +0 -216
  110. package/dist/src/types/client.d.ts.map +0 -1
  111. package/dist/src/types/client.js +0 -7
  112. package/dist/src/types/client.js.map +0 -1
  113. package/dist/src/types/generated.d.ts +0 -2834
  114. package/dist/src/types/generated.d.ts.map +0 -1
  115. package/dist/src/types/generated.js +0 -6
  116. package/dist/src/types/generated.js.map +0 -1
  117. package/dist/src/types/index.d.ts +0 -13
  118. package/dist/src/types/index.d.ts.map +0 -1
  119. package/dist/src/types/index.js +0 -8
  120. package/dist/src/types/index.js.map +0 -1
  121. package/dist/src/types/options.d.ts +0 -126
  122. package/dist/src/types/options.d.ts.map +0 -1
  123. package/dist/src/types/options.js +0 -8
  124. package/dist/src/types/options.js.map +0 -1
  125. package/dist/src/types/paywall.d.ts +0 -64
  126. package/dist/src/types/paywall.d.ts.map +0 -1
  127. package/dist/src/types/paywall.js +0 -7
  128. package/dist/src/types/paywall.js.map +0 -1
  129. package/dist/src/types/webhook.d.ts +0 -50
  130. package/dist/src/types/webhook.d.ts.map +0 -1
  131. package/dist/src/types/webhook.js +0 -2
  132. package/dist/src/types/webhook.js.map +0 -1
  133. package/dist/src/utils.d.ts +0 -110
  134. package/dist/src/utils.d.ts.map +0 -1
  135. package/dist/src/utils.js +0 -217
  136. package/dist/src/utils.js.map +0 -1
  137. package/dist/src/virtual-tools.d.ts +0 -44
  138. package/dist/src/virtual-tools.d.ts.map +0 -1
  139. package/dist/src/virtual-tools.js +0 -140
  140. package/dist/src/virtual-tools.js.map +0 -1
  141. package/dist/tsconfig.tsbuildinfo +0 -1
@@ -1,605 +0,0 @@
1
- /**
2
- * SolvaPay Factory
3
- *
4
- * Main entry point for creating SolvaPay instances with the unified payable API
5
- */
6
- import type { SolvaPayClient, PayableOptions, HttpAdapterOptions, NextAdapterOptions, McpAdapterOptions, McpToolExtra, CustomerResponseMapped, McpBootstrapRequest, McpBootstrapResponse, ConfigureMcpPlansRequest, ConfigureMcpPlansResponse } from './types';
7
- import type { VirtualToolsOptions, VirtualToolDefinition } from './virtual-tools';
8
- import { type McpServerLike, type RegisterVirtualToolsMcpOptions } from './register-virtual-tools-mcp';
9
- /**
10
- * Configuration for creating a SolvaPay instance.
11
- *
12
- * You can provide either an `apiKey` (for production) or an `apiClient` (for testing).
13
- * If neither is provided, the SDK will attempt to read `SOLVAPAY_SECRET_KEY` from
14
- * environment variables. If no API key is found, the SDK runs in stub mode.
15
- *
16
- * @example
17
- * ```typescript
18
- * // Production: Use API key
19
- * const config: CreateSolvaPayConfig = {
20
- * apiKey: process.env.SOLVAPAY_SECRET_KEY
21
- * };
22
- *
23
- * // Testing: Use mock client
24
- * const config: CreateSolvaPayConfig = {
25
- * apiClient: mockClient
26
- * };
27
- * ```
28
- */
29
- export interface CreateSolvaPayConfig {
30
- /**
31
- * API key for production use (creates client automatically).
32
- * Defaults to `SOLVAPAY_SECRET_KEY` environment variable if not provided.
33
- */
34
- apiKey?: string;
35
- /**
36
- * API client for testing or custom implementations.
37
- * Use this for stub mode, testing, or custom client implementations.
38
- */
39
- apiClient?: SolvaPayClient;
40
- /**
41
- * Optional API base URL override (only used with apiKey).
42
- * Defaults to production API URL if not provided.
43
- */
44
- apiBaseUrl?: string;
45
- /**
46
- * TTL in ms for the checkLimits cache (default 10 000).
47
- * Positive results are cached and optimistically decremented to avoid
48
- * redundant API calls during tool-call bursts.
49
- */
50
- limitsCacheTTL?: number;
51
- }
52
- /**
53
- * Payable function that provides explicit adapters for different frameworks.
54
- *
55
- * Use the appropriate adapter method for your framework:
56
- * - `http()` - Express.js, Fastify, and other HTTP frameworks
57
- * - `next()` - Next.js App Router API routes
58
- * - `mcp()` - Model Context Protocol servers
59
- * - `function()` - Pure functions, background jobs, or testing
60
- *
61
- * @example
62
- * ```typescript
63
- * const payable = solvaPay.payable({ product: 'prd_myapi', plan: 'pln_premium' });
64
- *
65
- * // Express.js
66
- * app.post('/tasks', payable.http(createTask));
67
- *
68
- * // Next.js
69
- * export const POST = payable.next(createTask);
70
- *
71
- * // MCP Server
72
- * const handler = payable.mcp(createTask);
73
- *
74
- * // Pure function
75
- * const protectedFn = await payable.function(createTask);
76
- * ```
77
- */
78
- export interface PayableFunction {
79
- /**
80
- * HTTP adapter for Express.js, Fastify, and other HTTP frameworks.
81
- *
82
- * @param businessLogic - Your business logic function
83
- * @param options - Optional adapter configuration
84
- * @returns HTTP route handler function
85
- *
86
- * @example
87
- * ```typescript
88
- * app.post('/tasks', payable.http(async (req) => {
89
- * const { title } = req.body;
90
- * return { success: true, task: { title } };
91
- * }));
92
- * ```
93
- */
94
- http<T = any>(businessLogic: (args: any) => Promise<T>, options?: HttpAdapterOptions): (req: any, reply: any) => Promise<unknown>;
95
- /**
96
- * Next.js adapter for App Router API routes.
97
- *
98
- * @param businessLogic - Your business logic function
99
- * @param options - Optional adapter configuration
100
- * @returns Next.js route handler function
101
- *
102
- * @example
103
- * ```typescript
104
- * // app/api/tasks/route.ts
105
- * export const POST = payable.next(async (request) => {
106
- * const body = await request.json();
107
- * return Response.json({ success: true });
108
- * });
109
- * ```
110
- */
111
- next<T = any>(businessLogic: (args: any) => Promise<T>, options?: NextAdapterOptions): (request: Request, context?: any) => Promise<Response>;
112
- /**
113
- * MCP adapter for Model Context Protocol servers.
114
- *
115
- * @param businessLogic - Your tool implementation function
116
- * @param options - Optional adapter configuration
117
- * @returns MCP tool handler function
118
- *
119
- * @example
120
- * ```typescript
121
- * const handler = payable.mcp(async (args) => {
122
- * return { success: true, result: 'tool output' };
123
- * });
124
- * ```
125
- */
126
- mcp<T = any>(businessLogic: (args: any) => Promise<T>, options?: McpAdapterOptions): (args: Record<string, unknown>, extra?: McpToolExtra) => Promise<unknown>;
127
- /**
128
- * Pure function adapter for direct function protection.
129
- *
130
- * Use this for testing, background jobs, or non-framework contexts.
131
- *
132
- * @param businessLogic - Your business logic function
133
- * @returns Protected function that requires customer reference in args
134
- *
135
- * @example
136
- * ```typescript
137
- * const protectedFn = await payable.function(async (args) => {
138
- * return { result: 'processed' };
139
- * });
140
- *
141
- * // Call with customer reference
142
- * const result = await protectedFn({
143
- * auth: { customer_ref: 'user_123' },
144
- * // ... other args
145
- * });
146
- * ```
147
- */
148
- function<T = any>(businessLogic: (args: any) => Promise<T>): Promise<(args: any) => Promise<T>>;
149
- }
150
- /**
151
- * SolvaPay instance with payable method and common API methods.
152
- *
153
- * This interface provides the main API for interacting with SolvaPay.
154
- * Use `createSolvaPay()` to create an instance.
155
- *
156
- * @example
157
- * ```typescript
158
- * const solvaPay = createSolvaPay();
159
- *
160
- * // Create payable handlers
161
- * const payable = solvaPay.payable({ product: 'prd_myapi', plan: 'pln_premium' });
162
- *
163
- * // Manage customers
164
- * const customerRef = await solvaPay.ensureCustomer('user_123', 'user_123', {
165
- * email: 'user@example.com'
166
- * });
167
- *
168
- * // Create payment intents
169
- * const intent = await solvaPay.createPaymentIntent({
170
- * productRef: 'prd_myapi',
171
- * planRef: 'pln_premium',
172
- * customerRef: 'user_123'
173
- * });
174
- * ```
175
- */
176
- export interface SolvaPay {
177
- /**
178
- * Create a payable handler with explicit adapters for different frameworks.
179
- *
180
- * @param options - Payable options including product and plan references
181
- * @returns PayableFunction with framework-specific adapters
182
- *
183
- * @example
184
- * ```typescript
185
- * const payable = solvaPay.payable({
186
- * product: 'prd_myapi',
187
- * plan: 'pln_premium'
188
- * });
189
- *
190
- * app.post('/tasks', payable.http(createTask));
191
- * ```
192
- */
193
- payable(options?: PayableOptions): PayableFunction;
194
- /**
195
- * Ensure customer exists in SolvaPay backend (idempotent).
196
- *
197
- * Creates a customer if they don't exist, or returns existing customer reference.
198
- * This is automatically called by the paywall system, but you can call it
199
- * explicitly for setup or testing.
200
- *
201
- * @param customerRef - The customer reference used as a cache key (e.g., Supabase user ID)
202
- * @param externalRef - Optional external reference for backend lookup (e.g., Supabase user ID).
203
- * If provided, will lookup existing customer by externalRef before creating new one.
204
- * The externalRef is stored on the SolvaPay backend for customer lookup.
205
- * @param options - Optional customer details for customer creation
206
- * @param options.email - Customer email address
207
- * @param options.name - Customer name
208
- * @returns Customer reference (backend customer ID)
209
- *
210
- * @example
211
- * ```typescript
212
- * // Ensure customer exists before processing payment
213
- * const customerRef = await solvaPay.ensureCustomer(
214
- * 'user_123', // customerRef (your user ID)
215
- * 'user_123', // externalRef (same or different)
216
- * {
217
- * email: 'user@example.com',
218
- * name: 'John Doe'
219
- * }
220
- * );
221
- * ```
222
- */
223
- ensureCustomer(customerRef: string, externalRef?: string, options?: {
224
- email?: string;
225
- name?: string;
226
- }): Promise<string>;
227
- /**
228
- * Create a Stripe payment intent for a customer to purchase a plan.
229
- *
230
- * This creates a payment intent that can be confirmed on the client side
231
- * using Stripe.js. After confirmation, call `processPaymentIntent()` to complete
232
- * the purchase.
233
- *
234
- * @param params - Payment intent parameters
235
- * @param params.productRef - Product reference
236
- * @param params.planRef - Plan reference to purchase
237
- * @param params.customerRef - Customer reference
238
- * @param params.idempotencyKey - Optional idempotency key for retry safety
239
- * @returns Payment intent with client secret and publishable key
240
- *
241
- * @example
242
- * ```typescript
243
- * const intent = await solvaPay.createPaymentIntent({
244
- * productRef: 'prd_myapi',
245
- * planRef: 'pln_premium',
246
- * customerRef: 'user_123',
247
- * idempotencyKey: 'unique-key-123'
248
- * });
249
- *
250
- * // Use intent.clientSecret with Stripe.js on client
251
- * ```
252
- */
253
- createPaymentIntent(params: {
254
- productRef: string;
255
- planRef: string;
256
- customerRef: string;
257
- idempotencyKey?: string;
258
- }): Promise<{
259
- id: string;
260
- clientSecret: string;
261
- publishableKey: string;
262
- accountId?: string;
263
- }>;
264
- /**
265
- * Process a payment intent after client-side Stripe confirmation.
266
- *
267
- * Creates the purchase immediately, eliminating webhook delay.
268
- * Call this after the client has confirmed the payment intent with Stripe.js.
269
- *
270
- * @param params - Payment processing parameters
271
- * @param params.paymentIntentId - Stripe payment intent ID from client confirmation
272
- * @param params.productRef - Product reference
273
- * @param params.customerRef - Customer reference
274
- * @param params.planRef - Optional plan reference (if not in payment intent)
275
- * @returns Payment processing result with purchase details
276
- *
277
- * @example
278
- * ```typescript
279
- * // After client confirms payment with Stripe.js
280
- * const result = await solvaPay.processPaymentIntent({
281
- * paymentIntentId: 'pi_1234567890',
282
- * productRef: 'prd_myapi',
283
- * customerRef: 'user_123',
284
- * planRef: 'pln_premium'
285
- * });
286
- *
287
- * if (result.success) {
288
- * console.log('Purchase created:', result.purchase);
289
- * }
290
- * ```
291
- */
292
- processPaymentIntent(params: {
293
- paymentIntentId: string;
294
- productRef: string;
295
- customerRef: string;
296
- planRef?: string;
297
- }): Promise<import('./types/client').ProcessPaymentResult>;
298
- /**
299
- * Check if customer is within usage limits for a product.
300
- *
301
- * This method checks purchase status and usage limits without
302
- * executing business logic. Use `payable()` for automatic protection.
303
- *
304
- * @param params - Limit check parameters
305
- * @param params.customerRef - Customer reference
306
- * @param params.productRef - Product reference
307
- * @returns Limit check result with remaining usage and checkout URL if needed
308
- *
309
- * @example
310
- * ```typescript
311
- * const limits = await solvaPay.checkLimits({
312
- * customerRef: 'user_123',
313
- * productRef: 'prd_myapi',
314
- * planRef: 'pln_premium'
315
- * });
316
- *
317
- * if (!limits.withinLimits) {
318
- * // Redirect to checkout
319
- * window.location.href = limits.checkoutUrl;
320
- * }
321
- * ```
322
- */
323
- checkLimits(params: {
324
- customerRef: string;
325
- productRef: string;
326
- planRef?: string;
327
- meterName?: string;
328
- usageType?: string;
329
- }): Promise<{
330
- withinLimits: boolean;
331
- remaining: number;
332
- plan: string;
333
- checkoutUrl?: string;
334
- meterName?: string;
335
- creditBalance?: number;
336
- pricePerUnit?: number;
337
- currency?: string;
338
- }>;
339
- /**
340
- * Track usage for a customer action.
341
- *
342
- * This is automatically called by the paywall system. You typically
343
- * don't need to call this manually unless implementing custom tracking.
344
- *
345
- * @param params - Usage tracking parameters
346
- * @param params.customerRef - Customer reference
347
- * @param params.productRef - Product reference
348
- * @param params.planRef - Plan reference
349
- * @param params.outcome - Action outcome ('success', 'paywall', or 'fail')
350
- * @param params.action - Optional action name for analytics
351
- * @param params.requestId - Unique request ID
352
- * @param params.actionDuration - Action duration in milliseconds
353
- * @param params.timestamp - ISO timestamp of the action
354
- *
355
- * @example
356
- * ```typescript
357
- * await solvaPay.trackUsage({
358
- * customerRef: 'cus_3C4D5E6F',
359
- * actionType: 'api_call',
360
- * units: 1,
361
- * outcome: 'success',
362
- * metadata: { toolName: 'search', endpoint: '/search' },
363
- * });
364
- * ```
365
- */
366
- trackUsage(params: {
367
- customerRef: string;
368
- actionType?: 'transaction' | 'api_call' | 'hour' | 'email' | 'storage' | 'custom';
369
- units?: number;
370
- outcome?: 'success' | 'paywall' | 'fail';
371
- productRef?: string;
372
- purchaseRef?: string;
373
- description?: string;
374
- metadata?: Record<string, unknown>;
375
- duration?: number;
376
- timestamp?: string;
377
- idempotencyKey?: string;
378
- }): Promise<void>;
379
- /**
380
- * Create a new customer in SolvaPay backend.
381
- *
382
- * Note: `ensureCustomer()` is usually preferred as it's idempotent.
383
- * Use this only if you need explicit control over customer creation.
384
- *
385
- * @param params - Customer creation parameters
386
- * @param params.email - Customer email address (required)
387
- * @param params.name - Optional customer name
388
- * @returns Created customer reference
389
- *
390
- * @example
391
- * ```typescript
392
- * const { customerRef } = await solvaPay.createCustomer({
393
- * email: 'user@example.com',
394
- * name: 'John Doe'
395
- * });
396
- * ```
397
- */
398
- createCustomer(params: {
399
- email: string;
400
- name?: string;
401
- metadata?: Record<string, unknown>;
402
- }): Promise<{
403
- customerRef: string;
404
- }>;
405
- /**
406
- * Get customer details including purchases and usage.
407
- *
408
- * Returns full customer information from the SolvaPay backend, including
409
- * all active purchases, usage history, and customer metadata.
410
- *
411
- * @param params - Customer lookup parameters
412
- * @param params.customerRef - Optional customer reference (SolvaPay ID)
413
- * @param params.externalRef - Optional external reference (e.g., Supabase ID)
414
- * @returns Customer details with purchases and metadata
415
- *
416
- * @example
417
- * ```typescript
418
- * // Lookup by SolvaPay customer ID
419
- * const customer = await solvaPay.getCustomer({
420
- * customerRef: 'cust_123'
421
- * });
422
- *
423
- * // Lookup by external ID (e.g. Supabase user ID)
424
- * const customer = await solvaPay.getCustomer({
425
- * externalRef: 'user_123'
426
- * });
427
- * ```
428
- */
429
- getCustomer(params: {
430
- customerRef?: string;
431
- externalRef?: string;
432
- }): Promise<CustomerResponseMapped>;
433
- /**
434
- * Create a hosted checkout session for a customer.
435
- *
436
- * This creates a Stripe Checkout session that redirects the customer
437
- * to a hosted payment page. After payment, customer is redirected back.
438
- *
439
- * @param params - Checkout session parameters
440
- * @param params.productRef - Product reference
441
- * @param params.customerRef - Customer reference
442
- * @param params.planRef - Optional plan reference (if not specified, shows plan selector)
443
- * @param params.returnUrl - URL to redirect to after successful payment
444
- * @returns Checkout session with redirect URL
445
- *
446
- * @example
447
- * ```typescript
448
- * const session = await solvaPay.createCheckoutSession({
449
- * productRef: 'prd_myapi',
450
- * customerRef: 'user_123',
451
- * planRef: 'pln_premium',
452
- * returnUrl: 'https://myapp.com/success'
453
- * });
454
- *
455
- * // Redirect customer to checkout
456
- * window.location.href = session.checkoutUrl;
457
- * ```
458
- */
459
- createCheckoutSession(params: {
460
- productRef: string;
461
- customerRef: string;
462
- planRef?: string;
463
- returnUrl?: string;
464
- }): Promise<{
465
- sessionId: string;
466
- checkoutUrl: string;
467
- }>;
468
- /**
469
- * Create a customer portal session for managing purchases.
470
- *
471
- * This creates a Stripe Customer Portal session that allows customers
472
- * to manage their purchases, update payment methods, and view invoices.
473
- *
474
- * @param params - Customer session parameters
475
- * @param params.customerRef - Customer reference
476
- * @param params.productRef - Optional product reference for scoping portal view
477
- * @returns Customer portal session with redirect URL
478
- *
479
- * @example
480
- * ```typescript
481
- * const session = await solvaPay.createCustomerSession({
482
- * customerRef: 'user_123'
483
- * });
484
- *
485
- * // Redirect customer to portal
486
- * window.location.href = session.customerUrl;
487
- * ```
488
- */
489
- createCustomerSession(params: {
490
- customerRef: string;
491
- productRef?: string;
492
- }): Promise<{
493
- sessionId: string;
494
- customerUrl: string;
495
- }>;
496
- /**
497
- * Bootstrap an MCP-enabled product with plans and tool mappings.
498
- *
499
- * This helper wraps the backend orchestration endpoint and is intended for
500
- * fast setup flows where you want one call for product + plans + MCP config.
501
- */
502
- bootstrapMcpProduct(params: McpBootstrapRequest): Promise<McpBootstrapResponse>;
503
- /**
504
- * Configure MCP plans and tool mappings for an existing MCP product.
505
- *
506
- * This helper wraps the backend MCP plans endpoint and supports adding/removing
507
- * paid plans as well as remapping tool access.
508
- */
509
- configureMcpPlans(productRef: string, params: ConfigureMcpPlansRequest): Promise<ConfigureMcpPlansResponse>;
510
- /**
511
- * Get virtual tool definitions with bound handlers for MCP server integration.
512
- *
513
- * Returns an array of tool objects (name, description, inputSchema, handler)
514
- * that provide self-service capabilities: user info, upgrade, and account management.
515
- * These tools bypass the paywall and are not usage-tracked.
516
- *
517
- * Register the returned tools on your MCP server alongside your own tools.
518
- *
519
- * @param options - Virtual tools configuration
520
- * @param options.product - Product reference (required)
521
- * @param options.getCustomerRef - Function to extract customer ref from tool args
522
- * @param options.exclude - Optional list of tool names to exclude
523
- * @returns Array of virtual tool definitions with handlers
524
- *
525
- * @example
526
- * ```typescript
527
- * const virtualTools = solvaPay.getVirtualTools({
528
- * product: 'prd_myapi',
529
- * getCustomerRef: (_args, extra) => String(extra?.authInfo?.extra?.customer_ref || 'anonymous'),
530
- * });
531
- *
532
- * // Register on your MCP server
533
- * for (const tool of virtualTools) {
534
- * // Add to tools/list and tools/call handlers
535
- * }
536
- * ```
537
- */
538
- getVirtualTools(options: VirtualToolsOptions): VirtualToolDefinition[];
539
- /**
540
- * Register virtual tools directly on an MCP server with one call.
541
- *
542
- * This helper converts virtual tool JSON schemas to Zod schemas and registers
543
- * each tool on an MCP server that supports `registerTool()`.
544
- */
545
- registerVirtualToolsMcp(server: McpServerLike, options: RegisterVirtualToolsMcpOptions): Promise<void>;
546
- /**
547
- * Direct access to the API client for advanced operations.
548
- *
549
- * Use this for operations not exposed by the SolvaPay interface,
550
- * such as product/plan management or custom API calls.
551
- *
552
- * @example
553
- * ```typescript
554
- * // Access API client directly for custom operations
555
- * const products = await solvaPay.apiClient.listProducts();
556
- * ```
557
- */
558
- apiClient: SolvaPayClient;
559
- }
560
- /**
561
- * Create a SolvaPay instance with paywall protection capabilities.
562
- *
563
- * This factory function creates a SolvaPay instance that can be used to
564
- * protect API endpoints, functions, and MCP tools with usage limits and
565
- * purchase checks.
566
- *
567
- * @param config - Optional configuration object
568
- * @param config.apiKey - API key for production use (defaults to `SOLVAPAY_SECRET_KEY` env var)
569
- * @param config.apiClient - Custom API client for testing or advanced use cases
570
- * @param config.apiBaseUrl - Optional API base URL override
571
- * @returns SolvaPay instance with payable() method and API client access
572
- *
573
- * @example
574
- * ```typescript
575
- * // Production: Use environment variable (recommended)
576
- * const solvaPay = createSolvaPay();
577
- *
578
- * // Production: Pass API key explicitly
579
- * const solvaPay = createSolvaPay({
580
- * apiKey: process.env.SOLVAPAY_SECRET_KEY
581
- * });
582
- *
583
- * // Testing: Use mock client
584
- * const solvaPay = createSolvaPay({
585
- * apiClient: mockClient
586
- * });
587
- *
588
- * // Create payable handlers for your product
589
- * const payable = solvaPay.payable({
590
- * product: 'prd_myapi',
591
- * plan: 'pln_premium'
592
- * });
593
- *
594
- * // Protect endpoints with framework-specific adapters
595
- * app.post('/tasks', payable.http(createTask)); // Express/Fastify
596
- * export const POST = payable.next(createTask); // Next.js App Router
597
- * const handler = payable.mcp(createTask); // MCP servers
598
- * ```
599
- *
600
- * @see {@link SolvaPay} for the returned instance interface
601
- * @see {@link CreateSolvaPayConfig} for configuration options
602
- * @since 1.0.0
603
- */
604
- export declare function createSolvaPay(config?: CreateSolvaPayConfig): SolvaPay;
605
- //# sourceMappingURL=factory.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/factory.ts"],"names":[],"mappings":"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"}