@foxpixel/react 0.1.0

package/README.md

@@ -0,0 +1,216 @@
+# @foxpixel/react
+
+React SDK for FoxPixel API - Headless integration for custom sites and portals.
+
+## Installation
+
+```bash
+npm install @foxpixel/react
+# or
+yarn add @foxpixel/react
+# or
+pnpm add @foxpixel/react
+```
+
+## Quick Start
+
+### 1. Wrap your app with FoxPixelProvider
+
+```tsx
+// app.tsx or _app.tsx
+import { FoxPixelProvider } from '@foxpixel/react';
+
+function App() {
+  return (
+    <FoxPixelProvider>
+      <YourApp />
+    </FoxPixelProvider>
+  );
+}
+```
+
+### 2. Use hooks in your components
+
+```tsx
+import { useServices } from '@foxpixel/react';
+
+function ServicesPage() {
+  const { services, isLoading, error } = useServices({ active: true });
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      {services?.map(service => (
+        <div key={service.id}>
+          <h3>{service.name}</h3>
+          <p>{service.description}</p>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Configuration
+
+### Environment Variables
+
+```env
+# Client-side (public)
+NEXT_PUBLIC_FOXPIXEL_API_URL=https://api.foxpixel.com
+
+# Server-side only (NEVER expose in client)
+FOXPIXEL_API_KEY=sk_live_your_key_here
+FOXPIXEL_TENANT_ID=your_tenant_id_here
+```
+
+### Provider Configuration
+
+```tsx
+<FoxPixelProvider
+  config={{
+    apiUrl: 'https://api.foxpixel.com',
+    // apiKey: Only use server-side (via proxy)
+    // tenantId: Optional, can be set per request
+  }}
+>
+  <App />
+</FoxPixelProvider>
+```
+
+## Security: Server-Side Proxy
+
+**IMPORTANT:** API Keys should NEVER be exposed in client-side code.
+
+Use Next.js API routes to proxy requests:
+
+```tsx
+// pages/api/foxpixel/[...path].ts
+import type { NextApiRequest, NextApiResponse } from 'next';
+
+export default async function handler(
+  req: NextApiRequest,
+  res: NextApiResponse
+) {
+  const apiKey = process.env.FOXPIXEL_API_KEY;
+  const apiUrl = process.env.NEXT_PUBLIC_FOXPIXEL_API_URL;
+
+  // Proxy request with API Key
+  const response = await fetch(`${apiUrl}${req.url}`, {
+    method: req.method,
+    headers: {
+      'Authorization': `Bearer ${apiKey}`,
+      'Content-Type': 'application/json',
+    },
+    body: req.method !== 'GET' ? JSON.stringify(req.body) : undefined,
+  });
+
+  const data = await response.json();
+  res.status(response.status).json(data);
+}
+```
+
+Then configure SDK to use proxy:
+
+```tsx
+<FoxPixelProvider
+  config={{
+    apiUrl: '/api/foxpixel', // Use proxy instead of direct API
+  }}
+>
+  <App />
+</FoxPixelProvider>
+```
+
+## Hooks
+
+### `useServices(options?)`
+
+Fetch services from Projects module.
+
+```tsx
+const { services, isLoading, error, refetch } = useServices({
+  category: 'pools',
+  active: true,
+});
+```
+
+### `useLeadCapture()`
+
+Capture leads (create lead in CRM).
+
+```tsx
+const { captureLead, isLoading, error } = useLeadCapture();
+
+await captureLead({
+  fullName: 'John Doe',
+  email: 'john@example.com',
+  phone: '+1234567890',
+  source: 'website',
+});
+```
+
+### `useAuth()`
+
+Authenticate End Users (clients of your tenant).
+
+```tsx
+const { user, isAuthenticated, login, logout, isLoading } = useAuth();
+
+// Login
+await login({
+  email: 'user@example.com',
+  password: 'password123',
+});
+
+// Logout
+await logout();
+```
+
+## End User Authentication
+
+End Users are authenticated via httpOnly cookies (secure, XSS-resistant).
+
+```tsx
+function LoginPage() {
+  const { login, isLoading, error } = useAuth();
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    try {
+      await login({
+        email: e.target.email.value,
+        password: e.target.password.value,
+      });
+      router.push('/dashboard');
+    } catch (err) {
+      console.error('Login failed:', err);
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input name="email" type="email" required />
+      <input name="password" type="password" required />
+      <button type="submit" disabled={isLoading}>
+        {isLoading ? 'Logging in...' : 'Login'}
+      </button>
+      {error && <div>{error.message}</div>}
+    </form>
+  );
+}
+```
+
+## TypeScript
+
+Full TypeScript support with exported types:
+
+```tsx
+import type { Service, Lead, EndUser } from '@foxpixel/react';
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,408 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, ComponentType } from 'react';
+import { AxiosInstance, AxiosRequestConfig } from 'axios';
+
+/**
+ * Core types for FoxPixel React SDK
+ */
+interface FoxPixelConfig {
+    /**
+     * Base URL of the FoxPixel API
+     * Default: process.env.NEXT_PUBLIC_FOXPIXEL_API_URL
+     */
+    apiUrl?: string;
+    /**
+     * API Key for authentication (server-side only)
+     * NEVER expose this in client-side code
+     * Default: process.env.FOXPIXEL_API_KEY
+     */
+    apiKey?: string;
+    /**
+     * Tenant ID (optional, can be set per request)
+     */
+    tenantId?: string;
+}
+interface Service {
+    id: string;
+    name: string;
+    description?: string;
+    category?: string;
+    price?: number;
+    active: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ServiceCatalogResponse {
+    id: string;
+    tenantId: string;
+    name: string;
+    description?: string;
+    unitPrice: number;
+    unitType: string;
+    currency: string;
+    category?: string;
+    isActive: boolean;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Lead {
+    id: string;
+    fullName: string;
+    email: string;
+    phone?: string;
+    source?: string;
+    status: string;
+    createdAt: string;
+}
+interface CreateLeadRequest {
+    fullName: string;
+    email?: string;
+    phone?: string;
+    source?: string;
+    notes?: string;
+}
+interface EndUser {
+    id: string;
+    email: string;
+    fullName?: string;
+    phone?: string;
+    tenantId: string;
+    subscriptionStatus: 'trial' | 'active' | 'inactive' | 'cancelled';
+    trialEndsAt?: string;
+    hasAccess: boolean;
+    [key: string]: any;
+}
+interface EndUserLoginRequest {
+    email: string;
+    password: string;
+}
+interface ApiError$1 {
+    message: string;
+    code?: string;
+    status?: number;
+    expected?: boolean;
+}
+
+/**
+ * HTTP client for FoxPixel API
+ * Handles authentication and request/response transformation
+ */
+
+declare class FoxPixelHttpClient {
+    private client;
+    private apiKey?;
+    private tenantId?;
+    private endUserToken?;
+    constructor(config: FoxPixelConfig);
+    /**
+     * Set API Key (server-side only)
+     */
+    setApiKey(apiKey: string): void;
+    /**
+     * Set tenant ID
+     */
+    setTenantId(tenantId: string): void;
+    /**
+     * Set end user token (for client-side auth)
+     * Note: In practice, end user auth uses httpOnly cookies
+     */
+    setEndUserToken(token: string): void;
+    /**
+     * Clear end user token (logout)
+     */
+    clearEndUserToken(): void;
+    /**
+     * Get underlying axios instance
+     */
+    getInstance(): AxiosInstance;
+    /**
+     * Make GET request
+     */
+    get<T>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * Make POST request
+     */
+    post<T>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * Make PUT request
+     */
+    put<T>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * Make DELETE request
+     */
+    delete<T>(url: string, config?: AxiosRequestConfig): Promise<T>;
+}
+
+interface FoxPixelContextValue {
+    client: FoxPixelHttpClient;
+    config: FoxPixelConfig;
+}
+interface FoxPixelProviderProps {
+    children: ReactNode;
+    config?: FoxPixelConfig;
+}
+/**
+ * FoxPixelProvider - Wraps your app and provides SDK functionality
+ *
+ * IMPORTANT: API Key should NEVER be passed from client-side.
+ * Use server-side proxy (Next.js API routes) for API Key authentication.
+ *
+ * @example
+ * ```tsx
+ * // Client-side (no API Key)
+ * <FoxPixelProvider>
+ *   <App />
+ * </FoxPixelProvider>
+ *
+ * // Server-side proxy (Next.js API route)
+ * // pages/api/foxpixel/[...path].ts
+ * export default async function handler(req, res) {
+ *   const apiKey = process.env.FOXPIXEL_API_KEY;
+ *   // Proxy request with API Key
+ * }
+ * ```
+ */
+declare function FoxPixelProvider({ children, config }: FoxPixelProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access FoxPixel context
+ * @throws Error if used outside FoxPixelProvider
+ */
+declare function useFoxPixelContext(): FoxPixelContextValue;
+
+interface AuthContextValue {
+    user: EndUser | null;
+    isLoading: boolean;
+    isAuthenticated: boolean;
+    error: ApiError$1 | null;
+    login: (credentials: EndUserLoginRequest) => Promise<void>;
+    logout: () => Promise<void>;
+    register: (data: {
+        email: string;
+        password: string;
+        fullName: string;
+        phone?: string;
+    }) => Promise<void>;
+    updateProfile: (data: {
+        fullName?: string;
+        phone?: string;
+    }) => Promise<void>;
+    refetch: () => Promise<void>;
+}
+interface AuthProviderProps {
+    children: ReactNode;
+    /**
+     * Redirect path when user is not authenticated
+     * Default: '/login'
+     */
+    loginPath?: string;
+    /**
+     * Redirect path after successful login
+     * Default: '/account'
+     */
+    accountPath?: string;
+}
+/**
+ * AuthProvider - Manages authentication state globally
+ *
+ * Automatically:
+ * - Restores session on mount (checks httpOnly cookie)
+ * - Manages user state across the app
+ * - Handles login/logout transparently
+ *
+ * @example
+ * ```tsx
+ * // In _app.tsx
+ * <FoxPixelProvider>
+ *   <AuthProvider>
+ *     <Component {...pageProps} />
+ *   </AuthProvider>
+ * </FoxPixelProvider>
+ * ```
+ */
+declare function AuthProvider({ children, loginPath, accountPath }: AuthProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access authentication context
+ * @throws Error if used outside AuthProvider
+ */
+declare function useAuth(): AuthContextValue;
+
+interface ProtectedRouteProps {
+    children: ReactNode;
+    /**
+     * Redirect path when not authenticated
+     * Default: '/login'
+     */
+    loginPath?: string;
+    /**
+     * Show loading spinner while checking auth
+     */
+    loadingComponent?: ReactNode;
+}
+declare function ProtectedRoute({ children, loginPath, loadingComponent, }: ProtectedRouteProps): string | number | true | Iterable<ReactNode> | react_jsx_runtime.JSX.Element | null;
+
+interface GuestOnlyRouteProps {
+    children: ReactNode;
+    /**
+     * Where to redirect when already authenticated.
+     * Default: '/account'
+     */
+    redirectTo?: string;
+    /**
+     * Show this while checking auth or redirecting.
+     */
+    loadingComponent?: ReactNode;
+}
+declare function GuestOnlyRoute({ children, redirectTo, loadingComponent, }: GuestOnlyRouteProps): string | number | true | Iterable<ReactNode> | react_jsx_runtime.JSX.Element;
+
+interface WithAuthOptions {
+    loginPath?: string;
+    loadingComponent?: ReactNode;
+}
+declare function withAuth<P extends object>(Component: ComponentType<P>, options?: WithAuthOptions): (props: P) => string | number | true | Iterable<ReactNode> | react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Hook to fetch and manage services (Projects module)
+ */
+
+interface UseServicesOptions {
+    category?: string;
+    active?: boolean;
+}
+interface UseServicesReturn {
+    services: ServiceCatalogResponse[] | null;
+    isLoading: boolean;
+    error: ApiError$1 | null;
+    refetch: () => Promise<void>;
+}
+/**
+ * Fetch services from Projects module
+ *
+ * @example
+ * ```tsx
+ * function ServicesPage() {
+ *   const { services, isLoading, error } = useServices({ active: true });
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   return (
+ *     <div>
+ *       {services?.map(service => (
+ *         <ServiceCard key={service.id} service={service} />
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useServices(options?: UseServicesOptions): UseServicesReturn;
+
+/**
+ * Hook to capture leads (CRM module)
+ */
+
+interface UseLeadCaptureReturn {
+    captureLead: (data: CreateLeadRequest) => Promise<Lead>;
+    isLoading: boolean;
+    error: ApiError$1 | null;
+}
+/**
+ * Capture a lead (create lead in CRM)
+ *
+ * @example
+ * ```tsx
+ * function ContactForm() {
+ *   const { captureLead, isLoading, error } = useLeadCapture();
+ *
+ *   const handleSubmit = async (e) => {
+ *     e.preventDefault();
+ *     try {
+ *       const lead = await captureLead({
+ *         fullName: 'John Doe',
+ *         email: 'john@example.com',
+ *         phone: '+1234567890',
+ *         source: 'website',
+ *       });
+ *       alert('Lead created!');
+ *     } catch (err) {
+ *       console.error('Error:', err);
+ *     }
+ *   };
+ *
+ *   return <form onSubmit={handleSubmit}>...</form>;
+ * }
+ * ```
+ */
+declare function useLeadCapture(): UseLeadCaptureReturn;
+
+/**
+ * Hook to capture contacts (CRM module)
+ */
+interface Contact {
+    id: string;
+    fullName: string;
+    email?: string;
+    phone?: string;
+    company?: string;
+    notes?: string;
+    postalCode?: string;
+    address?: string;
+    city?: string;
+    createdAt: string;
+}
+interface CreateContactRequest {
+    fullName: string;
+    email?: string;
+    phone?: string;
+    company?: string;
+    notes?: string;
+    nif?: string;
+    address?: string;
+    postalCode?: string;
+    city?: string;
+}
+interface ApiError {
+    message: string;
+    status?: number;
+    code?: string;
+}
+interface UseContactCaptureReturn {
+    captureContact: (data: CreateContactRequest) => Promise<Contact>;
+    isLoading: boolean;
+    error: ApiError | null;
+}
+/**
+ * Capture a contact (create contact in CRM)
+ *
+ * The frontend/SDK decides which fields to fill.
+ * This hook accepts any fields from CreateContactRequest.
+ *
+ * @example
+ * ```tsx
+ * function ContactForm() {
+ *   const { captureContact, isLoading, error } = useContactCapture();
+ *
+ *   const handleSubmit = async (e) => {
+ *     e.preventDefault();
+ *     try {
+ *       const contact = await captureContact({
+ *         fullName: 'John Doe',
+ *         email: 'john@example.com',
+ *         phone: '+1234567890',
+ *         postalCode: '75001',
+ *         notes: 'Interested in garden maintenance',
+ *       });
+ *       alert('Contact created!');
+ *     } catch (err) {
+ *       console.error('Error:', err);
+ *     }
+ *   };
+ *
+ *   return <form onSubmit={handleSubmit}>...</form>;
+ * }
+ * ```
+ */
+declare function useContactCapture(): UseContactCaptureReturn;
+
+export { type ApiError$1 as ApiError, AuthProvider, type CreateLeadRequest, type EndUser, type EndUserLoginRequest, type FoxPixelConfig, FoxPixelHttpClient, FoxPixelProvider, GuestOnlyRoute, type Lead, ProtectedRoute, type Service, type ServiceCatalogResponse, useAuth, useContactCapture, useFoxPixelContext, useLeadCapture, useServices, withAuth };