@alleyboss/micropay-solana-x402-paywall 2.0.1 β†’ 2.0.2

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 (2) hide show
  1. package/README.md +63 -115
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,165 +1,113 @@
1
1
  # @alleyboss/micropay-solana-x402-paywall
2
2
 
3
- > Production-ready Solana micropayments library implementing the x402 protocol with SPL token support.
3
+ > Production-ready Solana micropayments library implementing the x402 protocol.
4
4
 
5
- [![npm version](https://img.shields.io/npm/v/@alleyboss/micropay-solana-x402-paywall)](https://www.npmjs.com/package/@alleyboss/micropay-solana-x402-paywall)
5
+ [![npm](https://img.shields.io/npm/v/@alleyboss/micropay-solana-x402-paywall)](https://www.npmjs.com/package/@alleyboss/micropay-solana-x402-paywall)
6
6
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
7
+ [![Bundle Size](https://img.shields.io/badge/bundle-38KB-green)](https://bundlephobia.com/package/@alleyboss/micropay-solana-x402-paywall)
7
8
 
8
- ## Features
9
+ ## πŸš€ What It Does
9
10
 
10
- - πŸ” **x402 Protocol** β€” HTTP 402 Payment Required standard
11
- - ⚑ **Solana Native** β€” Fast, low-cost SOL & USDC micropayments
12
- - πŸ”‘ **JWT Sessions** β€” Secure unlock tracking with anti-replay
13
- - πŸ“¦ **Framework Agnostic** β€” Express, Next.js, Fastify ready
14
- - 🌳 **Tree-shakeable** β€” Import only what you need (35KB full, 1-13KB per module)
15
- - πŸ’° **SPL Tokens** β€” USDC, USDT, and custom token support
16
- - πŸ”„ **Retry Logic** β€” Built-in resilience for RPC failures
17
-
18
- ## Installation
11
+ Turn any content into paid content with **one-time micropayments** on Solana. No subscriptions, no recurring chargesβ€”just pay to unlock.
19
12
 
20
13
  ```bash
21
14
  npm install @alleyboss/micropay-solana-x402-paywall @solana/web3.js
22
15
  ```
23
16
 
24
- ## Quick Start
17
+ ## ✨ Features
18
+
19
+ | Feature | Description |
20
+ |---------|-------------|
21
+ | πŸ’° **SOL & USDC Payments** | Native SOL and SPL tokens (USDC, USDT) |
22
+ | πŸ” **x402 Protocol** | HTTP 402 Payment Required standard |
23
+ | πŸ”‘ **JWT Sessions** | Secure unlock tracking with anti-replay |
24
+ | �️ **Signature Store** | Prevent double-spend at app layer |
25
+ | πŸ”Œ **Express & Next.js** | Zero-boilerplate middleware |
26
+ | οΏ½ **Price Conversion** | USD↔SOL with multi-provider fallback |
27
+ | 🌳 **Tree-Shakeable** | Import only what you need |
25
28
 
26
- ### Verify a Payment (SOL or USDC)
29
+ ## πŸ“¦ Quick Example
27
30
 
28
31
  ```typescript
29
- import { verifyPayment, verifySPLPayment } from '@alleyboss/micropay-solana-x402-paywall';
32
+ import { verifyPayment, createSession } from '@alleyboss/micropay-solana-x402-paywall';
30
33
 
31
- // SOL payment
34
+ // Verify on-chain payment
32
35
  const result = await verifyPayment({
33
36
  signature: 'tx...',
34
37
  expectedRecipient: 'CreatorWallet',
35
38
  expectedAmount: 10_000_000n, // 0.01 SOL
36
- clientConfig: { network: 'devnet' },
37
- });
38
-
39
- // USDC payment
40
- const usdcResult = await verifySPLPayment({
41
- signature: 'tx...',
42
- expectedRecipient: 'CreatorWallet',
43
- expectedAmount: 1_000_000n, // 1 USDC
44
- asset: 'usdc',
45
39
  clientConfig: { network: 'mainnet-beta' },
46
40
  });
47
- ```
48
-
49
- ### Express Middleware (Zero Boilerplate)
50
41
 
51
- ```typescript
52
- import express from 'express';
53
- import { createExpressMiddleware } from '@alleyboss/micropay-solana-x402-paywall/middleware';
54
-
55
- const app = express();
56
-
57
- app.use('/api/premium', createExpressMiddleware({
58
- sessionSecret: process.env.SESSION_SECRET!,
59
- protectedPaths: ['/**'],
60
- }));
61
-
62
- app.get('/api/premium/content', (req, res) => {
63
- res.json({ content: 'Premium!', wallet: req.session?.walletAddress });
64
- });
42
+ // Create session for unlocked content
43
+ if (result.valid) {
44
+ const { token } = await createSession(
45
+ result.from!,
46
+ 'article-123',
47
+ { secret: process.env.SESSION_SECRET!, durationHours: 24 }
48
+ );
49
+ }
65
50
  ```
66
51
 
67
- ### Next.js Middleware
68
-
69
- ```typescript
70
- // middleware.ts
71
- import { createPaywallMiddleware } from '@alleyboss/micropay-solana-x402-paywall/middleware';
72
-
73
- export const middleware = createPaywallMiddleware({
74
- sessionSecret: process.env.SESSION_SECRET!,
75
- protectedPaths: ['/api/premium/*', '/api/content/*'],
76
- });
77
-
78
- export const config = { matcher: ['/api/premium/:path*'] };
79
- ```
52
+ ## πŸ”§ Modules
80
53
 
81
- ### Prevent Signature Replay (Anti-Double-Spend)
54
+ 9 tree-shakeable entry points for minimal bundle size:
82
55
 
83
56
  ```typescript
84
- import { createMemoryStore, createRedisStore } from '@alleyboss/micropay-solana-x402-paywall/store';
85
-
86
- // Development
87
- const store = createMemoryStore();
57
+ // Core verification
58
+ import { verifyPayment, verifySPLPayment } from '@alleyboss/micropay-solana-x402-paywall/solana';
88
59
 
89
- // Production (with ioredis or node-redis)
90
- const store = createRedisStore({ client: redisClient });
91
-
92
- // Check before verification
93
- if (await store.hasBeenUsed(signature)) {
94
- throw new Error('Payment already used');
95
- }
60
+ // Session management
61
+ import { createSession, validateSession } from '@alleyboss/micropay-solana-x402-paywall/session';
96
62
 
97
- // Mark after successful verification
98
- await store.markAsUsed(signature, articleId, new Date(Date.now() + 86400000));
99
- ```
63
+ // x402 protocol
64
+ import { buildPaymentRequirement } from '@alleyboss/micropay-solana-x402-paywall/x402';
100
65
 
101
- ### Client-Side Payment Flow
66
+ // Express/Next.js middleware
67
+ import { createExpressMiddleware, createPaywallMiddleware } from '@alleyboss/micropay-solana-x402-paywall/middleware';
102
68
 
103
- ```typescript
104
- import { createPaymentFlow, formatPriceDisplay } from '@alleyboss/micropay-solana-x402-paywall';
69
+ // Anti-replay signature store
70
+ import { createMemoryStore, createRedisStore } from '@alleyboss/micropay-solana-x402-paywall/store';
105
71
 
106
- const flow = createPaymentFlow({
107
- network: 'mainnet-beta',
108
- recipientWallet: 'CreatorWallet',
109
- amount: 10_000_000n,
110
- });
72
+ // Client-side helpers
73
+ import { createPaymentFlow, buildSolanaPayUrl } from '@alleyboss/micropay-solana-x402-paywall/client';
111
74
 
112
- // Generate QR code for mobile wallets
113
- const qrUrl = flow.getSolanaPayUrl({ label: 'Unlock Article' });
75
+ // Price conversion (4-provider rotation)
76
+ import { getSolPrice, formatPriceDisplay, configurePricing } from '@alleyboss/micropay-solana-x402-paywall/pricing';
114
77
 
115
- // Display price with USD equivalent
116
- const price = await formatPriceDisplay(10_000_000n);
117
- // "0.0100 SOL (~$1.50)"
78
+ // Retry utilities
79
+ import { withRetry } from '@alleyboss/micropay-solana-x402-paywall/utils';
118
80
  ```
119
81
 
120
- ## Module Exports
121
-
122
- Import only what you need for minimal bundle size:
82
+ ## πŸ”₯ New in v2.0
123
83
 
124
- | Import Path | Size | Functions |
125
- |-------------|------|-----------|
126
- | `@.../solana` | 13KB | `verifyPayment`, `verifySPLPayment`, `getConnection` |
127
- | `@.../session` | 4.5KB | `createSession`, `validateSession`, `isArticleUnlocked` |
128
- | `@.../x402` | 10KB | `buildPaymentRequirement`, `verifyX402Payment` |
129
- | `@.../middleware` | 8KB | `createExpressMiddleware`, `createPaywallMiddleware` |
130
- | `@.../store` | 2.6KB | `createMemoryStore`, `createRedisStore` |
131
- | `@.../client` | 3.3KB | `createPaymentFlow`, `buildSolanaPayUrl` |
132
- | `@.../pricing` | 2KB | `getSolPrice`, `formatPriceDisplay` |
133
- | `@.../utils` | 1.7KB | `withRetry`, `isRetryableRPCError` |
84
+ - **SPL Token Support** β€” USDC, USDT, custom tokens
85
+ - **Multi-Provider Pricing** β€” CoinCap β†’ Binance β†’ CoinGecko β†’ Kraken fallback
86
+ - **Custom Price API** β€” `configurePricing({ customProvider: yourFn })`
87
+ - **Express Middleware** β€” Works with Express, Fastify, Polka
88
+ - **Signature Store** β€” Memory & Redis adapters for anti-replay
89
+ - **Client Helpers** β€” Solana Pay URLs for QR codes
134
90
 
135
- ## TypeScript Support
91
+ ## πŸ“š Documentation
136
92
 
137
- Full TypeScript with exported types:
93
+ **Full documentation, API reference, and examples:**
138
94
 
139
- ```typescript
140
- import type {
141
- PaymentRequirement,
142
- PaymentAsset,
143
- SessionData,
144
- SignatureStore,
145
- PaywallMiddlewareConfig,
146
- } from '@alleyboss/micropay-solana-x402-paywall';
147
- ```
95
+ πŸ‘‰ **[solana-x402-paywall.vercel.app/docs](https://solana-x402-paywall.vercel.app/docs)**
148
96
 
149
- ## RPC Configuration
97
+ ## πŸ› οΈ RPC Providers
150
98
 
151
- Supports multiple RPC providers:
99
+ Works with any Solana RPC provider:
152
100
 
153
101
  ```typescript
154
- const clientConfig = {
102
+ const config = {
155
103
  network: 'mainnet-beta',
156
- // Option 1: Tatum.io
157
- tatumApiKey: 'your-api-key',
158
- // Option 2: Custom RPC (Helius, QuickNode, etc.)
159
- rpcUrl: 'https://your-rpc-endpoint.com',
104
+ // Tatum.io
105
+ tatumApiKey: 'your-key',
106
+ // Or custom (Helius, QuickNode, etc.)
107
+ rpcUrl: 'https://your-rpc.com',
160
108
  };
161
109
  ```
162
110
 
163
- ## License
111
+ ## πŸ“„ License
164
112
 
165
113
  MIT Β© AlleyBoss
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alleyboss/micropay-solana-x402-paywall",
3
- "version": "2.0.1",
3
+ "version": "2.0.2",
4
4
  "description": "Production-ready Solana micropayments library implementing x402 protocol with SPL token support",
5
5
  "author": "AlleyBoss",
6
6
  "license": "MIT",