@oxyhq/services 5.7.3 → 5.7.4

package/lib/typescript/node/middleware.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Zero-config Express middleware for OxyHQ Services authentication
+ *
+ * This provides a simple, one-line solution for adding authentication to Express apps.
+ * Simply import and use: app.use('/api', createOxyAuth())
+ */
+import { ApiError } from '../models/interfaces';
+export interface OxyAuthConfig {
+    /** Base URL of your Oxy API server */
+    baseURL?: string;
+    /** Whether to load full user data (default: true) */
+    loadUser?: boolean;
+    /** Routes that don't require authentication */
+    publicPaths?: string[];
+    /** Custom error handler */
+    onError?: (error: ApiError, req: any, res: any) => void;
+}
+export interface AuthenticatedRequest {
+    user?: any;
+    userId?: string;
+    accessToken?: string;
+}
+/**
+ * Creates zero-config authentication middleware for Express.js
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { createOxyAuth } from '@oxyhq/services/node';
+ *
+ * const app = express();
+ *
+ * // Zero-config auth for all /api routes
+ * app.use('/api', createOxyAuth());
+ *
+ * // Now all routes under /api automatically have req.user available
+ * app.get('/api/profile', (req, res) => {
+ *   res.json({ user: req.user }); // req.user is automatically available
+ * });
+ * ```
+ */
+export declare function createOxyAuth(config?: OxyAuthConfig): (req: any, res: any, next: any) => Promise<any>;
+/**
+ * Creates optional authentication middleware
+ * This middleware will attach user data if a valid token is present, but won't fail if missing
+ *
+ * @example
+ * ```typescript
+ * import { createOptionalOxyAuth } from '@oxyhq/services/node';
+ *
+ * app.use('/api', createOptionalOxyAuth());
+ *
+ * app.get('/api/content', (req, res) => {
+ *   if (req.user) {
+ *     // User is authenticated, show personalized content
+ *     res.json({ content: 'personalized', user: req.user });
+ *   } else {
+ *     // Anonymous user, show public content
+ *     res.json({ content: 'public' });
+ *   }
+ * });
+ * ```
+ */
+export declare function createOptionalOxyAuth(config?: OxyAuthConfig): (req: any, res: any, next: any) => Promise<any>;
+/**
+ * Utility function to quickly set up a complete Express app with authentication
+ *
+ * @example
+ * ```typescript
+ * import { createOxyExpressApp } from '@oxyhq/services/node';
+ *
+ * const app = createOxyExpressApp();
+ *
+ * // All routes automatically have authentication and req.user available
+ * app.get('/api/profile', (req, res) => {
+ *   res.json({ user: req.user });
+ * });
+ *
+ * app.listen(3000);
+ * ```
+ */
+export declare function createOxyExpressApp(config?: OxyAuthConfig & {
+    /** Express app configuration */
+    cors?: boolean;
+    /** JSON body parser limit */
+    jsonLimit?: string;
+    /** Additional middleware to apply */
+    middleware?: any[];
+}): void;
+export { OxyServices } from '../core';
+export * from '../models/interfaces';
+//# sourceMappingURL=middleware.d.ts.map

package/lib/typescript/node/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../../src/node/middleware.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEhD,MAAM,WAAW,aAAa;IAC5B,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,2BAA2B;IAC3B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,KAAK,IAAI,CAAC;CACzD;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,GAAG,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,MAAM,GAAE,aAAkB,IAUxC,KAAK,GAAG,EAAE,KAAK,GAAG,EAAE,MAAM,GAAG,kBA+E5C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,GAAE,aAAkB,IAQhD,KAAK,GAAG,EAAE,KAAK,GAAG,EAAE,MAAM,GAAG,kBAgC5C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,GAAE,aAAa,GAAG;IAC1D,gCAAgC;IAChC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,UAAU,CAAC,EAAE,GAAG,EAAE,CAAC;CACf,QAKL;AAGD,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,cAAc,sBAAsB,CAAC"}

package/lib/typescript/ui/index.d.ts

@@ -1,5 +1,6 @@
 declare let OxyProvider: any, OxySignInButton: any, OxyLogo: any, Avatar: any, FollowButton: any, OxyPayButton: any, FontLoader: any, setupFonts: any, OxyIcon: any, useOxy: any, OxyContextProvider: any, OxyContextState: any, OxyContextProviderProps: any, useFollow: any, ProfileScreen: any, OxyRouter: any, useAuthStore: any, fontFamilies: any, fontStyles: any, toast: any;
-export { OxyProvider, OxySignInButton, OxyLogo, Avatar, FollowButton, OxyPayButton, FontLoader, setupFonts, OxyIcon, useOxy, OxyContextProvider, OxyContextState, OxyContextProviderProps, useFollow, ProfileScreen, OxyRouter, useAuthStore, fontFamilies, fontStyles, toast };
+declare let OxyZeroConfigProvider: any, useOxyZeroConfig: any, useOxyApi: any;
+export { OxyProvider, OxySignInButton, OxyLogo, Avatar, FollowButton, OxyPayButton, FontLoader, setupFonts, OxyIcon, useOxy, OxyContextProvider, OxyContextState, OxyContextProviderProps, useFollow, ProfileScreen, OxyRouter, useAuthStore, fontFamilies, fontStyles, toast, OxyZeroConfigProvider, useOxyZeroConfig, useOxyApi };
 export { OxyServices } from '../core';
 export type { User, LoginResponse, ApiError } from '../models/interfaces';
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/ui/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ui/index.ts"],"names":[],"mappings":"AASA,QAAA,IAAI,WAAW,KAAA,EAAE,eAAe,KAAA,EAAE,OAAO,KAAA,EAAE,MAAM,KAAA,EAAE,YAAY,KAAA,EAAE,YAAY,KAAA,EAAE,UAAU,KAAA,EAAE,UAAU,KAAA,EAAE,OAAO,KAAA,EAAE,MAAM,KAAA,EAA8H,kBAAkB,KAAA,EAAE,eAAe,KAAA,EAAE,uBAAuB,KAAA,EAAE,SAAS,KAAA,EAAE,aAAa,KAAA,EAAE,SAAS,KAAA,EAAE,YAAY,KAAA,EAAE,YAAY,KAAA,EAAE,UAAU,KAAA,EAAE,KAAK,KAAA,CAAC;AAiDrY,OAAO,EACL,WAAW,EACX,eAAe,EACf,OAAO,EACP,MAAM,EACN,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,UAAU,EACV,OAAO,EACP,MAAM,EACN,kBAAkB,EAClB,eAAe,EACf,uBAAuB,EACvB,SAAS,EACT,aAAa,EACb,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,KAAK,EACN,CAAC;AAGF,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ui/index.ts"],"names":[],"mappings":"AASA,QAAA,IAAI,WAAW,KAAA,EAAE,eAAe,KAAA,EAAE,OAAO,KAAA,EAAE,MAAM,KAAA,EAAE,YAAY,KAAA,EAAE,YAAY,KAAA,EAAE,UAAU,KAAA,EAAE,UAAU,KAAA,EAAE,OAAO,KAAA,EAAE,MAAM,KAAA,EAA8H,kBAAkB,KAAA,EAAE,eAAe,KAAA,EAAE,uBAAuB,KAAA,EAAE,SAAS,KAAA,EAAE,aAAa,KAAA,EAAE,SAAS,KAAA,EAAE,YAAY,KAAA,EAAE,YAAY,KAAA,EAAE,UAAU,KAAA,EAAE,KAAK,KAAA,CAAC;AAGrY,QAAA,IAAI,qBAAqB,KAAA,EAAE,gBAAgB,KAAA,EAAE,SAAS,KAAA,CAAC;AA2DvD,OAAO,EACL,WAAW,EACX,eAAe,EACf,OAAO,EACP,MAAM,EACN,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,UAAU,EACV,OAAO,EACP,MAAM,EACN,kBAAkB,EAClB,eAAe,EACf,uBAAuB,EACvB,SAAS,EACT,aAAa,EACb,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,KAAK,EAGL,qBAAqB,EACrB,gBAAgB,EAChB,SAAS,EACV,CAAC;AAGF,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC"}

package/lib/typescript/ui/zero-config/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Zero-config exports for OxyHQ Services
+ */
+export { OxyZeroConfigProvider, useOxyZeroConfig, useOxyApi, type OxyZeroConfigState, type OxyZeroConfigProviderProps } from './provider';
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/ui/zero-config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/ui/zero-config/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,qBAAqB,EACrB,gBAAgB,EAChB,SAAS,EACT,KAAK,kBAAkB,EACvB,KAAK,0BAA0B,EAChC,MAAM,YAAY,CAAC"}

package/lib/typescript/ui/zero-config/provider.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Zero-config OxyHQ Provider and Hook for React/React Native
+ *
+ * This provides a simplified, one-line setup for frontend authentication
+ * with automatic token management and API integration.
+ */
+import React, { ReactNode } from 'react';
+import { OxyServices } from '../../core';
+import { User } from '../../models/interfaces';
+export interface OxyZeroConfigState {
+    user: User | null;
+    isAuthenticated: boolean;
+    isLoading: boolean;
+    error: string | null;
+    login: (username: string, password: string) => Promise<User>;
+    logout: () => Promise<void>;
+    register: (username: string, email: string, password: string) => Promise<User>;
+    api: OxyServices;
+}
+export interface OxyZeroConfigProviderProps {
+    children: ReactNode;
+    /** Base URL of your Oxy API server (defaults to process.env.REACT_APP_OXY_API_URL or http://localhost:3001) */
+    apiUrl?: string;
+    /** Called when authentication state changes */
+    onAuthChange?: (user: User | null) => void;
+    /** Storage key prefix (default: 'oxy_zero') */
+    storagePrefix?: string;
+}
+/**
+ * Zero-config provider for OxyHQ Services
+ *
+ * @example
+ * ```tsx
+ * import { OxyZeroConfigProvider } from '@oxyhq/services/ui';
+ *
+ * function App() {
+ *   return (
+ *     <OxyZeroConfigProvider>
+ *       <MyApp />
+ *     </OxyZeroConfigProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare const OxyZeroConfigProvider: React.FC<OxyZeroConfigProviderProps>;
+/**
+ * Zero-config hook for OxyHQ Services
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { user, login, logout, isAuthenticated } = useOxyZeroConfig();
+ *
+ *   const handleLogin = () => {
+ *     login('username', 'password');
+ *   };
+ *
+ *   if (isAuthenticated) {
+ *     return <div>Welcome, {user?.username}!</div>;
+ *   }
+ *
+ *   return <button onClick={handleLogin}>Login</button>;
+ * }
+ * ```
+ */
+export declare const useOxyZeroConfig: () => OxyZeroConfigState;
+/**
+ * Hook for automatic API client with authentication
+ * This automatically includes the auth token in requests
+ *
+ * @example
+ * ```tsx
+ * function ProfileComponent() {
+ *   const api = useOxyApi();
+ *
+ *   const updateProfile = async (data) => {
+ *     const user = await api.updateProfile(data);
+ *     // Token is automatically included
+ *   };
+ * }
+ * ```
+ */
+export declare const useOxyApi: () => OxyServices;
+//# sourceMappingURL=provider.d.ts.map

package/lib/typescript/ui/zero-config/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../../src/ui/zero-config/provider.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,EAAkD,SAAS,EAAe,MAAM,OAAO,CAAC;AACtG,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,IAAI,EAAiB,MAAM,yBAAyB,CAAC;AAE9D,MAAM,WAAW,kBAAkB;IAEjC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IAClB,eAAe,EAAE,OAAO,CAAC;IACzB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAGrB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAG/E,GAAG,EAAE,WAAW,CAAC;CAClB;AAID,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,SAAS,CAAC;IACpB,+GAA+G;IAC/G,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,KAAK,IAAI,CAAC;IAC3C,+CAA+C;IAC/C,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,qBAAqB,EAAE,KAAK,CAAC,EAAE,CAAC,0BAA0B,CA6MtE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,gBAAgB,QAAO,kBAMnC,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,SAAS,QAAO,WAG5B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@oxyhq/services",
-    "version": "5.7.3",
+    "version": "5.7.4",
     "description": "Reusable OxyHQ module to handle authentication, user management, karma system, device-based session management and more 🚀",
     "main": "lib/commonjs/index.js",
     "module": "lib/module/index.js",
@@ -23,6 +23,11 @@
             "require": "./lib/commonjs/ui/index.js",
             "types": "./lib/typescript/ui/index.d.ts"
         },
+        "./node": {
+            "import": "./lib/module/node/index.js",
+            "require": "./lib/commonjs/node/index.js",
+            "types": "./lib/typescript/node/index.d.ts"
+        },
         "./full": {
             "import": "./lib/module/index.js",
             "require": "./lib/commonjs/index.js",

package/src/node/index.ts

@@ -1,7 +1,19 @@
 /**
- * OxyHQServices Node.js Entry Point
+ * Node.js-specific exports for OxyHQ Services
+ * 
+ * This module provides zero-config Express.js middleware and utilities
+ * for backend integration with OxyHQ Services.
  */
 
+// Export the zero-config middleware
+export {
+  createOxyAuth,
+  createOptionalOxyAuth,
+  createOxyExpressApp,
+  type OxyAuthConfig,
+  type AuthenticatedRequest
+} from './middleware';
+
 // ------------- Core Imports -------------
 import { OxyServices, OXY_CLOUD_URL } from '../core'; // Adjusted path
 import { createAuth } from './createAuth';
@@ -16,6 +28,10 @@ export { createAuth };
 // ------------- Model Exports -------------
 export { Models };  // Export all models as a namespace
 export * from '../models/interfaces'; // Export all models directly
+export * from '../models/secureSession';
+
+// Re-export utilities
+export { DeviceManager } from '../utils/deviceManager';
 
 // Default export for consistency or specific use cases if needed
 export default OxyServices;

package/src/node/middleware.ts

@@ -0,0 +1,234 @@
+/**
+ * Zero-config Express middleware for OxyHQ Services authentication
+ * 
+ * This provides a simple, one-line solution for adding authentication to Express apps.
+ * Simply import and use: app.use('/api', createOxyAuth())
+ */
+
+import { OxyServices } from '../core';
+import { ApiError } from '../models/interfaces';
+
+export interface OxyAuthConfig {
+  /** Base URL of your Oxy API server */
+  baseURL?: string;
+  /** Whether to load full user data (default: true) */
+  loadUser?: boolean;
+  /** Routes that don't require authentication */
+  publicPaths?: string[];
+  /** Custom error handler */
+  onError?: (error: ApiError, req: any, res: any) => void;
+}
+
+export interface AuthenticatedRequest {
+  user?: any;
+  userId?: string;
+  accessToken?: string;
+}
+
+/**
+ * Creates zero-config authentication middleware for Express.js
+ * 
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { createOxyAuth } from '@oxyhq/services/node';
+ * 
+ * const app = express();
+ * 
+ * // Zero-config auth for all /api routes
+ * app.use('/api', createOxyAuth());
+ * 
+ * // Now all routes under /api automatically have req.user available
+ * app.get('/api/profile', (req, res) => {
+ *   res.json({ user: req.user }); // req.user is automatically available
+ * });
+ * ```
+ */
+export function createOxyAuth(config: OxyAuthConfig = {}) {
+  const {
+    baseURL = process.env.OXY_API_URL || 'http://localhost:3001',
+    loadUser = true,
+    publicPaths = [],
+    onError
+  } = config;
+
+  const oxy = new OxyServices({ baseURL });
+
+  return async (req: any, res: any, next: any) => {
+    // Check if this is a public path
+    const isPublicPath = publicPaths.some(path => 
+      req.path === path || req.path.startsWith(path + '/')
+    );
+
+    if (isPublicPath) {
+      return next();
+    }
+
+    try {
+      const authHeader = req.headers['authorization'];
+      const token = authHeader && authHeader.split(' ')[1]; // Bearer TOKEN
+
+      if (!token) {
+        const error: ApiError = {
+          message: 'Access token required',
+          code: 'MISSING_TOKEN',
+          status: 401
+        };
+
+        if (onError) {
+          return onError(error, req, res);
+        }
+
+        return res.status(401).json({
+          error: 'Access token required',
+          code: 'MISSING_TOKEN'
+        });
+      }
+
+      // Validate token using the OxyServices client
+      const authResult = await oxy.authenticateToken(token);
+
+      if (!authResult.valid) {
+        const error: ApiError = {
+          message: authResult.error || 'Invalid token',
+          code: 'INVALID_TOKEN',
+          status: 403
+        };
+
+        if (onError) {
+          return onError(error, req, res);
+        }
+
+        return res.status(403).json({
+          error: authResult.error || 'Invalid token',
+          code: 'INVALID_TOKEN'
+        });
+      }
+
+      // Attach user data to request
+      req.userId = authResult.userId;
+      req.accessToken = token;
+
+      if (loadUser && authResult.user) {
+        req.user = authResult.user;
+      } else {
+        req.user = { id: authResult.userId };
+      }
+
+      next();
+    } catch (error: any) {
+      const apiError: ApiError = {
+        message: error.message || 'Authentication failed',
+        code: error.code || 'AUTH_ERROR',
+        status: error.status || 500
+      };
+
+      if (onError) {
+        return onError(apiError, req, res);
+      }
+
+      res.status(apiError.status).json({
+        error: apiError.message,
+        code: apiError.code
+      });
+    }
+  };
+}
+
+/**
+ * Creates optional authentication middleware
+ * This middleware will attach user data if a valid token is present, but won't fail if missing
+ * 
+ * @example
+ * ```typescript
+ * import { createOptionalOxyAuth } from '@oxyhq/services/node';
+ * 
+ * app.use('/api', createOptionalOxyAuth());
+ * 
+ * app.get('/api/content', (req, res) => {
+ *   if (req.user) {
+ *     // User is authenticated, show personalized content
+ *     res.json({ content: 'personalized', user: req.user });
+ *   } else {
+ *     // Anonymous user, show public content
+ *     res.json({ content: 'public' });
+ *   }
+ * });
+ * ```
+ */
+export function createOptionalOxyAuth(config: OxyAuthConfig = {}) {
+  const {
+    baseURL = process.env.OXY_API_URL || 'http://localhost:3001',
+    loadUser = true
+  } = config;
+
+  const oxy = new OxyServices({ baseURL });
+
+  return async (req: any, res: any, next: any) => {
+    try {
+      const authHeader = req.headers['authorization'];
+      const token = authHeader && authHeader.split(' ')[1]; // Bearer TOKEN
+
+      if (!token) {
+        // No token provided, continue without authentication
+        return next();
+      }
+
+      // Validate token using the OxyServices client
+      const authResult = await oxy.authenticateToken(token);
+
+      if (authResult.valid) {
+        // Attach user data to request if token is valid
+        req.userId = authResult.userId;
+        req.accessToken = token;
+
+        if (loadUser && authResult.user) {
+          req.user = authResult.user;
+        } else {
+          req.user = { id: authResult.userId };
+        }
+      }
+
+      next();
+    } catch (error) {
+      // If there's an error, continue without authentication
+      // This makes the middleware truly optional
+      next();
+    }
+  };
+}
+
+/**
+ * Utility function to quickly set up a complete Express app with authentication
+ * 
+ * @example
+ * ```typescript
+ * import { createOxyExpressApp } from '@oxyhq/services/node';
+ * 
+ * const app = createOxyExpressApp();
+ * 
+ * // All routes automatically have authentication and req.user available
+ * app.get('/api/profile', (req, res) => {
+ *   res.json({ user: req.user });
+ * });
+ * 
+ * app.listen(3000);
+ * ```
+ */
+export function createOxyExpressApp(config: OxyAuthConfig & {
+  /** Express app configuration */
+  cors?: boolean;
+  /** JSON body parser limit */
+  jsonLimit?: string;
+  /** Additional middleware to apply */
+  middleware?: any[];
+} = {}) {
+  // This is a lightweight helper - users should import express themselves
+  // We'll provide the middleware setup instructions instead
+  
+  throw new Error('createOxyExpressApp is not implemented yet. Please use createOxyAuth() middleware with your existing Express app.');
+}
+
+// Re-export for convenience
+export { OxyServices } from '../core';
+export * from '../models/interfaces';

package/src/ui/index.ts

@@ -9,6 +9,9 @@ import isFrontend from './isFrontend';
 // Real UI exports
 let OxyProvider, OxySignInButton, OxyLogo, Avatar, FollowButton, OxyPayButton, FontLoader, setupFonts, OxyIcon, useOxy, useOxyAuth, useOxyUser, useOxyKarma, useOxyPayments, useOxyDevices, useOxyNotifications, useOxySocket, useOxyQR, useOxyIAP, OxyContextProvider, OxyContextState, OxyContextProviderProps, useFollow, ProfileScreen, OxyRouter, useAuthStore, fontFamilies, fontStyles, toast;
 
+// Zero-config exports
+let OxyZeroConfigProvider, useOxyZeroConfig, useOxyApi;
+
 if (isFrontend) {
   OxyProvider = require('./components/OxyProvider').default;
   OxySignInButton = require('./components/OxySignInButton').default;
@@ -30,6 +33,11 @@ if (isFrontend) {
   fontFamilies = require('./styles/fonts').fontFamilies;
   fontStyles = require('./styles/fonts').fontStyles;
   toast = require('../lib/sonner').toast;
+  
+  // Zero-config components
+  OxyZeroConfigProvider = require('./zero-config').OxyZeroConfigProvider;
+  useOxyZeroConfig = require('./zero-config').useOxyZeroConfig;
+  useOxyApi = require('./zero-config').useOxyApi;
 } else {
   // Backend: no-op fallbacks
   const noopComponent = () => null;
@@ -54,6 +62,11 @@ if (isFrontend) {
   fontFamilies = {};
   fontStyles = {};
   toast = () => {};
+  
+  // Zero-config no-ops
+  OxyZeroConfigProvider = noopComponent;
+  useOxyZeroConfig = noopHook;
+  useOxyApi = () => ({});
 }
 
 export {
@@ -76,7 +89,12 @@ export {
   useAuthStore,
   fontFamilies,
   fontStyles,
-  toast
+  toast,
+  
+  // Zero-config exports
+  OxyZeroConfigProvider,
+  useOxyZeroConfig,
+  useOxyApi
 };
 
 // Re-export core services for convenience in UI context

package/src/ui/zero-config/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Zero-config exports for OxyHQ Services
+ */
+
+export {
+  OxyZeroConfigProvider,
+  useOxyZeroConfig,
+  useOxyApi,
+  type OxyZeroConfigState,
+  type OxyZeroConfigProviderProps
+} from './provider';