@usequota/nextjs 0.1.0

package/dist/server.d.mts

@@ -0,0 +1,477 @@
+export { Q as QuotaError, a as QuotaInsufficientCreditsError, b as QuotaNotConnectedError, d as QuotaRateLimitError, c as QuotaTokenExpiredError, e as errorFromResponse } from './errors-CmNx3kSz.mjs';
+import { QuotaUser, CreditPackage } from '@usequota/types';
+
+/**
+ * @usequota/nextjs - Token Storage Adapter
+ *
+ * Defines the interface for pluggable token storage backends.
+ * The default implementation uses httpOnly cookies, but apps can
+ * provide their own (e.g., Supabase, Redis, a database).
+ */
+/**
+ * Pluggable token storage adapter for the Quota SDK.
+ *
+ * Implement this interface to store Quota OAuth tokens in your own backend
+ * (database, Redis, etc.) instead of the default httpOnly cookies.
+ *
+ * @example
+ * ```typescript
+ * import { QuotaTokenStorage } from '@usequota/nextjs/server';
+ * import { createClient } from '@supabase/supabase-js';
+ *
+ * const supabaseTokenStorage: QuotaTokenStorage = {
+ *   async getTokens(request) {
+ *     const supabase = createClient(...);
+ *     const userId = await getUserId(request);
+ *     const { data } = await supabase
+ *       .from('quota_accounts')
+ *       .select('access_token, refresh_token')
+ *       .eq('user_id', userId)
+ *       .single();
+ *     if (!data) return null;
+ *     return { accessToken: data.access_token, refreshToken: data.refresh_token };
+ *   },
+ *
+ *   async setTokens(tokens, request) {
+ *     const supabase = createClient(...);
+ *     const userId = await getUserId(request);
+ *     await supabase.from('quota_accounts').upsert({
+ *       user_id: userId,
+ *       access_token: tokens.accessToken,
+ *       refresh_token: tokens.refreshToken,
+ *     });
+ *   },
+ *
+ *   async deleteTokens(request) {
+ *     const supabase = createClient(...);
+ *     const userId = await getUserId(request);
+ *     await supabase.from('quota_accounts').delete().eq('user_id', userId);
+ *   },
+ * };
+ * ```
+ */
+interface QuotaTokenStorage {
+    /**
+     * Retrieve stored tokens for the current request's user.
+     * Return null if no tokens are stored.
+     */
+    getTokens(request: Request): Promise<{
+        accessToken: string;
+        refreshToken?: string;
+    } | null>;
+    /**
+     * Persist tokens for the current request's user.
+     * Called after OAuth callback and after token refresh.
+     *
+     * For storage backends that modify the Response (like cookies),
+     * return the modified Response. For backends that don't modify
+     * the Response (like databases), return void.
+     */
+    setTokens(tokens: {
+        accessToken: string;
+        refreshToken?: string;
+        expiresIn?: number;
+    }, request: Request, response?: Response): Promise<Response | void>;
+    /**
+     * Delete all stored tokens for the current request's user.
+     * Called on disconnect.
+     *
+     * For storage backends that modify the Response (like cookies),
+     * return the modified Response. For backends that don't modify
+     * the Response (like databases), return void.
+     */
+    deleteTokens(request: Request, response?: Response): Promise<Response | void>;
+    /**
+     * Get the external user ID for hosted mode.
+     * Only required if you use hosted storage mode alongside tokenStorage.
+     */
+    getExternalUserId?(request: Request): Promise<string | null>;
+}
+
+/**
+ * @usequota/nextjs - Route Handler Factory
+ *
+ * Creates all necessary Next.js App Router route handlers for Quota integration.
+ * Similar pattern to NextAuth's auth() handler.
+ *
+ * @example
+ * ```typescript
+ * // lib/quota.ts
+ * import { createQuotaRouteHandlers } from '@usequota/nextjs/server';
+ *
+ * export const quotaHandlers = createQuotaRouteHandlers({
+ *   clientId: process.env.QUOTA_CLIENT_ID!,
+ *   clientSecret: process.env.QUOTA_CLIENT_SECRET!,
+ * });
+ *
+ * // app/api/quota/authorize/route.ts
+ * export { authorize as GET } from '@/lib/quota';
+ * // OR: export const GET = quotaHandlers.authorize;
+ *
+ * // 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';
+ *
+ * // app/api/quota/packages/route.ts
+ * export { packages as GET } from '@/lib/quota';
+ *
+ * // app/api/quota/checkout/route.ts
+ * export { checkout as POST } from '@/lib/quota';
+ *
+ * // app/api/quota/disconnect/route.ts
+ * export { disconnect as POST } from '@/lib/quota';
+ * ```
+ */
+
+interface QuotaRouteHandlerConfig {
+    /**
+     * OAuth client ID from Quota dashboard
+     */
+    clientId: string;
+    /**
+     * OAuth client secret (keep this secure, server-side only)
+     */
+    clientSecret: string;
+    /**
+     * Quota API base URL
+     * @default 'https://api.usequota.app'
+     */
+    baseUrl?: string;
+    /**
+     * Cookie name prefix
+     * @default 'quota'
+     */
+    cookiePrefix?: string;
+    /**
+     * Cookie max age in seconds
+     * @default 604800 (7 days)
+     */
+    cookieMaxAge?: number;
+    /**
+     * Token storage mode
+     * - 'client': Tokens stored in httpOnly cookies (default)
+     * - 'hosted': Tokens stored server-side by Quota
+     * @default 'client'
+     */
+    storageMode?: "client" | "hosted";
+    /**
+     * Function to get the external user ID (for hosted mode)
+     * Receives the Request object; return the ID of the currently logged-in user
+     * in your own auth system.
+     */
+    getExternalUserId?: (request: Request) => string | Promise<string>;
+    /**
+     * Pluggable token storage adapter.
+     * When provided, tokens are stored/retrieved using this adapter
+     * instead of httpOnly cookies.
+     */
+    tokenStorage?: QuotaTokenStorage;
+    /**
+     * OAuth callback path
+     * @default '/api/quota/callback'
+     */
+    callbackPath?: string;
+    /**
+     * URL to redirect after successful connection
+     * @default '/'
+     */
+    successRedirect?: string;
+    /**
+     * URL to redirect after errors
+     * @default '/'
+     */
+    errorRedirect?: string;
+    /**
+     * Callbacks for lifecycle events
+     */
+    callbacks?: {
+        /**
+         * Called after a user successfully connects their Quota account.
+         * Use this to save tokens, update your database, etc.
+         */
+        onConnect?: (data: {
+            user: QuotaUser;
+            accessToken: string;
+            refreshToken: string;
+            expiresIn: number;
+            request: Request;
+        }) => void | Promise<void>;
+        /**
+         * Called when a user disconnects their Quota account.
+         */
+        onDisconnect?: (request: Request) => void | Promise<void>;
+    };
+}
+interface QuotaRouteHandlers {
+    /** GET handler - initiates OAuth authorization flow */
+    authorize: (request: Request) => Promise<Response>;
+    /** GET handler - handles OAuth callback, exchanges code for tokens */
+    callback: (request: Request) => Promise<Response>;
+    /** GET handler - returns user connection status and balance */
+    status: (request: Request) => Promise<Response>;
+    /** GET handler - returns available credit packages */
+    packages: (request: Request) => Promise<Response>;
+    /** POST handler - creates a Stripe checkout session */
+    checkout: (request: Request) => Promise<Response>;
+    /** POST handler - disconnects the user's Quota account */
+    disconnect: (request: Request) => Promise<Response>;
+}
+/**
+ * Creates all needed API route handlers for Quota integration.
+ *
+ * Returns an object with handlers for: authorize, callback, status, packages, checkout, disconnect.
+ * Each handler is a standard Next.js App Router route handler function.
+ */
+declare function createQuotaRouteHandlers(config: QuotaRouteHandlerConfig): QuotaRouteHandlers;
+
+/**
+ * @usequota/nextjs - withQuotaAuth API route wrapper
+ *
+ * Wraps a Next.js API route handler to automatically check Quota authentication,
+ * fetch user info, and pass it to the handler. Returns proper error responses
+ * for common failure modes.
+ *
+ * @example
+ * ```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 and be connected
+ *     // accessToken can be used to proxy AI requests through Quota
+ *     const client = new Anthropic({
+ *       authToken: accessToken,
+ *       baseURL: 'https://api.usequota.app',
+ *     });
+ *
+ *     const result = await client.messages.create({ ... });
+ *     return Response.json(result);
+ *   }
+ * );
+ * ```
+ */
+
+interface WithQuotaAuthConfig {
+    /**
+     * OAuth client ID
+     */
+    clientId: string;
+    /**
+     * OAuth client secret
+     */
+    clientSecret: string;
+    /**
+     * Quota API base URL
+     * @default 'https://api.usequota.app'
+     */
+    baseUrl?: string;
+    /**
+     * Cookie prefix (must match middleware/route handler config)
+     * @default 'quota'
+     */
+    cookiePrefix?: string;
+    /**
+     * Cookie max age in seconds
+     * @default 604800 (7 days)
+     */
+    cookieMaxAge?: number;
+    /**
+     * Token storage mode
+     * @default 'client'
+     */
+    storageMode?: "client" | "hosted";
+    /**
+     * Function to get external user ID (required for hosted mode)
+     */
+    getExternalUserId?: (request: Request) => string | Promise<string>;
+    /**
+     * Pluggable token storage adapter.
+     * When provided, tokens are read/refreshed using this adapter
+     * instead of httpOnly cookies.
+     */
+    tokenStorage?: QuotaTokenStorage;
+}
+interface QuotaAuthContext {
+    /** The authenticated Quota user */
+    user: QuotaUser;
+    /** The OAuth access token (empty string in hosted mode) */
+    accessToken: string;
+}
+type QuotaAuthHandler = (request: Request, context: QuotaAuthContext) => Promise<Response>;
+/**
+ * Wraps an API route handler with Quota authentication.
+ *
+ * The wrapper:
+ * 1. Checks if the user has a Quota access token
+ * 2. Fetches the user's info from Quota
+ * 3. If the token is expired, attempts to refresh it
+ * 4. Passes the user and token to the handler
+ * 5. Catches typed Quota errors and returns proper HTTP responses
+ */
+declare function withQuotaAuth(config: WithQuotaAuthConfig, handler: QuotaAuthHandler): (request: Request) => Promise<Response>;
+
+/**
+ * @usequota/nextjs/server - Server-side utilities for Quota SDK
+ *
+ * Provides utilities for accessing Quota from Next.js server components and API routes.
+ */
+
+interface QuotaServerConfig {
+    /**
+     * OAuth client ID from Quota dashboard
+     */
+    clientId: string;
+    /**
+     * OAuth client secret (keep this secure, server-side only)
+     */
+    clientSecret: string;
+    /**
+     * Quota API base URL
+     * @default 'https://api.usequota.app'
+     */
+    baseUrl?: string;
+    /**
+     * Cookie prefix (must match middleware config)
+     * @default 'quota'
+     */
+    cookiePrefix?: string;
+    /**
+     * Cookie max age in seconds
+     * @default 604800 (7 days)
+     */
+    cookieMaxAge?: number;
+    /**
+     * Token storage mode
+     * - 'client': Tokens stored in httpOnly cookies (default)
+     * - 'hosted': Tokens stored server-side by Quota
+     * @default 'client'
+     */
+    storageMode?: "client" | "hosted";
+    /**
+     * Function to get external user ID for hosted mode
+     * Only required when storageMode is 'hosted'
+     */
+    getExternalUserId?: () => string | Promise<string>;
+}
+/**
+ * Gets the current authenticated user from server-side
+ *
+ * @example
+ * ```typescript
+ * // app/api/quota/me/route.ts
+ * 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);
+ * }
+ * ```
+ */
+declare function getQuotaUser(config: QuotaServerConfig): Promise<QuotaUser | null>;
+/**
+ * Requires authentication, redirects to login if not authenticated
+ *
+ * @example
+ * ```typescript
+ * // app/dashboard/page.tsx
+ * import { requireQuotaAuth } from '@usequota/nextjs/server';
+ *
+ * export default async function DashboardPage() {
+ *   const user = await requireQuotaAuth({
+ *     clientId: process.env.QUOTA_CLIENT_ID!,
+ *     clientSecret: process.env.QUOTA_CLIENT_SECRET!,
+ *   });
+ *
+ *   return <div>Welcome, {user.email}!</div>;
+ * }
+ * ```
+ */
+declare function requireQuotaAuth(config: QuotaServerConfig): Promise<QuotaUser>;
+/**
+ * Fetches available credit packages
+ *
+ * @example
+ * ```typescript
+ * // app/api/packages/route.ts
+ * import { getQuotaPackages } from '@usequota/nextjs/server';
+ *
+ * export async function GET() {
+ *   const packages = await getQuotaPackages({
+ *     baseUrl: process.env.NEXT_PUBLIC_QUOTA_BASE_URL,
+ *   });
+ *
+ *   return Response.json(packages);
+ * }
+ * ```
+ */
+declare function getQuotaPackages(config?: {
+    baseUrl?: string;
+}): Promise<CreditPackage[]>;
+/**
+ * Creates a Stripe checkout session for purchasing credits
+ *
+ * @example
+ * ```typescript
+ * // app/api/checkout/route.ts
+ * import { createQuotaCheckout } from '@usequota/nextjs/server';
+ *
+ * export async function POST(request: Request) {
+ *   const { packageId } = await request.json();
+ *
+ *   const checkoutUrl = await createQuotaCheckout({
+ *     clientId: process.env.QUOTA_CLIENT_ID!,
+ *     clientSecret: process.env.QUOTA_CLIENT_SECRET!,
+ *     packageId,
+ *     successUrl: `${process.env.NEXT_PUBLIC_APP_URL}/success`,
+ *     cancelUrl: `${process.env.NEXT_PUBLIC_APP_URL}/cancel`,
+ *   });
+ *
+ *   return Response.json({ url: checkoutUrl });
+ * }
+ * ```
+ */
+declare function createQuotaCheckout(config: {
+    clientId: string;
+    clientSecret: string;
+    packageId: string;
+    successUrl: string;
+    cancelUrl: string;
+    baseUrl?: string;
+    cookiePrefix?: string;
+    storageMode?: "client" | "hosted";
+    getExternalUserId?: () => string | Promise<string>;
+}): Promise<string>;
+/**
+ * Clears authentication cookies (logout)
+ *
+ * @example
+ * ```typescript
+ * // app/api/quota/logout/route.ts
+ * import { clearQuotaAuth } from '@usequota/nextjs/server';
+ *
+ * export async function POST() {
+ *   await clearQuotaAuth();
+ *   return Response.json({ success: true });
+ * }
+ * ```
+ */
+declare function clearQuotaAuth(config?: {
+    cookiePrefix?: string;
+}): Promise<void>;
+
+export { type QuotaAuthContext, type QuotaRouteHandlerConfig, type QuotaRouteHandlers, type QuotaServerConfig, type QuotaTokenStorage, type WithQuotaAuthConfig, clearQuotaAuth, createQuotaCheckout, createQuotaRouteHandlers, getQuotaPackages, getQuotaUser, requireQuotaAuth, withQuotaAuth };