@usequota/nextjs 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,585 @@
+import { NextRequest, NextResponse } from 'next/server';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { QuotaUser } from '@usequota/types';
+export { ChatCompletionRequest, ChatCompletionResponse, ChatMessage, CreditPackage, QuotaError as QuotaErrorResponse, QuotaMetadata, QuotaSession, QuotaUser, Tool, ToolCall } from '@usequota/types';
+export { Q as QuotaError, a as QuotaInsufficientCreditsError, b as QuotaNotConnectedError, d as QuotaRateLimitError, c as QuotaTokenExpiredError } from './errors-CmNx3kSz.js';
+
+/**
+ * @usequota/nextjs - Next.js middleware for OAuth callback handling
+ *
+ * This middleware handles the OAuth callback route and manages token storage.
+ * For client-side storage, tokens are stored in httpOnly cookies.
+ * For hosted storage, the link is established server-side via external_user_id.
+ */
+
+interface QuotaConfig {
+    /**
+     * 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;
+    /**
+     * OAuth callback path
+     * @default '/api/quota/callback'
+     */
+    callbackPath?: string;
+    /**
+     * Token storage mode
+     * - 'client': Store tokens in httpOnly cookies (default)
+     * - 'hosted': Use hosted token storage (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?: (request: NextRequest) => string | Promise<string>;
+    /**
+     * Cookie settings
+     */
+    cookie?: {
+        /**
+         * Cookie name prefix
+         * @default 'quota'
+         */
+        prefix?: string;
+        /**
+         * Cookie domain
+         */
+        domain?: string;
+        /**
+         * Cookie path
+         * @default '/'
+         */
+        path?: string;
+        /**
+         * Cookie max age in seconds
+         * @default 604800 (7 days)
+         */
+        maxAge?: number;
+    };
+}
+/**
+ * Creates Next.js middleware to handle OAuth callback
+ *
+ * @example
+ * ```typescript
+ * // middleware.ts
+ * 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',
+ * };
+ * ```
+ */
+declare function createQuotaMiddleware(config: QuotaConfig): (request: NextRequest) => Promise<NextResponse<unknown>>;
+
+interface QuotaContextValue {
+    /**
+     * Current authenticated user, or null if not logged in
+     */
+    user: QuotaUser | null;
+    /**
+     * Whether the user data is currently loading
+     */
+    isLoading: boolean;
+    /**
+     * Error that occurred during authentication or user fetch
+     */
+    error: Error | null;
+    /**
+     * Redirects to OAuth login flow
+     */
+    login: () => void;
+    /**
+     * Logs out the current user
+     */
+    logout: () => Promise<void>;
+    /**
+     * Refetches user data from the server
+     */
+    refetch: () => Promise<void>;
+}
+declare const QuotaContext: react.Context<QuotaContextValue | null>;
+interface QuotaProviderProps {
+    children: ReactNode;
+    /**
+     * OAuth client ID from Quota dashboard
+     */
+    clientId: string;
+    /**
+     * Quota API base URL
+     * @default 'https://api.usequota.app'
+     */
+    baseUrl?: string;
+    /**
+     * OAuth callback path (must match middleware config)
+     * @default '/api/quota/callback'
+     */
+    callbackPath?: string;
+    /**
+     * Path to your Next.js API route that fetches user data
+     * @default '/api/quota/me'
+     */
+    apiPath?: string;
+}
+/**
+ * React context provider for Quota authentication
+ *
+ * @example
+ * ```tsx
+ * // app/layout.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>
+ *   );
+ * }
+ * ```
+ */
+declare function QuotaProvider({ children, clientId, baseUrl, callbackPath, apiPath, }: QuotaProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access Quota authentication context
+ *
+ * @example
+ * ```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</button>;
+ *
+ *   return <div>Welcome, {user.email}!</div>;
+ * }
+ * ```
+ */
+declare function useQuota(): QuotaContextValue;
+
+/**
+ * @usequota/nextjs - React hooks for Quota SDK
+ *
+ * Provides convenient hooks for accessing Quota features.
+ */
+
+/**
+ * Hook to get the current authenticated user
+ *
+ * @example
+ * ```tsx
+ * 'use client';
+ * import { useQuotaUser } from '@usequota/nextjs';
+ *
+ * export function UserProfile() {
+ *   const user = useQuotaUser();
+ *
+ *   if (!user) return <div>Not logged in</div>;
+ *
+ *   return (
+ *     <div>
+ *       <p>Email: {user.email}</p>
+ *       <p>Balance: {user.balance} credits</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useQuotaUser(): QuotaUser | null;
+/**
+ * Hook to check if user is authenticated
+ *
+ * @example
+ * ```tsx
+ * 'use client';
+ * import { useQuotaAuth } from '@usequota/nextjs';
+ *
+ * export function ProtectedContent() {
+ *   const { isAuthenticated, isLoading, login } = useQuotaAuth();
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   if (!isAuthenticated) return <button onClick={login}>Sign in</button>;
+ *
+ *   return <div>Protected content</div>;
+ * }
+ * ```
+ */
+declare function useQuotaAuth(): {
+    isAuthenticated: boolean;
+    isLoading: boolean;
+    login: () => void;
+    logout: () => Promise<void>;
+};
+/**
+ * Hook to get user's credit balance
+ *
+ * @example
+ * ```tsx
+ * 'use client';
+ * import { useQuotaBalance } from '@usequota/nextjs';
+ *
+ * export function CreditDisplay() {
+ *   const { balance, isLoading } = useQuotaBalance();
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   if (balance === null) return <div>Not logged in</div>;
+ *
+ *   return (
+ *     <div>
+ *       Balance: {balance} credits (${(balance / 100).toFixed(2)})
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useQuotaBalance(): {
+    balance: number | null;
+    isLoading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+};
+
+interface QuotaConnectButtonProps {
+    /**
+     * Custom button content when not logged in
+     * @default 'Connect Wallet'
+     */
+    children?: ReactNode;
+    /**
+     * Additional CSS class names for styling customization
+     */
+    className?: string;
+    /**
+     * Callback fired when OAuth login completes successfully
+     */
+    onSuccess?: () => void;
+    /**
+     * Callback fired when an error occurs during login
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Button variant style
+     * @default 'primary'
+     */
+    variant?: "primary" | "secondary" | "ghost";
+    /**
+     * Show loading spinner during authentication
+     * @default true
+     */
+    showLoadingState?: boolean;
+    /**
+     * If true, shows user info when logged in instead of hiding
+     * @default false
+     */
+    showWhenConnected?: boolean;
+}
+/**
+ * OAuth login button for Quota authentication
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <QuotaConnectButton />
+ *
+ * // With custom text
+ * <QuotaConnectButton>Sign in with Quota</QuotaConnectButton>
+ *
+ * // With callbacks
+ * <QuotaConnectButton
+ *   onSuccess={() => console.log('Connected!')}
+ *   onError={(err) => console.error(err)}
+ * />
+ * ```
+ */
+declare function QuotaConnectButton({ children, className, onSuccess, onError, variant, showLoadingState, showWhenConnected, }: QuotaConnectButtonProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * @usequota/nextjs - QuotaBalance
+ *
+ * Display component for showing the user's credit balance.
+ * Supports both credit and dollar formatting.
+ */
+interface QuotaBalanceProps {
+    /**
+     * Display format for the balance
+     * - 'credits': Shows raw credit count (e.g., "1,250 credits")
+     * - 'dollars': Shows dollar equivalent (e.g., "$12.50")
+     * @default 'credits'
+     */
+    format?: "credits" | "dollars";
+    /**
+     * Whether to show the coin/dollar icon
+     * @default true
+     */
+    showIcon?: boolean;
+    /**
+     * Additional CSS class names for styling customization
+     */
+    className?: string;
+    /**
+     * Label text for accessibility
+     * @default 'Credit balance'
+     */
+    ariaLabel?: string;
+    /**
+     * Show a refresh button to manually refetch balance
+     * @default false
+     */
+    showRefresh?: boolean;
+    /**
+     * Callback when balance is clicked (useful for linking to buy credits)
+     */
+    onClick?: () => void;
+}
+/**
+ * Display component for user's Quota credit balance
+ *
+ * @example
+ * ```tsx
+ * // Basic usage - shows credits
+ * <QuotaBalance />
+ *
+ * // Show as dollars
+ * <QuotaBalance format="dollars" />
+ *
+ * // Clickable balance
+ * <QuotaBalance onClick={() => router.push('/buy-credits')} />
+ * ```
+ */
+declare function QuotaBalance({ format, showIcon, className, ariaLabel, showRefresh, onClick, }: QuotaBalanceProps): react_jsx_runtime.JSX.Element;
+
+interface QuotaBuyCreditsProps {
+    /**
+     * Specific package ID to purchase (from /v1/packages)
+     */
+    packageId?: string;
+    /**
+     * Desired credit amount (used to auto-select best package)
+     * Ignored if packageId is provided
+     */
+    amount?: number;
+    /**
+     * Custom button content
+     * @default 'Buy Credits'
+     */
+    children?: ReactNode;
+    /**
+     * Additional CSS class names for styling customization
+     */
+    className?: string;
+    /**
+     * Callback fired when checkout session is created successfully
+     */
+    onSuccess?: () => void;
+    /**
+     * Callback fired when an error occurs
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Button variant style
+     * @default 'primary'
+     */
+    variant?: "primary" | "secondary" | "ghost";
+    /**
+     * Path to the checkout API endpoint
+     * @default '/api/quota/checkout'
+     */
+    checkoutPath?: string;
+    /**
+     * Disable the button
+     * @default false
+     */
+    disabled?: boolean;
+}
+/**
+ * Credit purchase button that redirects to Stripe checkout
+ *
+ * @example
+ * ```tsx
+ * // Basic usage - shows package selection
+ * <QuotaBuyCredits />
+ *
+ * // Specific package
+ * <QuotaBuyCredits packageId="pack_1000" />
+ *
+ * // Custom amount (finds best matching package)
+ * <QuotaBuyCredits amount={5000}>Get 5000 Credits</QuotaBuyCredits>
+ * ```
+ */
+declare function QuotaBuyCredits({ packageId, amount, children, className, onSuccess, onError, variant, checkoutPath, disabled, }: QuotaBuyCreditsProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * @usequota/nextjs - QuotaUserMenu
+ *
+ * Dropdown menu component showing user avatar, balance, and account actions.
+ * Uses headless UI patterns with no external dependencies.
+ */
+interface QuotaUserMenuProps {
+    /**
+     * Additional CSS class names for styling customization
+     */
+    className?: string;
+    /**
+     * Callback when "Buy Credits" is clicked
+     */
+    onBuyCredits?: () => void;
+    /**
+     * Callback when logout completes
+     */
+    onLogout?: () => void;
+    /**
+     * Show the buy credits menu item
+     * @default true
+     */
+    showBuyCredits?: boolean;
+    /**
+     * Custom content to render in the dropdown
+     */
+    children?: React.ReactNode;
+}
+/**
+ * User account dropdown menu with balance display
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <QuotaUserMenu />
+ *
+ * // With callbacks
+ * <QuotaUserMenu
+ *   onBuyCredits={() => router.push('/buy-credits')}
+ *   onLogout={() => router.push('/')}
+ * />
+ *
+ * // With custom menu items
+ * <QuotaUserMenu>
+ *   <button onClick={() => router.push('/settings')}>Settings</button>
+ * </QuotaUserMenu>
+ * ```
+ */
+declare function QuotaUserMenu({ className, onBuyCredits, onLogout, showBuyCredits, children, }: QuotaUserMenuProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Webhook event types sent by Quota
+ */
+interface WebhookEvent {
+    /** Unique event identifier */
+    id: string;
+    /** Event type */
+    type: "user.connected" | "user.disconnected" | "balance.updated" | "balance.low" | "usage.completed";
+    /** ISO 8601 timestamp when event was created */
+    created_at: string;
+    /** Event-specific data payload */
+    data: Record<string, unknown>;
+}
+/**
+ * Options for verifying webhook signatures
+ */
+interface VerifyWebhookOptions {
+    /** Raw webhook payload (string or Buffer) */
+    payload: string | Buffer;
+    /** Signature from X-Quota-Signature header */
+    signature: string;
+    /** Webhook secret from Quota dashboard */
+    secret: string;
+}
+/**
+ * Verify a webhook signature from Quota using HMAC-SHA256
+ *
+ * @param options - Verification options
+ * @returns true if signature is valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const isValid = verifyWebhookSignature({
+ *   payload: rawBody,
+ *   signature: request.headers.get('x-quota-signature')!,
+ *   secret: process.env.QUOTA_WEBHOOK_SECRET!
+ * });
+ * ```
+ */
+declare function verifyWebhookSignature({ payload, signature, secret, }: VerifyWebhookOptions): boolean;
+/**
+ * Parse and verify a webhook request
+ * For use in Next.js API routes (App Router)
+ *
+ * @param req - Next.js Request object
+ * @param secret - Webhook secret from Quota dashboard
+ * @returns Parsed and verified webhook event
+ * @throws Error if signature is missing or invalid
+ *
+ * @example
+ * ```typescript
+ * // app/api/quota/webhook/route.ts
+ * export async function POST(req: Request) {
+ *   try {
+ *     const event = await parseWebhook(req, process.env.QUOTA_WEBHOOK_SECRET!);
+ *
+ *     if (event.type === 'balance.low') {
+ *       await sendLowBalanceEmail(event.data);
+ *     }
+ *
+ *     return Response.json({ received: true });
+ *   } catch (error) {
+ *     return Response.json({ error: error.message }, { status: 400 });
+ *   }
+ * }
+ * ```
+ */
+declare function parseWebhook(req: Request, secret: string): Promise<WebhookEvent>;
+/**
+ * Create a webhook handler for Next.js App Router
+ * Automatically verifies signatures and routes events to handlers
+ *
+ * @param secret - Webhook secret from Quota dashboard
+ * @param handlers - Map of event types to handler functions
+ * @returns Next.js route handler function
+ *
+ * @example
+ * ```typescript
+ * // app/api/quota/webhook/route.ts
+ * import { createWebhookHandler } from '@usequota/nextjs';
+ *
+ * export const POST = createWebhookHandler(process.env.QUOTA_WEBHOOK_SECRET!, {
+ *   'balance.low': async (event) => {
+ *     // Send email notification
+ *     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);
+ *   }
+ * });
+ * ```
+ */
+declare function createWebhookHandler(secret: string, handlers: Partial<Record<WebhookEvent["type"], (event: WebhookEvent) => Promise<void>>>): (req: Request) => Promise<Response>;
+
+export { QuotaBalance, type QuotaBalanceProps, QuotaBuyCredits, type QuotaBuyCreditsProps, type QuotaConfig, QuotaConnectButton, type QuotaConnectButtonProps, QuotaContext, type QuotaContextValue, QuotaProvider, type QuotaProviderProps, QuotaUserMenu, type QuotaUserMenuProps, type VerifyWebhookOptions, type WebhookEvent, createQuotaMiddleware, createWebhookHandler, parseWebhook, useQuota, useQuotaAuth, useQuotaBalance, useQuotaUser, verifyWebhookSignature };