@metagptx/web-sdk 0.0.49 → 0.0.51

package/README.md

@@ -1,6 +1,6 @@
 # FuncSea WebSDK
 
-A TypeScript SDK for interacting with FuncSea API, providing modules for authentication, entity management, API calls, and integrations.
+A TypeScript SDK for interacting with FuncSea API, providing modules for authentication, entity management, API calls, integrations, and a Vite plugin for automatic 404 page setup.
 
 ## Installation
 
@@ -14,6 +14,8 @@ yarn add @metagptx/web-sdk
 
 ## Quick Start
 
+### Basic Usage
+
 ```typescript
 import { createClient } from '@metagptx/web-sdk';
 
@@ -24,9 +26,27 @@ const client = createClient();
 const user = await client.auth.me();
 ```
 
+### Using the Vite Plugin
+
+If you're using Vite with React Router, you can use the included plugin to automatically add a 404 page:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { vitePlugin404 } from '@metagptx/web-sdk';
+
+export default defineConfig({
+  plugins: [
+    react(),
+    vitePlugin404(), // Automatically adds 404 page to your routes
+  ],
+});
+```
+
 ## Modules
 
-The SDK provides six main modules:
+The SDK provides six main modules and a Vite plugin:
 
 - **auth**: User authentication operations
 - **entities**: Dynamic entity CRUD operations
@@ -34,6 +54,7 @@ The SDK provides six main modules:
 - **integrations**: Integration function invocations
 - **frame**: Frame communication operations for iframe/parent window messaging
 - **utils**: Utility functions for URL opening and window management
+- **vitePlugin404**: Vite plugin for automatically adding a 404 page to React Router applications
 
 ## API Reference
 
@@ -598,6 +619,117 @@ The SDK automatically handles 401 (Unauthorized) responses by redirecting to the
 
 ---
 
+## Vite Plugin
+
+The SDK provides a Vite plugin for automatically adding a 404 page to your React Router application.
+
+### `vitePlugin404()`
+
+A Vite plugin that automatically creates a virtual 404 React component and adds it to your routing configuration.
+
+**Features:**
+- Automatically creates a beautiful 404 page component
+- Automatically adds a wildcard route (`path="*"`) to your `App.tsx`
+- Detects if already configured (won't duplicate routes)
+- Works seamlessly with React Router
+- Provides "Create page" functionality when running in MGX iframe
+
+**Setup:**
+
+1. Import the plugin in your `vite.config.ts`:
+
+```typescript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { vitePlugin404 } from '@metagptx/web-sdk';
+
+export default defineConfig({
+  plugins: [
+    react(),
+    vitePlugin404(), // Add the plugin
+  ],
+});
+```
+
+2. The plugin will automatically:
+   - Create a virtual `NotFoundPage` component
+   - Add the import statement to your `App.tsx`
+   - Add a `<Route path="*" element={<NotFoundPage />} />` route
+
+**Requirements:**
+
+- Your project must have an `App.tsx` file (or any file containing `App.tsx` in the path)
+- Your project must use React Router with `<Routes>` component
+- Your project should have `@/components/ui/button` component (or adjust the import in the plugin code)
+
+**How it works:**
+
+The plugin uses multiple strategies to intelligently add the 404 route:
+
+1. **Import placement strategies:**
+   - After `AuthError` import (if exists)
+   - After `MODULE_IMPORTS_END` comment (if exists)
+   - Before `MODULE_IMPORTS_START` comment (if exists)
+   - After the last import statement (fallback)
+
+2. **Route placement strategies:**
+   - Before `MODULE_ROUTES_END` comment (if exists)
+   - Before closing `</Routes>` tag
+   - After the last `<Route>` tag (fallback)
+
+**Example - Before plugin:**
+
+```tsx
+// App.tsx
+import { Route, Routes } from 'react-router-dom';
+
+export default function App() {
+  return (
+    <Routes>
+      <Route path="/" element={<Home />} />
+      <Route path="/about" element={<About />} />
+    </Routes>
+  );
+}
+```
+
+**Example - After plugin (automatically transformed):**
+
+```tsx
+// App.tsx
+import { Route, Routes } from 'react-router-dom';
+import NotFoundPage from 'virtual:404-page';
+
+export default function App() {
+  return (
+    <Routes>
+      <Route path="/" element={<Home />} />
+      <Route path="/about" element={<About />} />
+      <Route path="*" element={<NotFoundPage />} />
+    </Routes>
+  );
+}
+```
+
+**404 Page Features:**
+
+The generated 404 page includes:
+- Modern, responsive design with gradient background
+- "Return Home" button
+- "Create page" button (when running in MGX iframe) - uses `client.frame.createPage()`
+- "Go to MGX" button (when not in iframe)
+
+**Customization:**
+
+If you need to customize the 404 page, you can:
+1. Create your own 404 component
+2. Import it manually in `App.tsx`
+3. The plugin will detect existing 404 routes and skip automatic addition
+
+**Note:** The plugin only processes files that contain `App.tsx` in their path and end with `.tsx`. It will skip files that already have a 404 route configured.
+
+---
+
 ## TypeScript Support
 
 The SDK is written in TypeScript and provides full type definitions. You can use generic types for typed responses:
@@ -636,3 +768,38 @@ try {
   }
 }
 ```
+
+---
+
+## Exports
+
+The SDK exports the following:
+
+### Main Exports
+
+```typescript
+import { createClient, vitePlugin404 } from '@metagptx/web-sdk';
+```
+
+- **`createClient(config?)`**: Creates a new SDK client instance
+- **`vitePlugin404()`**: Vite plugin for automatic 404 page setup
+
+### Type Exports
+
+```typescript
+import type {
+  AnyType,
+  ApiCallParams,
+  ClientConfig,
+  IntegrationFunction,
+  IntegrationParams,
+  RequestConfig,
+} from '@metagptx/web-sdk';
+```
+
+- **`ClientConfig`**: Configuration options for `createClient()`
+- **`ApiCallParams`**: Parameters for `apiCall.invoke()`
+- **`IntegrationFunction`**: Type for integration functions
+- **`IntegrationParams`**: Parameters for integration function calls
+- **`RequestConfig`**: Axios request configuration options
+- **`AnyType`**: Generic type utility

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@metagptx/web-sdk",
   "type": "module",
-  "version": "0.0.49",
+  "version": "0.0.51",
   "packageManager": "pnpm@10.15.0+sha512.486ebc259d3e999a4e8691ce03b5cac4a71cbeca39372a9b762cb500cfdf0873e2cb16abe3d951b1ee2cf012503f027b98b6584e4df22524e0c7450d9ec7aa7b",
   "description": "TypeScript SDK for interacting with FuncSea API",
   "author": "MetaGPTX",