npm - @usequota/nextjs - Versions diffs - 0.1.0 - Mend

@usequota/nextjs 0.1.0

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 (19) hide show

package/README.md +462 -0
package/dist/chunk-BMI3VFWV.mjs +120 -0
package/dist/chunk-RSPDHXC2.mjs +119 -0
package/dist/chunk-SJ3X4KTV.mjs +117 -0
package/dist/chunk-ZF7WJBQC.mjs +114 -0
package/dist/errors-CmNx3kSz.d.mts +109 -0
package/dist/errors-CmNx3kSz.d.ts +109 -0
package/dist/errors-DVurmYT7.d.mts +109 -0
package/dist/errors-DVurmYT7.d.ts +109 -0
package/dist/index.d.mts +585 -0
package/dist/index.d.ts +585 -0
package/dist/index.js +1079 -0
package/dist/index.mjs +968 -0
package/dist/server.d.mts +477 -0
package/dist/server.d.ts +477 -0
package/dist/server.js +1068 -0
package/dist/server.mjs +916 -0
package/dist/styles.css +439 -0
package/package.json +69 -0

package/README.md ADDED Viewed

@@ -0,0 +1,462 @@
+# @usequota/nextjs
+Next.js SDK for [Quota](https://quota.io) - AI credit wallet and multi-provider inference API.
+## Installation
+```bash
+npm install @usequota/nextjs
+```
+## Quick Start
+### 1. Set up environment variables
+```env
+# .env.local
+QUOTA_CLIENT_ID=your_client_id
+QUOTA_CLIENT_SECRET=your_client_secret
+NEXT_PUBLIC_QUOTA_CLIENT_ID=your_client_id
+```
+### 2. Configure middleware
+Create `middleware.ts` in your project root:
+```typescript
+import { createQuotaMiddleware } from "@usequota/nextjs";
+export const middleware = createQuotaMiddleware({
+  clientId: process.env.QUOTA_CLIENT_ID!,
+  clientSecret: process.env.QUOTA_CLIENT_SECRET!,
+});
+export const config = {
+  matcher: "/api/quota/callback",
+};
+```
+### 3. Add QuotaProvider
+Wrap your app with the provider in `app/layout.tsx`:
+```tsx
+import { QuotaProvider } from "@usequota/nextjs";
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <QuotaProvider clientId={process.env.NEXT_PUBLIC_QUOTA_CLIENT_ID!}>
+          {children}
+        </QuotaProvider>
+      </body>
+    </html>
+  );
+}
+```
+### 4. Create API routes
+Create the following API routes:
+**`app/api/quota/me/route.ts`** - Fetch user data:
+```typescript
+import { getQuotaUser } from "@usequota/nextjs/server";
+export async function GET() {
+  const user = await getQuotaUser({
+    clientId: process.env.QUOTA_CLIENT_ID!,
+    clientSecret: process.env.QUOTA_CLIENT_SECRET!,
+  });
+  if (!user) {
+    return new Response("Unauthorized", { status: 401 });
+  }
+  return Response.json(user);
+}
+```
+**`app/api/quota/logout/route.ts`** - Handle logout:
+```typescript
+import { clearQuotaAuth } from "@usequota/nextjs/server";
+export async function POST() {
+  await clearQuotaAuth();
+  return Response.json({ success: true });
+}
+```
+### 5. Use in components
+```tsx
+"use client";
+import { useQuota } from "@usequota/nextjs";
+export function MyComponent() {
+  const { user, isLoading, login } = useQuota();
+  if (isLoading) return <div>Loading...</div>;
+  if (!user) return <button onClick={login}>Sign in with Quota</button>;
+  return (
+    <div>
+      <p>Welcome, {user.email}!</p>
+      <p>Balance: {user.balance} credits</p>
+    </div>
+  );
+}
+```
+## Features
+- **OAuth 2.0 Authentication** - Secure user authentication flow
+- **Token Management** - Automatic token refresh and cookie management
+- **React Hooks** - Convenient hooks for auth state and user data
+- **Server-Side Utilities** - Functions for API routes and server components
+- **TypeScript Support** - Full type safety with TypeScript
+- **Hosted Mode** - Optional server-side token storage for enhanced security
+## API Reference
+### Client-Side
+#### Hooks
+- `useQuota()` - Access full Quota context
+- `useQuotaUser()` - Get current user
+- `useQuotaAuth()` - Auth state and actions
+- `useQuotaBalance()` - User credit balance
+#### Components
+- `<QuotaProvider>` - React context provider
+### Server-Side
+Import from `@usequota/nextjs/server`:
+- `getQuotaUser(config)` - Get authenticated user
+- `requireQuotaAuth(config)` - Require auth (redirects if not logged in)
+- `getQuotaPackages(config?)` - Fetch available credit packages
+- `createQuotaCheckout(config)` - Create Stripe checkout session
+- `clearQuotaAuth(config?)` - Clear auth cookies
+- `createQuotaRouteHandlers(config)` - Generate all 6 API route handlers in one call
+- `withQuotaAuth(config, handler)` - Wrap a route handler with automatic Quota auth
+#### Typed Errors
+- `QuotaError` - Base error class (`code`, `statusCode`, `hint`)
+- `QuotaInsufficientCreditsError` - 402, includes `balance` and `required`
+- `QuotaNotConnectedError` - 401, user has no Quota account connected
+- `QuotaTokenExpiredError` - 401, token expired and refresh failed
+- `QuotaRateLimitError` - 429, includes `retryAfter` (seconds)
+### Middleware
+- `createQuotaMiddleware(config)` - Create OAuth callback middleware
+## Storage Modes
+### Client Mode (Default)
+Tokens are stored in httpOnly cookies:
+```typescript
+export const middleware = createQuotaMiddleware({
+  clientId: process.env.QUOTA_CLIENT_ID!,
+  clientSecret: process.env.QUOTA_CLIENT_SECRET!,
+  storageMode: "client", // default
+});
+```
+### Hosted Mode
+Tokens stored server-side by Quota (more secure):
+```typescript
+export const middleware = createQuotaMiddleware({
+  clientId: process.env.QUOTA_CLIENT_ID!,
+  clientSecret: process.env.QUOTA_CLIENT_SECRET!,
+  storageMode: "hosted",
+  getExternalUserId: async (request) => {
+    // Return your user's ID from your auth system
+    const session = await getSession(request);
+    return session.userId;
+  },
+});
+```
+## Advanced Usage
+### Custom OAuth Flow
+```typescript
+const { login } = useQuota();
+// Trigger OAuth flow
+login();
+```
+### Server Components
+```tsx
+import { getQuotaUser } from "@usequota/nextjs/server";
+export default async function DashboardPage() {
+  const user = await getQuotaUser({
+    clientId: process.env.QUOTA_CLIENT_ID!,
+    clientSecret: process.env.QUOTA_CLIENT_SECRET!,
+  });
+  if (!user) {
+    redirect("/");
+  }
+  return <div>Welcome, {user.email}!</div>;
+}
+```
+### Protected Routes
+```tsx
+import { requireQuotaAuth } from "@usequota/nextjs/server";
+export default async function ProtectedPage() {
+  // Automatically redirects to login if not authenticated
+  const user = await requireQuotaAuth({
+    clientId: process.env.QUOTA_CLIENT_ID!,
+    clientSecret: process.env.QUOTA_CLIENT_SECRET!,
+  });
+  return <div>Protected content for {user.email}</div>;
+}
+```
+### Credit Packages
+```tsx
+"use client";
+import { useState, useEffect } from "react";
+import type { CreditPackage } from "@usequota/nextjs";
+export function BuyCredits() {
+  const [packages, setPackages] = useState<CreditPackage[]>([]);
+  useEffect(() => {
+    fetch("/api/packages")
+      .then((res) => res.json())
+      .then(setPackages);
+  }, []);
+  const handleBuy = async (packageId: string) => {
+    const res = await fetch("/api/checkout", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ packageId }),
+    });
+    const { url } = await res.json();
+    window.location.href = url;
+  };
+  return (
+    <div>
+      {packages.map((pkg) => (
+        <button key={pkg.id} onClick={() => handleBuy(pkg.id)}>
+          Buy {pkg.credits} credits for {pkg.price_display}
+        </button>
+      ))}
+    </div>
+  );
+}
+```
+### Webhook Verification
+Quota can send webhooks to notify your application about events. The SDK provides utilities to verify webhook signatures and handle events securely.
+#### Set up webhook endpoint
+Add your webhook secret to `.env.local`:
+```env
+QUOTA_WEBHOOK_SECRET=your_webhook_secret
+```
+#### Create webhook handler
+**`app/api/quota/webhook/route.ts`**:
+```typescript
+import { createWebhookHandler } from "@usequota/nextjs";
+export const POST = createWebhookHandler(process.env.QUOTA_WEBHOOK_SECRET!, {
+  "balance.low": async (event) => {
+    // Send email notification when user balance is low
+    await sendLowBalanceEmail(event.data.user_id, event.data.current_balance);
+  },
+  "user.connected": async (event) => {
+    // Track new user connection
+    await analytics.track("user_connected", event.data);
+  },
+  "usage.completed": async (event) => {
+    // Log usage for analytics
+    await logUsage(event.data);
+  },
+});
+```
+#### Webhook event types
+Quota sends the following webhook events:
+- `user.connected` - User completed OAuth connection
+- `user.disconnected` - User disconnected their account
+- `balance.updated` - User's credit balance changed
+- `balance.low` - User's balance fell below threshold
+- `usage.completed` - API request completed and billed
+#### Manual signature verification
+For custom implementations:
+```typescript
+import { verifyWebhookSignature, parseWebhook } from "@usequota/nextjs";
+export async function POST(req: Request) {
+  try {
+    // Option 1: Parse and verify in one step
+    const event = await parseWebhook(req, process.env.QUOTA_WEBHOOK_SECRET!);
+    // Option 2: Manual verification
+    const payload = await req.text();
+    const signature = req.headers.get("x-quota-signature")!;
+    const isValid = verifyWebhookSignature({
+      payload,
+      signature,
+      secret: process.env.QUOTA_WEBHOOK_SECRET!,
+    });
+    if (!isValid) {
+      return Response.json({ error: "Invalid signature" }, { status: 400 });
+    }
+    const event = JSON.parse(payload);
+    // Handle event...
+    return Response.json({ received: true });
+  } catch (error) {
+    return Response.json({ error: error.message }, { status: 400 });
+  }
+}
+```
+## Route Handler Factory
+`createQuotaRouteHandlers` generates all API route handlers for Quota integration in one call, replacing 6 separate route files with boilerplate.
+```typescript
+// lib/quota.ts
+import { createQuotaRouteHandlers } from "@usequota/nextjs/server";
+export const {
+  authorize, // GET - initiates OAuth flow
+  callback, // GET - handles OAuth callback
+  status, // GET - returns connection status + balance
+  packages, // GET - returns credit packages
+  checkout, // POST - creates Stripe checkout session
+  disconnect, // POST - disconnects user's Quota account
+} = createQuotaRouteHandlers({
+  clientId: process.env.QUOTA_CLIENT_ID!,
+  clientSecret: process.env.QUOTA_CLIENT_SECRET!,
+});
+```
+Then create thin route files:
+```typescript
+// app/api/quota/authorize/route.ts
+export { authorize as GET } from "@/lib/quota";
+// app/api/quota/callback/route.ts
+export { callback as GET } from "@/lib/quota";
+// app/api/quota/status/route.ts
+export { status as GET } from "@/lib/quota";
+```
+## withQuotaAuth
+Wraps a route handler with automatic Quota authentication, token refresh, and error handling:
+```typescript
+// app/api/summarize/route.ts
+import { withQuotaAuth } from "@usequota/nextjs/server";
+export const POST = withQuotaAuth(
+  {
+    clientId: process.env.QUOTA_CLIENT_ID!,
+    clientSecret: process.env.QUOTA_CLIENT_SECRET!,
+  },
+  async (request, { user, accessToken }) => {
+    // user is guaranteed to exist
+    // accessToken can proxy requests through Quota
+    const response = await fetch(
+      "https://api.usequota.app/v1/chat/completions",
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          model: "gpt-4o-mini",
+          messages: [{ role: "user", content: "Hello" }],
+        }),
+      },
+    );
+    return Response.json(await response.json());
+  },
+);
+```
+## Typed Errors
+Handle specific failure modes with `instanceof` checks:
+```typescript
+import {
+  QuotaInsufficientCreditsError,
+  QuotaNotConnectedError,
+  QuotaRateLimitError,
+  QuotaError,
+} from "@usequota/nextjs/server";
+try {
+  await callQuotaAPI();
+} catch (e) {
+  if (e instanceof QuotaInsufficientCreditsError) {
+    console.log(e.balance, e.required); // current balance, credits needed
+  }
+  if (e instanceof QuotaNotConnectedError) {
+    // redirect to login
+  }
+  if (e instanceof QuotaRateLimitError) {
+    await delay(e.retryAfter * 1000); // seconds until retry
+  }
+  if (e instanceof QuotaError) {
+    console.log(e.code, e.statusCode, e.hint);
+  }
+}
+```
+## License
+MIT

package/dist/chunk-BMI3VFWV.mjs ADDED Viewed

@@ -0,0 +1,120 @@
+// src/errors.ts
+var QuotaError = class extends Error {
+  /** Machine-readable error code */
+  code;
+  /** HTTP status code associated with this error */
+  statusCode;
+  /** Optional hint for resolving the error */
+  hint;
+  constructor(message, code, statusCode, hint) {
+    super(message);
+    this.name = "QuotaError";
+    this.code = code;
+    this.statusCode = statusCode;
+    this.hint = hint;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var QuotaInsufficientCreditsError = class extends QuotaError {
+  /** Current balance (if available) */
+  balance;
+  /** Credits required for the operation (if available) */
+  required;
+  constructor(message, options) {
+    super(
+      message ?? "Insufficient credits to complete this operation",
+      "insufficient_credits",
+      402,
+      "Purchase more credits or reduce usage"
+    );
+    this.name = "QuotaInsufficientCreditsError";
+    this.balance = options?.balance;
+    this.required = options?.required;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var QuotaNotConnectedError = class extends QuotaError {
+  constructor(message) {
+    super(
+      message ?? "User has not connected a Quota account",
+      "not_connected",
+      401,
+      "Connect your Quota account to use this feature"
+    );
+    this.name = "QuotaNotConnectedError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var QuotaTokenExpiredError = class extends QuotaError {
+  constructor(message) {
+    super(
+      message ?? "Quota access token has expired and could not be refreshed",
+      "token_expired",
+      401,
+      "Reconnect your Quota account"
+    );
+    this.name = "QuotaTokenExpiredError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var QuotaRateLimitError = class extends QuotaError {
+  /** Seconds until the rate limit resets */
+  retryAfter;
+  constructor(message, retryAfter) {
+    super(
+      message ?? "Rate limit exceeded",
+      "rate_limit_exceeded",
+      429,
+      "Wait before retrying"
+    );
+    this.name = "QuotaRateLimitError";
+    this.retryAfter = retryAfter ?? 60;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+async function errorFromResponse(response) {
+  if (response.ok) {
+    return null;
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+  }
+  const message = body?.error?.message ?? response.statusText;
+  const code = body?.error?.code;
+  switch (response.status) {
+    case 402: {
+      const opts = {};
+      if (body?.error?.balance !== void 0) opts.balance = body.error.balance;
+      if (body?.error?.required !== void 0)
+        opts.required = body.error.required;
+      return new QuotaInsufficientCreditsError(message, opts);
+    }
+    case 429: {
+      const parsed = parseInt(response.headers.get("retry-after") ?? "60", 10);
+      const retryAfter = Number.isNaN(parsed) ? 60 : parsed;
+      return new QuotaRateLimitError(message, retryAfter);
+    }
+    case 401: {
+      if (code === "not_connected") {
+        return new QuotaNotConnectedError(message);
+      }
+      if (code === "token_expired") {
+        return new QuotaTokenExpiredError(message);
+      }
+      return new QuotaTokenExpiredError(message);
+    }
+    default:
+      return new QuotaError(message, code ?? "unknown", response.status);
+  }
+}
+export {
+  QuotaError,
+  QuotaInsufficientCreditsError,
+  QuotaNotConnectedError,
+  QuotaTokenExpiredError,
+  QuotaRateLimitError,
+  errorFromResponse
+};

package/dist/chunk-RSPDHXC2.mjs ADDED Viewed

@@ -0,0 +1,119 @@
+// src/errors.ts
+var QuotaError = class extends Error {
+  /** Machine-readable error code */
+  code;
+  /** HTTP status code associated with this error */
+  statusCode;
+  /** Optional hint for resolving the error */
+  hint;
+  constructor(message, code, statusCode, hint) {
+    super(message);
+    this.name = "QuotaError";
+    this.code = code;
+    this.statusCode = statusCode;
+    this.hint = hint;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var QuotaInsufficientCreditsError = class extends QuotaError {
+  /** Current balance (if available) */
+  balance;
+  /** Credits required for the operation (if available) */
+  required;
+  constructor(message, options) {
+    super(
+      message ?? "Insufficient credits to complete this operation",
+      "insufficient_credits",
+      402,
+      "Purchase more credits or reduce usage"
+    );
+    this.name = "QuotaInsufficientCreditsError";
+    this.balance = options?.balance;
+    this.required = options?.required;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var QuotaNotConnectedError = class extends QuotaError {
+  constructor(message) {
+    super(
+      message ?? "User has not connected a Quota account",
+      "not_connected",
+      401,
+      "Connect your Quota account to use this feature"
+    );
+    this.name = "QuotaNotConnectedError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var QuotaTokenExpiredError = class extends QuotaError {
+  constructor(message) {
+    super(
+      message ?? "Quota access token has expired and could not be refreshed",
+      "token_expired",
+      401,
+      "Reconnect your Quota account"
+    );
+    this.name = "QuotaTokenExpiredError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var QuotaRateLimitError = class extends QuotaError {
+  /** Seconds until the rate limit resets */
+  retryAfter;
+  constructor(message, retryAfter) {
+    super(
+      message ?? "Rate limit exceeded",
+      "rate_limit_exceeded",
+      429,
+      "Wait before retrying"
+    );
+    this.name = "QuotaRateLimitError";
+    this.retryAfter = retryAfter ?? 60;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+async function errorFromResponse(response) {
+  if (response.ok) {
+    return null;
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+  }
+  const message = body?.error?.message ?? response.statusText;
+  const code = body?.error?.code;
+  switch (response.status) {
+    case 402: {
+      const opts = {};
+      if (body?.error?.balance !== void 0) opts.balance = body.error.balance;
+      if (body?.error?.required !== void 0)
+        opts.required = body.error.required;
+      return new QuotaInsufficientCreditsError(message, opts);
+    }
+    case 429: {
+      const retryAfter = parseInt(
+        response.headers.get("retry-after") ?? "60",
+        10
+      );
+      return new QuotaRateLimitError(message, retryAfter);
+    }
+    case 401: {
+      if (code === "not_connected") {
+        return new QuotaNotConnectedError(message);
+      }
+      return new QuotaTokenExpiredError(message);
+    }
+    default:
+      return new QuotaError(message, code ?? "unknown", response.status);
+  }
+}
+export {
+  QuotaError,
+  QuotaInsufficientCreditsError,
+  QuotaNotConnectedError,
+  QuotaTokenExpiredError,
+  QuotaRateLimitError,
+  errorFromResponse
+};