@zap-js/client 0.0.2 → 0.0.5

package/dist/runtime/csrf.d.ts

@@ -0,0 +1,146 @@
+/**
+ * CSRF (Cross-Site Request Forgery) Protection Utilities
+ *
+ * Provides client-side utilities for working with CSRF tokens:
+ * - Reading tokens from cookies
+ * - Including tokens in fetch requests
+ * - Form components with automatic token injection
+ */
+/**
+ * CSRF configuration
+ */
+export interface CsrfConfig {
+    /** Cookie name for CSRF token (default: "csrf_token") */
+    cookieName?: string;
+    /** Header name for CSRF token (default: "X-CSRF-Token") */
+    headerName?: string;
+    /** Form field name for CSRF token (default: "_csrf") */
+    formFieldName?: string;
+}
+/**
+ * Get CSRF token from cookie
+ */
+export declare function getCsrfToken(config?: CsrfConfig): string | null;
+/**
+ * React hook to get CSRF token
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const csrfToken = useCsrfToken();
+ *
+ *   const handleSubmit = async () => {
+ *     await fetch('/api/data', {
+ *       method: 'POST',
+ *       headers: {
+ *         'X-CSRF-Token': csrfToken || '',
+ *         'Content-Type': 'application/json',
+ *       },
+ *       body: JSON.stringify({ data: 'value' }),
+ *     });
+ *   };
+ * }
+ * ```
+ */
+export declare function useCsrfToken(config?: CsrfConfig): string | null;
+/**
+ * Create a fetch wrapper that automatically includes CSRF token
+ *
+ * @example
+ * ```tsx
+ * const csrfFetch = createCsrfFetch();
+ *
+ * // Token is automatically included in POST/PUT/DELETE/PATCH requests
+ * await csrfFetch('/api/data', {
+ *   method: 'POST',
+ *   body: JSON.stringify({ data: 'value' }),
+ * });
+ * ```
+ */
+export declare function createCsrfFetch(config?: CsrfConfig): typeof fetch;
+/**
+ * CSRF token input component for forms
+ *
+ * @example
+ * ```tsx
+ * function MyForm() {
+ *   return (
+ *     <form method="POST" action="/api/submit">
+ *       <CsrfTokenInput />
+ *       <input name="username" />
+ *       <button type="submit">Submit</button>
+ *     </form>
+ *   );
+ * }
+ * ```
+ */
+export interface CsrfTokenInputProps {
+    /** Configuration for CSRF token retrieval */
+    config?: CsrfConfig;
+}
+export declare function CsrfTokenInput({ config }: CsrfTokenInputProps): import("react/jsx-runtime").JSX.Element | null;
+/**
+ * Enhanced form component with automatic CSRF protection
+ *
+ * @example
+ * ```tsx
+ * function MyPage() {
+ *   const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
+ *     e.preventDefault();
+ *     const formData = new FormData(e.currentTarget);
+ *     await fetch('/api/submit', {
+ *       method: 'POST',
+ *       body: formData,
+ *     });
+ *   };
+ *
+ *   return (
+ *     <CsrfForm onSubmit={handleSubmit}>
+ *       <input name="username" />
+ *       <button type="submit">Submit</button>
+ *     </CsrfForm>
+ *   );
+ * }
+ * ```
+ */
+export interface CsrfFormProps extends React.FormHTMLAttributes<HTMLFormElement> {
+    /** Configuration for CSRF token retrieval */
+    config?: CsrfConfig;
+    /** Child elements */
+    children: React.ReactNode;
+}
+export declare function CsrfForm({ config, children, ...formProps }: CsrfFormProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Utility to manually add CSRF token to FormData
+ *
+ * @example
+ * ```tsx
+ * const formData = new FormData();
+ * formData.append('username', 'john');
+ * addCsrfToFormData(formData);
+ *
+ * await fetch('/api/submit', {
+ *   method: 'POST',
+ *   body: formData,
+ * });
+ * ```
+ */
+export declare function addCsrfToFormData(formData: FormData, config?: CsrfConfig): void;
+/**
+ * Utility to get headers object with CSRF token
+ *
+ * @example
+ * ```tsx
+ * const headers = {
+ *   'Content-Type': 'application/json',
+ *   ...getCsrfHeaders(),
+ * };
+ *
+ * await fetch('/api/data', {
+ *   method: 'POST',
+ *   headers,
+ *   body: JSON.stringify({ data: 'value' }),
+ * });
+ * ```
+ */
+export declare function getCsrfHeaders(config?: CsrfConfig): Record<string, string>;

package/dist/runtime/csrf.js

@@ -0,0 +1,166 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * CSRF (Cross-Site Request Forgery) Protection Utilities
+ *
+ * Provides client-side utilities for working with CSRF tokens:
+ * - Reading tokens from cookies
+ * - Including tokens in fetch requests
+ * - Form components with automatic token injection
+ */
+import { useState, useEffect } from 'react';
+const DEFAULT_CONFIG = {
+    cookieName: 'csrf_token',
+    headerName: 'X-CSRF-Token',
+    formFieldName: '_csrf',
+};
+/**
+ * Get CSRF token from cookie
+ */
+export function getCsrfToken(config = {}) {
+    const { cookieName } = { ...DEFAULT_CONFIG, ...config };
+    if (typeof document === 'undefined') {
+        return null;
+    }
+    const cookies = document.cookie.split(';');
+    for (const cookie of cookies) {
+        const [name, value] = cookie.trim().split('=');
+        if (name === cookieName) {
+            return value;
+        }
+    }
+    return null;
+}
+/**
+ * React hook to get CSRF token
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const csrfToken = useCsrfToken();
+ *
+ *   const handleSubmit = async () => {
+ *     await fetch('/api/data', {
+ *       method: 'POST',
+ *       headers: {
+ *         'X-CSRF-Token': csrfToken || '',
+ *         'Content-Type': 'application/json',
+ *       },
+ *       body: JSON.stringify({ data: 'value' }),
+ *     });
+ *   };
+ * }
+ * ```
+ */
+export function useCsrfToken(config = {}) {
+    const [token, setToken] = useState(() => getCsrfToken(config));
+    useEffect(() => {
+        // Update token if cookie changes
+        const interval = setInterval(() => {
+            const newToken = getCsrfToken(config);
+            if (newToken !== token) {
+                setToken(newToken);
+            }
+        }, 1000);
+        return () => clearInterval(interval);
+    }, [config, token]);
+    return token;
+}
+/**
+ * Create a fetch wrapper that automatically includes CSRF token
+ *
+ * @example
+ * ```tsx
+ * const csrfFetch = createCsrfFetch();
+ *
+ * // Token is automatically included in POST/PUT/DELETE/PATCH requests
+ * await csrfFetch('/api/data', {
+ *   method: 'POST',
+ *   body: JSON.stringify({ data: 'value' }),
+ * });
+ * ```
+ */
+export function createCsrfFetch(config = {}) {
+    const { headerName } = { ...DEFAULT_CONFIG, ...config };
+    return async (input, init) => {
+        const token = getCsrfToken(config);
+        // Only add token for state-changing methods
+        const method = init?.method?.toUpperCase() || 'GET';
+        const needsToken = ['POST', 'PUT', 'DELETE', 'PATCH'].includes(method);
+        if (needsToken && token) {
+            const headers = new Headers(init?.headers);
+            if (!headers.has(headerName)) {
+                headers.set(headerName, token);
+            }
+            return fetch(input, {
+                ...init,
+                headers,
+            });
+        }
+        return fetch(input, init);
+    };
+}
+export function CsrfTokenInput({ config = {} }) {
+    const token = useCsrfToken(config);
+    const { formFieldName } = { ...DEFAULT_CONFIG, ...config };
+    if (!token) {
+        console.warn('CSRF token not found. Form submission may fail.');
+        return null;
+    }
+    return _jsx("input", { type: "hidden", name: formFieldName, value: token });
+}
+export function CsrfForm({ config, children, ...formProps }) {
+    return (_jsxs("form", { ...formProps, children: [_jsx(CsrfTokenInput, { config: config }), children] }));
+}
+/**
+ * Utility to manually add CSRF token to FormData
+ *
+ * @example
+ * ```tsx
+ * const formData = new FormData();
+ * formData.append('username', 'john');
+ * addCsrfToFormData(formData);
+ *
+ * await fetch('/api/submit', {
+ *   method: 'POST',
+ *   body: formData,
+ * });
+ * ```
+ */
+export function addCsrfToFormData(formData, config = {}) {
+    const token = getCsrfToken(config);
+    const { formFieldName } = { ...DEFAULT_CONFIG, ...config };
+    if (token) {
+        formData.append(formFieldName, token);
+    }
+    else {
+        console.warn('CSRF token not found. FormData submission may fail.');
+    }
+}
+/**
+ * Utility to get headers object with CSRF token
+ *
+ * @example
+ * ```tsx
+ * const headers = {
+ *   'Content-Type': 'application/json',
+ *   ...getCsrfHeaders(),
+ * };
+ *
+ * await fetch('/api/data', {
+ *   method: 'POST',
+ *   headers,
+ *   body: JSON.stringify({ data: 'value' }),
+ * });
+ * ```
+ */
+export function getCsrfHeaders(config = {}) {
+    const token = getCsrfToken(config);
+    const { headerName } = { ...DEFAULT_CONFIG, ...config };
+    if (!token) {
+        console.warn('CSRF token not found. Request may fail.');
+        return {};
+    }
+    return {
+        [headerName]: token,
+    };
+}

package/dist/runtime/error-boundary.d.ts

@@ -0,0 +1,129 @@
+/**
+ * ZapJS Error Boundary
+ *
+ * TanStack Router style error boundary with explicit errorComponent prop.
+ * Provides structured error handling with server error correlation.
+ */
+import React, { Component, type ReactNode, type ErrorInfo } from 'react';
+/**
+ * Structured route error with full context
+ *
+ * Matches the ErrorResponse from Rust server for consistency.
+ */
+export interface ZapRouteError {
+    /** Human-readable error message */
+    message: string;
+    /** Stack trace (development only) */
+    stack?: string;
+    /** Unique error identifier for log correlation (from server) */
+    digest?: string;
+    /** Machine-readable error code (e.g., "HANDLER_ERROR", "VALIDATION_ERROR") */
+    code?: string;
+    /** HTTP status code */
+    status?: number;
+    /** Additional error-specific details */
+    details?: Record<string, unknown>;
+}
+/**
+ * Props for error component
+ */
+export interface ErrorComponentProps {
+    /** The error that was caught */
+    error: ZapRouteError;
+    /** Reset function to retry rendering */
+    reset: () => void;
+}
+/**
+ * Error component type (TanStack style)
+ */
+export type ErrorComponent = React.ComponentType<ErrorComponentProps>;
+interface RouteErrorContextValue {
+    error: ZapRouteError;
+    reset: () => void;
+}
+/**
+ * Context for accessing error state in error components
+ */
+export declare const RouteErrorContext: React.Context<RouteErrorContextValue | null>;
+interface ErrorBoundaryProps {
+    /** The content to render when no error */
+    children: ReactNode;
+    /** Custom error component (TanStack style) */
+    errorComponent?: ErrorComponent;
+    /** Fallback when no errorComponent provided */
+    fallback?: ReactNode;
+    /** Callback when an error is caught */
+    onError?: (error: ZapRouteError, errorInfo: ErrorInfo) => void;
+    /** Reset keys - when these change, the boundary resets */
+    resetKeys?: unknown[];
+}
+interface ErrorBoundaryState {
+    hasError: boolean;
+    error: ZapRouteError | null;
+}
+/**
+ * Error Boundary with TanStack Router style errorComponent prop
+ *
+ * @example
+ * ```tsx
+ * // Route file: routes/users.$id.tsx
+ * export default function UserPage() {
+ *   // ... component
+ * }
+ *
+ * export function errorComponent({ error, reset }: ErrorComponentProps) {
+ *   return (
+ *     <div>
+ *       <h1>Failed to load user</h1>
+ *       <p>{error.message}</p>
+ *       {error.digest && <small>Error ID: {error.digest}</small>}
+ *       <button onClick={reset}>Try Again</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    componentDidUpdate(prevProps: ErrorBoundaryProps): void;
+    /**
+     * Reset the error boundary state
+     */
+    reset: () => void;
+    render(): ReactNode;
+}
+/**
+ * Default error fallback UI
+ *
+ * Shows:
+ * - Error message
+ * - Error code (if available)
+ * - Error digest (for server errors)
+ * - Stack trace (development only)
+ * - "Try Again" button
+ */
+export declare function DefaultErrorComponent({ error, reset }: ErrorComponentProps): JSX.Element;
+/**
+ * Create a ZapRouteError from server error response
+ */
+export declare function createRouteError(options: {
+    message: string;
+    code?: string;
+    status?: number;
+    digest?: string;
+    details?: Record<string, unknown>;
+}): ZapRouteError;
+/**
+ * Wrap an Error with ZapRouteError metadata
+ */
+export declare class ZapError extends Error {
+    code?: string;
+    status?: number;
+    digest?: string;
+    details?: Record<string, unknown>;
+    constructor(message: string, options?: Omit<ZapRouteError, 'message' | 'stack'>);
+    toRouteError(): ZapRouteError;
+}
+export {};