{"_id":"@aipp/satsgate-vercel-ai","name":"@aipp/satsgate-vercel-ai","dist-tags":{"latest":"0.2.0"},"versions":{"0.2.0":{"name":"@aipp/satsgate-vercel-ai","version":"0.2.0","description":"Vercel AI SDK integration for satsgate — L402 paywalled AI endpoints","type":"module","main":"dist/src/index.js","types":"dist/src/index.d.ts","exports":{".":{"types":"./dist/src/index.d.ts","import":"./dist/src/index.js"}},"scripts":{"build":"tsc","test":"node --test dist/tests/test_middleware.js","prepublishOnly":"npm run build"},"keywords":["vercel","ai-sdk","satsgate","l402","paywall","lightning"],"license":"MIT","engines":{"node":">=18"},"peerDependencies":{"ai":">=4.0.0"},"peerDependenciesMeta":{"ai":{"optional":true}},"devDependencies":{"typescript":"^5.4.0","@types/node":"^20.0.0","ai":"^4.0.0"},"_id":"@aipp/satsgate-vercel-ai@0.2.0","gitHead":"31222addf3639c355a351c4709b02822078342b6","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-F78PHC7mIMCYj7/8V+Ki292rqprenFySkxhmIu6fFqtlIgiyun+aJ3GfPaQoO8/79EAEYlHJUB33LKAoe5iTeQ==","shasum":"752386a38d070a3fbf00475c8d760e03c4cfa7e4","tarball":"https://registry.npmjs.org/@aipp/satsgate-vercel-ai/-/satsgate-vercel-ai-0.2.0.tgz","fileCount":26,"unpackedSize":53087,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFFrO4lknxA9GaNQGfe7XOD17RHeSidZL3YgMHv7N1ZKAiB/n47hRalCtEbLD9Mqd8L+3AjWjbCxt6rLfII4hS4k8A=="}]},"_npmUser":{"name":"aipp","email":"farukucal@gmail.com"},"directories":{},"maintainers":[{"name":"aipp","email":"farukucal@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/satsgate-vercel-ai_0.2.0_1781978890777_0.1838834128220619"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-20T18:08:10.663Z","0.2.0":"2026-06-20T18:08:10.916Z","modified":"2026-06-20T18:08:11.078Z"},"maintainers":[{"name":"aipp","email":"farukucal@gmail.com"}],"description":"Vercel AI SDK integration for satsgate — L402 paywalled AI endpoints","keywords":["vercel","ai-sdk","satsgate","l402","paywall","lightning"],"license":"MIT","readme":"# @satsgate/vercel-ai\n\nVercel AI SDK integration for [satsgate](https://aipp.dev) -- add L402 Lightning paywall protection to your AI endpoints in minutes.\n\n## Features\n\n- **Paywall middleware** -- protect Next.js / Vercel AI SDK routes with L402 Lightning payments\n- **Tool helpers** -- expose satsgate balance checks and challenge creation as Vercel AI SDK tools for tool-calling models\n- **Edge-compatible** -- uses standard Web `Request` / `Response` API (works on Vercel Edge, Cloudflare Workers, Deno Deploy, etc.)\n- **Zero runtime dependencies** -- `ai` is a peer dependency, so you only install what you use\n- **Built-in verification cache** -- avoids redundant network calls for repeat requests\n\n## Installation\n\n```bash\nnpm install @satsgate/vercel-ai ai\n```\n\n> `ai` (the Vercel AI SDK) is a peer dependency and must be installed separately.\n\n## Quick Start\n\n### 1. Protect an API route with the paywall middleware\n\n```typescript\n// app/api/chat/route.ts  (Next.js App Router)\nimport { satsgatePaywallMiddleware } from '@satsgate/vercel-ai';\nimport { streamText } from 'ai';\nimport { openai } from '@ai-sdk/openai';\n\nconst paywall = satsgatePaywallMiddleware({\n  apiKey: process.env.SATSGATE_API_KEY!,\n  resource: 'ai/chat',\n  amountSats: 10,\n  costCredits: 1,\n});\n\nexport async function POST(request: Request) {\n  // Run the paywall check\n  const blocked = await paywall(request);\n  if (blocked) return blocked; // 402 or error response\n\n  // Request is paid -- proceed with AI logic\n  const { messages } = await request.json();\n  const result = streamText({\n    model: openai('gpt-4o'),\n    messages,\n  });\n\n  return result.toDataStreamResponse();\n}\n```\n\n### 2. Use satsgate tools with tool-calling models\n\n```typescript\nimport { generateText } from 'ai';\nimport { openai } from '@ai-sdk/openai';\nimport { createPaywallTool } from '@satsgate/vercel-ai';\n\nconst tools = createPaywallTool({\n  apiKey: process.env.SATSGATE_API_KEY!,\n});\n\nconst result = await generateText({\n  model: openai('gpt-4o'),\n  tools: {\n    checkBalance: tools.checkBalance,\n    createChallenge: tools.createChallenge,\n    verifyPayment: tools.verifyPayment,\n  },\n  prompt: 'Check my satsgate balance',\n});\n\nconsole.log(result.text);\n```\n\n## API Reference\n\n### `satsgatePaywallMiddleware(options)`\n\nCreates a middleware handler function that enforces L402 payment on incoming requests.\n\n**Options:**\n\n| Option        | Type       | Default                  | Description                                  |\n|---------------|------------|--------------------------|----------------------------------------------|\n| `apiKey`      | `string`   | *(required)*             | Your satsgate API key                        |\n| `baseUrl`     | `string`   | `https://api.aipp.dev`   | Satsgate API base URL                        |\n| `resource`    | `string`   | `\"ai/chat\"`              | Resource identifier for the paywall          |\n| `amountSats`  | `number`   | `10`                     | Challenge amount in satoshis                 |\n| `costCredits` | `number`   | `1`                      | Credits charged per verification             |\n| `paths`       | `string[]` | *(all paths)*            | Paths to protect (glob patterns)             |\n\n**Returns:** `async (request: Request) => Response | null`\n\n- Returns `null` when the request is authorized (let it proceed).\n- Returns a `Response` (402 or error) when the request should be blocked.\n\n### `createPaywallTool(config)`\n\nCreates Vercel AI SDK tool definitions for satsgate operations.\n\n**Config:**\n\n| Option    | Type     | Default                | Description           |\n|-----------|----------|------------------------|-----------------------|\n| `apiKey`  | `string` | *(required)*           | Your satsgate API key |\n| `baseUrl` | `string` | `https://api.aipp.dev` | Satsgate API base URL |\n\n**Returns:** An object with three tools:\n\n| Tool              | Description                                        |\n|-------------------|----------------------------------------------------|\n| `checkBalance`    | Query the current credit balance                   |\n| `createChallenge` | Generate an L402 Lightning invoice challenge       |\n| `verifyPayment`   | Verify an L402 authorization header                |\n\n### `SatsgateClient`\n\nLow-level HTTP client for direct satsgate API access.\n\n```typescript\nimport { SatsgateClient } from '@satsgate/vercel-ai';\n\nconst client = new SatsgateClient('https://api.aipp.dev', 'sg_...');\n\nconst challenge = await client.paywallChallenge('ai/chat', 10);\nconst verification = await client.paywallVerify(authHeader, 'ai/chat');\nconst balance = await client.balance();\n```\n\n## How the L402 Flow Works\n\n```\nClient                          Your Server                    Satsgate API\n  |                                 |                               |\n  |  POST /api/chat (no auth)       |                               |\n  |-------------------------------->|                               |\n  |                                 |  POST /v1/paywall/challenge   |\n  |                                 |------------------------------->|\n  |                                 |  { invoice, macaroon, ... }   |\n  |                                 |<-------------------------------|\n  |  402 Payment Required           |                               |\n  |  { invoice, macaroon, ... }     |                               |\n  |<--------------------------------|                               |\n  |                                                                 |\n  |  [Client pays the Lightning invoice]                            |\n  |  [Client receives the preimage]                                 |\n  |                                                                 |\n  |  POST /api/chat                 |                               |\n  |  Authorization: L402 <mac>:<pre>|                               |\n  |-------------------------------->|                               |\n  |                                 |  POST /v1/paywall/verify      |\n  |                                 |------------------------------->|\n  |                                 |  { ok: true, ... }            |\n  |                                 |<-------------------------------|\n  |  200 OK (AI response)           |                               |\n  |<--------------------------------|                               |\n```\n\n1. The client sends a request to your paywalled endpoint.\n2. If no `Authorization` header is present, the middleware creates a challenge via satsgate and returns a `402` with a Lightning invoice.\n3. The client pays the invoice off-chain and receives a preimage.\n4. The client retries the request with `Authorization: L402 <macaroon>:<preimage>`.\n5. The middleware verifies the token with satsgate. On success, the request proceeds to your handler.\n6. Verified payment hashes are cached in-memory to avoid re-verification within the validity window.\n\n## TypeScript\n\nThis package is written in TypeScript and ships with full type declarations.\n\n```typescript\nimport type {\n  SatsgateMiddlewareOptions,\n  PaywallToolConfig,\n  Challenge,\n  VerifyResult,\n  SatsgateError,\n} from '@satsgate/vercel-ai';\n```\n\n## Requirements\n\n- Node.js >= 18\n- Vercel AI SDK (`ai`) >= 4.0.0 (optional, only if using tool helpers)\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-9cbf00a156af6770fbb59661acf1cc77"}