@xcript-dev/next 0.1.1 → 0.1.2

package/README.md

@@ -0,0 +1,129 @@
+# @xcript-dev/next
+
+> Next.js integration for [Xcript](https://xcript.dev) — middleware, React hooks, and server utilities for license validation.
+
+[![npm](https://img.shields.io/npm/v/@xcript-dev/next)](https://www.npmjs.com/package/@xcript-dev/next)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/@xcript-dev/next)](https://bundlephobia.com/package/@xcript-dev/next)
+[![license](https://img.shields.io/npm/l/@xcript-dev/next)](https://github.com/xcript/xcript-js/blob/main/LICENSE)
+
+## Install
+
+```bash
+npm install @xcript-dev/next
+```
+
+## 1. Middleware — Protect Routes
+
+```typescript
+// middleware.ts
+import { withXcript } from '@xcript-dev/next'
+
+export default withXcript({
+  apiKey: process.env.XCRIPT_API_KEY!,
+  licenseKey: process.env.XCRIPT_LICENSE_KEY!,
+  protectedRoutes: ['/dashboard/*', '/api/*'],
+  onInvalid: '/license-expired',
+})
+
+export const config = {
+  matcher: ['/dashboard/:path*', '/api/:path*'],
+}
+```
+
+Validates once, caches in a cookie, re-validates every 5 minutes. If invalid → redirects to `onInvalid`.
+
+## 2. React Hook — Conditional UI
+
+```tsx
+'use client'
+import { useLicense } from '@xcript-dev/next/client'
+
+function PremiumFeature() {
+  const { isValid, config, isLoading } = useLicense()
+
+  if (isLoading) return <Spinner />
+  if (!isValid) return <UpgradePrompt />
+
+  return <PremiumContent maxUsers={config.max_users} />
+}
+```
+
+## 3. Provider — Wrap Your Layout
+
+```tsx
+// app/layout.tsx
+import { XcriptProvider } from '@xcript-dev/next/client'
+
+export default function Layout({ children }) {
+  return <XcriptProvider>{children}</XcriptProvider>
+}
+```
+
+## 4. Server Utilities — Protect Actions
+
+```typescript
+// Server Action or Route Handler
+import { requireLicense } from '@xcript-dev/next/server'
+
+export async function POST() {
+  const license = await requireLicense()  // Throws if invalid
+  const maxReports = license.config['max_reports']
+  return Response.json({ ok: true })
+}
+```
+
+### Other server utilities
+
+```typescript
+import { getLicense, getLicenseConfig } from '@xcript-dev/next/server'
+
+// Returns null if invalid (no throw)
+const license = await getLicense()
+
+// Get a single config value
+const maxUsers = await getLicenseConfig('max_users')
+```
+
+## Middleware Options
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `apiKey` | `string` | ✅ | — | Your API key (`xk_...`) |
+| `licenseKey` | `string` | ✅ | — | License key to validate |
+| `publicKey` | `string` | — | — | Ed25519 public key (hex) |
+| `protectedRoutes` | `string[]` | — | All routes | Glob patterns (`*` wildcard) |
+| `onInvalid` | `string` | — | Returns 403 | Redirect path on failure |
+| `revalidateInterval` | `number` | — | `300` (5 min) | Re-validation interval in seconds |
+
+## Environment Variables
+
+```env
+XCRIPT_API_KEY=xk_your_api_key
+XCRIPT_LICENSE_KEY=XCR-XXXX-XXXX-XXXX
+```
+
+## How It Works
+
+```
+Request → Middleware checks cookie
+  ├── Cookie valid + fresh → Pass through ✅
+  ├── Cookie expired → Re-validate against API
+  │   ├── Valid → Update cookie, pass through ✅
+  │   └── Invalid → Redirect to onInvalid ❌
+  └── No cookie → Validate against API
+      ├── Valid → Set cookie, pass through ✅
+      └── Invalid → Redirect to onInvalid ❌
+```
+
+## Requirements
+
+- Next.js ≥ 14
+- React ≥ 18
+
+## Core SDK
+
+This package uses [`@xcript-dev/sdk`](https://www.npmjs.com/package/@xcript-dev/sdk) under the hood. For non-Next.js projects, install the SDK directly.
+
+## License
+
+MIT — [xcript.dev](https://xcript.dev)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@xcript-dev/next",
-    "version": "0.1.1",
+    "version": "0.1.2",
     "description": "Next.js integration for Xcript — middleware, hooks, and server utilities for license validation",
     "main": "./dist/index.js",
     "module": "./dist/index.mjs",